Skip to main content
A Bach setup file is one executable that carries your app inside itself. This page explains how that file is put together, what it does when it runs, and how updates and removal work. You do not need any of this to use Bach, but it explains why the guarantees hold.

One executable, three parts

There are three pieces in the project:
  • bach is the command developers run: init, check, build, preview, inspect and more. It runs on Windows, macOS and Linux.
  • bach-setup is the installer and uninstaller window, a native Rust app. Every setup file is a copy of it with a payload appended.
  • bach-pack is what both agree on: the config, the manifest, the archive, the container format and the path rules. It has no UI and no Windows calls.
bach-setup.exe is the installer window. On its own it installs nothing. bach build copies it, gives the copy your icon and version details, and appends your app to its end:
Windows ignores bytes after an executable’s last section, so the setup file still runs as bach-setup.exe. On start it reads its own trailer, finds the manifest and shows the install window. Fields added to the manifest over time all have defaults, so a newer setup file still reads the uninstaller an older one installed.

Installing

1

Checks before anything changes

What the app needs (requirements) is there, no other setup for the same app is running, the app is not open, and the drive has room for every file.
2

Unpack, then swap

Every chosen file is unpacked next to its target as <name>.bach-new. The setup file is read once: while it is unpacked, its archive is checked against the SHA-256 recorded when it was built, so the progress bar moves from the first byte. If the archive does not match, everything unpacked is deleted and nothing is replaced. Only when all of them are on disk and the check has passed are they swapped into place, each old file stepping aside as <name>.bach-old first. If one cannot be moved (a file in use), every move is undone, so an update either completes or leaves the earlier version exactly as it was. A journal in the install folder makes that true after a power cut too (see below).
3

Clean up after an older version

If an earlier version is installed, the files it installed and this one does not (including components the user unticked) are removed. The earlier file list comes from its uninstaller. This happens after the update is complete, so it is not part of the all-or-nothing swap: a file the user changed since it was installed is kept (as the uninstaller keeps it), and a file a program still holds stays and is written to the log.
4

Write the uninstaller

uninstall.exe is written: bach-setup.exe again, with the manifest of what was installed and the user’s choices, and no archive.
5

Register

Shortcuts, start with Windows, the PATH entry, link schemes and file types are added (or taken away, when an update unticked them), and the app is listed under Settings › Apps at HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\<id>.
Everything is per user by default, so nothing asks for administrator rights. An app that sets installer.scope = "machine" installs the same way into %ProgramFiles% and HKLM instead, after setup has started itself again with administrator rights: one Windows prompt, before anything is changed. See machine-wide installs. While the files are only being unpacked the window offers “Cancel” (Esc too): setup deletes what it unpacked and ends, and nothing of the earlier version was touched. The window cannot be closed while files are moving. On a first install, an older install of the same app by another installer is removed before the files are unpacked, when the app lists it in [[migrate]]. The build reads every file once: each file’s SHA-256 is taken from the same bytes that go into the archive, and the manifest, which sits behind the archive, is written last with those checksums in it. Setup files record every file’s SHA-256, which is what lets an update patch leave unchanged files where they are.

The online installer

bach build --online also writes a setup file that is the same runtime with the same manifest and no archive. When it runs, it asks the update feed, downloads the newest full setup file into %LOCALAPPDATA%\Bach\updates\<app id> (resuming if it was cut off), and checks it exactly like an update: SHA-256 against the feed, same app id, the feed’s version. Then it installs from that file, with the downloaded runtime, and deletes the download once the app is installed. See Online and offline installers.

Access keys

An app with [access] carries encryption settings in its manifest (salt, nonce, key-derivation costs and a hash that tells a right key from a wrong one) and one “slot” per access key: the files’ random key, locked with a key made from that access key. Every access key opens the setup file on its own, and taking one away is a build without it. Its archive is encrypted in authenticated chunks. Setup derives the key on a background thread, checks it against the manifest before touching the disk, and decrypts while unpacking, so the all-or-nothing install is unchanged.

Run steps

[[run]] programs start after the files are in place (or before removal), from the app’s own packaged files, with no shell. They run as the user, unless a step says elevated = true: then Windows asks for administrator rights for that program alone.

Updates from the app

With [updates], the installed uninstall.exe (the runtime with the app’s manifest) answers --check-update, --download-update, --apply-update, --update and --auto-update. It reads the feed’s JSON with Windows’ own curl.exe, https only, and downloads the newer setup file into %LOCALAPPDATA%\Bach\updates\<app id>, where it waits, and continues after an interruption, until it is installed. Before it runs, it is hashed again and must match the feed’s SHA-256, carry the same app id and the version the feed names. The setup file does the update as usual, silently when --apply-update or the background task starts it. The “Automatic updates” box registers a per-user scheduled task, Bach\<app id>, that runs uninstall.exe --auto-update every few hours. It installs only while the app is not running. Unticking the box, an update without it, and uninstalling all delete the task. The running uninstaller can run an update. Windows lets a running program be renamed but not overwritten, so the new uninstall.exe takes its place, and the old copy (uninstall.exe.bach-old) is deleted once the process has ended.

Interrupted updates

Moving the new files into place is all or nothing while the process lives. A power cut or a crash leaves no process to undo anything, so before the first move a small journal, .bach-update, lists every file that is about to move. The next install, update or removal, and each background round while the app is closed, reads it and puts back what was half moved. When all the moves are done, the new files are flushed to disk, and only then do the journal and the old copies go. The journal can only act on paths inside the install folder. The journal is deleted only once every file is confirmed back as it was. If Windows refuses a delete or rename on the way (a program holds the file), the journal stays, and the next install, update or removal stops with the “in use” sentence naming that file instead of writing over a half-undone folder. Close the program that holds it and run setup again.

Removing

Settings › Apps runs uninstall.exe. A running program cannot delete its own file, so it copies itself to the temp folder, starts the copy and exits. (A machine-wide uninstaller runs elevated and removes from where it is, and a hidden helper deletes its file once it has exited.) The copy shows the window and removes the program, every listed file, the shortcuts and the Apps entry, the integrations that are this install’s own, the data folders if the user ticked the box, and the install folder only if it is empty. See The uninstaller and your users’ data.

Logs

Every run writes %TEMP%\<app id>-setup.log (or the file given with --log): the steps and, when something fails, why. Logging never holds setup up.

Languages

The window’s texts live in one table per language. At start the window reads the user’s Windows display languages, most preferred first, and picks the first one the app offers (installer.languages, or every built-in language). If none matches, it uses the app’s first language. The developer’s [text] replaces any built-in text, per language.

Signing

The payload sits before the signature’s certificate table, so signtool signs a setup file like any other program and the signature covers the payload. Signing is optional; bach build --sign can run your signer for you. See Signing.

Reproducible builds

The same files, the same bach.toml and the same bach version give the same setup file, byte for byte, on any computer. Files are packed in sorted order, nothing in the file records a time or a path, and the compressed archive does not depend on how many processor cores made it. A test builds one project in two folders, with different file times, and compares the two setup files. That lets anyone check that a setup file comes from its sources: build it again and compare the SHA-256.
Three things make a build differ on purpose: an [access] key (its salt and nonce are random), signing (a signature carries the time it was made, and a signed file is the unsigned one plus the signature), and another version of bach or of its bach-setup.exe runtime.

Windows on ARM

A setup file is the setup runtime with the app’s files appended, and the runtime is a native Windows program. The bach-setup.exe that bach build downloads is built for x64, which Windows 11 on ARM runs through its emulation. For a native ARM64 setup file, build with the ARM64 runtime: every Bach release has a bach-<version>-windows-arm64.zip with an ARM64 bach.exe and bach-setup.exe.
BACH_RUNTIME does the same. The runtime copies files and writes registry values, so it does not care what architecture your app is. Requirements that look for a runtime are architecture-specific: kind = "vcredist" looks for the x64 redistributable.

The file list

The manifest is plain JSON, about 120 bytes per file (the path, the size and the 64 hex digits of the SHA-256), so an app of 30,000 files has a manifest of about 3.5 MB, in the setup file and again in uninstall.exe. It is not compressed on purpose: an installed app’s updater reads the manifest of every setup file it downloads with the older runtime it was installed with, so a new encoding would stop every installed copy from updating. Changing it needs a new format version that runtimes read in both forms for a long time first. bach check warns when the list passes about 2 MB; ship fewer, larger files (an asar archive for Electron).

A stable format

Setup files in the wild must keep working. The payload format changes only with a new format version and a clear error for the old one. If a setup file’s payload is damaged or edited, the window shows a page with a sentence about the problem instead of misbehaving.