For contributors and collaborators: from a fresh clone to a change that passes CI. If you only want to use Mobium — install it and drive a device — you want the quick start instead.
Every command here was run from a fresh clone of main: make build,
make lint-install, make ci and the five-client device check all passed.
- 1. Toolchains
- 2. Clone and build
- 3. Run what CI runs
- 4. Drive a device
- 5. Work on a client
- 6. Regenerate what is generated
- 7. Send a pull request
- Before you write a test
| For | You need | CI uses |
|---|---|---|
| the binary and the Go client | Go 1.24 or later | the version in go.mod |
| linting | golangci-lint 2.13.2 — make lint-install fetches it and checks its checksum |
the same |
| the JavaScript client | Node.js 18 or later | 22 |
| the Python client | Python 3.9 or later | the runner's |
| the Java client | a JDK, 17 or later; the Maven wrapper fetches Maven | Temurin 17 |
| the .NET client | the .NET 10 SDK (its tests target net10.0) |
10.0.x |
| Android devices | the Android SDK: platform-tools, and the emulator | — |
| iOS devices | Xcode, on macOS | — |
make java and make dotnet skip with a note when their toolchain is
missing, so you can work on the Go without either. CI has all of them, and a
change that touches a client is only checked once its toolchain is installed.
git clone https://github.com/mobiumdev/mobium.git
cd mobium
make build # -> bin/mobium
bin/mobium --version
make lint-install # once; installs golangci-lint into $(go env GOPATH)/binmake ciIt is exactly what the CI workflow runs, so a green local run means a green
build. Among its other lines it prints gofmt clean, clients parse, a
line per JavaScript and Python client check, a checks, 0 failed total for
each of the Java and .NET suites, license copies match and docs: spelling, anchors and quick-start pages clean; the counts in them grow with the API,
so none is quoted here. It also covers go vet, the linter, both Go modules' tests, cross-compilation
for six targets, and the checks that the generated docs are current.
make test alone is faster and skips most of that. clients/go is its own
module, so go test ./... from the root does not reach it — use make test.
After rebuilding, run bin/mobium daemon stop. A daemon already running
keeps serving the old binary, and you will debug code you are not running.
The Go suite is hermetic — fake servers and captured fixtures, no device. Behavior on a device is checked by the scripts in checks/, each of which drives a real emulator, simulator or phone and asserts on what happened rather than on an exit code.
Start one device — mobium boot mobium-test for an emulator, mobium boot "iPhone 17 Pro" for a simulator; SETUP.md has every kind, and
the traps — then run the check for what you changed. The five clients' end-to-end flows are
one script:
sh docs/checks/clients.sh emulator-5554 python passed
javascript passed
go passed
java passed
dotnet passed
checks/README.md lists every script and what it proves; RELEASE-CHECKLIST.md is the set to run before a release. When you are done, stop cleanly — the daemon before the device:
sh docs/checks/clean-stop.sh --quitor, for one device, mobium shutdown emulator-5554, which ends its daemon's
session and then shuts the device down (SHUTDOWN.md).
Each client's tests start a fake mobium and need no device:
| Client | Its tests | Run a program against it from this clone |
|---|---|---|
| Python | make clients |
pip install ./clients/python in a virtualenv |
| JavaScript | make clients |
npm install ./clients/javascript |
| Go | make test |
go mod edit -replace=github.com/mobiumdev/mobium/clients/go=<path to this clone>/clients/go in your module |
| Java | make java |
cd clients/java && ./mvnw install, then depend on dev.mobium:mobium:0.1.0-SNAPSHOT |
| .NET | make dotnet |
dotnet pack clients/dotnet/Mobium -o ./nupkgs, then dotnet add package Mobium --source ./nupkgs |
The examples in quickstart/examples/ are a ready-made program for each, and every client's end-to-end flow is in checks/clients.sh.
Adding a tool, a flag or an error code touches every client at once; the build refuses a gap. CONTRIBUTING.md has the procedure.
Some documents are built from the code, and make ci fails when one is
stale:
| When you change | Run | It writes |
|---|---|---|
| a tool, or which surfaces reach it | make api |
API.md |
| a tool's arguments or a command's flags | make flags |
FLAGS.md |
| a quick-start example or its captured output | make quickstart |
the quick start pages |
the root LICENSE |
for d in python javascript go; do cp LICENSE clients/$d/; done |
the clients' copies |
The checks compare against the git index, so git add the regenerated files
before running make ci.
main is protected. A change reaches it through a pull request that has been
reviewed and whose Build, vet and test check passes. Two more jobs run on
Windows: one runs the .NET client's tests, and go-windows runs both Go
modules' tests, the named-pipe daemon transport's, and a smoke test of the
built mobium.exe. History stays linear: pull requests are
squash-merged, merge commits are off, force-pushes to main are refused, and a
merged branch is deleted.
- Branch from an up-to-date
main. - Make the change, with tests, and run
make ci. - Run the device check for what you touched, and say in the pull request which device and which result.
- Open the pull request against
main.
Read CHALLENGES.md. Most of the defects in it were found only by running against a real device, and several of the rest by a test that could not fail. A fixture cannot tell you what a platform does, and a measurement that comes back "zero" is not a result until it has been shown it can come back non-zero.
The design rule behind all of it is in PHILOSOPHY.md.