Compiles the project then pushes BEAM files to a frozen set of selected Android and iOS devices.

Modes

Fast deploy (default) — load the new BEAMs into the app. Use this for day-to-day Elixir code changes. Requires the native app already installed on device. When the app's node is reachable over Erlang distribution, the modules are hot-loaded in place with no restart; otherwise the BEAMs are written to the device and the app is restarted to pick them up. An app built against a pre-MOB-49 mob is restarted instead of hot-loaded, which moves it to its private cookie, except on a physical iPhone: writing BEAMs to a phone over devicectl has no undo, so a connected legacy iPhone app is still hot-loaded and keeps mob_secret until you deploy with --native.

mix mob.deploy

Full deploy — build native binary + install APK/app + push BEAMs + restart. Use this the first time, or after changes to native C/Java/Swift/Zig code.

mix mob.deploy --native

Plugin NIFs only reach the device through a native build. --native warns about deps that ship a NIF but aren't in config :mob, :plugins, and records which NIF plugins it built in; a fast deploy warns when a NIF plugin was activated since that record (see MobDev.Plugin.NifActivation). Both are warnings — otherwise the first sign is :nif_not_loaded at the first call.

Device selection is resolved once before any build or push starts. With no selection flag, one emulator or simulator is selected automatically and the task prints which; physical devices always require an explicit --device or --all-physical. The ANDROID_SERIAL environment variable is treated like --device for Android.

When agent-device is on PATH, selection honours its device claims (MobDev.DeviceLeases): auto-selection and --all-devices / --all-physical skip a device another agent-device session has claimed, and say so. A claim is yours when its session matches AGENT_DEVICE_SESSION. A claimed device named with --device is still used, after a warning.

Options

• --native — build native binaries before pushing BEAMs

• --no-restart — write the BEAMs without restarting the app (a

                       hot load over dist never restarts anyway)

• -d, --device <id> — target a specific device; use mix mob.devices to find IDs

• --all-devices — target all emulators and simulators

• --all-physical — target all physical devices; combine with

                       `--all-devices` to target every connected device

• --dist-port <N> — pin the BEAM dist listen port (default: derived per

                      device from the device serial and app name, in
                      `9100..9899`, moved past ports another device already
                      uses; `mix mob.connect` derives the same port). Use to
                      resolve a collision with a non-BEAM listener on that port.

• --node-suffix <S> — append _<S> to the BEAM node name (default: auto-derived

                      from device serial on Android, SIMULATOR_UDID on iOS sim). Use
                      for scripted scenarios where you need a specific naming scheme.

• --schedulers <N> — set BEAM scheduler count (saved to mob.exs)

• --beam-flags "<flags>" — arbitrary BEAM flags string (saved to mob.exs)

• --json — machine-readable result on stdout; progress goes to

                      stderr, so `mix mob.deploy --json | jq` gets one document

• --slim — strip OTP source/debug for size measurement on

                        a real device. OFF by default for dev iteration
                        (the strip pass adds ~5-10s per build); use this
                        to verify a slim build runs before
                        `mix mob.republish` round-trips through TestFlight.
                        The strip set is controlled by `MobDev.OtpAudit.Slim`;
                        per-app overrides live in `mob.exs`:
  
                            config :mob_dev,
                              slim: [
                                drop_libs: ["my_unused_dep"],
                                keep_libs: ["mnesia"],
                                audit: true,                       # opt in
                                # Single capture (a starting point):
                                trace_json: "priv/mob_trace.json",
                                # OR multiple captures unioned —
                                # much safer for production
                                # stripping. A lib is trace-
                                # strippable only if NONE of the
                                # captures observed any of its
                                # modules.
                                trace_jsons: [
                                  "priv/boot.json",
                                  "priv/ui.json",
                                  "priv/auth.json"
                                ]
                              ]
  
                        With `audit: true`, the slim pass runs
                        `MobDev.OtpAudit` against the bundle and
                        expands the strip set with foreign apps
                        + (when a trace is supplied) the
                        trace-augmented strip set. Trace JSON
                        comes from `mix mob.trace_otp --json`.

BEAM scheduler tuning

The default native build uses 1:1 (single scheduler) for battery efficiency. Override for the current deploy and all future deploys until changed:

# Pin to 2 schedulers
mix mob.deploy --schedulers 2

# Let BEAM auto-detect — one scheduler per logical core
mix mob.deploy --schedulers 0

# Arbitrary flags (replaces --schedulers)
mix mob.deploy --beam-flags "-S 4:4 -A 4"

The chosen value is written to mob.exs under beam_flags: and reused on subsequent mix mob.deploy runs that don't pass either flag. The flags are written alongside the BEAMs as a mob_beam_flags file that the native launcher reads at startup — no APK/app rebuild required.

Under the hood

A fast deploy is equivalent to:

mix compile

# Each target whose app answers over Erlang distribution: hot load in
# place, no restart — `nl(Module)` in IEx for every module
:rpc.call(node, :code, :load_binary, [Module, path, beam_binary])

# Any other Android target: copy the BEAMs into the app's files, restart
adb push <beams> /data/data/<package>/files/otp/<app>/   # as root (emulator), or
                                                        # via /data/local/tmp + `run-as tar xf`
adb shell am force-stop <package>
adb shell am start -n <package>/.MainActivity --ei mob_dist_port <port> ...

# Any other iOS simulator: copy into the simulator runtime, relaunch
rsync -a <compile path>/ ~/.mob/runtime/ios-sim/<app>/
xcrun simctl launch <udid> <ios bundle id>

# Any other physical iPhone: replace Documents/otp/<app>, relaunch
xcrun devicectl device copy to --device <udid> ... Documents/otp/<app>

The BEAMs come from Mix's active build path (Mix.Project.compile_path/0 and Mix.Project.build_path/0): the app and its runtime dependencies, never dev-only tooling.

With --native, it first runs mix deps.get and the platform build, installs the result, then writes the BEAMs and restarts (never a hot load: the old BEAM is gone after an install):

# Android
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

# iOS: ios/build.zig (simulator) or ios/build_device.zig (device), then
xcrun simctl install <udid> <app>.app            # simulator
xcrun devicectl device install app --device <udid> <app>.app   # device

A named --device supplies the platform when --native is used, so mix mob.deploy --native --device <id> does not also need --android or --ios. Before an Android build, the task creates android/local.properties when the SDK is detectable, just as mix mob.install does during first-run setup.

Exit status

Every targeted device is attempted and the full summary printed, then the task exits non-zero if any device landed in the Failed on N device(s) bucket — including a partial success where other devices deployed fine.

Devices under Skipped on N device(s) (app not installed for that platform) do not fail an implicit single-emulator run. They do fail when an explicit device, broad scope, or platform was requested and nothing reached that target platform:

• mix mob.deploy --ios --device X where X lacked the app — exit 1.
• mix mob.deploy --all-devices where every selected iOS simulator was skipped — exit 1 for the requested iOS target set.
• mix mob.deploy --ios --all-devices where one simulator deployed and a stale one was skipped — exit 0. The rule remains per platform.
• mix mob.deploy --device X that reached X and deployed nothing — exit 1.
• mix mob.deploy --device NOPE matching no device — exit 1.
• mix mob.deploy --android --native that built the APK with no device attached — exit 0. The artifact is what was asked for.

--native fails the run when a platform you named — directly or through --device — built nothing at all. If the Android SDK cannot be detected, a missing sdk.dir therefore produces a non-zero exit instead of a warning followed by success.