Packaging and Deployment #

A Budo app starts as a folder, but the same folder can be run locally, exported to a static web build, or packaged as an Android APK or AAB. The packaging tools read the same entrypoints, project-relative assets, and app.json metadata used by the runtime.

Local desktop runs #

Use run while developing.

# Run one of the bundled examples on desktop.
./build/budo run examples/demo
# Run your app with an explicit window size and title.
./build/budo run my-app --width 1280 --height 720 --title "My App"

The implicit shorthand also works:

# Use the shorthand form when you only want to run a project.
./build/budo my-app

Useful run options include --fullscreen, --no-vsync, and --file-root <path>. --file-root changes the root used by sys.file on desktop without changing where project assets such as shaders and fonts are resolved.

Project bootstrap #

init writes a starter project into the target directory.

# Create a starter project with metadata and editor helper files.
./build/budo init my-app

It creates main.js, app.json, jsconfig.json, a copy of the developer API reference, and TypeScript declarations. This is the quickest way to get editor autocompletion for the runtime globals.

Web export #

The web target supports JavaScript, TypeScript, and Lua entrypoints. It packages a self-contained static folder with the Emscripten runtime and your project assets.

# Export a self-contained static web folder.
./build/budo web-export my-app -o dist/my-app-web

To export and serve locally:

# Export the project and serve it locally for browser testing.
./build/budo web-serve my-app

The Makefile also provides web helpers for rebuilding the base runtime and staging the playground.

# Rebuild the base web runtime.
make web-build-runtime
# Export the project named by WEB_APP.
make web-export WEB_APP=examples/demo
# Rebuild the website playground assets.
make playground

Web builds use QuickJS and Lua compiled through Emscripten. The Wasmtime runtime is not available in the browser build. Raw UDP and RTP-MIDI are also unavailable on web because browsers do not expose UDP sockets.

Android packaging #

Budo Pro: Android APK/AAB packaging is a paid feature. Public builds keep these commands visible, but require the private Android feature pack under private/android before packaging is enabled.

Android packaging is driven by the desktop budo binary. The public contract is the command surface, supported entrypoints, project assets, and app.json metadata; the Android runtime architecture and build backend are private to the Budo Pro feature pack.

# Build a debug APK for local testing.
./build/budo android-apk my-app
# Build a release APK.
./build/budo android-apk my-app --release
# Build a release Android App Bundle for store delivery.
./build/budo android-aab my-app --release

Use --install with android-apk to install the produced APK on connected adb devices.

# Build and install the APK on connected adb devices.
./build/budo android-apk my-app --install

The packager applies identity and release metadata, bundles the selected app's runtime assets, and writes the final APK/AAB to dist/ by default. Temporary paths and generated files are implementation details, not stable API.

Android metadata #

Budo Pro: These metadata fields are consumed by the paid Android packaging feature.

The same app.json used by your app can carry Android release details.

{
  "app_name": "Pulse Orbit",
  "package_name": "com.example.pulseorbit",
  "version_name": "1.0.0",
  "version_code": 1,
  "orientation": "portrait",
  "fullscreen": true,
  "icon": "icon.png",
  "network": ["api.example.com"],
  "filesystem": false,
  "permissions": ["INTERNET"]
}

Fields are optional, but release packages should set a stable package identifier and version code. Icons may be PNG or SVG depending on the packaging path and available tooling.

The packager skips packaging metadata that should not become runtime assets, including store listing folders, icon source files used for generation, and keystore files.

Signing and release builds #

Debug builds use the normal Android debug signing flow. Release builds need release signing configuration. Keep signing material outside the runtime asset set and outside source control.

The Android packaging helpers can read signing-related metadata from app.json. For Play Store delivery, prefer android-aab --release once you have verified the APK locally.

Store listing scaffolding #

Apps can include store listing metadata and media beside their project files. The packager can prepare Play Store listing scaffolding while keeping that material out of the runtime asset bundle.

This is useful for examples such as games that ship with screenshots, feature images, privacy pages, and localized descriptions.

Build prerequisites #

Desktop builds require CMake, a C and C++ compiler, SDL2, Skia, and platform libraries such as FreeType, Fontconfig, OpenSSL, and ALSA where applicable. CMake fetches QuickJS, Lua, Wasmtime, SQLite, and several pinned dependencies during configuration.

Android builds require the private Budo Pro feature pack, the Android SDK and NDK, Android-ready native dependencies prepared by the Pro setup flow, and a rebuilt desktop Budo binary. ONNX Runtime Android support is prepared separately when neural inference is enabled for Android.

Web builds require an activated Emscripten SDK and the Skia-WASM setup used by the web/ CMake project.

Release checklist #

Before shipping, run the app on every target you claim to support. Check capability branches, asset paths, network policy, file policy, shader compilation, display density, touch ergonomics, audio start behavior, and package metadata.

For Android, test both debug and release artifacts. For web, serve the exported folder over HTTP rather than opening it directly from the filesystem; browser security rules are different under file://.