> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bach builds Windows installers from one bach.toml with the bach command: bach init, bach check, bach preview, bach build. Installs are per user and need no administrator rights by default. installer.scope = "machine" installs for every user after one Windows prompt. On Windows, run setup files with Start-Process -Wait -PassThru in PowerShell, and give signtool arguments that start with the word sign.

# [installer]: look, folder, options, languages and license

> Reference for the [installer] section of bach.toml: output, theme, accent, logo, compression, install folder, the four option values, languages and license.

The `[installer]` section controls how the setup file looks, where it installs, which options the user sees, which languages the window speaks and which license it shows. Every setting is optional.

## Look

| Setting | Default | Meaning |
| - | - | - |
| `output` | `dist/{name}-Setup-{version}.exe` | Where the setup file goes. `{name}`, `{version}` and `{id}` are filled in. |
| `theme` | `system` | `system` follows Windows' light or dark setting, live. `light` or `dark` fixes it. A style that looks best dark starts dark unless you set this. |
| `style` | `bach` | The window's built-in style, like `"aurora"` or `"arcade"`: its colours, fonts and corners. Without it every app gets Bach's own style. See [`[style]`](/docs/reference/config/style) for all 14 and how to change them. |
| `accent` | none (black in light mode, white in dark) | A colour like `#2563eb` for buttons, the progress bar and ticked boxes. The button text picks black or white for contrast. |
| `logo` | your icon, else the Bach mark | An `.svg` or `.png` shown at the top of the window, or `"none"` for no logo at all. An SVG is drawn in one colour that follows the theme, so use a PNG for a full-colour logo. A wide PNG (a wordmark) keeps its shape. Give a PNG twice the size it is shown at for sharp results. |
| `logo_height` | `56` | The logo's height in points, 32 to 96. |
| `compression` | `best` | `best` makes the smallest file, `normal` and `fast` build quicker. Unpacking is fast either way. `bach build --fast` overrides it once. |
| `compression_threads` | as many as the memory budget allows | How many threads compress, from 1 to 256 (never more than the processor cores). The setup file is the same whatever the number. |
| `compression_memory` | `1024` | The memory budget for compressing, in MiB (64 to 65536). It holds the number of threads back, but one thread always runs, and the build says so when it does. See [what compressing costs](#what-compressing-costs). |
| `online` | `false` | `true` also builds the [online installer](#online-and-offline-installers). Needs [`[updates]`](/docs/reference/config/updates). `bach build --online` does the same once. |
| `online_output` | `dist/{name}-Web-Setup.exe` | Where the online installer goes. It has no version in its name, so one download link keeps pointing at the newest. With `github` set, it is named the way GitHub serves a release download. |

## What compressing costs

Measured with a Release build on 300 MB of mixed files (half random, half text) on 12 cores. The setup file's size does not change with the thread count.

| Level | Threads | Peak memory | Time |
| - | - | - | - |
| `best` (zstd 19) | 1 / 4 / 12 | 291 / 714 / 961 MB | 172 / 76 / 68 s |
| `normal` (zstd 9) | 1 / 4 / 12 | 156 / 299 / 443 MB | 2.1 / 1.4 / 1.5 s |
| `fast` (zstd 3) | 1 / 4 / 12 | 83 / 140 / 268 MB | 1.2 / 1.1 / 1.1 s |

`best` takes the most memory, so by default a build keeps it under `compression_memory` (1024 MB) by using fewer threads: 6 of 12 here, with a peak of 880 MB. In a container with a memory limit, set `compression_memory` below it, or `compression_threads = 1`.

## Online and offline installers

`bach build` writes the **offline installer**: one setup file that carries the app, installs without a network and always installs the version it was built from.

With `online = true` it also writes the **online installer**: a small setup file with the same window and choices and no files. When it runs, it reads the [update feed](/docs/guides/updates.md#how-an-installed-app-knows-what-is-new), downloads the newest full setup file, checks it and installs from that. It installs what is current, not what was current when it was built.

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[installer]
online = true

[updates]
github = "owner/repo"
```

```console theme={"theme":{"light":"github-light","dark":"github-dark"}}
$ bach build
Wrote dist\Hello-Setup-1.4.0.exe (9.7 MB)
Wrote dist\Hello-Web-Setup.exe (8.9 MB), the online installer
```

* The download is checked three ways before anything runs: its SHA-256 against the feed's, that it is a setup file for the same app id, and that it carries the version the feed names.
* It needs a network and the feed. If either is missing, the window says so and "Try again" resumes the download.
* Choices a newer version added, like a new component that is ticked by default, are carried over.
* The feed always describes the full setup file, never the online one. The Bach action [signs and publishes both](/docs/guides/ci.md).
* It never shows the "older version" page, because it cannot know which version it will install.

## Where it installs

| Setting | Default | Meaning |
| - | - | - |
| `scope` | `"user"` | `"user"` installs for the person who runs setup and needs no administrator rights. `"machine"` installs for every user of the computer, into `%ProgramFiles%`, and Windows asks for administrator rights once. See [machine-wide installs](/docs/guides/machine-wide-installs.md). |
| `folder` | the app id | The install folder's name under `%LOCALAPPDATA%\Programs` (`%ProgramFiles%` with `scope = "machine"`). When the user picks another place, this name is added to it. |
| `change_folder` | `true` | Whether the user may pick another folder ("Change", or a click on the Location row). Updates always stay where they are. |
| `open_button` | `true` | Whether the last page offers "Open My App". |
| `start_menu_folder` | none | A folder in the Start menu for the shortcuts, like your company's name. Removed when it is empty after uninstalling. |
| `website_button` | `false` | Whether the last page links to `app.website`. |

With `scope = "machine"`, the Apps entry, the shortcuts, start with Windows, `PATH`, link schemes, file types, [`[[registry]]`](/docs/reference/config/registry), [`[[env]]`](/docs/reference/config/env) and [`[[context_menu]]`](/docs/reference/config/context-menu) all go to the computer's side (`HKLM` and the shared folders) instead of the user's. Background updates are off then: `[updates] auto` must be left out or `"never"`. The install folder must be inside Program Files then. Do not change `scope` after your first release, because an app installed per user and one installed machine-wide are two installs to Windows.

## Options

Each option takes one of four values:

| Value | The install page | What happens |
| - | - | - |
| `true` | Shows a ticked box | Done, unless the user unticks it |
| `false` | Shows an unticked box | Done only if the user ticks it |
| `"always"` | Shows nothing | Always done |
| `"never"` | Shows nothing | Never done |

| Setting | Default | What it does |
| - | - | - |
| `desktop_shortcut` | `true` | A shortcut on the desktop. |
| `start_menu_shortcut` | `"always"` | A shortcut in the Start menu. |
| `start_with_windows` | `"never"` | Starts the app when the user signs in (`HKCU\...\Run`). |
| `add_to_path` | `"never"` | Adds the app's folder to the user's `PATH`, so command-line tools run from any terminal. Only that one entry is ever added or removed. |
| `path_folder` | the install folder | The folder, inside the install folder, that goes on `PATH`, like `"bin"`. |

Every shortcut setup writes (the Start menu one, the desktop one and those of [`[[shortcuts]]`](/docs/reference/config/shortcuts)) carries the app's AppUserModelID, which is the app id with every character other than letters, digits, `.`, `_` and `-` turned into a `.` (at most 128 characters), so `My App` becomes `My.App`. Windows uses it to group the app's windows on the taskbar and to tie its notifications to the app. It does not change with the version, and it lives in the shortcut file, so removing the shortcuts leaves nothing behind. For the grouping to follow a window, your program has to use the same ID: call `SetCurrentProcessExplicitAppUserModelID` with it, or leave the ID to Windows.

The whole row is a click target. On an update, the boxes start the way the user left them last time, and unticking one takes the shortcut, `PATH` entry or autostart away again.

## Languages and license

| Setting | Default | Meaning |
| - | - | - |
| `languages` | every built-in language | The languages the window may speak, like `["en", "de"]`. The window follows the user's Windows display language when it is in this list, and otherwise uses the first one. With a single language, like `["de"]`, the window always speaks it. |
| `license` | none | A UTF-8 text file the user accepts before the install page, like `"LICENSE.txt"`, or one per language: `{ en = "LICENSE.txt", de = "LIZENZ.txt" }`. An update shows it again only when it changed. |

Built-in languages: `en` English, `de` Deutsch, `nl` Nederlands, `fr` Français, `es` Español, `it` Italiano, `pt` Português, `pl` Polski, `ru` Русский, `tr` Türkçe, `ja` 日本語, `ko` 한국어, `zh` 简体中文, `zh-tw` 繁體中文 (Traditional Chinese). The tags `zh-TW`, `zh-HK`, `zh-MO` and `zh-Hant` pick `zh-tw`, and `zh-CN`, `zh-SG` and `zh-Hans` pick `zh`. `pt` is Brazilian Portuguese. Also built in: `sv` Svenska, `cs` Čeština, `vi` Tiếng Việt, `id` Bahasa Indonesia and `hi` हिन्दी.

## Example

```toml bach.toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[installer]
output = "dist/Hello-Setup-{version}.exe"
style = "aurora"
theme = "system"
accent = "#2563eb"
logo = "assets/logo.svg"
logo_height = 56
compression = "best"
folder = "Hello"
change_folder = true
open_button = true
start_menu_folder = "Hello Inc."
website_button = false
desktop_shortcut = true
start_menu_shortcut = "always"
start_with_windows = false
add_to_path = false
path_folder = "bin"
languages = ["en", "de"]
license = { en = "LICENSE.txt", de = "LIZENZ.txt" }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.