Configuration

Everything whitehall.toml accepts. Only [project] and [app] are required; every other table has defaults.

[project]

Key	Meaning
`name`	Project name. Also the source of the default app icon.
`version`	App version.

[project]
name = "my-app"
version = "0.1.0"

[app]

Key	Default	Meaning
`package`	required	Application ID, e.g. `com.example.myapp`
`min_sdk`	`24`	Oldest Android supported
`target_sdk`	—	API level the app targets
`compile_sdk`	derived	Override only. Whitehall picks the floor the bundled AndroidX libraries need; setting it lower fails in Gradle's AAR metadata check
`icon`	—	Path to a PNG. Omit for the default icon
`icons`	—	Named variants, as a table
`notification_icon`	—	Status bar icon. See App Icon
`predictive_back`	`false`	Android's back preview gesture. See Navigation Hooks
`deep_link`	—	URL scheme. See Deep Links
`permissions`	`[]`	Extra manifest permissions. $permission already declares what it names
`manifest_additions`	—	Raw XML spliced into `AndroidManifest.xml`, for what nothing else covers

[app]
package = "com.example.myapp"
min_sdk = 24
target_sdk = 36
icon = "static/icon.png"
predictive_back = true
deep_link = "myapp"

[app.icons]
default = "static/icon-default.png"
dark = "static/icon-dark.png"

permissions is for what cannot be inferred — permissions that follow from runtime behavior, or that get granted out of band with pm grant. Anything $permission() names is added to the manifest for you, so there is nothing to declare twice.

[theme]

Key	Meaning
`preset`	`"shadcn"` (default), `"material3"` or `"none"`. Chooses the component library and what paints it — see Theming
`base_color`	Which neutral ramp the palette is built on. `"shadcn"` only
`colors`	Per-token overrides, inline

[theme]
preset = "shadcn"

[theme.colors]
primary = "#0F172A"

A theme.toml beside whitehall.toml is found automatically and sits between the preset and these inline overrides. See Theming.

[toolchain]

Pin the versions Whitehall downloads and builds with:

[toolchain]
java = "21"
gradle = "8.4"
agp = "8.2.0"
kotlin = "2.0.0"

Omit the table entirely to track Whitehall's tested set. See Toolchain.

[build]

Key	Default	Meaning
`output_dir`	`"build"`	Where the generated Gradle project goes
`optimize_level`	—	Release optimization level

[env]

Key	Meaning
`debug` / `release`	Env file for each build type
`flavors`	Named env files beyond debug and release
`public_prefix`	The prefix that marks a variable safe to compile in. Defaults to `PUBLIC_`

[env]
debug = ".env.debug"
release = ".env.release"

See $env — only prefixed variables compile into the app, and reading any other from .wh is a build error.

[wear]

[wear]
min_sdk = 30
target_sdk = 36

[wear.dependencies]
"androidx.wear.compose/compose-material" = "1.3.0"

See Wear OS.

[ffi]

Native builds are configured per language. See FFI.

Key	Meaning
`enabled`	Turn native builds on or off explicitly
`ffi_only`	Build the native side and nothing else
`cpp.standard`	C++ standard, e.g. `"c++17"`
`cpp.flags`	Extra compiler flags
`cpp.libraries`	Libraries to link
`rust.profile`	Cargo profile
`rust.targets`	ABIs to build for
`cpp.library_name` / `rust.library_name`	Override the output library name

[ffi.rust]
profile = "release"
targets = ["aarch64-linux-android", "x86_64-linux-android"]

[ffi.cpp]
standard = "c++17"

Dependencies

Four tables, by when the dependency is needed:

[dependencies]
"io.coil-kt/coil-compose" = "2.6.0"

[build-dependencies]
"com.google.devtools/ksp" = "2.0.0-1.0.21"

[dev-dependencies]
"io.mockk/mockk" = "1.13.9"

[android-dev-dependencies]
"androidx.test.espresso/espresso-core" = "3.5.1"

Table	Goes to
`dependencies`	`implementation`
`build-dependencies`	Annotation processors and Gradle plugins
`dev-dependencies`	`testImplementation` — JVM tests
`android-dev-dependencies`	`androidTestImplementation` — instrumented tests

Prefer whitehall deps add over editing these by hand — it resolves the version for you.

Configuration

[project]

[app]

[theme]

[toolchain]

[build]

[env]

[wear]

[ffi]

Dependencies

See Also