Skip to content

Latest commit

 

History

History
203 lines (169 loc) · 7.53 KB

README.md

File metadata and controls

203 lines (169 loc) · 7.53 KB

DevBricksX CLI (devbricksx)

A command-line interface tool written in Kotlin to quickly create and bootstrap new Android projects utilizing the DevBricksX libraries and architectural components.

Features

  • Project Generation: Scaffold a multi-module Android project ready for development using DevBricksX.
  • Template-Based: Bundles the official DevBricksX Android template inside the CLI distribution.
  • Developer-Friendly Template: The template project inside template/ is an actual, testable Android project aligned with the root devbricksx-android project configuration (Gradle wrapper 9.7, AGP 9.3, Kotlin 2.3.10, SDK 37, JDK 21). You can open and test it directly in Android Studio.
  • Flexible UI Targets:
    • compose (default): Jetpack Compose only (app-compose and core).
    • views: Android Views (XML) only (app and core).
    • all: Scaffolds both Android Views (XML) and Jetpack Compose app modules.
  • Modular Components:
    • Optional ndk extra module (core-native module with CMake and JNI glue).
  • Theme & Branding:
    • Customize application theme primary color (--theme-color).
    • Automatic package renaming and source code alignment.
  • Full Icon Generation (SVG & PNG):
    • SVG Icons: Automatically converts SVG files to Android Vector Drawables (ic_launcher_foreground.xml) centered and scaled in 108dp canvas, renders crisp 512x512 composites for Play Store, and generates all legacy/round mipmap PNG assets.
    • PNG Icons: Supports transparent PNG logos (composited over the theme background) and opaque icons, generating adaptive foregrounds, Play Store 512x512 icons, and all mipmap densities.
    • Fully self-contained without external dependencies (magick, rsvg-convert, etc.).

Installation

Quick Install

Run the installer script from the root repository or inside devbricksx-cli:

# From root repository:
./install-cli.sh

# Or from devbricksx-cli directory:
cd devbricksx-cli
./install.sh

The installer will:

  1. Check Java Environment: DevBricksX CLI requires Java 21 or higher. The installer checks your local Java runtime (JAVA_HOME or PATH).
  2. Download Dedicated JRE If Needed: If no compatible Java 21+ is found on your PC, the installer automatically downloads Eclipse Adoptium Temurin JRE 21 for your OS and architecture into ~/.devbricksx/jre, ensuring the CLI always has its required JRE. You can also force a dedicated JRE with --download-jre.
  3. Install Binary & Libraries: Deploys devbricksx binary into ~/.devbricksx/bin and libraries into ~/.devbricksx/lib.
  4. Configure Shell Auto-Completion: Automatically configures tab auto-completion for your shell (zsh, bash, fish) and adds ~/.devbricksx/bin to your PATH in ~/.zshrc / ~/.bashrc.

Installer Options

./install.sh [options]

Options:
  -d, --prefix <dir>       Installation target directory (default: ~/.devbricksx)
      --download-jre       Force download and bundle a dedicated Java 21 JRE
      --no-completion      Skip modifying shell profile for auto-completion
  -s, --shell <shell>      Specify target shell for completions (zsh, bash, fish)
  -h, --help               Show installer options
      --uninstall          Remove DevBricksX CLI from ~/.devbricksx

Manual Shell Auto-Completion

If you prefer manual shell completion configuration:

  • Zsh:
    # In ~/.zshrc
    export PATH="$HOME/.devbricksx/bin:$PATH"
    source <(devbricksx completion zsh)
  • Bash:
    # In ~/.bashrc
    export PATH="$HOME/.devbricksx/bin:$PATH"
    source <(devbricksx completion bash)
  • Fish:
    devbricksx completion fish > ~/.config/fish/completions/devbricksx.fish

Build Distribution Manually

cd devbricksx-cli
./gradlew installDist

The executable binary will be generated at build/install/devbricksx/bin/devbricksx.

Run via Gradle

./gradlew run --args="--help"

Usage

Display Help

devbricksx --help

Output:

Usage: devbricksx [<options>] <command> [<args>]...

  DevBricksX CLI - Command-line tool for creating and managing Android projects
  with DevBricksX.

Options:
  --version   Show the version and exit
  -h, --help  Show this message and exit

Commands:
  create  Create a new Android project using DevBricksX template.
  studio  Manage and interact with Android Studio.

Create a Project (create)

devbricksx create --help

Arguments:

  • <dir>: Output directory for the generated project (default: ./<appName>). Supports tab key auto-completion.

Options:

  • -n, --name <text>: Application name (e.g. "My Application"). Required.
  • -p, --package <text>: Android package name (e.g. "com.example.myapp"). Required.
  • -u, --ui <text>: UI target: compose, views, all (default: compose).
  • -e, --extra-modules <text>: Extra modules to include, comma-separated (e.g. ndk).
  • -t, --theme-color <text>: Primary theme color hex (e.g. #008577 or #3F51B5).
  • -i, --icon <text>: Path to custom app icon file (.svg or .png).
  • --icon-fg-color <text>: Color tint for icon foreground (hex, e.g. #FFFFFF, or none to preserve original colors). Defaults to #FFFFFF for SVG icons.
  • --icon-scale <int>: Foreground scale percentage in icon composition (1-100, default: 70).
  • -h, --help: Show command help.

Examples

  1. Create project with SVG icon:
devbricksx create ./MyApp \
  -n "My App" \
  -p "com.example.myapp" \
  -u compose \
  -t "#008577" \
  -i /path/to/icon.svg
  1. Create full project with PNG icon and NDK module:
devbricksx create ./MyApp \
  -n "My App" \
  -p "com.example.myapp" \
  -u all \
  -e ndk \
  -t "#3F51B5" \
  -i /path/to/icon.png
  1. Create Views (XML)-only project in default directory (./ViewsApp):
devbricksx create -n "Views App" -p "com.example.viewsapp" -u views

Open a Project in Android Studio (studio open)

devbricksx studio open --help

Opens an Android project directory using Android Studio. By default, it automatically discovers Android Studio in common installation directories across macOS, Linux, and Windows (including JetBrains Toolbox, Spotlight, snap, flatpak, and standard application directories). You can also explicitly specify the Android Studio path using --android-studio <path>.

Options:

  • -s, --studio, --android-studio <path>: Path to Android Studio application bundle, installation directory, or executable.
  • -h, --help: Show command help.

Arguments:

  • <project_dir>: Path to the Android project directory (default: current directory .).

Examples

  1. Open current directory in Android Studio:
devbricksx studio open
# or
devbricksx studio open .
  1. Open a specific project directory:
devbricksx studio open ./MyApp
# or
devbricksx studio open /path/to/android/project
  1. Open with a specific Android Studio installation:
# On macOS:
devbricksx studio open ./MyApp --android-studio "/Applications/Android Studio Preview.app"

# On Linux:
devbricksx studio open ./MyApp --android-studio /opt/android-studio/bin/studio.sh

# On Windows:
devbricksx studio open ./MyApp --android-studio "C:\Program Files\Android\Android Studio\bin\studio64.exe"

Template Project

The template project is located in template/. You can open and test it independently:

cd devbricksx-cli/template
./gradlew assembleDebug

When building the CLI, the packageTemplate task packages the clean template project into a resource ZIP (template.zip) which is bundled into the CLI binary.