Android Command Line Tools sdkmanager Directory Structure Changes and Configuration Solutions

Problem Background and Error Analysis

In the Android development environment, sdkmanager is the core command-line tool for managing SDK packages. As Android development tools continue to evolve, developers frequently encounter the Warning: Could not create settings error with accompanying java.lang.IllegalArgumentException stack trace when transitioning from traditional sdk-tools repository to new command-line tools.

The root cause of this error lies in sdkmanager's strict validation mechanism for directory structures. In Android SDK Command-line Tools 1.0.0 (6200805) and later versions, the tool imposes specific requirements on parent directory names, which significantly differs from earlier versions.

Version Differences and Directory Structure Changes

Comparing Android SDK 26.1.1 (4333796) with Command-line Tools 1.0.0 (6200805):

In older versions, the tools directory was directly located under the ANDROID_HOME root directory. Developers could download the SDK tools package, extract it, and use it immediately with relatively simple directory structure.

New versions introduce hierarchical directory structure requirements. After extracting the downloaded commandlinetools archive, the resulting tools directory must be manually placed inside a directory named cmdline-tools. This change reflects Google's modular refactoring of SDK management tools.

The package structure can be verified through the sdkmanager --list command, whose output includes the entry cmdline-tools;1.0 | 1.0 | Android SDK Command-line Tools, confirming the tool's rigid requirements for directory naming.

Complete Configuration Solution

The correct Android SDK root directory structure should contain multiple parallel subdirectories:

• build-tools - Build tool versions
• cmdline-tools - Command line tools
• emulator - Emulator-related files
• licenses - License files
• patcher - Patch tools
• platform-tools - Platform tools
• platforms - Platform versions
• system-images - System images

Detailed configuration steps:

First, set the ANDROID_SDK_ROOT environment variable to point to the SDK root directory. It's recommended to use ANDROID_SDK_ROOT instead of the deprecated ANDROID_HOME to comply with the latest specifications.

After downloading and extracting the command-line tools package, create the directory structure:

mkdir -p $ANDROID_SDK_ROOT/cmdline-tools
mv tools $ANDROID_SDK_ROOT/cmdline-tools/

Configure the PATH environment variable to ensure the system can locate sdkmanager:

export PATH=$PATH:$ANDROID_SDK_ROOT/cmdline-tools/tools/bin

The key point is that the cmdline-tools directory should not be set as ANDROID_SDK_ROOT itself, but rather as its subdirectory. This design allows other SDK components installed subsequently to be correctly placed under the root directory, maintaining structural clarity and maintainability.

Version Evolution and Update Strategy

Starting from Android SDK Command-line Tools 3.0 (6858069), directory structure requirements have been further refined. The top-level directory after extraction is named cmdline-tools, which needs to be renamed to tools and placed under $ANDROID_SDK_ROOT/cmdline-tools.

The final path should be: $ANDROID_SDK_ROOT/cmdline-tools/tools, containing files such as NOTICE.txt, bin, lib, and source.properties.

The official documentation suggests the path pattern android_sdk/cmdline-tools/version/bin/, but practical testing shows no functional difference between using tools or version numbers as directory names.

To accommodate future updates, the recommended PATH configuration strategy:

export PATH=$PATH:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$ANDROID_SDK_ROOT/cmdline-tools/tools/bin

This configuration ensures that newer version tools receive higher search priority while maintaining backward compatibility.

GitLab CI/CD Configuration Optimization

Based on the above analysis, optimize the GitLab CI configuration file:

image: openjdk:9-jdk

variables:
  ANDROID_COMPILE_SDK: "29"
  ANDROID_BUILD_TOOLS: "29.0.3"
  ANDROID_SDK_TOOLS: "6200805"
  ANDROID_SDK_ROOT: "$PWD/android-sdk-linux"

before_script:
  - apt-get --quiet update --yes
  - apt-get --quiet install --yes wget tar unzip lib32stdc++6 lib32z1
  - wget --quiet --output-document=android-sdk.zip https://dl.google.com/android/repository/commandlinetools-linux-${ANDROID_SDK_TOOLS}_latest.zip
  - unzip -q android-sdk.zip
  - mkdir -p $ANDROID_SDK_ROOT/cmdline-tools
  - mv cmdline-tools/* $ANDROID_SDK_ROOT/cmdline-tools/
  - export PATH=$PATH:$ANDROID_SDK_ROOT/cmdline-tools/tools/bin
  - set +o pipefail
  - yes | sdkmanager --licenses
  - set -o pipefail
  - sdkmanager "platform-tools" "platforms;android-${ANDROID_COMPILE_SDK}"
  - sdkmanager "build-tools;${ANDROID_BUILD_TOOLS}"
  - export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools/
  - chmod +x ./gradlew

Main improvements include: explicitly setting ANDROID_SDK_ROOT, correctly building directory structure, simplifying command invocation (no need to specify --sdk_root parameter), and optimizing the license acceptance process.

Alternative Solutions and Compatibility Considerations

Although using the --sdk_root parameter can serve as a temporary solution, this is not a fundamental fix. This parameter forcibly specifies the SDK root directory, bypassing the tool's built-in directory validation logic.

It's worth noting that executing sdkmanager --sdk_root=${ANDROID_HOME} "tools" might upgrade the tools from 3.6.0 to 26.1.1, temporarily resolving compatibility issues. However, this approach requires additional download time and bandwidth, and is not a sustainable solution.

In the long term, following the officially recommended directory structure configuration is the best practice, ensuring compatibility with future versions of the tool and reducing maintenance costs.

Conclusion

The directory structure changes in Android command-line tools represent significant developments in development environment configuration. Understanding and correctly implementing the new directory structure requirements is key to resolving the Warning: Could not create settings error. By following the configuration steps described in this article, developers can establish stable and reliable Android development environments that support continuous integration and automated build processes.

As Android development tools continue to evolve, maintaining awareness of official documentation and best practices will help promptly adapt to future changes, improving development efficiency and quality.