Metadata-Version: 2.4
Name: kivyforge
Version: 3.0.0.dev1
Summary: Declarative, PEP 621-aligned build toolchain for Kivy apps — successor to kivy-ios, python-for-android, and buildozer (iOS, Android, macOS, Linux, and Windows)
Author-email: The Kivy Team <kivy-dev@googlegroups.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ElliotGarbus/kivyforge
Project-URL: Source, https://github.com/ElliotGarbus/kivyforge
Project-URL: Bug Reports, https://github.com/ElliotGarbus/kivyforge/issues
Keywords: kivy,ios,android,toolchain,packaging,mobile,buildozer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: rich>=13
Requires-Dist: packaging>=24
Requires-Dist: pbxproj>=3.5
Requires-Dist: tomli-w>=1.1
Requires-Dist: pip>=25.1
Requires-Dist: Pillow>=10
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: pyright>=1.1.400; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocs-click>=0.8; extra == "docs"
Dynamic: license-file

# kivyforge


[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](https://opencollective.com/kivy)
[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](https://opencollective.com/kivy)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)

![PyPI - Version](https://img.shields.io/pypi/v/kivyforge)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/kivyforge)

[![kivyforge](https://github.com/ElliotGarbus/kivyforge/actions/workflows/kivyforge.yml/badge.svg)](https://github.com/ElliotGarbus/kivyforge/actions/workflows/kivyforge.yml)

kivyforge is a declarative, [PEP 621](https://peps.python.org/pep-0621/)-aligned
build toolchain for [Kivy](https://kivy.org) (and other Python) apps. You
describe your app once in `pyproject.toml`; kivyforge resolves your dependencies
into a lockfile and packages the app for the platform you target. It is the
successor to **kivy-ios**, **python-for-android**, and **buildozer**, unifying
their per-platform workflows behind a single declarative configuration.

The goal is one toolchain for every platform Kivy runs on — **Android, iOS,
Linux (including **Raspberry Pi**), macOS, and Windows**.

📖 **Documentation:** <https://elliotgarbus.github.io/kivyforge/> — installation,
quickstarts for every platform, the configuration and CLI reference, and
troubleshooting. Build it locally with `pip install -e ".[docs]"` then
`mkdocs serve`.

> **Status: early development — iOS + macOS + Linux (x86_64 and Raspberry Pi) + Windows + Android.**
> kivyforge targets **iOS** (resolve into `pylock.ios.toml`, download the official
> [`Python.xcframework`](https://www.python.org/downloads/) + prebuilt iOS
> wheels, generate an [Xcode](https://developer.apple.com/xcode/) project),
> **macOS** (resolve into `pylock.macos.toml`, bundle a relocatable
> [python-build-standalone](https://github.com/astral-sh/python-build-standalone)
> CPython + wheels into a signed, double-clickable `.app`), **Linux** (resolve
> into `pylock.linux.toml`, bundle a PBS gnu/glibc CPython + manylinux wheels into
> an [AppImage](https://appimage.org/) — with a run-from-folder AppDir substrate;
> `x86_64` PCs and `aarch64` **Raspberry Pi** boards, the latter cross-built from
> an x86_64 host),
> **Windows** (resolve into `pylock.windows.toml`, bundle a PBS MSVC CPython +
> `win_amd64` wheels into a run-from-folder `onedir` with a windowed launcher
> `.exe`, optionally Authenticode-signed), and **Android** (resolve into
> `pylock.android.toml`, assemble the official
> [python.org Android runtime](https://www.python.org/downloads/android/) +
> per-ABI `android_*` wheels into a generated Gradle project, and produce a
> signed `.apk`/`.aab` — with pyjnius as a prebuilt wheel, no per-app
> compilation). If you need a shipping toolchain today, use kivy-ios 2.x,
> python-for-android, or buildozer.

### Currently supported targets

| Target | Architectures | Output | Signing | Build host |
|---|---|---|---|---|
| [iOS](https://www.apple.com/ios/) device | arm64 (iPhone / iPad) | generated Xcode project → `.app` | Apple Developer signing via Xcode | macOS + [Xcode](https://developer.apple.com/xcode/) |
| iOS Simulator | arm64 | generated Xcode project → `.app` | none required | macOS + Xcode |
| [Android](https://www.android.com/) device / emulator | `arm64_v8a`, `x86_64` | generated Gradle/AGP project → `.apk` / `.aab` | auto debug keystore, or release keystore (v1–v4 schemes) | Windows, macOS, or Linux + JDK/Android SDK/NDK |
| [macOS](https://www.apple.com/macos/) | arm64 (Apple Silicon) | `.app` | ad-hoc (default) **or** Developer ID sign + notarize + staple | macOS (Apple Silicon) |
| [Linux](https://appimage.org/) | x86_64 (glibc ≥ 2.17), aarch64 | `.AppImage` / AppDir | none | Linux |
| [Raspberry Pi](https://www.raspberrypi.com/) (Pi 4 / Pi 5, 64-bit Raspberry Pi OS) | aarch64 | `.AppImage` (a Linux target — see [Build for Raspberry Pi](docs/guides/guides/linux/raspberry-pi.md)) | none | x86_64 Linux (cross-build; WSL2 works) |
| [Windows](https://learn.microsoft.com/windows/) | amd64 | `onedir` folder + windowed launcher `.exe` | optional Authenticode (unsigned by default) | Windows |

Desktop targets (macOS / Linux / Windows) bundle a self-contained runtime +
wheels; on Linux (including Raspberry Pi), libGL/EGL and X11/Wayland come from
the host. Raspberry Pi is built as `archs = ["aarch64"]` on the Linux backend;
you do not install kivyforge on the Pi. It is tested on a Raspberry Pi 5; the
Pi 4 is supported but untested, and 32-bit Raspberry Pi OS is not supported. Building for iOS
requires a Mac with Xcode; Android builds on any of the three desktop hosts.

**Apple targets are Apple Silicon only.** kivyforge does not build Intel (`x86_64`)
macOS apps or pin the Intel iOS-Simulator slice: macOS 27 stops installing on
Intel hardware and macOS 28 removes Rosetta, so an Intel slice would be one
nothing can execute or validate. `universal2` *wheels* are still resolved
normally — they contain arm64.

kivyforge builds on the work of the [Kivy Team](https://kivy.org/about.html).

## Requirements

Each target platform has its own host requirements. **Building for iOS requires
macOS** (Xcode-based), so the iOS workflow below is useful only on a Mac:

- macOS with the full [Xcode](https://developer.apple.com/xcode/) 15 or newer installed
  from the [Mac App Store](https://apps.apple.com/app/xcode/id497799835).
  (`xcode-select --install` installs only the command-line tools, which are
  not enough for iOS.) Point the tools at it:

      sudo xcode-select --switch /Applications/Xcode.app

- Accept the Xcode license once:

      sudo xcodebuild -license

**Building for Android** works from Windows, macOS, or Linux, and needs three
user-installed prerequisites (kivyforge never installs a host toolchain — it only
detects one):

- A **JDK 17 to 23** on `PATH` or `JAVA_HOME` (the range the pinned Gradle can
  run on; Android Studio's bundled JDK may be newer than that).
- The **Android SDK** (`ANDROID_HOME`/`ANDROID_SDK_ROOT`), with the `compile_sdk`
  platform, build-tools, platform-tools, and recorded SDK licenses (see the
  [Android quickstart](docs/guides/get-started/quickstart-android.md#sdk-licenses-and-sdkmanager)).
  Android Studio's SDK Manager covers all of it.
- The **NDK** — required for *every* Android build, not just apps with native
  code: it compiles the bootstrap's native launcher (`libmain.so`).

`kivyforge doctor -p android` checks each of these and prints the `sdkmanager`
command for whatever is missing. Add an AVD (or attach a device with USB debugging
enabled) before `kivyforge run`.

## Installation

kivyforge is a command-line tool and needs Python 3.13 or newer. It is on PyPI,
but every release so far is a **pre-release** (currently `3.0.0.dev1`). pipx and
pip skip pre-releases unless you opt in, so their commands below carry a
pre-release flag; uv picks a pre-release when no stable release exists, so it
needs none. The recommended installer is [uv](https://docs.astral.sh/uv/), which
installs it into its own isolated environment and puts `kivyforge` on your
`PATH`:

      uv tool install kivyforge

If your shell reports that `kivyforge` is not found, run `uv tool update-shell`
and open a new terminal. Upgrade or remove it later with
`uv tool upgrade kivyforge` / `uv tool uninstall kivyforge`.
Once a stable release is published, the pre-release flags are no longer needed.

Alternatives: [pipx](https://pipx.pypa.io/)
(`pipx install --pip-args="--pre" kivyforge`), or pip inside a virtual
environment so it does not collide with other projects:

      python3 -m venv .venv
      . .venv/bin/activate          # Windows PowerShell: .venv\Scripts\Activate.ps1
      pip install --pre kivyforge

Check the install with `kivyforge --version` and `kivyforge capabilities`. The
install also provides a short alias, `kf`. For the full walk-through, see
[Install kivyforge](https://elliotgarbus.github.io/kivyforge/get-started/install/).
To work on kivyforge itself, see [Development](#development).

> **Mobile examples need no local wheel-building.** Kivy (2.3.1 and 3.0),
> pyobjus, and pyjnius resolve from the
> [kivy-mobile-wheels](https://github.com/ElliotGarbus/kivy-mobile-wheels)
> index — a companion repo of first-party iOS/Android cross-builds published as
> a static PEP 503 index — so `kivyforge lock` just works against any mobile
> example. `scripts/build_ios_wheels.sh` / `scripts/build_pyobjus_ios_wheels.sh`
> remain for cross-building your own iOS wheels locally (e.g. to vendor one via
> a `path` lock instead of the index); neither is required to run the examples.
>
> **Desktop needs no wheel-building either.** The desktop examples under
> [`examples/desktop/`](examples/desktop/) build straight from PyPI — Kivy
> 2.3.1 ships universal2 macOS wheels, so there is no macOS wheel-building
> step. Kivy 3.0 has no public desktop wheels yet, which is why desktop
> examples stay on 2.3.1; the iOS mobile examples need 3.0 for its structural
> mobile changes, while the Android examples run either generation (2.3.1/SDL2
> for most, 3.0/SDL3 for `hello-sdl3`) depending on which bootstrap they gate.

> **Detailed documentation.** For the full design and reference docs — the
> cross-platform model, the `pyproject.toml` / `pylock.<platform>.toml` schemas,
> artifact distribution, the CLI shape, and the per-platform backends (Android,
> iOS, macOS, Linux, Windows) — start with the
> [kivyforge design overview](docs/design/common/00-overview.md).

## Quick start (iOS)

The workflow below targets iOS; see Quick start (Android), (macOS), (Linux),
and (Windows) further down for the other backends. Run every command from the
directory that contains your app's `pyproject.toml`.

      # 1. Seed [tool.kivy] / [tool.kivy.ios] config into pyproject.toml
      kivyforge init

      # 2. Resolve dependencies into pylock.ios.toml
      kivyforge lock

      # 3. Download artifacts and generate <app>-ios/<app>.xcodeproj
      kivyforge build

      # 4a. Open the project in Xcode and press Run...
      kivyforge open

      # 4b. ...or build, install, and launch on the simulator from the CLI
      kivyforge build --simulator
      kivyforge run --simulator

## Quick start (macOS)

macOS needs only the Xcode command-line tools (`codesign`), not the full Xcode
IDE. The macOS backend bundles a relocatable CPython + your wheels into a signed
`.app`:

      # 1. Seed [tool.kivy] / [tool.kivy.macos] config (or add the overlay by hand)
      kivyforge init            # then add a [tool.kivy.macos] table

      # 2. Resolve dependencies + pin the runtime into pylock.macos.toml
      kivyforge lock -p macos

      # 3. Build the .app (arm64)
      kivyforge build -p macos

      # 4a. Launch it (foreground, so you see stdout/tracebacks)
      kivyforge run -p macos

      # 4b. ...or produce the finished, signed distributable
      kivyforge package -p macos      # -> build/macos/<App>.app

`package` is config-driven: with no signing config it ships the **ad-hoc**-signed
`.app` (runs locally; downloaded copies hit Gatekeeper). For distribution to
other Macs, configure `[tool.kivy.macos.signing]` with a *Developer ID
Application* identity (paid Apple Developer Program) and a `notary_profile`
(created with `xcrun notarytool store-credentials`) — then the same command
deep-signs with Hardened Runtime, **notarizes, and staples** the `.app` so
Gatekeeper trusts it everywhere. `--no-notarize` skips the submission. (Hit
`errSecInternalComponent` from `codesign`? See the
[FAQ entry](FAQ.md#macos-developer-id-signing-fails-with-errsecinternalcomponent)
on corrupted keychain ACLs.)

`kivyforge doctor -p macos` reports environment + project health (host, codesign,
arch coverage, runtime floor, signing identity, notary setup, reachable hosts).

## Quick start (Linux)

The Linux backend bundles a relocatable CPython + your manylinux wheels into an
[AppImage](https://appimage.org/) (the default) or a run-from-folder **AppDir**.
It needs a Linux host (the runtime is a gnu/glibc build); no compiler or FUSE is
required at build time.

      # 1. Add a [tool.kivy.linux] table to pyproject.toml (app_id, icons, ...)

      # 2. Resolve dependencies + pin the runtime into pylock.linux.toml
      kivyforge lock -p linux

      # 3. Build the AppDir (build/linux/<App>.AppDir)
      kivyforge build -p linux

      # 4a. Launch it (runs ./AppRun directly — the fast dev loop, no FUSE)
      kivyforge run -p linux

      # 4b. ...or produce the distributable
      kivyforge package -p linux              # -> dist/linux/<app>-<ver>-x86_64.AppImage
      kivyforge package -p linux -f folder    # -> the AppDir itself

The AppImage embeds a **static-FUSE runtime**, so recipients need no `libfuse2`;
`./<App>.AppImage --appimage-extract-and-run` is the universal no-FUSE fallback.
The **host contract** is explicit: the bundle never vendors libGL/libEGL or a
display server, so the host must provide glibc ≥ the artifact's effective floor,
`libGL.so.1`/`libEGL.so.1`, and an X11 or Wayland session.

`kivyforge doctor -p linux` reports environment + project health (Linux/glibc
host, GL libraries, display session, glibc floor, arch coverage, generated
`.desktop` validity, reachable hosts).

### Raspberry Pi

Raspberry Pi is a first-class **Linux** target, not a separate platform. Set
`archs = ["aarch64"]` in `[tool.kivy.linux]`, then cross-build the AppImage on
an x86_64 Linux machine (WSL2 works) and copy it to a Pi 4 or Pi 5 running
64-bit Raspberry Pi OS with a desktop:

      kivyforge lock -p linux
      kivyforge package -p linux -f appimage --arch aarch64   # -> dist/linux/<app>-<ver>-aarch64.AppImage

On the Pi: `chmod +x <app>.AppImage && ./<app>.AppImage`. An `aarch64` build
cannot be launched with `kivyforge run` on the x86_64 host. See
[Build for Raspberry Pi](docs/guides/guides/linux/raspberry-pi.md) for the full
guide and scope.

## Quick start (Windows)

The Windows backend bundles a relocatable CPython + your `win_amd64` wheels into
a run-from-folder **`onedir`**: a windowed launcher `.exe` beside a full
python-build-standalone prefix, your app source, and any declared native
binaries. It needs a Windows host (the runtime is an MSVC amd64 build and the
resource/signing tools are Windows-only); no compiler is required at build time.

      # 1. Add a [tool.kivy.windows] table to pyproject.toml (app_id, icons, ...)

      # 2. Resolve dependencies + pin the runtime into pylock.windows.toml
      kivyforge lock -p windows

      # 3. Build the onedir bundle (build\windows\<App>\)
      kivyforge build -p windows

      # 4a. Launch it (runs the launcher .exe in the foreground — the dev loop)
      kivyforge run -p windows

      # 4b. ...or produce the distributable (copied to dist\windows\)
      kivyforge package -p windows            # -> dist\windows\<app>-<ver>-amd64\

Double-clicking the launcher opens the app with **no console flash**; `kivyforge
run` attaches it to the terminal so stdout/stderr and tracebacks are visible. The
`onedir` folder keeps every file real and signable — installers stay external.
**Authenticode signing** is optional and off by default: configure
`[tool.kivy.windows.signing]` with a certificate-store `thumbprint` and `package`
signs (and RFC-3161 timestamps) the launcher in the `dist\windows` copy.

`kivyforge doctor -p windows` reports environment + project health (Windows host,
long-path support, `app_id` style, arch coverage, icon, native-binary
sources/collisions/arch, build-output lock, build volume (Dev Drive advisory),
reachable hosts, signtool + signing certificate).

## Quick start (Android)

The Android backend assembles the official
[python.org Android runtime](https://www.python.org/downloads/android/) + your
`android_*` wheels into a generated **Gradle/AGP** project and produces a
signed **`.apk`** (sideload/CI) or **`.aab`** (Play upload) — a wheel-assembly
and Gradle-drive backend, no python-for-android recipe system, no per-app C
compilation. It needs a JDK, the Android SDK, and the NDK, but builds on
Windows, macOS, or Linux. 64-bit only (`arm64_v8a`, `x86_64`).

      # 1. Seed [tool.kivy] + [tool.kivy.android] into pyproject.toml
      kivyforge init -p android               # then set `package`, kivy_generation, ...
      #    If your app depends on kivy or pyjnius, uncomment `extra_index_urls`
      #    in [tool.kivy.android] (see "Android wheels" below).

      # 2. Resolve dependencies + pin the runtime into pylock.android.toml
      kivyforge lock -p android

      # 3. Generate the Gradle project (<app>-android/) and assemble a debug APK
      kivyforge build -p android --debug      # -> <app>-android/app/build/outputs/apk/debug/

      # 4a. Install and launch on a connected device or emulator
      kivyforge run -p android --emulator

      # 4b. ...or produce the signed release distributable
      kivyforge package -p android            # -> <app>-android/app/build/outputs/apk/release/
      kivyforge package -p android -f aab     # -> .../outputs/bundle/release/ (Play upload)

**Android wheels.** Kivy has no Android wheel on PyPI, so `kivyforge lock -p android`
fails with "pip could not resolve the Android ABI" until you point it at the
first-party [kivy-mobile-wheels](https://github.com/ElliotGarbus/kivy-mobile-wheels)
index. `kivyforge init -p android` writes the line commented out; uncomment it
(this is the recommended route, and needs no wheel-building):

      [tool.kivy.android]
      extra_index_urls = ["https://elliotgarbus.github.io/kivy-mobile-wheels/simple/"]

The index carries Kivy and pyjnius only. Every other dependency must already
publish an `android_*` wheel, or you supply one in a directory listed in
`find_links` (cross-building your own wheel). The error names the package pip
could not find, so check it before changing anything else. `lock` uses the pip
that ships inside kivyforge, not the one in your app's virtual environment.

Without `--debug`, step 3 stops after generating the project — ready to open in
Android Studio (`kivyforge open -p android`) or to drive `gradlew` by hand.

`kivy_generation = 2` targets Kivy 2.3.1 (SDL2, stable); `kivy_generation = 3`
targets Kivy 3.0 (SDL3, pre-release) — mutually exclusive per app, and the SDL
Java glue + `libSDL*.so` must come from the same release (`kivyforge build`
fails fast on a mismatch rather than the silent black-screen failure that
would otherwise produce).
Debug builds sign with an auto-managed debug keystore; `package` requires a
configured release keystore (`[tool.kivy.android.signing]`, passwords from
environment variables, never in `pyproject.toml`).

`kivyforge doctor -p android` reports environment + project health
(JDK/SDK/build-tools/NDK/emulator/adb, the SDL↔Kivy pairing, the pyjnius
`invoke0` contract, a hermetic 16 KB page-alignment scanner, ABI coverage,
signing, lock-host reachability). `kivyforge run --smoke` runs a generated
instrumented contract test on a real device/emulator — validated on an x86_64
API-31 emulator and a Pixel 8a (Android 16 / API 36) for both SDL2 and SDL3.

See the runnable examples for complete, copy-pasteable walk-throughs. They are
split by runtime requirement — **desktop uses Kivy 2.3.1 from PyPI, mobile
resolves Kivy (2.3.1 and 3.0) from the
[kivy-mobile-wheels](https://github.com/ElliotGarbus/kivy-mobile-wheels)
index**:

**Desktop** ([`examples/desktop/`](examples/desktop/)) — macOS/Linux/Windows:

- [`dice-roller`](examples/desktop/dice-roller/) — minimal Kivy UI that **builds &
  runs on macOS, Linux (x86_64 and Raspberry Pi), and Windows today** from PyPI
  (Kivy 2.3.1).
- [`notes`](examples/desktop/notes/) — Kivy app with a pure-Python dependency
  (`platformdirs`); builds on macOS, Linux, and Windows from PyPI.
- [`desktop-viewer`](examples/desktop/desktop-viewer/) — a **macOS-only** Kivy app
  (resizable window, ⌘ keyboard shortcuts, and Finder's native open panel via
  `osascript`); no Linux/Windows overlay.
- [`hello-native`](examples/desktop/hello-native/) — ships **non-wheel** native
  binaries (a helper executable + a shared library) via
  `[tool.kivy.<platform>.native.binaries]`; builds and runs on macOS, Linux, and
  Windows (`greet.dll` loaded by name, `roll.exe` run by name).

**Mobile** ([`examples/mobile/`](examples/mobile/)) — iOS and Android; iOS on
Kivy 3.0, Android on either generation (wheels from
[`kivy-mobile-wheels`](https://github.com/ElliotGarbus/kivy-mobile-wheels)):

*iOS:*

- [`hello-world`](examples/mobile/hello-world/) — Kivy-free toolchain smoke test;
  no dependencies, no wheels (builds on iOS via the python.org `Python.xcframework`;
  the first example to bring up a new backend).
- [`hello-kivy`](examples/mobile/hello-kivy/) — minimal Kivy 3.0 UI.
- [`mobile-geometry`](examples/mobile/mobile-geometry/) — showcases the
  `kivy.mobile` runtime-geometry API (DPI, safe-area insets, keyboard height).
- [`svg-explorer`](examples/mobile/svg-explorer/) — interactive SVG viewer
  (multitouch pan/zoom/rotate).
- [`pyobjus-ball`](examples/mobile/pyobjus-ball/) — calls native iOS APIs
  (CoreMotion, UIScreen) from Python via the Objective-C runtime.
- [`pyobjus-deviceinfo`](examples/mobile/pyobjus-deviceinfo/) — reads native iOS
  device info (model, system version, battery) via pyobjus; a CPython 3.15
  pre-release example.
- [`keychain-spm`](examples/mobile/keychain-spm/) — declares a remote Swift Package
  (`KeychainAccess`), pins it with `kivyforge lock`, and calls it from Python
  through a local `@objc` shim package.

*Android:*

- [`hello-android`](examples/mobile/hello-android/) — the smallest kivyforge
  Android app (a single `Label`); the Kivy 2.3.1 / SDL2 on-device gate.
- [`hello-sdl3`](examples/mobile/hello-sdl3/) — the same app on **Kivy 3.0 /
  SDL3**; deliberately identical to `hello-android` apart from the SDL
  generation, and the SDL3 on-device gate.
- [`pyjnius-deviceinfo`](examples/mobile/pyjnius-deviceinfo/) — reads Android
  device info (`Build`, `BatteryManager`, display metrics) via pyjnius, no
  Java written.
- [`qr-maven`](examples/mobile/qr-maven/) — renders a QR code with Google's
  ZXing, resolved as a Gradle/Maven coordinate (channel 4) and driven from
  Python via a pyjnius `invoke0` round-trip.

## Configuring your app

Your app is described declaratively in `pyproject.toml`. Standard
[PEP 621](https://peps.python.org/pep-0621/) `[project]` metadata supplies the
name, version, and runtime `dependencies`; shared, platform-neutral settings live
under `[tool.kivy]`, and iOS-specific settings live under `[tool.kivy.ios]`
(each other platform has its own `[tool.kivy.<platform>]` table — `macos`,
`linux`, `windows`, `android`):

```toml
[project]
name = "hello-world"
version = "0.1.0"
requires-python = ">=3.15.0b4"
dependencies = []                       # PyPI/local deps resolved into the lockfile

[tool.kivy]
display_name = "Hello World"            # name shown under the icon
app_dir = "src"                         # folder containing your Python source
entry_point = "main"                    # module run as __main__ at launch (main.py)
orientation = ["portrait"]

[tool.kivy.ios]
bundle_id = "org.example.hello-world"   # reverse-DNS; UTI characters only (no underscores)
build = 1
deployment_target = "16.0"
# find_links = ["../../wheels/ios"]     # repo-relative wheel directory for lock
# exclude = ["docutils", "pygments"]    # drop transitive deps you don't use at runtime

[tool.kivy.ios.python]
version = "3.15.0b4"                     # python.org Python.xcframework version

[tool.kivy.ios.signing]
team_id = ""                            # Apple Developer Team ID (device / release builds)
identity = "Apple Development"
auto_signing = true
```

`kivyforge build` syncs your `app_dir` into the generated `<app>-ios/` tree on
every run, so make changes in your source folder (e.g. `src/`), never in the
generated project.

Kivy's wheel declares dependencies that are not all needed at runtime on iOS.
The `exclude` list trims them; the
[hello-kivy example](examples/mobile/hello-kivy/pyproject.toml) documents what each one
is for, so you can re-enable only the few that map to widgets you actually use
(e.g. `docutils` for `RSTDocument`, `pygments` for `CodeInput`, or `requests`
for `UrlRequest`).

## Commands

The verbs are platform-neutral; each resolves a target from `-p/--platform`, the
`KIVYFORGE_PLATFORM` environment variable, or the host default, and then does the
platform's version of the same job. `init` is the one exception: `-p` is
repeatable there (`-p ios -p android`), since seeding several platforms into
one `pyproject.toml` is its normal use case — every other verb builds, runs,
or packages exactly one target per invocation.

      kivyforge init       Seed [tool.kivy] + the target's overlay into pyproject.toml
      kivyforge lock       Generate pylock.<platform>.toml from pyproject.toml
      kivyforge build      Download artifacts, generate the native project, build
      kivyforge run        Build (unless --no-build), install, and launch the app
      kivyforge package    Produce the signed, distributable artifact
      kivyforge open       Open the generated project in Xcode / Android Studio
      kivyforge status     Show app identity, Python version, lock sync, build state
      kivyforge clean      Remove generated artifacts in the project folder
      kivyforge upgrade    Re-fetch the pinned runtime and native artifacts
      kivyforge doctor     Run environment and project health checks

Run `kivyforge <command> -h` (or `kf <command> -h`) for the full set of
options on any verb. A few common ones:

- `kivyforge init -p ios -p android` — seed several platforms' overlays in one run.
- `kivyforge lock --check` — CI pre-flight; exits non-zero if the lock is stale.
- `kivyforge build --simulator | --device | --release` (iOS) — pick the build flavor.
- `kivyforge build --debug [--abi arm64_v8a|x86_64]` (Android) — assemble a debug APK, optionally for one ABI.
- `kivyforge run --list-devices` — list available simulators/emulators and devices.
- `kivyforge run --smoke` (Android) — run the generated on-device contract test.
- `kivyforge run --release` (Android, Linux, macOS, Windows) — build and launch the release flavor, to exercise `byte_compile`/`strip_source` outside of `package`.
- `kivyforge clean --cache` — also flush the artifact download cache.

Downloaded artifacts (`Python.xcframework`, the per-ABI Android runtime,
`.aar`/`.jar`s, runtime archives) are cached per-user and shared across projects.

Every verb but `run` also takes `--json`, for scripting or driving kivyforge
from an agent — see [Working with agents](#working-with-agents) below.

## Typical workflow

A normal session is a one-time setup followed by a tight edit → run loop. You only
re-run `kivyforge lock` when dependencies change, and `kivyforge build` when you
change app config (or need to regenerate the native project).

How cheap the inner loop is depends on the platform. On **iOS** the generated
project *links* your source directory (`app/` is a symlink to `app_dir`), so
editing Python source needs no rebuild — just relaunch. On **Android** the app's
code is packed into the APK's asset bundle, so a source edit needs a re-pack:
`kivyforge run` does that for you every iteration, which is why the Android loop
goes through `run` rather than a bare relaunch.

```mermaid
flowchart TD
    A["kivyforge init<br/>seed pyproject.toml"] --> B["Edit pyproject.toml<br/>dependencies + app config"]
    B --> C["Write your app<br/>src/main.py"]
    C --> D["kivyforge lock<br/>→ pylock.&lt;platform&gt;.toml"]
    D --> E["kivyforge build<br/>fetch artifacts + generate the native project"]
    E --> F{"Launch it"}
    F -->|from the CLI| G["kivyforge run<br/>--simulator / --emulator / --device"]
    F -->|from the IDE| H["kivyforge open → Xcode ⌘R / Android Studio Run"]
    G --> I(["Iterate"])
    H --> I
    I -->|changed Python source| F
    I -->|changed app config| E
    I -->|changed dependencies| D
```

Supporting commands fit around this loop: `kivyforge status` shows whether your
lock and build are current, `kivyforge doctor` diagnoses environment problems,
`kivyforge upgrade` re-fetches the pinned runtime, and `kivyforge clean` resets
the generated project when you want a fresh build.

## Working with agents

kivyforge is designed to also be driven non-interactively — by CI, or by an
agent (Claude Code and similar) building or maintaining a Kivy app on your
behalf. No verb prompts for input, and every verb but `run` accepts `--json`.

- **Discover capabilities first:** `kivyforge capabilities --json` lists every
  platform, its architectures and package formats, **which hosts can build
  which targets**, every verb and whether it takes `--json`, and the exit-code
  and `KF-*` diagnostic-code vocabularies. It needs no project, lock, or
  network access, so it's the right first call before touching a real project.
- **`--json` puts exactly one envelope on stdout** —
  `{"schema", "kivyforge", "command", "platform", "ok", "data", "diagnostics"}`
  — on success *and* on every failure. Progress and log lines go to stderr, so
  a build log and a parseable result coexist on the same run.
- **Branch on the exit code first, then `diagnostics[].code`**: `1` — fix
  `pyproject.toml`; `2` — a bad flag (click's own usage error; kivyforge never
  raises it); `3` — fix the machine (missing toolchain); `4` — the lock is
  stale, re-run `kivyforge lock`; `5` — a build genuinely failed, read the log
  on stderr. The code is a stable contract; the human-readable message next to
  it is not, and may be reworded across releases.
- **`diagnostics` on an `ok: true` run are warnings, not failures** — an
  unsigned package, a byte-compile that silently degraded to shipping source,
  a resolver policy note. Read them; don't treat `ok: true` as "nothing to
  look at."
- **Build/package outputs are `data.artifacts`**, as `{"path", "kind"}` pairs
  relative to the project root, always posix-spelled — read that instead of
  guessing the layout, and only trust artifacts a run reports for *itself*: a
  failed run's `artifacts` never names a stale file left over from a previous
  one.
- **`run` is the one verb without `--json`.** It hands your app's own process
  the console directly (stdout/stderr pass through untouched), which is the
  point of the verb; script against `build`/`package` plus `status --json`
  instead.

## Development

Clone the repository and install it into a virtual environment:

      git clone https://github.com/ElliotGarbus/kivyforge.git
      cd kivyforge/
      python3 -m venv .venv
      . .venv/bin/activate
      pip install -e ".[dev]"

Run the test suite and the linter:

      pytest
      ruff check .

## FAQ

For troubleshooting advice and other frequently asked questions, consult
the latest 
[kivyforge FAQ](https://github.com/ElliotGarbus/kivyforge/blob/main/FAQ.md).

## License

kivyforge is [MIT licensed](LICENSE), and builds on work actively developed by a
great community and supported by many projects managed by the 
[Kivy Organization](https://www.kivy.org/about.html).

## Support

Are you having trouble using kivyforge or any of its related projects in the Kivy
ecosystem?
Is there an error you don’t understand? Are you trying to figure out how to use 
it? We have volunteers who can help!

The best channels to contact us for support are listed in the latest 
[Contact Us](https://github.com/ElliotGarbus/kivyforge/blob/main/CONTACT.md) document.

## Contributing

kivyforge builds on the [Kivy](https://kivy.org) ecosystem - a large group of
products used by many thousands of developers for free, but it
is built entirely by the contributions of volunteers. We welcome (and rely on) 
users who want to give back to the community by contributing to the project.

Contributions can come in many forms. See the latest 
[Contribution Guidelines](https://github.com/ElliotGarbus/kivyforge/blob/main/CONTRIBUTING.md)
for how you can help us.

## Code of Conduct

In the interest of fostering an open and welcoming community, we as 
contributors and maintainers need to ensure participation in our project and 
our sister projects is a harassment-free and positive experience for everyone. 
It is vital that all interaction is conducted in a manner conveying respect, 
open-mindedness and gratitude.

Please consult the [latest Kivy Code of Conduct](https://github.com/kivy/kivy/blob/master/CODE_OF_CONDUCT.md).

## Contributors

This project exists thanks to 
[all the people who contribute](https://github.com/ElliotGarbus/kivyforge/graphs/contributors).
[[Become a contributor](CONTRIBUTING.md)].

<img src="https://contrib.nn.ci/api?repo=ElliotGarbus/kivyforge&pages=5&no_bot=true&radius=22&cols=18">

## Backers

Thank you to [all of our backers](https://opencollective.com/kivy)! 
🙏 [[Become a backer](https://opencollective.com/kivy#backer)]

<img src="https://opencollective.com/kivy/backers.svg?width=890&avatarHeight=44&button=false">

## Sponsors

Special thanks to 
[all of our sponsors, past and present](https://opencollective.com/kivy).
Support this project by 
[[becoming a sponsor](https://opencollective.com/kivy#sponsor)].

Here are our top current sponsors. Please click through to see their websites,
and support them as they support us. 

<!--- See https://github.com/orgs/kivy/discussions/15 for explanation of this code. -->
<a href="https://opencollective.com/kivy/sponsor/0/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/1/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/2/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/3/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/3/avatar.svg"></a>

<a href="https://opencollective.com/kivy/sponsor/4/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/5/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/6/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/7/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/7/avatar.svg"></a>

<a href="https://opencollective.com/kivy/sponsor/8/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/9/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/9/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/10/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/10/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/11/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/11/avatar.svg"></a>

<a href="https://opencollective.com/kivy/sponsor/12/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/12/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/13/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/13/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/14/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/14/avatar.svg"></a>
<a href="https://opencollective.com/kivy/sponsor/15/website" target="_blank"><img src="https://opencollective.com/kivy/sponsor/15/avatar.svg"></a>
