RedBoxVM Build Guide

This comprehensive guide covers building RedBoxVM from source, including development environment setup, compilation process, and deployment procedures.

Development Environment Setup

Required Tools and Dependencies

Environment Setup Steps

Environment Variables

# Add to ~/.bashrc or ~/.zshrc (Linux/macOS)
export ANDROID_HOME=$HOME/Android/Sdk
export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/29.0.13846066
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

# Windows (PowerShell)
$env:ANDROID_HOME = "C:\Users\$env:USERNAME\AppData\Local\Android\Sdk"
$env:ANDROID_NDK_HOME = "$env:ANDROID_HOME\ndk\29.0.13846066"
$env:JAVA_HOME = "C:\Program Files\Java\jdk-17"

Project Structure

Understanding the RedBoxVM project structure is essential for successful building:

RedBoxVM/
├── app/                          # Main Android application
│   ├── src/main/
│   │   ├── java/com/redbox/      # Java source code
│   │   ├── res/                  # Android resources
│   │   └── AndroidManifest.xml   # App manifest
│   └── build.gradle              # App build configuration
├── Core/                        # Core virtualization library
│   ├── src/main/
│   │   ├── aidl/                 # AIDL interfaces
│   │   ├── assets/               # Runtime assets
│   │   ├── cpp/                  # Native C++ code
│   │   │   ├── Dobby/            # Hook framework
│   │   │   ├── Hook/             # System hooks
│   │   │   ├── JniHook/          # JNI bridge
│   │   │   └── Utils/            # Utilities
│   │   ├── java/                 # Java wrapper code
│   │   └── res/                  # Library resources
│   ├── CMakeLists.txt            # Native build configuration
│   └── build.gradle              # Library build configuration
├── build.gradle                  # Root build configuration
├── settings.gradle               # Project settings
├── gradle.properties             # Build properties
└── gradle/                       # Gradle wrapper

Build Process Overview

The RedBoxVM build process involves multiple stages:

Building from Source

Step 1: Clone Repository

# Clone the repository
git clone https://github.com/TheRedXStudio/RedBoxVM.git
cd RedBoxVM

# Initialize submodules
git submodule update --init --recursive

Step 2: Configure Build

Edit gradle.properties to configure build settings:

# Build configuration
android.useAndroidX=true
android.enableJetifier=true

# Performance optimizations
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=512m
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configureondemand=true

# NDK configuration
android.ndkVersion=29.0.13846066
android.ndkPath=/path/to/ndk

# Signing configuration (for release builds)
RELEASE_STORE_FILE=release.keystore
RELEASE_STORE_PASSWORD=your_password
RELEASE_KEY_ALIAS=redboxvm
RELEASE_KEY_PASSWORD=your_password

Step 3: Build Commands

# Clean build
./gradlew clean

# Debug build
./gradlew assembleDebug

# Release build
./gradlew assembleRelease

# Build specific module
./gradlew :Core:assembleRelease

# Run tests
./gradlew test

# Install debug APK
./gradlew installDebug

Native Code Compilation

CMake Configuration

The native components use CMake for cross-platform building:

# Core/CMakeLists.txt
cmake_minimum_required(VERSION 3.22.1)
project(redboxvm-native)

# Set C++ standard
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Architecture-specific optimizations
if(${ANDROID_ABI} STREQUAL "arm64-v8a")
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O3 -ffast-math")
elseif(${ANDROID_ABI} STREQUAL "armeabi-v7a")
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -O2 -mfpu=neon")
endif()

# Source files
file(GLOB_RECURSE NATIVE_SOURCES
    "src/main/cpp/*.cpp"
    "src/main/cpp/*.c"
)

# Create shared library
add_library(redboxvm-native SHARED ${NATIVE_SOURCES})

# Link libraries
target_link_libraries(redboxvm-native
    android
    log
    dl
)

# Include directories
target_include_directories(redboxvm-native PRIVATE
    src/main/cpp/include
    src/main/cpp/Dobby/include
)

Architecture Support

Build Variants and Flavors

Build Types

android {
    buildTypes {
        debug {
            debuggable true
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
            buildConfigField "boolean", "DEBUG_MODE", "true"
            ndk {
                debugSymbolLevel 'FULL'
            }
        }
        
        release {
            debuggable false
            minifyEnabled false  // Disabled for BlackReflection compatibility
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            buildConfigField "boolean", "DEBUG_MODE", "false"
            ndk {
                debugSymbolLevel 'SYMBOL_TABLE'
            }
        }
        
        benchmark {
            initWith release
            debuggable false
            signingConfig signingConfigs.debug
            buildConfigField "boolean", "BENCHMARK_MODE", "true"
        }
    }
}

Product Flavors

android {
    flavorDimensions "version", "architecture"
    
    productFlavors {
        free {
            dimension "version"
            applicationIdSuffix ".free"
            buildConfigField "boolean", "IS_PRO_VERSION", "false"
        }
        
        pro {
            dimension "version"
            applicationIdSuffix ".pro"
            buildConfigField "boolean", "IS_PRO_VERSION", "true"
        }
        
        universal {
            dimension "architecture"
            ndk {
                abiFilters 'arm64-v8a', 'armeabi-v7a'
            }
        }
        
        arm64 {
            dimension "architecture"
            ndk {
                abiFilters 'arm64-v8a'
            }
        }
    }
}

Testing and Quality Assurance

Test Types

Running Tests

# Run all tests
./gradlew test

# Run unit tests only
./gradlew testDebugUnitTest

# Run instrumented tests
./gradlew connectedAndroidTest

# Run native tests
./gradlew :Core:testDebugUnitTest

# Generate test coverage report
./gradlew jacocoTestReport

# Run lint checks
./gradlew lint

# Run security analysis
./gradlew dependencyCheckAnalyze

Continuous Integration

GitHub Actions Workflow

# .github/workflows/build.yml
name: Build and Test

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v4
      with:
        submodules: recursive
    
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
    
    - name: Setup Android SDK
      uses: android-actions/setup-android@v2
    
    - name: Cache Gradle packages
      uses: actions/cache@v3
      with:
        path: |
          ~/.gradle/caches
          ~/.gradle/wrapper
        key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
    
    - name: Grant execute permission for gradlew
      run: chmod +x gradlew
    
    - name: Build with Gradle
      run: ./gradlew assembleDebug
    
    - name: Run tests
      run: ./gradlew test
    
    - name: Upload APK
      uses: actions/upload-artifact@v3
      with:
        name: debug-apk
        path: app/build/outputs/apk/debug/*.apk

Deployment and Distribution

Release Process

APK Signing

# Generate release keystore
keytool -genkey -v -keystore release.keystore -alias redboxvm -keyalg RSA -keysize 2048 -validity 10000

# Sign APK manually
jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 -keystore release.keystore app-release-unsigned.apk redboxvm

# Align APK
zipalign -v 4 app-release-unsigned.apk RedBoxVM-release.apk

Troubleshooting Build Issues

Common Problems and Solutions

Debug Build Issues

# Enable verbose logging
./gradlew assembleDebug --info --stacktrace

# Clean and rebuild
./gradlew clean build

# Check dependency tree
./gradlew :app:dependencies

# Verify NDK installation
./gradlew :Core:externalNativeBuildDebug --info