Fail fast with setup instructions when SDK_REGISTRY_TOKEN is missing

DEVELOPING.md

@@ -64,9 +64,18 @@ or update them inline in the source code:
 
 The SDK_REGISTRY_TOKEN is a Mapbox access token, used during compile time, with a scope set to `DOWNLOADS:READ`.
 This token allows to download all required Mapbox dependencies from a Mapbox Maven instance.
-The DOWNLOADS:READ scope can be set when creating a new access token on https://account.mapbox.com/.
+The DOWNLOADS:READ scope can be set when creating a new access token on https://account.mapbox.com/access-tokens/.
+It is a secret scope, so the resulting token is a secret token starting with `sk.`; a public token (`pk.`) will not work.
 The token configuration can be found in the root `build.gradle.kts` of the project.
 
+Besides exporting it as an environment variable, the token can also be set as a Gradle property in `~/.gradle/gradle.properties`:
+
+```
+SDK_REGISTRY_TOKEN=sk.xxx
+```
+
+The build fails early with setup instructions if the token is missing.
+
 #### Mapbox Access token
 
 The MAPBOX_ACCESS_TOKEN is a mapbox access token, packaged as part of test application, to load Mapbox tiles and resources.

compose/settings.gradle.kts

@@ -7,6 +7,8 @@ pluginManagement {
   includeBuild("../mapbox-convention-plugin")
 }
 
+apply(from = "../gradle/sdk-registry-token.settings.gradle.kts")
+
 dependencyResolutionManagement {
   versionCatalogs {
     create("libs") {

gradle/sdk-registry-token.settings.gradle.kts

@@ -0,0 +1,30 @@
+// Fails fast with setup instructions when the token needed to download Mapbox dependencies is
+// missing or of the wrong kind, instead of an "unknown property" or HTTP 401/403 error later on.
+val sdkRegistryToken = providers.environmentVariable("SDK_REGISTRY_TOKEN")
+  .orElse(providers.gradleProperty("SDK_REGISTRY_TOKEN"))
+  .orNull
+
+val problem = when {
+  sdkRegistryToken.isNullOrBlank() -> "SDK_REGISTRY_TOKEN is not set."
+  sdkRegistryToken.startsWith("pk.") ->
+    "SDK_REGISTRY_TOKEN is a public token (pk.), but a secret token (sk.) is required."
+  else -> null
+}
+
+if (problem != null) {
+  throw GradleException(
+    """
+    |$problem
+    |
+    |Building this project requires a Mapbox secret access token with the DOWNLOADS:READ scope:
+    |  1. Sign up or log in at https://account.mapbox.com/
+    |  2. Create a token at https://account.mapbox.com/access-tokens/ with the DOWNLOADS:READ
+    |     secret scope checked, and copy the generated token (it starts with "sk.").
+    |  3. Either export it as the SDK_REGISTRY_TOKEN environment variable, or add it to
+    |     ~/.gradle/gradle.properties:
+    |       SDK_REGISTRY_TOKEN=sk.xxx
+    |
+    |See DEVELOPING.md for more details.
+    """.trimMargin()
+  )
+}

settings.gradle.kts

@@ -7,6 +7,8 @@ pluginManagement {
   includeBuild("mapbox-convention-plugin")
 }
 
+apply(from = "gradle/sdk-registry-token.settings.gradle.kts")
+
 dependencyResolutionManagement {
   versionCatalogs {
     create("commonLibs") {