Skip to main content

Reading the code

The whole project (the app, its patches, this website and the editor extension) lives in one repository. This page is a map, so you know where to look.

Top level structure​

The src folder is the most important one. It contains all the Rust code, and the few Java classes that Android needs.

Other important files and folders:

  • manifest.yaml: The Android manifest and build config for xbuild: package name, permissions, activities, services and assets. The package name comes from here, so don't hard-code it anywhere else.
  • assets: The app icon, the HTML pages for the installer and the "Device Unsupported" page, and the prebuilt native libraries (PRoot, libxkbcommon, PipeWire, the guest's GPU drivers) for the APK to pick up.
  • patches: Our patched copies of upstream projects, like smithay, winit, xbuild and PRoot. These let us fix things without waiting, and we send the good changes back upstream. See Patching dependencies.
  • scripts: The 16 KB ELF alignment check, the Termux build script, and the PipeWire AAudio sink build.
  • build.rs: Tells Cargo where the prebuilt native libraries are, so the crate can link against them.
  • Makefile, Dockerfile: Build shortcuts, see Building the app.
  • docs/architecture.md: A short architecture overview that goes into the PDF manuals.
  • gh-pages: This website (Docusaurus), and the Bear War game on the home page.
  • vscode-extension: The Local Desktop Dev extension, and its MCP server and CLI.
  • target: Your build artifacts go here.

Source code structure​

  • lib.rs: This file behaves more like a contact book. You only register the modules here, no actual logic goes here.
  • core/config.rs: Default values: where the Arch filesystem lives, the rootfs download URL, and the default Check, Install and Launch commands.
  • android/main.rs: Did you see that #[no_mangle] fn android_main function? Android apps do not have a main function, instead:
    • When you open an Android app (by tapping the app icon), Android launches an activity.
    • An activity is a Java class that extends android.app.Activity. Most of Local Desktop is written in Rust, so we register a special NativeActivity.
    • The NativeActivity loads the android_main inside liblocaldesktop.so (the library into which all of our Rust code is compiled). That's why we need the #[no_mangle] annotation, to prevent the Rust compiler from changing the function name.

So android/main.rs is the genesis of all the spaghetti code. In case you get lost, just put a breakpoint at the beginning of this function and follow the execution flow. It also sets up logging and Sentry, and keeps the screen on.

android/​

PathWhat it does
app/build.rsBuilds PolarBearApp and decides between the installer and the desktop
app/run.rsThe winit event loop: resume, suspend, resize, and user events
backend/webview.rsThe installer and "Device Unsupported" pages, and the WebSocket that sends them progress
backend/wayland/compositor.rsThe Smithay compositor state: surfaces, seats, the clipboard, xdg-shell
backend/wayland/event_centralizer.rsTurns winit events (touch, mouse, keys) into one input type, and decides between tap, scroll, long press and drag
backend/wayland/event_handler.rsSends that input to the Wayland clients, and draws frames
backend/wayland/winit_backend.rsEGL setup and rendering to the Android window
backend/wayland/hardware_buffer.rsFast AHardwareBuffer uploads for wl_shm clients
backend/wayland/frame_clock.rs, watcher.rsThe vsync-driven frame loop, and the thread that wakes it when a client writes
backend/wayland/output_state.rsWrites the screen size and scale to /tmp/localdesktop-output for the guest
backend/wayland/keymap.rsMaps winit's physical keys to Linux scan codes
backend/wayland/input.rsThe winit input types, wrapped for Smithay
backend/wayland/bind.rsCreates the wayland-0 socket in the guest's /tmp
backend/pipewire_standalone_aaudio.rsStarts and watches PipeWire, WirePlumber and pipewire-pulse on the Android side
proot/setup.rsThe 13 setup stages, see Understanding the architecture
proot/process.rsBuilds the proot command line: binds, environment, user
proot/launch.rsRuns the Launch command once the compositor is ready
accessibility.rsThe bridge to the keyboard accessibility service
external_display.rsThe bridge to ExternalDisplay.java, for monitors
utils/settings.rsReads the settings saved by SettingsActivity
utils/application_context.rsPaths, permissions and other facts about the app, read once at start
utils/ndk.rsScreen density and other values from Android

android/java/​

Some things are much easier in Java than through JNI, so a few small classes live in src/android/java/io/github/localdesktop/:

ClassWhat it does
SettingsActivityThe settings page in App info
PhoneKeyboardShows and hides the Android keyboard, and resizes the desktop above it
KeyboardAccessibilityService, KeyboardShortcutsPromptThe physical keyboard service, and the prompt that suggests it
ExternalDisplay, TrackpadControlsThe desktop on a monitor, and the trackpad on the phone

The Gradle build (xbuild) compiles them. The cargo run builder uses the prebuilt src/android/dex/classes.dex instead, see its README.md.

bin/​

FileWhat it does
build_apk.rsThe small APK builder behind cargo run, for building on Termux
build_docs.rsBuilds the PDF manuals
download_sdk.rsDownloads the Android SDK build-tools, for building on Termux
localdesktop_pipewire_aaudio_sink.rsThe PipeWire sink that plays through AAudio

Execution flow​

The names PolarBearApp, PolarBearFrontend and PolarBearBackend are from the project's first name, Polar Bear 🐻‍❄️, which is also why the app icon is a bear.