Merge pull request #99 from ArcGIS/v.next

merge v.next to main

Author: sorenoid

.gitignore

@@ -4,6 +4,7 @@
 /build
 /captures
 .externalNativeBuild
+build/
 
 # Local configuration file (sdk path, etc)
 /local.properties

README.md

@@ -1,12 +1,38 @@
 # ArcGIS Maps SDK for Kotlin Toolkit
 
+The ArcGIS Maps SDK for Kotlin Toolkit contains components that will simplify your Kotlin app development. It is built off of the new ArcGIS Maps SDK for Kotlin.
 
 ## Toolkit Components
 
+* **[Authenticator](toolkit/authentication)** - Displays a user interface when network and ArcGIS authentication challenges occur.
+* **[Compass](toolkit/compass)** - Shows a compass direction when the map is rotated. Auto-hides when the map points north.
+* **[FloorFilter](toolkit/indoors)** - Allows filtering of floor plan data in a geo view by a site, a facility in the site, or a floor in the facility.
+
 ## Requirements
+
+Please see the [developer setup](doc/general/developer_setup.md) for a complete description of requirements
 * ArcGIS Maps SDK for Kotlin    
   See [this guide](https://developers.arcgis.com/kotlin/install-and-set-up/) for complete instructions and
 other options for installing the SDK.
+* JDK 17
+
+The *ArcGIS Maps SDK for Kotlin Toolkit* has a *Minimum SDK* version of *26*, meaning that it can run on devices with *Android Oreo (8.0)* or newer.
+
+## Installation
+
+### Using the BOM
+
+The *ArcGIS Maps SDK for Kotlin Toolkit* is released with a "bill of materials" (`BOM`). The releasable BOM is versioned and represents a set of versions of the toolkit components which are compatible with one another. You may specify dependencies as follows
+
+```
+implementation(platform('com.esri:arcgis-maps-kotlin-toolkit-bom:200.2.0'))
+implementation('com.esri:arcgis-maps-kotlin-toolkit-authenticator')
+implementation('com.esri:arcgis-maps-kotlin-toolkit-compass')
+```
+
+The template and TemplateApp modules are for bootstrapping new modules.
+
+Please see the [package structure](doc/general/developer_setup.md#package-structure) documentation for more details.
 
 ## Issues
 
@@ -16,6 +42,41 @@ Find a bug or want to request a new feature enhancement? Please let us know by [
 
 Esri welcomes contributions from anyone and everyone. Please see our [guidelines for contributing](https://github.com/esri/contributing).
 
+### Creating a New Toolkit Component
+
+A new toolkit component can be added to this project by running the bash script at the top level
+`./new-component-starter.sh -n NameOfNewComponent"`
+
+This will create a new library module for the new component, and a new app module which depends on the library.
+Capitalization isn't necessary, but it won't capitalize anything but the first letter if none is specified.
+
+This script requires bash 4.0 or higher.
+
+### About this Repo
+
+The project is structured into two folders, `microapps` and `toolkit` each containing many modules, and a folder for releasing a bill of materials (BOM).
+
+```
+arcgis-maps-sdk-kotlin-toolkit
+├── bom
+│   └── build.gradle.kts
+├── microapps
+│   └── TemplateApp
+│   ├── ...App
+├── toolkit
+│   ├── template
+│   ├── ...
+├── build.gradle.kts
+└── settings.gradle.kts
+```
+The `toolkit` folder contains releasable libraries -- these are the components of the toolkit.
+For each module in the `toolkit` folder there is a corresponding app in the `microapps` folder which depends on it.
+The apps are not released but are useful for working on a particular component in isolation.
+
+The template and TemplateApp modules are for bootstrapping new modules.
+
+Please see the [package structure](doc/general/developer_setup.md#package-structure) documentation for more details.
+
 ## Licensing
 
 Copyright 2019-2022 Esri
@@ -26,4 +87,4 @@ http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 
-A copy of the license is available in the repository's [LICENSE](LICENSE) file.
+A copy of the license is available in the repository's [LICENSE](LICENSE) file.

authentication/build.gradle

@@ -0,0 +1,94 @@
+/*
+ *
+ *  Copyright 2023 Esri
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ */
+
+plugins {
+    id("maven-publish")
+    id("java-platform")
+}
+
+// Find these in properties passed through command line or read from GRADLE_HOME/gradle.properties
+// or local gradle.properties
+val artifactoryGroupId: String by project
+val artifactoryArtifactBaseId: String by project
+val artifactoryArtifactId: String = "$artifactoryArtifactBaseId-${project.name}"
+val artifactoryUrl: String by project
+val artifactoryUsername: String by project
+val artifactoryPassword: String by project
+val versionNumber: String by project
+val buildNumber: String by project
+val ignoreBuildNumber: String by project
+val artifactVersion: String = if (ignoreBuildNumber == "true") {
+    versionNumber
+} else {
+    "$versionNumber-$buildNumber"
+}
+
+// ensure that the evaluation of the bom project happens after all other projects
+// so that plugins are applied to all projects, and can be used to identify
+// which projects should get written into the BOM's pom file.
+rootProject.subprojects.filter {
+    it.name != project.name
+}.forEach {
+    evaluationDependsOn(":${it.name}")
+}
+
+// now find projects which are publishable based on their inclusion
+// of the publishing plugin, and add them as api dependencies.
+dependencies {
+    constraints {
+        project.rootProject.subprojects.filter {
+            it.plugins.findPlugin("artifact-deploy") != null
+        }.forEach { subproject ->
+            // add all the intended library projects as api dependencies.
+            api(subproject)
+        }
+    }
+}
+
+afterEvaluate {
+    /**
+     * Maven publication configuration for aar and pom file. Run as follows:
+     * ./gradlew publishAarPublicationToMavenRepository -PartifactoryUsername=<username> -PartifactoryPassword=<password>
+     *
+     * More details:
+     * https://docs.gradle.org/current/userguide/publishing_maven.html
+     */
+    publishing {
+        publications {
+            create<MavenPublication>("bom") {
+                groupId = artifactoryGroupId
+                artifactId = artifactoryArtifactId
+                version = artifactVersion
+                
+                from(components["javaPlatform"])
+            }
+        }
+        
+        repositories {
+            maven {
+                url = uri(artifactoryUrl)
+                credentials {
+                    username = artifactoryUsername
+                    password = artifactoryPassword
+                }
+            }
+        }
+    }
+}
+
+

bom/build.gradle.kts

@@ -0,0 +1,31 @@
+/*
+ *
+ *  Copyright 2023 Esri
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ */
+
+// Top-level build file where you can add configuration options common to all sub-projects/modules.
+plugins {
+    @Suppress("DSL_SCOPE_VIOLATION") // fixed in gradle 8.1
+    alias(libs.plugins.android.application) apply false
+    @Suppress("DSL_SCOPE_VIOLATION")
+    alias(libs.plugins.android.library) apply false
+    @Suppress("DSL_SCOPE_VIOLATION")
+    alias(libs.plugins.kotlin.android) apply false
+    @Suppress("DSL_SCOPE_VIOLATION")
+    alias(libs.plugins.gradle.secrets) apply false
+    @Suppress("DSL_SCOPE_VIOLATION")
+    alias(libs.plugins.kotlin.serialization) apply false
+}

build.gradle

@@ -0,0 +1,39 @@
+/*
+ *
+ *  Copyright 2023 Esri
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ */
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+plugins {
+    `kotlin-dsl`
+    `maven-publish`
+}
+
+version = "1.0"
+
+gradlePlugin {
+    plugins {
+        create("artifactDeploy") {
+            group = "internal"
+            id = "artifact-deploy"
+            implementationClass = "deploy.ArtifactPublisher"
+        }
+    }
+}

build.gradle.kts

@@ -0,0 +1,88 @@
+/*
+ *
+ *  Copyright 2023 Esri
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ */
+
+package deploy
+
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.api.publish.PublishingExtension
+import org.gradle.api.publish.maven.plugins.MavenPublishPlugin
+import org.gradle.kotlin.dsl.*
+import org.gradle.api.publish.maven.MavenPublication
+import org.gradle.configurationcache.extensions.capitalized
+import java.net.URI
+
+/**
+ * This class will provide maven publication to projects which apply it as a plugin.
+ * This class does not support platform publication (e.g. a BOM artifact).
+ *
+ * Though the name is `ArtifactPublisher` applying this plugin will provide
+ * all maven publication tasks to a project, such as publishToMavenLocal.
+ * The name is qualified to not overload the term `Publisher`.
+ *
+ * @since 200.2.0
+ */
+class ArtifactPublisher : Plugin<Project> {
+    override fun apply(project: Project) {
+        val artifactoryGroupId: String by project
+        val artifactoryArtifactBaseId: String by project
+        val artifactoryUrl: String by project
+        val artifactoryUsername: String by project
+        val artifactoryPassword: String by project
+        val versionNumber: String by project
+        val ignoreBuildNumber: String by project
+        val buildNumber: String by project
+        val artifactVersion: String = if (ignoreBuildNumber == "true") {
+            versionNumber
+        } else {
+            "$versionNumber-$buildNumber"
+        }
+        val artifactoryArtifactId: String = "$artifactoryArtifactBaseId-${project.name}"
+        
+        project.pluginManager.apply(MavenPublishPlugin::class.java)
+        project.afterEvaluate {
+            project.extensions.configure<PublishingExtension> {
+                repositories {
+                    repositories.maven {
+                        url = URI.create(artifactoryUrl)
+                        credentials {
+                            username = artifactoryUsername
+                            password = artifactoryPassword
+                        }
+                    }
+                }
+                publications {
+                    publications.create(
+                        project.name,
+                        MavenPublication::class.java
+                    ) {
+                        groupId = artifactoryGroupId
+                        artifactId = artifactoryArtifactId
+                        version = artifactVersion
+                        
+                        from(project.components["release"])
+                    }
+                }
+            }
+            
+            tasks.findByName("publish${project.name.capitalized()}PublicationToMavenRepository")
+                ?.dependsOn("assembleRelease")
+            tasks.findByName("publishToMavenLocal")?.dependsOn("assembleRelease")
+        }
+    }
+}