GiantCroissant.Lunar.Build.Mobile.Android 0.1.1-ci.90

RFC020: Android Build Integration

Complete Android build support with Gradle integration, signing, and deployment capabilities

Overview

The RFC020 Android Build Integration provides comprehensive Android build support following RFC018 Build Component Specification patterns. This component enables:

• 🤖 Gradle Build Integration - Full Android Gradle project support
• 🔐 Secure Signing Configuration - Environment-based keystore management
• 📦 AAB & APK Support - Android App Bundle and APK build variants
• 🧪 Testing Integration - Unit and instrumentation test execution
• 🚀 Deployment Automation - Google Play Console and Firebase App Distribution
• 🔍 Environment Validation - Comprehensive Android SDK and toolchain validation

Quick Start

1. Environment Setup

# Set required environment variables
export ANDROID_SDK_ROOT="/path/to/android-sdk"
export JAVA_HOME="/path/to/java-jdk-11"
export ANDROID_KEYSTORE_PASSWORD="your-keystore-password"
export ANDROID_KEY_ALIAS="your-key-alias"
export ANDROID_KEY_PASSWORD="your-key-password"

2. Build Configuration

Add to your build-config.json:

{
  "projectGroups": [
    {
      "name": "android-builds",
      "buildType": "android-mobile",
      "sourceDirectory": "android",
      "outputs": [
        {
          "type": "android-apk",
          "directory": "build/outputs/apk",
          "destinations": ["artifacts", "firebase"]
        },
        {
          "type": "android-aab",
          "directory": "build/outputs/bundle",
          "destinations": ["artifacts", "playstore"]
        }
      ],
      "configuration": {
        "android": {
          "enabled": true,
          "gradlePath": "gradlew",
          "projectPath": "./android",
          "buildTypes": ["debug", "release", "staging"],
          "productFlavors": ["demo", "full"],
          "defaultBuildVariant": "demoDebug",
          "targetSdkVersion": 33,
          "minSdkVersion": 21,
          "compileSdkVersion": 33,
          "buildToolsVersion": "33.0.0"
        }
      }
    }
  ]
}

3. NUKE Build Integration

Use RFC020 targets in your build script:

// Build Android components
Target BuildAndroid => _ => _
    .DependsOn(RFC020BuildAndroidCore)
    .Executes(() =>
    {
        // Your custom Android build logic
    });

// Full Android integration
Target AndroidComplete => _ => _
    .DependsOn(RFC020AndroidBuildIntegration)
    .Executes(() =>
    {
        Serilog.Log.Information("🎉 Android build system ready!");
    });

Component Architecture

RFC018 Compliance

The Android build component implements the RFC018 Build Component Specification:

[BuildComponent("android")]
public class AndroidBuildComponent : IMobileBuildComponent
{
    // RFC018 Lifecycle Implementation
    public async Task<ComponentDiscoveryResult> DiscoverAsync(ComponentDiscoveryContext context)
    public async Task<ComponentInitializationResult> InitializeAsync(ComponentInitializationContext context)
    public async Task<ComponentConfigurationResult> ConfigureAsync(ComponentConfigurationContext context)
    public async Task<ComponentValidationResult> ValidateAsync(ComponentValidationContext context)

    // Mobile Build Implementation
    public async Task<MobileBuildResult> BuildAsync(MobileBuildContext context)
    public async Task<MobileTestResult> TestAsync(MobileTestContext context)
    public async Task<MobileDeployResult> DeployAsync(MobileDeployContext context)
    public async Task<MobileValidationResult> ValidateEnvironmentAsync(MobileValidationContext context)
}

Build Context Types

AndroidBuildContext - Build configuration:

var buildContext = new AndroidBuildContext
{
    BuildVariant = "release",
    GradlePath = "gradlew",
    GradleProjectPath = "./android",
    BuildBundle = true, // Generate AAB instead of APK
    TargetSdkVersion = 33,
    MinSdkVersion = 21,
    SigningConfig = new AndroidSigningConfig
    {
        KeystorePath = "path/to/keystore.jks",
        KeystorePassword = Environment.GetEnvironmentVariable("KEYSTORE_PASSWORD"),
        KeyAlias = Environment.GetEnvironmentVariable("KEY_ALIAS"),
        KeyPassword = Environment.GetEnvironmentVariable("KEY_PASSWORD")
    }
};

AndroidTestContext - Test configuration:

var testContext = new AndroidTestContext
{
    RunUnitTests = true,
    RunInstrumentationTests = true,
    AndroidDevice = "emulator-5554",
    ApiLevel = 33,
    TestRunner = "androidx.test.runner.AndroidJUnitRunner"
};

AndroidDeployContext - Deployment configuration:

var deployContext = new AndroidDeployContext
{
    UploadToPlayStore = true,
    ServiceAccountKeyFile = "path/to/service-account.json",
    PlayStoreTrack = "internal",
    UploadToFirebase = true,
    FirebaseConfig = new FirebaseDistributionConfig
    {
        AppId = "1:123456789:android:abc123",
        ServiceAccountKeyFile = "path/to/firebase-service-account.json",
        ReleaseNotes = "New release with exciting features!"
    }
};

Build Targets

Core Targets

Testing Targets

Integration Targets

Environment Validation

The component performs comprehensive environment validation:

Required Components

• ✅ Android SDK - ANDROID_SDK_ROOT or ANDROID_HOME
• ✅ Java JDK 11+ - JAVA_HOME with JDK 11, 17, or 21
• ✅ Gradle Wrapper - gradlew or gradlew.bat in project directory
• 🔧 Fastlane Gem - For build automation (optional but recommended)

Validation Command

cd build/nuke
./build.ps1 RFC020ValidateAndroidEnvironment

Expected output:

🔍 RFC020: Validating Android development environment...
📋 Android Environment Validation Results:
  ✅ AndroidSDK
  ✅ JavaJDK
  ✅ GradleWrapper
  ✅ FastlaneGem
🎉 Android development environment fully configured

Signing Configuration

Development Signing (Debug)

Automatically configured for development builds:

// app/build.gradle
android {
    signingConfigs {
        debug {
            storeFile file('debug.keystore')
            storePassword 'android'
            keyAlias 'androiddebugkey'
            keyPassword 'android'
        }
    }
}

Production Signing (Release)

Environment-based release signing:

// app/build.gradle
android {
    signingConfigs {
        release {
            storeFile file(System.getenv('ANDROID_KEYSTORE_PATH'))
            storePassword System.getenv('ANDROID_KEYSTORE_PASSWORD')
            keyAlias System.getenv('ANDROID_KEY_ALIAS')
            keyPassword System.getenv('ANDROID_KEY_PASSWORD')
        }
    }
    
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

Signing Environment Variables

# Required for release builds
export ANDROID_KEYSTORE_PATH="/secure/path/to/release.keystore"
export ANDROID_KEYSTORE_PASSWORD="your-secure-keystore-password"
export ANDROID_KEY_ALIAS="your-release-key-alias"
export ANDROID_KEY_PASSWORD="your-secure-key-password"

Fastlane Integration

Available Lanes

Build Lanes:

• fastlane android build - Build Android APK or AAB
• fastlane android configure_signing - Setup signing configuration

Testing Lanes:

• fastlane android unit_test - Run unit tests
• fastlane android instrumentation_test - Run instrumentation tests

Deployment Lanes:

• fastlane android deploy_play_store - Deploy to Google Play Console
• fastlane android deploy_firebase - Deploy to Firebase App Distribution

Validation Lanes:

• fastlane android validate_environment - Validate build environment

Example Fastlane Usage

# Build release AAB with signing
fastlane android build \
  project_path:"./android" \
  build_variant:"release" \
  bundle_enabled:"true" \
  keystore_path:"release.keystore" \
  output_path:"build/outputs"

# Deploy to Play Store internal track
fastlane android deploy_play_store \
  service_account_key:"service-account.json" \
  artifact_path:"app-release.aab" \
  track:"internal"

# Deploy to Firebase App Distribution
fastlane android deploy_firebase \
  app_id:"1:123456789:android:abc123" \
  service_account_key:"firebase-service-account.json" \
  artifact_path:"app-debug.apk" \
  testers:"test@example.com,test2@example.com" \
  release_notes:"Beta release for testing"

Build Variants and Flavors

Standard Build Types

• debug - Development builds with debug symbols
• release - Production builds with ProGuard/R8 optimization
• staging - Pre-production builds with staging configuration

Product Flavors

Configure in build-config.json:

{
  "android": {
    "productFlavors": ["demo", "full", "enterprise"],
    "buildTypes": ["debug", "release", "staging"],
    "defaultBuildVariant": "demoDebug"
  }
}

Resulting build variants:

• demoDebug, demoRelease, demoStaging
• fullDebug, fullRelease, fullStaging
• enterpriseDebug, enterpriseRelease, enterpriseStaging

Advanced Features

Android App Bundle (AAB) Support

Enable AAB builds for Google Play Console:

var buildContext = new AndroidBuildContext
{
    BuildVariant = "release",
    BuildBundle = true, // Generate .aab instead of .apk
    // ... other configuration
};

Version Management

Automatic version code and version name management:

# Via NUKE build parameters
./build.ps1 RFC020AndroidBuildIntegration \
  --android-version-code 42 \
  --android-version-name "2.1.0"

# Via Fastlane parameters
fastlane android build \
  version_code:42 \
  version_name:"2.1.0"

ProGuard/R8 Optimization

Configure obfuscation in build context:

var buildContext = new AndroidBuildContext
{
    ObfuscationConfig = new AndroidObfuscationConfig
    {
        Enabled = true,
        EnableMinification = true,
        ShrinkResources = true,
        OptimizationLevel = 2,
        ConfigFiles = new List<string> { "proguard-rules.pro" }
    }
};

CI/CD Integration

GitHub Actions Workflow

The component includes a comprehensive GitHub Actions workflow:

# .github/workflows/rfc020-android-integration.yml
name: RFC020 Android Build Integration
on:
  push:
    branches: [ feature/rfc020-android-build-integration, main ]

jobs:
  build-android-components:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '11'
      - uses: android-actions/setup-android@v3
      - name: Build Android
        run: ./build.ps1 RFC020AndroidBuildIntegration

Required Secrets

Configure in your CI/CD environment:

# GitHub Secrets
ANDROID_KEYSTORE_PASSWORD=your-keystore-password
ANDROID_KEY_ALIAS=your-key-alias  
ANDROID_KEY_PASSWORD=your-key-password
GOOGLE_PLAY_SERVICE_ACCOUNT_KEY=base64-encoded-service-account.json
FIREBASE_SERVICE_ACCOUNT_KEY=base64-encoded-firebase-service-account.json

Troubleshooting

Common Issues

Android SDK Not Found:

# Set the correct Android SDK path
export ANDROID_SDK_ROOT="/Users/username/Library/Android/sdk"
# or
export ANDROID_HOME="/Users/username/Library/Android/sdk"

Gradle Build Failed:

# Clean and rebuild
cd android
./gradlew clean
./gradlew assembleDebug --stacktrace

Signing Configuration Issues:

# Verify keystore file exists and passwords are correct
keytool -list -v -keystore path/to/keystore.jks

Fastlane Lane Failures:

# Run with verbose logging
fastlane android build --verbose

Debug Mode

Enable detailed logging:

# NUKE build with debug logging
./build.ps1 RFC020AndroidBuildIntegration --verbosity diagnostic

# Fastlane with debug mode
export FASTLANE_VERBOSE=1
fastlane android build

Examples and Samples

The RFC020 implementation includes sample projects:

• Unity Android Game - Unity project with Android build integration
• Gradle Android App - Pure Android Gradle application
• Multi-Variant App - Application with multiple build variants and flavors

Sample projects are available in:

samples/android-builds/
├── unity-android-game/
├── gradle-android-app/
└── multi-variant-app/

Component Testing

Unit Tests

Run Android component unit tests:

cd build/nuke
./build.ps1 RFC020RunAndroidTests

Integration Tests

Test full Android build integration:

cd build/nuke
./build.ps1 RFC020AndroidBuildIntegration --test-mode

Validation Tests

Validate environment and configuration:

cd build/nuke
./build.ps1 RFC020ValidateAndroidCI

Performance Optimization

Build Performance

• Gradle Daemon - Enabled by default for faster builds
• Parallel Builds - Configure org.gradle.parallel=true
• Build Cache - Enable Gradle build cache
• Incremental Compilation - Automatic incremental builds

Resource Optimization

// app/build.gradle - Optimize resources
android {
    buildTypes {
        release {
            shrinkResources true
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
        }
    }
}

Contributing

Development Setup

1. Clone the repository
2. Setup Android development environment
3. Install dependencies: dotnet restore
4. Run tests: ./build.ps1 RFC020RunAndroidTests

Extending the Component

Follow RFC018 patterns for component extensions:

[BuildComponent("android-custom")]
public class CustomAndroidComponent : AndroidBuildComponent
{
    // Custom Android build logic
}

Support and Documentation

• RFC020 Documentation: /docs/architecture/RFC020-ANDROID-BUILD-INTEGRATION.md
• Component API Reference: Auto-generated from code documentation
• Build Guides: Step-by-step Android build setup guides
• Troubleshooting Guide: Common issues and solutions

License

Copyright © 2025 GiantCroissant. All rights reserved.

RFC020: Android Build Integration - Complete Android build support with enterprise-grade automation, security, and deployment capabilities.