# Working on Omalauncher This file is for coding agents (and people) changing this repository. Read [README.md](README.md) for what the app is, then [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), which also lists where to change common things. ## Two kinds of agent The app itself runs coding agents on the phone, and they write widgets. That is a different job from changing this code: - **Writing or fixing a widget** (`*.owl`): the language is documented for agents in [app/src/main/assets/widgets/README.md](app/src/main/assets/widgets/README.md) and its `docs/` folder. Those files ship inside the app and are what agents on the phone read. A widget needs no Kotlin change. - **Changing the launcher** (Kotlin, the OWL compiler, the Linux setup): this file. The `AGENTS.md` that agents in the phone's Linux see is generated by `app/src/main/kotlin/dev/omalauncher/widgets/WidgetEngine.kt`. It is not this file. ## Build and test ```sh ./scripts/fetch-proot.sh # once per checkout, and again when the build asks; needs bsdtar ./gradlew :owl:test :app:testFossDebugUnitTest :owl:owlJar ./gradlew :app:assembleFossDebug :app:lintFossDebug :app:lintPlayDebug ``` These are what CI runs (`.github/workflows/ci.yml`). Run both before you call a change done. - `app/src/main/jniLibs/` (proot) and `local.properties` are gitignored. A new `git worktree` has neither: its APK installs, but every Linux command exits -1. Run `fetch-proot.sh` there, or copy both from the main checkout. The build stops when `patches/proot` or the script changed after the libraries were built. - Tests: `owl/src/test` (the language) and `app/src/test` (plain JVM tests of the app). New behavior gets a test where the code allows one. - With more than one device connected, set `ANDROID_SERIAL` before `installFossDebug`. Don't uninstall the app from a device you didn't set up: it holds the user's Linux install and widgets. - Debug builds run guest commands from adb: `adb shell am start -n dev.omalauncher/.MainActivity --es exec ''`. Output goes to logcat. - On a device, `owl-check ` compiles a widget and renders a preview PNG. ## Rules the code doesn't show - **Existing installs must keep working.** The app is on Play with real users. A change to saved data, the rootfs setup or files the launcher writes goes through one of the four update mechanisms in ARCHITECTURE.md "Updates": a new rootfs step id, a `Versioned` migration, or a `ManagedFiles` policy. Never delete an old reader. - **OWL language level.** `Compiler.LEVEL` (owl module) is the language version. Anything a widget could depend on goes into the next unreleased level: if the current level has already shipped in a release (see CHANGELOG.md), bump it, otherwise add to it. Record the addition in `SINCE` (`owl/.../widgets/lang/Schema.kt`) and in `app/src/main/assets/widgets/docs/versions.md`. - **The widget docs are part of the feature.** A language change updates the matching page in `app/src/main/assets/widgets/docs/`. Agents on the phone only know what's written there. - **No `inline` functions in owl that the app calls.** owl builds for JVM 17, the app for JVM 11, so an inline owl function fails the app build (`INLINE_FROM_HIGHER_PLATFORM`). Write a plain method instead. - **UI text goes in `res/values/strings_.xml`**, with a translation in every `values-*` folder (de, es, in, ja, pt, ru, zh). `HardcodedTextTest` fails on literal text in UI calls. German is lower case wherever the English is, and casual (du). Agent prompts, owl errors, logs and the stock `.owl` files stay English. - **Don't enable `generateLocaleConfig`.** With a locale config, changing the app language in Android Settings crashes Settings for a launcher. - **Fix what's asked.** Don't change behavior or add mechanisms beyond the task. Mention anything else you notice instead of changing it. ## Commits Look at `git log` and match it: one subject line, written as a sentence or two, about what changed for the user and why, with `(#N)` at the end when there is an issue or PR. No body is needed. Stage files by name, not with `git add -A`. Add a CHANGELOG.md entry only when preparing a release. ## Docs - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): the compositor, rendering, GPU, updates, and where to change what - [docs/RELEASING.md](docs/RELEASING.md): Play releases (the maintainer's job) - [docs/plans/](docs/plans/): design plans for features that have landed. They are history: where a plan and the code disagree, the code is right