From b2ad27faf40527b26d92cfefbc5f0eeff48f8b60 Mon Sep 17 00:00:00 2001 From: Andrea Bueide Date: Wed, 18 Feb 2026 15:58:40 -0600 Subject: [PATCH 01/86] doc updates --- CLAUDE.md | 73 +++--- README.md | 65 +++--- plugins/devbox-mcp/README.md | 4 - plugins/devbox-mcp/package.json | 1 - wiki/README.md | 2 +- wiki/guides/android-guide.md | 245 ++++++++------------ wiki/guides/cheatsheets/android.md | 41 ++-- wiki/guides/cheatsheets/ios.md | 31 +-- wiki/guides/cheatsheets/react-native.md | 101 ++++---- wiki/guides/device-management.md | 143 ++++++------ wiki/guides/ios-guide.md | 196 ++++++++-------- wiki/guides/quick-start.md | 293 +++++++++++++++++------- wiki/guides/react-native-guide.md | 83 ++++--- wiki/guides/testing.md | 22 +- wiki/project/ARCHITECTURE.md | 8 +- wiki/project/CI-CD.md | 75 +++--- wiki/project/CONTRIBUTING.md | 7 +- wiki/project/TESTING.md | 26 +-- wiki/reference/android.md | 8 +- wiki/reference/cli-commands.md | 144 ++++++------ wiki/reference/configuration.md | 29 +-- wiki/reference/ios.md | 36 +-- wiki/reference/react-native.md | 38 ++- 23 files changed, 840 insertions(+), 831 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 224f7b6..a466c26 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -169,15 +169,17 @@ log_file="/tmp/test.log" # WRONG - may be cleaned up by system Three main plugins are located in `plugins/`: 1. **android** - Android SDK + emulator management via Nix flake - - SDK flake: `devbox.d/android/flake.nix` - - Device definitions: `devbox.d/android/devices/*.json` + - SDK flake: `devbox.d//flake.nix` + - Device definitions: `devbox.d//devices/*.json` - Scripts: `.devbox/virtenv/android/scripts/` - Configuration: Environment variables in `plugin.json` + - Note: `` is `android` for local includes, but for GitHub includes it uses the full path (e.g., `segment-integrations.devbox-plugins.android`) 2. **ios** - iOS toolchain + simulator management for macOS - - Device definitions: `devbox.d/ios/devices/*.json` + - Device definitions: `devbox.d//devices/*.json` - Scripts: `.devbox/virtenv/ios/scripts/` - Configuration: Environment variables in `plugin.json` + - Note: `` is `ios` for local includes, but for GitHub includes it uses the full path (e.g., `segment-integrations.devbox-plugins.ios`) 3. **react-native** - Composition layer over Android + iOS plugins - Inherits both Android and iOS device management @@ -185,7 +187,7 @@ Three main plugins are located in `plugins/`: ### Key Concepts -**Device Definitions**: JSON files defining emulator/simulator configurations +**Device Definitions**: JSON files defining emulator/simulator configurations stored in `devbox.d//devices/`. The actual directory name for `` depends on how the plugin is included: for local includes (e.g., `plugin:../plugins/android`) it matches the plugin name (e.g., `android`), but for GitHub includes it uses the full dotted path (e.g., `segment-integrations.devbox-plugins.android`). - Android: `{name, api, device, tag, preferred_abi}` - iOS: `{name, runtime}` - Default devices: `min.json` and `max.json` @@ -360,34 +362,34 @@ devbox run --pure ios.sh config show ```bash cd examples/android -# Build the app -devbox run --pure build-android +# Build the app (user-defined in example devbox.json) +devbox run --pure build:android -# Start emulator -devbox run --pure start-emu [device] # Defaults to ANDROID_DEFAULT_DEVICE +# Start emulator (plugin-provided) +devbox run --pure start:emu [device] # Defaults to ANDROID_DEFAULT_DEVICE -# Build, install, and launch app on emulator -devbox run --pure start-app [device] +# Build, install, and launch app on emulator (user-defined in example devbox.json) +devbox run --pure start:app [device] -# Stop emulator -devbox run --pure stop-emu +# Stop emulator (plugin-provided) +devbox run --pure stop:emu ``` #### iOS ```bash cd examples/ios -# Build the app -devbox run --pure build-ios +# Build the app (user-defined in example devbox.json) +devbox run --pure build:ios -# Start simulator -devbox run --pure start-sim [device] # Defaults to IOS_DEFAULT_DEVICE +# Start simulator (plugin-provided) +devbox run --pure start:sim [device] # Defaults to IOS_DEFAULT_DEVICE -# Build, install, and launch app on simulator -devbox run --pure start-ios [device] +# Build, install, and launch app on simulator (user-defined in example devbox.json) +devbox run --pure start:ios [device] -# Stop simulator -devbox run --pure stop-sim +# Stop simulator (plugin-provided) +devbox run --pure stop:sim ``` #### React Native @@ -398,17 +400,17 @@ cd examples/react-native npm install # Android workflow -devbox run --pure start-emu [device] -devbox run --pure start-app [device] -devbox run --pure stop-emu +devbox run --pure start:emu [device] # plugin-provided +devbox run --pure start:app [device] # user-defined +devbox run --pure stop:emu # plugin-provided # iOS workflow -devbox run --pure start-sim [device] -devbox run --pure start-ios [device] -devbox run --pure stop-sim +devbox run --pure start:sim [device] # plugin-provided +devbox run --pure start:ios [device] # user-defined +devbox run --pure stop:sim # plugin-provided -# Build for all platforms -devbox run build # Runs build-android, build-ios, build-web +# Build for all platforms (user-defined) +devbox run build # Runs build:android, build:ios, build:web ``` ### Testing @@ -468,8 +470,8 @@ act -j ios-plugin-tests │ ├── e2e-sequential.sh │ └── e2e-all.sh ├── .github/workflows/ -│ ├── pr-checks.yml # Fast PR validation (~15-30 min) -│ └── e2e-full.yml # Full E2E tests (~45-60 min per platform) +│ ├── pr-checks.yml # Fast PR validation +│ └── e2e-full.yml # Full E2E tests └── devbox.json # Root devbox config ``` @@ -513,7 +515,7 @@ See `wiki/project/ARCHITECTURE.md` for complete documentation. ### Device Management Workflow -1. Device definitions are JSON files in `devbox.d/{platform}/devices/` +1. Device definitions are JSON files in `devbox.d//devices/` (where `` depends on the include method; see Plugin System above) 2. Modify devices using CLI commands (not manual editing) 3. After changes, regenerate lock file: `{platform}.sh devices eval` 4. Lock files should be committed to optimize CI @@ -702,12 +704,15 @@ plugins/{platform}/ ``` examples/{platform}/ ├── devbox.d/ -│ └── {platform}/ +│ └── / # Directory name depends on include method │ └── devices/ # User device definitions │ ├── *.json │ └── devices.lock ├── devbox.json # Includes plugin └── README.md # Usage guide +# Note: is "{platform}" for local includes (plugin:../plugins/{platform}), +# but for GitHub includes it uses the full dotted path +# (e.g., "segment-integrations.devbox-plugins.android"). ``` **Test Directory Layout:** @@ -782,7 +787,6 @@ Examples: ### Fast PR Checks (`pr-checks.yml`) - Runs automatically on every PR - Plugin validation and quick smoke tests -- ~15-30 minutes total - Tests default devices only ### Full E2E Tests (`e2e-full.yml`) @@ -790,7 +794,6 @@ Examples: - Tests min/max platform versions: - Android: API 21 (min) to API 36 (max) - iOS: iOS 15.4 (min) to iOS 26.2 (max) -- ~45-60 minutes per platform - Matrix execution for parallel testing ### Running CI Locally @@ -831,7 +834,7 @@ Configuration for both Android and iOS plugins is now managed via environment va ## Important Implementation Notes ### Android SDK via Nix Flake -- The Android SDK is composed via Nix flake at `devbox.d/android/flake.nix` +- The Android SDK is composed via Nix flake at `devbox.d//flake.nix` (directory name depends on include method) - Flake outputs: `android-sdk`, `android-sdk-full`, `android-sdk-preview` - Nix handles flake evaluation caching internally (fast after first evaluation) - Lock file limits which API versions are evaluated (optimization for CI) diff --git a/README.md b/README.md index 749ddea..d2f2b79 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,14 @@ Reproducible, project-local development environments for Android, iOS, and React ## Quick Start ```bash +# Install devbox (if you haven't already) +curl -fsSL https://get.jetify.com/devbox | bash + # Initialize devbox in your project devbox init - -# Add the Android plugin include to your devbox.json -# (devbox add only works for packages, not plugins — edit devbox.json manually) ``` -Add the plugin to your `devbox.json`: +Replace the contents of your `devbox.json` with the Android plugin: ```json { @@ -27,18 +27,20 @@ Add the plugin to your `devbox.json`: } ``` +> **Note:** Plugins are added via `include` in `devbox.json`, not with `devbox add`. The plugin provides the Android SDK, emulator, and device management tools. You add your own build tooling (JDK, Gradle) as packages. + ```bash -# Enter development environment +# Enter development environment (downloads SDK on first run) devbox shell -# Start emulator and run app +# List available devices +devbox run android.sh devices list + +# Start the default emulator devbox run start:emu -devbox run start:app ``` -The app's package name is auto-detected from the APK at install time. - -**New to devbox-plugins?** Check out the [Quick Start Guide](wiki/guides/quick-start.md) for detailed setup instructions. +**New to devbox-plugins?** Check out the [Quick Start Guide](wiki/guides/quick-start.md) for a complete walkthrough including how to set up build and deploy scripts. ## Features @@ -94,7 +96,7 @@ Composition layer over Android and iOS with Metro bundler management. ### For Users -- **[Quick Start](wiki/guides/quick-start.md)** - Get started in 5 minutes +- **[Quick Start](wiki/guides/quick-start.md)** - Set up your first project - **[Device Management](wiki/guides/device-management.md)** - Managing emulators and simulators - **[Testing Guide](wiki/guides/testing.md)** - Testing strategies and best practices - **[Troubleshooting](wiki/guides/troubleshooting.md)** - Common issues and solutions @@ -111,34 +113,37 @@ Composition layer over Android and iOS with Metro bundler management. ## Examples -The repository includes example projects demonstrating plugin usage: +The repository includes example projects demonstrating full workflows including build scripts, deploy commands, and E2E test suites: + +- **[examples/android](examples/android/)** - Minimal Android app with Gradle build +- **[examples/ios](examples/ios/)** - Swift package with xcodebuild +- **[examples/react-native](examples/react-native/)** - React Native app with Android, iOS, and Web targets -- **[examples/android](examples/android/)** - Minimal Android app -- **[examples/ios](examples/ios/)** - Swift package example -- **[examples/react-native](examples/react-native/)** - React Native app with Android, iOS, and Web +These examples show how to wire up your own build and deploy scripts on top of the plugin-provided device and emulator management. -Each example includes device definitions, test suites, and build scripts. +## Plugin-Provided Commands -## Common Commands +The plugins provide device management, emulator/simulator control, and diagnostics. Build and deploy commands are project-specific — you define them in your own `devbox.json` (see the [Quick Start Guide](wiki/guides/quick-start.md) or the [examples](examples/) for patterns). ```bash -# Android -devbox run start:emu # Start Android emulator -devbox run start:app # Build, install, and launch app -devbox run stop:emu # Stop emulator +# Android emulator +devbox run start:emu [device] # Start Android emulator +devbox run stop:emu # Stop emulator +devbox run reset:emu # Reset emulator state -# iOS -devbox run start:sim # Start iOS simulator -devbox run start:ios # Build and launch app -devbox run stop:sim # Stop simulator +# iOS simulator +devbox run start:sim [device] # Start iOS simulator +devbox run stop:sim # Stop simulator # Device management devbox run android.sh devices list +devbox run android.sh devices create mydevice --api 30 --device pixel devbox run ios.sh devices list +devbox run ios.sh devices create mydevice --runtime 18.0 -# Testing -devbox run test:fast # Quick tests (~2-5 min) -devbox run test:e2e # Full E2E tests (~15-30 min) +# Diagnostics +devbox run doctor # Check environment health +devbox run verify:setup # Quick verification ``` ## Requirements @@ -147,10 +152,6 @@ devbox run test:e2e # Full E2E tests (~15-30 min) - **macOS** - Required for iOS plugin (Xcode required) - **Linux** - Supported for Android and React Native (Android only) -## License - -MIT - ## Support - **Questions?** Check [Troubleshooting](wiki/guides/troubleshooting.md) diff --git a/plugins/devbox-mcp/README.md b/plugins/devbox-mcp/README.md index be9cc80..b1c2988 100644 --- a/plugins/devbox-mcp/README.md +++ b/plugins/devbox-mcp/README.md @@ -226,7 +226,3 @@ devbox_docs_read({ - Create at: https://github.com/settings/tokens - Requires: `public_repo` or `repo` read access - Configure via `GITHUB_TOKEN` environment variable in MCP config - -## License - -MIT diff --git a/plugins/devbox-mcp/package.json b/plugins/devbox-mcp/package.json index 08c8195..1abd346 100644 --- a/plugins/devbox-mcp/package.json +++ b/plugins/devbox-mcp/package.json @@ -16,7 +16,6 @@ "development-environment" ], "author": "", - "license": "MIT", "repository": { "type": "git", "url": "https://github.com/segment-integrations/devbox-plugins.git", diff --git a/wiki/README.md b/wiki/README.md index 87a95be..92adfe4 100644 --- a/wiki/README.md +++ b/wiki/README.md @@ -15,7 +15,7 @@ Welcome to the devbox-plugins documentation. This wiki provides comprehensive gu Step-by-step tutorials and practical workflows for using the plugins: -- [Quick Start](guides/quick-start.md) - Get started in 5 minutes +- [Quick Start](guides/quick-start.md) - Set up your first project - [Android Guide](guides/android-guide.md) - Complete Android workflow - [iOS Guide](guides/ios-guide.md) - Complete iOS workflow - [React Native Guide](guides/react-native-guide.md) - Complete React Native workflow diff --git a/wiki/guides/android-guide.md b/wiki/guides/android-guide.md index 237510a..0a621cb 100644 --- a/wiki/guides/android-guide.md +++ b/wiki/guides/android-guide.md @@ -6,11 +6,12 @@ A complete guide to Android development using the Devbox Android plugin. This gu The Android plugin enables reproducible Android development without touching global system state. It provides: -- **Project-local Android environment**: All Android user data (AVDs, emulator configs, adb keys) is stored in `.devbox/virtenv/android`, never in `~/.android` +- **Project-local Android environment**: All Android user data (AVDs, emulator configs, adb keys) is stored in `.devbox/virtenv/`, never in `~/.android` - **Reproducible SDK management**: Android SDK composed via Nix flake, ensuring consistent tooling across machines - **Device management**: JSON-based device definitions with CLI commands for creating, updating, and managing AVDs -- **Development scripts**: Runtime scripts for building, running, and debugging Android apps -- **Testing infrastructure**: E2E test suites with process-compose for automated testing +- **Emulator control**: Scripts for starting, stopping, and resetting emulators + +The plugin does **not** provide build or deploy commands. Every project has different build tooling (Gradle, Bazel, custom scripts), so you define those in your own `devbox.json`. See [Adding Build Scripts](#adding-build-and-deploy-scripts) for patterns. Pure shells with `devbox run --pure` guarantee isolated, reproducible execution without side effects. @@ -19,8 +20,8 @@ Pure shells with `devbox run --pure` guarantee isolated, reproducible execution ### Prerequisites - [Devbox](https://www.jetify.com/devbox/docs/installing_devbox/) installed -- Java Development Kit (JDK) - typically JDK 17 or later -- Gradle (for building Android projects) + +Devbox handles downloading JDK, Gradle, and all other tools — you don't need to install them separately. ### Adding the Plugin to Your Project @@ -39,6 +40,8 @@ Create or modify your `devbox.json` to include the Android plugin: } ``` +The `include` line adds the plugin. The `packages` section adds your build tooling. Set `ANDROID_APP_APK` to where your build outputs the APK. + ### Initial Setup Initialize the Devbox environment: @@ -49,8 +52,8 @@ devbox shell This command: 1. Downloads and installs the Android SDK via Nix -2. Creates device definitions in `devbox.d/android/devices/` -3. Sets up runtime scripts in `.devbox/virtenv/android/scripts/` +2. Creates device definitions in your devbox.d directory +3. Sets up runtime scripts 4. Configures environment variables for Android development Verify the installation: @@ -63,14 +66,16 @@ This displays resolved SDK information including SDK root, build tools version, ## Device Management -Device definitions are JSON files stored in `devbox.d/android/devices/`. Each device specifies an Android Virtual Device (AVD) configuration. +Device definitions are JSON files that describe AVD configurations. Each plugin install creates a `devices/` directory inside your `devbox.d/` folder with default device files. ### Default Devices The plugin includes two default devices: -- `min.json` - Minimum supported Android version (API 21) -- `max.json` - Latest Android version (currently API 36) +- `min.json` - Minimum supported Android version (API 21, named `pixel_api21`) +- `max.json` - Latest Android version (API 36, named `medium_phone_api36`) + +The filenames (`min`, `max`) are short nicknames you use in commands. The `name` field inside each JSON file is the full AVD name that appears in device listings. ### Listing Devices @@ -91,14 +96,14 @@ devbox run android.sh devices create pixel_api28 \ --api 28 \ --device pixel \ --tag google_apis \ - --preferred_abi x86_64 + --abi x86_64 ``` Parameters: - `--api` (required): Android API level - `--device` (required): AVD device profile (e.g., `pixel`, `pixel_xl`, `Nexus 5`) - `--tag`: System image tag (`google_apis`, `google_apis_playstore`, `play_store`, `aosp_atd`, `google_atd`) -- `--preferred_abi`: Preferred ABI architecture (`x86_64`, `arm64-v8a`, `x86`) +- `--abi`: Preferred ABI architecture (`x86_64`, `arm64-v8a`, `x86`) ### Viewing Device Details @@ -153,7 +158,7 @@ After creating, updating, or deleting devices, regenerate the lock file: devbox run android.sh devices eval ``` -The lock file (`devbox.d/android/devices.lock`) optimizes CI builds by limiting which SDK versions are downloaded. Commit this file to version control. +The lock file (in your devices directory) optimizes CI builds by limiting which SDK versions are downloaded. Commit this file to version control. ### Syncing AVDs @@ -167,29 +172,6 @@ This creates or updates AVDs to match your JSON device definitions. Run this aft ## Development Workflow -### Building Your App - -Build the Android app using Gradle: - -```bash -# Standard build with info logging -devbox run build - -# Build with full debug output -gradle assembleDebug --debug - -# Clean build artifacts -gradle clean -``` - -Or use Gradle directly: - -```bash -devbox run gradle assembleDebug --info -``` - -The plugin sources the Android environment automatically, setting `ANDROID_SDK_ROOT` and adding SDK tools to PATH. - ### Starting an Emulator Start an Android emulator for testing: @@ -198,7 +180,7 @@ Start an Android emulator for testing: # Start default device devbox run start:emu -# Start specific device +# Start specific device by nickname devbox run start:emu pixel_api28 # Start with clean state (wipe data) @@ -217,50 +199,67 @@ Set the default device in `devbox.json`: } ``` -### Running Your App +### Stopping the Emulator -Build, install, and launch your app on the emulator: +Stop all running emulators: ```bash -# Build and run on default device -devbox run start:app +devbox run stop:emu +``` + +### Resetting Emulator State -# Build and run on specific device -devbox run start:app pixel_api28 +Reset AVD state (clears all data and app installations): -# Install pre-built APK without building -devbox run start:app path/to/app.apk +```bash +devbox run android.sh emulator reset ``` -The `run` command: -1. Builds the app (if no APK path provided) -2. Waits for emulator to be fully booted -3. Installs the APK via adb -4. Launches the app +This is useful after Nix package updates or when you need a clean slate. -### Stopping the Emulator +### Adding Build and Deploy Scripts -Stop all running emulators: +The plugin provides emulator and device management. Build and deploy commands are project-specific, so you define them in your `devbox.json`. Here's a typical setup: -```bash -devbox run stop:emu +```json +{ + "include": ["github:segment-integrations/devbox-plugins?dir=plugins/android"], + "packages": { + "jdk17": "latest", + "gradle": "latest" + }, + "env": { + "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk" + }, + "shell": { + "scripts": { + "build": [ + "gradle assembleDebug --info" + ], + "start:app": [ + "android.sh run ${1:-}" + ] + } + } +} ``` -Or stop the emulator for a specific device: +With these scripts defined, you can: ```bash -devbox run android.sh emulator stop -``` - -### Resetting Emulator State +# Build the APK +devbox run build -Reset AVD state (clears all data and app installations): +# Build, install, and launch on the emulator +devbox run start:app -```bash -devbox run android.sh emulator reset +# Run on a specific device +devbox run start:app min ``` -This is useful after Nix package updates or when you need a clean slate. +The `android.sh run` command waits for the emulator to boot, installs the APK, and launches the app. The app's package name is auto-detected from the APK. + +See the [Android example project](../../examples/android/) for a complete working setup. ### Complete Development Workflow Example @@ -273,7 +272,7 @@ devbox shell # 2. Start emulator devbox run start:emu max -# 3. Build and run app +# 3. Build and run app (using your custom scripts) devbox run build devbox run start:app max @@ -285,33 +284,30 @@ devbox run start:app max devbox run stop:emu ``` -For a streamlined workflow, use the combined command: - -```bash -# Build, install, and launch in one command -devbox run start:app -``` - -This starts the emulator, builds the app, and deploys it automatically. - ## Testing ### Running E2E Tests -The plugin includes E2E test infrastructure using process-compose. Example projects include test suites that: +The [Android example project](../../examples/android/) includes E2E test infrastructure using process-compose. You can use it as a template for your own project. -1. Build the app -2. Sync AVDs with device definitions -3. Start the emulator -4. Deploy and launch the app -5. Verify the app is running -6. Clean up (stop app and emulator in pure mode) - -Run the complete E2E test: +Copy the example test suite: ```bash -cd examples/android -devbox run test:e2e +cp -r examples/android/tests/ your-project/tests/ +``` + +Add a test script to your `devbox.json`: + +```json +{ + "shell": { + "scripts": { + "test:e2e": [ + "process-compose -f tests/test-suite.yaml --no-server --tui=${TEST_TUI:-false}" + ] + } + } +} ``` ### Deterministic Testing @@ -337,32 +333,6 @@ TEST_TUI=true devbox run test:e2e The TUI shows process status, logs, and resource usage during test execution. -### Adding Tests to Your Project - -Copy the example test suite: - -```bash -cp -r examples/android/tests/ your-project/tests/ -``` - -Configure for your app in `devbox.json`: - -```json -{ - "env": { - "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk", - "ANDROID_APP_ID": "com.mycompany.myapp" - }, - "shell": { - "scripts": { - "test:e2e": [ - "process-compose -f tests/test-suite.yaml --no-server --tui=${TEST_TUI:-false}" - ] - } - } -} -``` - ### Test Configuration Customize test behavior with environment variables: @@ -389,7 +359,6 @@ Configure the plugin by setting environment variables in `devbox.json`: "env": { "ANDROID_DEFAULT_DEVICE": "max", "ANDROID_APP_APK": "app/build/outputs/apk/debug/app-debug.apk", - "ANDROID_APP_ID": "com.example.myapp", "ANDROID_BUILD_TOOLS_VERSION": "36.1.0", "ANDROID_COMPILE_SDK": "36", "ANDROID_TARGET_SDK": "36" @@ -400,7 +369,6 @@ Configure the plugin by setting environment variables in `devbox.json`: Key variables: - `ANDROID_DEFAULT_DEVICE` - Default device when none specified - `ANDROID_APP_APK` - Path or glob pattern for APK -- `ANDROID_APP_ID` - Android package name - `ANDROID_BUILD_TOOLS_VERSION` - Build tools version - `ANDROID_COMPILE_SDK` - Compile SDK version - `ANDROID_TARGET_SDK` - Target SDK version @@ -439,12 +407,6 @@ Set `ANDROID_SDK_ROOT` to your local SDK path. Limit which devices are evaluated to reduce initialization time: -```bash -devbox run android.sh devices select min max -``` - -Or set in `devbox.json`: - ```json { "env": { @@ -482,17 +444,6 @@ Display all configuration settings: devbox run android.sh config show ``` -Update configuration by editing your `devbox.json` env section: - -```json -{ - "env": { - "ANDROID_DEFAULT_DEVICE": "pixel_api28", - "ANDROID_DEVICES": "min,max" - } -} -``` - Run `devbox shell` after changing `devbox.json` to apply the new values. To reset to defaults, remove the overrides from your `devbox.json`. ## Troubleshooting @@ -515,7 +466,7 @@ Run `devbox shell` after changing `devbox.json` to apply the new values. To rese 3. Reset emulator state: ```bash - devbox run android.sh emulator reset-device max + devbox run android.sh emulator reset ``` 4. Increase boot timeout: @@ -556,9 +507,10 @@ Run `devbox shell` after changing `devbox.json` to apply the new values. To rese **Solutions**: -1. Source the Android environment: +1. Re-enter devbox shell to reload the environment: ```bash - . ${ANDROID_RUNTIME_DIR}/scripts/init/setup.sh + exit + devbox shell ``` 2. Verify SDK installation: @@ -566,11 +518,6 @@ Run `devbox shell` after changing `devbox.json` to apply the new values. To rese devbox run android.sh info ``` -3. Regenerate the environment: - ```bash - devbox run devbox_sync - ``` - ### Lock File Checksum Mismatch **Symptom**: Warning about lock file checksum not matching device definitions. @@ -582,7 +529,7 @@ Regenerate the lock file: devbox run android.sh devices eval ``` -Commit the updated `devices.lock` file. +Commit the updated lock file. ### Multiple Emulators Conflict @@ -601,11 +548,6 @@ Commit the updated `devices.lock` file. EMU_PORT=5556 devbox run start:emu device2 ``` -3. Use device serials explicitly: - ```bash - ANDROID_SERIAL=emulator-5554 devbox run start:app - ``` - ### Build Fails with SDK Version Errors **Symptom**: Gradle build fails with "SDK Build Tools version X not found". @@ -645,9 +587,6 @@ ANDROID_DEBUG=1 devbox shell # Global debug DEBUG=1 devbox shell - -# Debug during tests -ANDROID_DEBUG=1 devbox run test:e2e ``` Debug logs show: @@ -677,9 +616,13 @@ Test your app across multiple Android versions: 3. Test on each device: ```bash - devbox run start:app api21 - devbox run start:app api28 - devbox run start:app api36 + devbox run start:emu api21 + # run your tests... + devbox run stop:emu + + devbox run start:emu api36 + # run your tests... + devbox run stop:emu ``` ### CI/CD Integration @@ -744,11 +687,11 @@ devbox run android.sh devices create minimal --api 34 --device pixel --tag defau - **[Device Management Guide](device-management.md)**: Deep dive into device definitions and management - **[Testing Guide](testing.md)**: Comprehensive testing strategies and best practices - **[Troubleshooting Guide](troubleshooting.md)**: Extended troubleshooting scenarios -- **[Quick Start](quick-start.md)**: Get up and running in 5 minutes +- **[Quick Start](quick-start.md)**: Get up and running quickly ### Example Projects -- **[Android Example](../../examples/android/)**: Minimal Android app demonstrating plugin usage +- **[Android Example](../../examples/android/)**: Complete Android app with build scripts, deploy commands, and E2E test suites - **[React Native Example](../../examples/react-native/)**: Cross-platform app using both Android and iOS plugins ### Community and Support diff --git a/wiki/guides/cheatsheets/android.md b/wiki/guides/cheatsheets/android.md index 5ed9ca5..46ce72e 100644 --- a/wiki/guides/cheatsheets/android.md +++ b/wiki/guides/cheatsheets/android.md @@ -55,15 +55,16 @@ devbox run stop:emu ## Build and Deploy -```bash -# Build app -devbox run build +Build and deploy scripts are project-specific. Define them in your `devbox.json`. -# Build, install, and launch app -devbox run start:app +```bash +# Plugin-provided: run app on emulator (builds, installs, launches) +devbox run android.sh run +devbox run android.sh run pixel_api30 -# Build and run on specific device -devbox run start:app pixel_api30 +# User-defined scripts (add to your devbox.json shell.scripts): +# "build": ["gradle assembleDebug --info"] +# "start:app": ["android.sh run ${1:-}"] ``` ## Configuration @@ -130,12 +131,12 @@ adb emu kill ## Testing -```bash -# Run fast tests -devbox run test:fast +Test scripts are project-specific. Define them in your `devbox.json`. -# Run E2E tests -devbox run test:e2e +```bash +# User-defined scripts (add to your devbox.json shell.scripts): +# "test": ["gradle test"] +# "test:e2e": ["process-compose -f tests/test-suite.yaml --no-server"] # Run with headless emulator EMU_HEADLESS=1 devbox run test:e2e @@ -145,14 +146,14 @@ EMU_HEADLESS=1 devbox run test:e2e ``` devbox.d/android/ -├── devices/ # Device definitions -│ ├── min.json -│ ├── max.json -│ └── devices.lock # Generated lock file -└── flake.nix # Nix SDK configuration - -.devbox/virtenv/android/ # Runtime directory (auto-regenerated) -└── scripts/ # Plugin scripts +└── devices/ # Device definitions + ├── min.json + ├── max.json + └── devices.lock # Generated lock file + +.devbox/virtenv/android/ # Runtime directory (auto-regenerated, never edit) +├── scripts/ # Plugin scripts +└── flake.nix # Nix SDK configuration (auto-generated) reports/ ├── logs/ # Test logs diff --git a/wiki/guides/cheatsheets/ios.md b/wiki/guides/cheatsheets/ios.md index 9881c35..b718cc5 100644 --- a/wiki/guides/cheatsheets/ios.md +++ b/wiki/guides/cheatsheets/ios.md @@ -55,15 +55,16 @@ devbox run stop:sim ## Build and Deploy -```bash -# Build app -devbox run build - -# Build, install, and launch app -devbox run start:ios +Build and deploy scripts are project-specific. Define them in your `devbox.json`. -# Build and run on specific device -devbox run start:ios iphone15 +```bash +# User-defined scripts (add to your devbox.json shell.scripts): +# "build": ["xcodebuild -project ${IOS_APP_PROJECT} -scheme ${IOS_APP_SCHEME} ..."] +# "start:app": [ +# "ios.sh simulator start ${1:-}", +# "xcrun simctl install booted path/to/app.app", +# "xcrun simctl launch booted ${IOS_APP_BUNDLE_ID}" +# ] ``` ## Configuration @@ -134,12 +135,12 @@ launchctl kickstart -k gui/$UID/com.apple.CoreSimulatorService ## Testing -```bash -# Run fast tests -devbox run test:fast +Test scripts are project-specific. Define them in your `devbox.json`. -# Run E2E tests -devbox run test:e2e +```bash +# User-defined scripts (add to your devbox.json shell.scripts): +# "test": ["xcodebuild ... test"] +# "test:e2e": ["process-compose -f tests/test-suite.yaml --no-server"] ``` ## Files and Directories @@ -151,9 +152,9 @@ devbox.d/ios/ ├── max.json └── devices.lock # Generated lock file -.devbox/virtenv/ios/ # Runtime directory (auto-regenerated) +.devbox/virtenv/ios/ # Runtime directory (auto-regenerated, never edit) ├── scripts/ # Plugin scripts -└── DerivedData/ # Build output +└── DerivedData/ # Build output (if configured) reports/ ├── logs/ # Test logs diff --git a/wiki/guides/cheatsheets/react-native.md b/wiki/guides/cheatsheets/react-native.md index e5b3f20..50c077a 100644 --- a/wiki/guides/cheatsheets/react-native.md +++ b/wiki/guides/cheatsheets/react-native.md @@ -41,59 +41,57 @@ devbox run ios.sh devices eval ## Running Apps ```bash -# Android -devbox run start:emu # Start emulator -devbox run start:android # Build and run app +# Plugin-provided +devbox run start:emu # Start Android emulator +devbox run stop:emu # Stop Android emulator +devbox run start:sim # Start iOS simulator +devbox run stop:sim # Stop iOS simulator -# iOS -devbox run start:sim # Start simulator -devbox run start:ios # Build and run app - -# Web -devbox run start:web # Start web dev server +# User-defined scripts (add to your devbox.json shell.scripts): +# "start:android": ["process-compose -f tests/dev-android.yaml"] +# "start:ios": ["process-compose -f tests/dev-ios.yaml"] +# "start:web": ["process-compose -f tests/dev-web.yaml"] ``` ## Metro Bundler ```bash -# Start Metro manually -devbox run start:metro +# Plugin-provided +devbox run rn:metro:port android # Get Metro port for test suite +devbox run rn:metro:clean android # Clean Metro for test suite + +# User-defined scripts (add to your devbox.json shell.scripts): +# "start:metro": ["metro.sh start ${1:-default}"] +# "stop:metro": ["metro.sh stop ${1:-default}"] # Metro with custom port RN_METRO_PORT=8091 devbox run start:metro - -# Clean Metro cache -devbox run clean-metro - -# Get Metro port for test suite -devbox run rn:metro:port android - -# Clean Metro for test suite -devbox run rn:metro:clean android ``` ## Building -```bash -# Build all platforms -devbox run build +Build scripts are project-specific. Define them in your `devbox.json`. -# Build specific platform -devbox run build:android -devbox run build:ios -devbox run build:web +```bash +# User-defined scripts (add to your devbox.json shell.scripts): +# "build": ["devbox run build:android", "devbox run build:ios", "devbox run build:web"] +# "build:android": ["cd android && gradle assembleDebug"] +# "build:ios": ["cd ios && pod install && xcodebuild ..."] +# "build:web": ["npx react-native-web build"] ``` ## Testing +Test scripts are project-specific. Define them in your `devbox.json`. + ```bash -# Run all tests -devbox run test:fast +# Plugin-provided +devbox run test:metro # Test Metro bundler setup -# Platform-specific E2E tests -devbox run test:e2e:android -devbox run test:e2e:ios -devbox run test:e2e:web +# User-defined scripts (add to your devbox.json shell.scripts): +# "test": ["npm test"] +# "test:e2e:android": ["bash tests/run-android-tests.sh"] +# "test:e2e:ios": ["bash tests/run-ios-tests.sh"] # With TUI (terminal UI) TEST_TUI=true devbox run test:e2e:android @@ -110,12 +108,10 @@ devbox run ios.sh config show ## Diagnostics ```bash -# Health checks -devbox run doctor -devbox run verify:setup - -# Check Metro -devbox run test:metro +# Plugin-provided +devbox run doctor # Health check +devbox run verify:setup # Quick verification +devbox run test:metro # Test Metro setup ``` ## Common Environment Variables @@ -154,8 +150,8 @@ RN_METRO_PORT_END="8199" # Enable debug logging ANDROID_DEBUG=1 IOS_DEBUG=1 devbox shell -# Reset Metro -devbox run clean-metro +# Reset Metro cache +devbox run rn:metro:clean android rm -rf node_modules/.cache npm start -- --reset-cache @@ -178,30 +174,27 @@ rm -rf .devbox/virtenv/ios/DerivedData ## Development Workflow +The commands below assume you have defined `build:android`, `build:ios`, `start:android`, and `start:ios` in your `devbox.json`. + ```bash # Full Android workflow -devbox run start:emu +devbox run start:emu # Plugin-provided npm install -devbox run build:android -devbox run start:android +devbox run build:android # User-defined +devbox run start:android # User-defined # Full iOS workflow -devbox run start:sim +devbox run start:sim # Plugin-provided npm install cd ios && pod install && cd .. -devbox run build:ios -devbox run start:ios - -# Development with hot reload -devbox run start:metro & -devbox run start:android # Android -devbox run start:ios # iOS +devbox run build:ios # User-defined +devbox run start:ios # User-defined ``` ## Process Isolation ```bash -# Run multiple test suites in parallel +# Run multiple test suites in parallel (user-defined test scripts) TEST_SUITE_NAME=android devbox run --pure test:e2e:android & TEST_SUITE_NAME=ios devbox run --pure test:e2e:ios & @@ -222,7 +215,7 @@ devbox.d/ ├── max.json └── devices.lock -.devbox/virtenv/ +.devbox/virtenv/ # Runtime directory (auto-regenerated, never edit) ├── android/ # Android runtime ├── ios/ # iOS runtime └── metro/ # Metro state diff --git a/wiki/guides/device-management.md b/wiki/guides/device-management.md index 28d6d06..d982348 100644 --- a/wiki/guides/device-management.md +++ b/wiki/guides/device-management.md @@ -17,7 +17,7 @@ Device management in Devbox plugins follows a declarative approach. You define d ### Android Device Definitions -Android device definitions specify AVD (Android Virtual Device) configurations. Each file in `devbox.d/android/devices/*.json` defines one device. +Android device definitions specify AVD (Android Virtual Device) configurations. Each JSON file in your devices directory defines one device. **Schema:** ```json @@ -74,7 +74,7 @@ Android device definitions specify AVD (Android Virtual Device) configurations. ### iOS Device Definitions -iOS device definitions specify simulator configurations. Each file in `devbox.d/ios/devices/*.json` defines one simulator. +iOS device definitions specify simulator configurations. Each JSON file in your devices directory defines one simulator. **Schema:** ```json @@ -127,16 +127,14 @@ Use `min.json` and `max.json` as standard device names for testing minimum and m - Standardized across projects **Example directory structure:** -``` -devbox.d/android/devices/ -├── min.json # API 21 - minimum supported -├── max.json # API 36 - latest available -└── pixel_api28.json # Custom device for specific testing -devbox.d/ios/devices/ -├── min.json # iOS 15.4 - minimum supported -├── max.json # iOS 26.2 - latest available -└── ipad_pro.json # Custom device for tablet testing +The exact path of the devices directory depends on how the plugin is included in your project (local path vs GitHub reference). Inside your `devbox.d` folder, you will have a platform directory containing a `devices/` subdirectory: + +``` +/ +├── min.json # Minimum supported version (e.g., API 21 or iOS 15.4) +├── max.json # Latest available version (e.g., API 36 or iOS 26.2) +└── custom.json # Custom device for specific testing ``` **CI usage:** @@ -368,16 +366,16 @@ Lock files optimize CI builds by limiting which SDK versions and system images a Without lock files: - Nix evaluates all possible device configurations - Downloads system images for all API levels -- Slow CI builds (can add 10+ minutes) +- Slower CI builds With lock files: - Only evaluates specified devices - Downloads only required system images -- Fast CI builds (evaluates in seconds) +- Faster CI builds ### Android Lock File -**Location:** `devbox.d/android/devices/devices.lock` +**Location:** `devices.lock` inside your Android devices directory **Format:** ```json @@ -408,7 +406,7 @@ With lock files: ### iOS Lock File -**Location:** `devbox.d/ios/devices/devices.lock` +**Location:** `devices.lock` inside your iOS devices directory **Format:** ```json @@ -582,7 +580,8 @@ set -euo pipefail for device in min max; do echo "Testing on $device" devbox run android.sh emulator start "$device" - devbox run test:android + # Run your project-specific test command here + # e.g., devbox run ./gradlew connectedAndroidTest devbox run android.sh emulator stop done ``` @@ -595,7 +594,8 @@ set -euo pipefail for device in min max; do echo "Testing on $device" devbox run ios.sh simulator start "$device" - devbox run test:ios + # Run your project-specific test command here + # e.g., devbox run xcodebuild test -scheme MyApp devbox run ios.sh simulator stop done ``` @@ -612,7 +612,7 @@ processes: test-android-min: command: | devbox run android.sh emulator start min - devbox run test:android + # Run your project-specific test command here depends_on: setup: condition: process_completed @@ -620,7 +620,7 @@ processes: test-android-max: command: | devbox run android.sh emulator start max - devbox run test:android + # Run your project-specific test command here depends_on: setup: condition: process_completed @@ -628,7 +628,7 @@ processes: test-ios-min: command: | devbox run ios.sh simulator start min - devbox run test:ios + # Run your project-specific test command here depends_on: setup: condition: process_completed @@ -636,7 +636,7 @@ processes: test-ios-max: command: | devbox run ios.sh simulator start max - devbox run test:ios + # Run your project-specific test command here depends_on: setup: condition: process_completed @@ -667,27 +667,24 @@ Override device selection for individual test runs. **Android:** ```bash -# Use default device -devbox run test:android +# Start emulator with default device +devbox run android.sh emulator start -# Override for specific device -ANDROID_DEVICE_NAME=pixel_api28 devbox run test:android - -# Legacy override variable -TARGET_DEVICE=pixel_api28 devbox run test:android +# Start emulator with specific device +devbox run android.sh emulator start pixel_api28 ``` **iOS:** ```bash -# Use default device -devbox run test:ios - -# Override for specific device (via command argument) -devbox run test:ios iphone15 +# Start simulator with default device +devbox run ios.sh simulator start -# Or set device in test suite configuration +# Start simulator with specific device +devbox run ios.sh simulator start iphone15 ``` +Build, test, and deploy commands are project-specific and must be defined by you in your `devbox.json` scripts section. + ### Matrix Testing Test all combinations of devices and configurations. @@ -705,7 +702,8 @@ for device in "${ANDROID_DEVICES[@]}"; do for config in "${CONFIGS[@]}"; do echo "Testing Android $device with $config" devbox run android.sh emulator start "$device" - devbox run test:android:$config + # Run your project-specific test command here, e.g.: + # devbox run ./gradlew connectedAndroidTest -PbuildType="$config" devbox run android.sh emulator stop done done @@ -714,7 +712,8 @@ for device in "${IOS_DEVICES[@]}"; do for config in "${CONFIGS[@]}"; do echo "Testing iOS $device with $config" devbox run ios.sh simulator start "$device" - devbox run test:ios:$config + # Run your project-specific test command here, e.g.: + # devbox run xcodebuild test -scheme MyApp -configuration "$config" devbox run ios.sh simulator stop done done @@ -744,15 +743,15 @@ Specify a default device used when no device is explicitly provided. } ``` -**Usage:** +**Usage with plugin-provided commands:** ```bash -# Uses default device -devbox run start:app -devbox run start:ios +# Start emulator/simulator with default device +devbox run android.sh emulator start +devbox run ios.sh simulator start -# Override with specific device -devbox run start:app min -devbox run start:ios min +# Start emulator/simulator with specific device +devbox run android.sh emulator start min +devbox run ios.sh simulator start min ``` ### CI Device Selection @@ -783,7 +782,7 @@ jobs: - uses: actions/checkout@v3 - run: devbox install - run: devbox run android.sh emulator start ${{ matrix.device }} - - run: devbox run test:android + - run: devbox run your-android-test-script # Define in devbox.json scripts - run: devbox run android.sh emulator stop test-ios: @@ -795,7 +794,7 @@ jobs: - uses: actions/checkout@v3 - run: devbox install - run: devbox run ios.sh simulator start ${{ matrix.device }} - - run: devbox run test:ios + - run: devbox run your-ios-test-script # Define in devbox.json scripts - run: devbox run ios.sh simulator stop ``` @@ -877,8 +876,8 @@ Use clear, descriptive names for devices. Commit device definitions and lock files. **What to commit:** -- `devbox.d/*/devices/*.json` - Device definitions -- `devbox.d/*/devices/devices.lock` - Lock files +- `*.json` files in your devices directories - Device definitions +- `devices.lock` files in your devices directories - Lock files **What to ignore:** - `.devbox/virtenv/` - Generated runtime files @@ -914,8 +913,8 @@ devbox run android.sh devices create pixel_api35 \ # Regenerate lock file devbox run android.sh devices eval -# Commit both -git add devbox.d/android/devices/ +# Commit both the device definition and updated lock file +git add / git commit -m "feat(android): add pixel_api35 device" ``` @@ -937,8 +936,8 @@ devbox run android.sh devices update max --api 36 # Regenerate lock devbox run android.sh devices eval -# Test compatibility -devbox run test:android max +# Test compatibility by starting the emulator with the updated device +devbox run android.sh emulator start max ``` ### Performance Optimization @@ -980,7 +979,7 @@ Execution continues. Regenerate lock file when convenient. **Missing device definition (error):** ``` -[ERROR] Device 'pixel_api30' not found in devbox.d/android/devices/ +[ERROR] Device 'pixel_api30' not found in devices directory Available devices: min, max ``` Execution stops. Create device or use an available device name. @@ -1011,18 +1010,19 @@ For React Native or hybrid apps, manage both Android and iOS devices. ``` **Directory structure:** + +The exact layout of your `devbox.d` directory depends on how the plugin is included (local path vs GitHub reference). Each platform will have its own devices directory containing your device definitions and lock file: + ``` -devbox.d/ -├── android/ -│ └── devices/ -│ ├── min.json -│ ├── max.json -│ └── devices.lock -└── ios/ - └── devices/ - ├── min.json - ├── max.json - └── devices.lock +/ +├── min.json +├── max.json +└── devices.lock + +/ +├── min.json +├── max.json +└── devices.lock ``` **Testing workflow:** @@ -1030,14 +1030,14 @@ devbox.d/ # Android testing devbox run android.sh devices list devbox run android.sh devices eval -devbox run start:app min -devbox run start:app max +devbox run android.sh emulator start min +devbox run android.sh emulator start max # iOS testing devbox run ios.sh devices list devbox run ios.sh devices eval -devbox run start:ios min -devbox run start:ios max +devbox run ios.sh simulator start min +devbox run ios.sh simulator start max ``` ## Troubleshooting @@ -1051,8 +1051,8 @@ devbox run start:ios max # List available devices devbox run {platform}.sh devices list -# Check file exists -ls devbox.d/{platform}/devices/ +# Check file exists in your devices directory +ls / # Ensure filename matches (case-sensitive) # device-name.json should match exactly @@ -1068,9 +1068,8 @@ ls devbox.d/{platform}/devices/ devbox run android.sh devices eval devbox run ios.sh devices eval -# Commit updated lock file -git add devbox.d/*/devices/devices.lock -git commit -m "chore: update device lock files" +# Commit updated lock files from your devices directories +git commit -am "chore: update device lock files" ``` ### Android System Image Not Found diff --git a/wiki/guides/ios-guide.md b/wiki/guides/ios-guide.md index 506b6ac..3900359 100644 --- a/wiki/guides/ios-guide.md +++ b/wiki/guides/ios-guide.md @@ -6,11 +6,12 @@ A complete guide to iOS development using the Devbox iOS plugin. This guide cove The iOS plugin enables reproducible iOS development by automatically discovering Xcode and managing iOS simulators project-locally. It provides: -- **Project-local simulator management**: Device definitions stored in `devbox.d/ios/devices/`, isolated from system-wide simulator configuration +- **Project-local simulator management**: Device definitions stored in your devbox.d directory, isolated from system-wide simulator configuration - **Automatic Xcode discovery**: Multi-strategy detection with caching for fast shell initialization - **Device management**: JSON-based device definitions with CLI commands for creating, updating, and managing simulators -- **Development scripts**: Runtime scripts for building, running, and debugging iOS apps -- **Testing infrastructure**: E2E test suites with process-compose for automated testing +- **Simulator control**: Scripts for starting and stopping simulators + +The plugin does **not** provide build or deploy commands. Every project has different Xcode configurations (project vs. workspace, different schemes, different derived data paths), so you define those in your own `devbox.json`. See [Adding Build Scripts](#adding-build-and-deploy-scripts) for patterns. Pure shells with `devbox run --pure` create test-specific simulators and clean up after execution, ensuring isolated, reproducible testing. @@ -18,10 +19,11 @@ Pure shells with `devbox run --pure` create test-specific simulators and clean u ### Prerequisites -- macOS (iOS development requires macOS) -- [Xcode](https://apps.apple.com/app/xcode/id497799835) installed from the App Store, or Xcode Command Line Tools +- macOS with [Xcode](https://apps.apple.com/app/xcode/id497799835) installed - [Devbox](https://www.jetify.com/devbox/docs/installing_devbox/) installed +Devbox handles downloading other tools — you don't need to install them separately. + ### Adding the Plugin to Your Project Create or modify your `devbox.json` to include the iOS plugin: @@ -32,11 +34,14 @@ Create or modify your `devbox.json` to include the iOS plugin: "env": { "IOS_APP_PROJECT": "MyApp.xcodeproj", "IOS_APP_SCHEME": "MyApp", - "IOS_APP_BUNDLE_ID": "com.example.myapp" + "IOS_APP_BUNDLE_ID": "com.example.myapp", + "IOS_APP_ARTIFACT": "DerivedData/Build/Products/Debug-iphonesimulator/MyApp.app" } } ``` +Set the `env` variables to match your Xcode project. Use `-derivedDataPath DerivedData` in your xcodebuild command to keep build output project-local. + ### Initial Setup Initialize the Devbox environment: @@ -47,8 +52,8 @@ devbox shell This command: 1. Discovers Xcode installation automatically -2. Creates device definitions in `devbox.d/ios/devices/` -3. Sets up runtime scripts in `.devbox/virtenv/ios/scripts/` +2. Creates device definitions in your devbox.d directory +3. Sets up runtime scripts 4. Configures environment variables for iOS development 5. Caches Xcode path for fast subsequent initialization @@ -70,14 +75,16 @@ This checks for Xcode installation, command-line tools, xcrun and simctl availab ## Device Management -Device definitions are JSON files stored in `devbox.d/ios/devices/`. Each device specifies an iOS simulator configuration. +Device definitions are JSON files that describe simulator configurations. Each plugin install creates a `devices/` directory inside your `devbox.d/` folder with default device files. ### Default Devices The plugin includes two default devices: -- `min.json` - Minimum supported iOS version (iOS 15.4) -- `max.json` - Latest iOS version (currently iOS 26.2) +- `min.json` - Minimum supported iOS version (iOS 15.4, named `iPhone 13`) +- `max.json` - Latest iOS version (iOS 26.2, named `iPhone 17`) + +The filenames (`min`, `max`) are short nicknames you use in commands. The `name` field inside each JSON file is the simulator display name that appears in device listings. ### Listing Devices @@ -87,7 +94,7 @@ View all available device definitions: devbox run ios.sh devices list ``` -Output shows device names, display names, and iOS runtime versions. +Output shows device names and iOS runtime versions. ### Viewing Available Device Types and Runtimes @@ -177,7 +184,7 @@ After creating, updating, or deleting devices, regenerate the lock file: devbox run ios.sh devices eval ``` -The lock file (`devbox.d/ios/devices/devices.lock`) tracks which devices should be created and includes checksums for validation. Commit this file to version control. +The lock file (in your devices directory) tracks which devices should be created and includes checksums for validation. Commit this file to version control. ### Syncing Simulators @@ -197,24 +204,6 @@ Run this after modifying device files or pulling changes. ## Development Workflow -### Building Your App - -Build the iOS app using Xcode: - -```bash -# Standard build -devbox run build - -# Or build with xcodebuild directly -xcodebuild -project ${IOS_APP_PROJECT} -scheme ${IOS_APP_SCHEME} -configuration Debug \ - -destination 'generic/platform=iOS Simulator' -derivedDataPath DerivedData build -``` - -The plugin automatically configures the build environment, setting `DEVELOPER_DIR` and adding Xcode tools to PATH. Builds are configured for: -- Destination: iOS Simulator -- Configuration: Debug -- Output: `IOS_APP_DERIVED_DATA` (default: `.devbox/virtenv/ios/DerivedData`) - ### Starting a Simulator Start an iOS simulator for testing: @@ -223,7 +212,7 @@ Start an iOS simulator for testing: # Start default device devbox run start:sim -# Start specific device +# Start specific device by nickname devbox run start:sim iphone15 ``` @@ -239,42 +228,56 @@ Set the default device in `devbox.json`: } ``` -### Running Your App +### Stopping the Simulator -Build, install, and launch your app on the simulator: +Stop all running simulators: ```bash -# Build and run on default device -devbox run start:ios - -# Build and run on specific device -devbox run start:ios iphone15 +devbox run stop:sim ``` -The `start-ios` command: -1. Builds the app (runs `build-ios`) -2. Installs the app bundle matched by `IOS_APP_ARTIFACT` -3. Launches the app on the simulator +### Adding Build and Deploy Scripts -The app artifact path is auto-detected based on your Xcode configuration. You can override it: +The plugin provides simulator and device management. Build and deploy commands are specific to your Xcode project, so you define them in your `devbox.json`. Here's a typical setup: ```json { + "include": ["github:segment-integrations/devbox-plugins?dir=plugins/ios"], "env": { - "IOS_APP_ARTIFACT": ".devbox/virtenv/ios/DerivedData/Build/Products/Debug-iphonesimulator/MyApp.app" + "IOS_APP_PROJECT": "MyApp.xcodeproj", + "IOS_APP_SCHEME": "MyApp", + "IOS_APP_BUNDLE_ID": "com.example.myapp", + "IOS_APP_ARTIFACT": "DerivedData/Build/Products/Debug-iphonesimulator/MyApp.app" + }, + "shell": { + "scripts": { + "build": [ + "xcodebuild -project ${IOS_APP_PROJECT} -scheme ${IOS_APP_SCHEME} -configuration Debug -destination 'generic/platform=iOS Simulator' -derivedDataPath DerivedData build" + ], + "start:app": [ + "devbox run start:sim ${1:-}", + "xcrun simctl install booted ${IOS_APP_ARTIFACT}", + "xcrun simctl launch booted ${IOS_APP_BUNDLE_ID}" + ] + } } } ``` -### Stopping the Simulator - -Stop all running simulators: +With these scripts defined, you can: ```bash -devbox run stop:sim +# Build the app +devbox run build + +# Start simulator, install, and launch +devbox run start:app + +# Run on a specific device +devbox run start:app min ``` -This shuts down all iOS simulators. +See the [iOS example project](../../examples/ios/) for a complete working setup. ### Complete Development Workflow Example @@ -287,46 +290,43 @@ devbox shell # 2. Start simulator devbox run start:sim max -# 3. Build and run app +# 3. Build and deploy app (using your custom scripts) devbox run build -devbox run start:ios max +devbox run start:app max # 4. Make code changes, rebuild, and redeploy devbox run build -devbox run start:ios max +devbox run start:app max # 5. Stop simulator when done devbox run stop:sim ``` -For a streamlined workflow, use the combined command that handles everything: - -```bash -# Build, install, and launch in one command -devbox run start:ios -``` - ## Testing ### Running E2E Tests -The plugin includes E2E test infrastructure using process-compose. Example projects include test suites that: - -1. Build the app -2. Sync simulators with device definitions -3. Start the simulator -4. Deploy and launch the app -5. Verify the app is running -6. Clean up (stop app and simulator in pure mode) +The [iOS example project](../../examples/ios/) includes E2E test infrastructure using process-compose. You can use it as a template for your own project. -Run the complete E2E test: +Copy the example test suite: ```bash -cd examples/ios -devbox run test:e2e +cp -r examples/ios/tests/ your-project/tests/ ``` -Duration: 3-5 minutes (faster with warm build cache) +Add a test script to your `devbox.json`: + +```json +{ + "shell": { + "scripts": { + "test:e2e": [ + "process-compose -f tests/test-suite.yaml --no-server --tui=${TEST_TUI:-false}" + ] + } + } +} +``` ### Normal Mode vs Pure Mode @@ -369,12 +369,6 @@ The TUI shows process status, logs, and resource usage during test execution. ### Adding Tests to Your Project -Copy the example test suite: - -```bash -cp -r examples/ios/tests/ your-project/tests/ -``` - Configure for your app in `devbox.json`: ```json @@ -384,7 +378,7 @@ Configure for your app in `devbox.json`: "IOS_APP_PROJECT": "YourApp.xcodeproj", "IOS_APP_SCHEME": "YourApp", "IOS_APP_BUNDLE_ID": "com.yourcompany.yourapp", - "IOS_APP_ARTIFACT": ".devbox/virtenv/ios/DerivedData/Build/Products/Debug-iphonesimulator/YourApp.app" + "IOS_APP_ARTIFACT": "DerivedData/Build/Products/Debug-iphonesimulator/YourApp.app" }, "shell": { "scripts": { @@ -435,7 +429,7 @@ Environment variables: | `IOS_APP_BUNDLE_ID` | App bundle identifier | Required | | `IOS_APP_ARTIFACT` | Path to built .app bundle | Auto-detected | | `IOS_DEFAULT_DEVICE` | Default simulator device | `max` | -| `IOS_DOWNLOAD_RUNTIME` | Auto-download missing runtimes (0/1) | `0` | +| `IOS_DOWNLOAD_RUNTIME` | Auto-download missing runtimes (0/1) | `1` | | `TEST_TUI` | Show process-compose TUI (true/false) | `false` | | `BOOT_TIMEOUT` | Simulator boot timeout (seconds) | `120` | | `TEST_TIMEOUT` | Overall test timeout (seconds) | `300` | @@ -454,8 +448,8 @@ Configure the plugin by setting environment variables in `devbox.json`: "IOS_APP_PROJECT": "ios.xcodeproj", "IOS_APP_SCHEME": "ios", "IOS_APP_BUNDLE_ID": "com.example.ios", - "IOS_APP_ARTIFACT": ".devbox/virtenv/ios/DerivedData/Build/Products/Debug-iphonesimulator/ios.app", - "IOS_DOWNLOAD_RUNTIME": "0" + "IOS_APP_ARTIFACT": "DerivedData/Build/Products/Debug-iphonesimulator/ios.app", + "IOS_DOWNLOAD_RUNTIME": "1" } } ``` @@ -467,14 +461,14 @@ Key variables: - `IOS_APP_SCHEME` - Xcode build scheme - `IOS_APP_BUNDLE_ID` - App bundle identifier - `IOS_APP_ARTIFACT` - Path to built .app bundle (auto-detected if not set) -- `IOS_DOWNLOAD_RUNTIME` - Auto-download missing iOS runtimes (0/1) +- `IOS_DOWNLOAD_RUNTIME` - Auto-download missing iOS runtimes (0/1, default: 1) ### Xcode Configuration The plugin automatically discovers Xcode using multiple fallback strategies: 1. Check `IOS_DEVELOPER_DIR` environment variable -2. Check cache file (`.devbox/virtenv/ios/.xcode_dev_dir.cache`, 1-hour TTL) +2. Check cache file (1-hour TTL) 3. Find latest Xcode in `/Applications/Xcode*.app` by version number 4. Use `xcode-select -p` output 5. Fallback to `/Applications/Xcode.app/Contents/Developer` @@ -489,8 +483,6 @@ Override discovery by setting `IOS_DEVELOPER_DIR`: } ``` -The discovered path is cached for 1 hour to improve shell startup performance. - ### Performance Optimization #### Skip iOS Setup for Faster Initialization @@ -666,7 +658,7 @@ This shows: **Symptom**: Xcode build errors related to linker flags or Nix environment variables. -**Solution**: The plugin automatically strips Nix-related flags from the build environment. If you still encounter issues, the build script uses: +**Solution**: Strip Nix-related flags from the build environment. Use: ```bash env -u LD -u LDFLAGS -u NIX_LDFLAGS xcodebuild ... @@ -700,8 +692,6 @@ Commit the updated lock file to version control. 2. Check system resources (CPU, memory): ```bash top - # or - htop ``` 3. View simulator logs: @@ -726,9 +716,6 @@ IOS_DEBUG=1 devbox shell # Global debug DEBUG=1 devbox shell - -# Debug during tests -IOS_DEBUG=1 devbox run test:e2e ``` Debug logs show: @@ -742,13 +729,13 @@ Debug logs show: **Check Test Logs:** -Test logs are written to `reports/ios-e2e-logs/`: +Test logs are written to `reports/`: ```bash # View all logs -ls -la reports/ios-e2e-logs/ +ls -la reports/ -# View specific process log +# View specific process log (paths depend on your test suite configuration) cat reports/ios-e2e-logs/build-app.log cat reports/ios-e2e-logs/ios-simulator.log cat reports/ios-e2e-logs/deploy-app.log @@ -767,13 +754,6 @@ xcrun simctl list devices | grep "Booted" tail -f ~/Library/Logs/CoreSimulator/*/system.log ``` -**Common Issues:** - -- **Build Failures**: Check Xcode installation, verify project path, check scheme exists, view build log -- **Simulator Won't Start**: Check CoreSimulatorService, restart service, check disk space, view simulator log -- **App Won't Install**: Verify app bundle exists, check simulator is booted, check bundle ID -- **Timeout Errors**: Increase `BOOT_TIMEOUT` for slow machines, increase `TEST_TIMEOUT` for large builds, check system resources - ## Common Use Cases ### Multi-Device Testing @@ -799,9 +779,13 @@ Test your app across multiple iOS versions: 4. Test on each device: ```bash - devbox run start:ios iphone_ios15 - devbox run start:ios iphone_ios17 - devbox run start:ios iphone_ios18 + devbox run start:sim iphone_ios15 + # run your tests... + devbox run stop:sim + + devbox run start:sim iphone_ios18 + # run your tests... + devbox run stop:sim ``` ### CI/CD Integration @@ -901,7 +885,7 @@ The device name in the JSON file should match the device type from `xcrun simctl ### Example Projects -- **[iOS Example](../../examples/ios/)**: Minimal iOS app demonstrating plugin usage +- **[iOS Example](../../examples/ios/)**: Complete iOS app with build scripts, deploy commands, and E2E test suites - **[React Native Example](../../examples/react-native/)**: Cross-platform app using both iOS and Android plugins ### Community and Support diff --git a/wiki/guides/quick-start.md b/wiki/guides/quick-start.md index dfa6665..9b74bd3 100644 --- a/wiki/guides/quick-start.md +++ b/wiki/guides/quick-start.md @@ -1,18 +1,18 @@ # Quick Start Guide -Get up and running with Android, iOS, or React Native development in 5 minutes. +Set up a project-local Android or iOS development environment from scratch. ## Prerequisites -Install Devbox if you haven't already: +Install [Devbox](https://www.jetify.com/devbox/docs/installing_devbox/) if you haven't already: ```sh curl -fsSL https://get.jetify.com/devbox | bash ``` -## Choose Your Platform +Devbox handles downloading all build tools (JDK, Gradle, Xcode CLI tools, etc.) so you don't need to install them separately. -Pick your platform and follow the quickstart below: +## Choose Your Platform - **[Android](#android-quickstart)** - Native Android development with emulators - **[iOS](#ios-quickstart)** - Native iOS development with simulators (macOS only) @@ -24,12 +24,13 @@ Pick your platform and follow the quickstart below: ### 1. Initialize Your Project +In your existing Android project directory: + ```sh -# Initialize devbox in your existing Android project devbox init ``` -Add the Android plugin to your `devbox.json`: +Replace the contents of your `devbox.json` with: ```json { @@ -44,9 +45,9 @@ Add the Android plugin to your `devbox.json`: } ``` -Set `ANDROID_APP_APK` to the path where your build outputs the APK. The app's package name (`ANDROID_APP_ID`) is auto-detected from the APK at install time. +The `include` line adds the Android plugin from GitHub. Devbox downloads the Android SDK, emulator, and device management tools automatically. The `packages` section adds JDK and Gradle for building your app. Set `ANDROID_APP_APK` to the path where your build outputs the APK. -> **Note:** These are custom plugins hosted on GitHub, not built-in devbox plugins. You cannot use `devbox add plugin:android` — add the `include` URL to your `devbox.json` manually. +> **Note:** Plugins are included via URL in `devbox.json`, not with `devbox add`. You cannot use `devbox add plugin:android`. ### 2. Enter the Development Environment @@ -54,7 +55,11 @@ Set `ANDROID_APP_APK` to the path where your build outputs the APK. The app's pa devbox shell ``` -This installs the Android SDK, build tools, and emulator without touching your global `~/.android` directory. +On first run, this downloads the Android SDK via Nix. Subsequent runs are fast. The SDK is stored project-locally — nothing is written to `~/.android`. + +Two quick devbox concepts: +- `devbox shell` enters an interactive shell with all tools on your PATH +- `devbox run