Build an app

Quick start

This is the smallest app that builds. It draws nothing, so it only shows a blank surface.

use androios_app::{run, App, Ctx, Damage, Surface};

struct Hello;

impl App for Hello {
    fn id(&self) -> &str { "is.example.hello" }

    fn draw(&mut self, _ctx: &Ctx, s: &mut Surface, _t: f64) -> Damage {
        let mut d = Damage::new(s.w, s.h);
        d.all();
        d
    }
}

fn main() {
    run(Hello);
}

1. Create the crate under springboard/apps/, with androios-app as a dependency (springboard/sdk). springboard/apps/calculator is a complete example.
2. Add manifest.toml, a 180 × 180 PNG named in icon, and a CHANGELOG.md with an entry for the version.
3. Build for the tablet: cargo build --release -p hello --target aarch64-linux-android.
4. Pack and publish: tools/aap.py pack apps/hello, then publish-app.sh with the resulting .aap file.

Which kind?

Most apps are app. Use another kind only in the cases below.

Manifest

Every package has a manifest.toml. The packer rejects a package if a required field is missing or a value is invalid.

id          = "is.olibuijr.calculator"
name        = "Calculator"
version     = "1.0.3"
exec        = "calculator"
icon        = "icon.png"
min_shell   = "0.1.0"
summary     = "Basic and scientific calculator with history."
category    = "Utilities"
permissions = ["storage"]

Permissions. The list below is the full set the packer accepts.

On the PC, the shell enforces network, storage, audio and remote-desktop, and rejects any other permission. Enforcement on the tablet is not documented yet. Declare only what the app really needs.

The app

The shell starts your executable and passes it a socket and a private data folder through environment variables. Your app implements the App trait. Only id and draw are required.

pub trait App {
    fn id(&self) -> &str;                                        // same as the manifest id
    fn configure(&mut self, ctx: &Ctx) {}                        // size, scale, safe area, dark mode
    fn event(&mut self, ctx: &Ctx, ev: Input) -> bool { false } // true when a new frame is needed
    fn draw(&mut self, ctx: &Ctx, s: &mut Surface, t: f64) -> Damage;
    fn suspend(&mut self, ctx: &Ctx) {}                          // leaving the foreground: save state now
    fn resume(&mut self, ctx: &Ctx) {}
    fn tick(&mut self, ctx: &Ctx, t: f64) -> bool { false }    // runs while in the foreground
    fn next_wake(&self, t: f64) -> Option<f64> { None }      // when tick has work; None sleeps
    fn controls(&self, ctx: &Ctx) -> Vec<Node> { Vec::new() }  // accessibility labels
    fn commands(&self, ctx: &Ctx) -> Commands { Commands::default() }
}

• Input. Input::Touch for touches, Input::Key for typed text, Input::Open for a URL handed to the app, Input::Command and Input::Activate for shell actions, and Input::Context and Input::ContextAction for menus (see below).
• Frames. draw writes premultiplied pixels with a stride equal to the width, and returns the area that changed. The first frame after a size change is always sent in full.
• Keyboard. Call ctx.wants_keyboard(true) to show the system keyboard. Typed text then arrives as Input::Key.
• Other calls. ctx.open_url, ctx.notify, ctx.haptic, ctx.log.
• Scrolling. Use kit::Scroller. Lists then scroll the same way as the system's own lists.
• Suspend. The shell may close a background app at any time to free memory. Save state when you get Suspend.

Clipboard and desktop

• Clipboard. kit::clipboard::text() returns the current text, and kit::clipboard::set_text(&str) sets it. The SDK sends changes to your app as they happen.
• Right-click menus (PC). A right-click arrives as Input::Context { x, y }, in your app's pixels. Call ctx.context_menu(x, y, items) with up to 32 ContextItems, each with an id, label and enabled. The chosen item comes back as Input::ContextAction(id). Disabled items never fire.
• Remote sharing (PC). ctx.remote_sharing(on) is only for the built-in Remote app.
• Links. On the PC, ctx.open_url opens HTTP and HTTPS links in BifrOSt Browser.

Testing

There is no app previewer yet. The home-screen preview in tools/preview.sh renders only the home screen.

• Run cargo test -p hello for unit tests in your crate.
• The Calculator crate has a test_ui() helper that loads the system font and symbols. Copy it when you need to test drawing without a device.
• Check the result on a real tablet with a screenshot before publishing.

Data and logs

• Data folder. The shell sets ANDROIOS_DATA to /data/local/springboard/appdata/<id>, and ctx.data_dir points at the same folder. Store everything your app needs there. Do not write outside it.
• Crashes. A crashed app never takes the shell down. It shows its last frame, and it starts again on the next open.
• Exit log. When an app exits, the shell writes springboard: app <id> exited <code> to its log. A code of 128 or more means the app was killed by a signal (128 + signal number).
• Your own log. Call ctx.log(text) to write a line to the shell log.

Icon and look

• The icon is a 180 × 180 PNG. The shell applies the rounded-square mask, so keep the important parts away from the corners.
• Use the kit module for text, lists and navigation bars. Apps then match the system's type, colors and spacing without extra work.
• Respect Configure: dark mode, text size and reduced motion come from there.

Shipping

Packing

tools/aap.py pack <app dir> reads the manifest, checks it, takes the binary from target/aarch64-linux-android/release/ (or --bin) and writes an uncompressed tar with a .aap extension. It fails if the icon is not 180 × 180 or if the changelog has no entry for the version. tools/aap.py info <file.aap> prints what a package contains.

Changelog

Each version needs a heading in the form ## <version> — <date>, followed by - notes, newest first. The store shows the newest entry as "What's New" and the older ones as version history.

Publishing

• publish-app.sh copies the package into the store and rebuilds the index. The store reads the app's details from its newest package.
• A published version cannot be replaced. Bump the version for every change.
• PC apps are built for x86_64-linux, set architecture = "x86_64-linux", and are published with bifrost pc app publish.
• Submissions from other developers are not open yet.

Updates on the device

• Pull only. The tablet asks for updates. Nothing is pushed to it.
• When it checks. About 30 seconds after start, when Wi-Fi connects, and every 6 hours. It skips the check in low-power mode unless the device is charging.
• Apps and system parts install automatically unless turned off. System parts update silently.
• The OS (shell and boot script) downloads and checks the update, then asks before installing. It is in Settings > General > Software Update.
• Rollback. A new shell starts on probation. If it does not stay healthy, the boot script restores the previous build.
• OS releases are published with bifrost publish, which needs a matching changelog entry.

Store API

Live catalogue: /api/v1/apps.json.

Protocol reference

The SDK handles all of this. Read it only if you are writing a client by hand.

• Socket. One SOCK_SEQPACKET socket, passed in ANDROIOS_SOCK. Each message is one packet: a little-endian u32 tag, then the fields. Unknown tags are ignored, so older apps and newer shells keep working together.
• Buffers. Allocate two buffers with memfd_create, or ashmem on Android. Each is w × h × 4 bytes. Send both file descriptors once in Buffers, using SCM_RIGHTS.
• Frames. Draw into the buffer the shell is not holding, and send Frame { buf, damage }. Do not touch that buffer until the shell returns it with Release { buf }.
• Size. The shell sends Configure before the first frame and on every rotation or resize. Reallocate and send Buffers again.
• Versioning. sdk_version is 1. It only goes up for breaking changes.

The byte-level encoding is in springboard/proto/src/lib.rs. It is shared by the shell and the SDK, and has round-trip tests.