Skip to content

Getting Started

This walks through resolving and building AmiBake's own smoke-test manifest, manifests/aros68k.toml — the zero-encumbrance target: it builds from a freely-available AROS 68k nightly, with no licensed media required, so it's the one every session (including CI) can build from nothing. It assumes amibake is on your PATH (see Installation) and that you're running commands from the repository root.

See CLI Reference for every flag used below, and Manifest Format for the full schema.

1. Look at the manifest

# manifests/aros68k.toml
base     = "aros68k"
machine  = { cpu = "68020" }
output   = ["hdf", "dir"]

One base (aros68k), a machine floor of a 68020, no packages, and two output formats — a bootable RDB/hard-disk image (hdf) and a plain host directory tree (dir).

2. Resolve it

amibake resolve validates the manifest and every recipe it touches, resolves package versions and requirements against the chosen base and machine, and writes a lockfile recording exactly what was resolved — without fetching or building anything yet:

$ amibake resolve manifests/aros68k.toml
resolved manifests/aros68k.toml: base=aros68k, packages=[(none)]
wrote manifests/aros68k.lock.toml

--print writes the lockfile to stdout instead, useful for a quick look without touching the filesystem:

$ amibake resolve manifests/aros68k.toml --print
# Generated by `amibake resolve`. Do not hand-edit.

output = ["hdf", "dir"]
emit = []

[base]
name = "aros68k"
os-version = "3.1"
dos-type = "ffs-intl-longname"
version = "20260814"
recipe-sha256 = "ee1ddca0c512a622ea5fc5887ad7cb0767c239215fad3ad04d7089498829fcd8"
[base.sources.url]
filename = "AROS-20260814-amiga-m68k-boot-iso.zip"
sha256 = "dcd80e76de846575864d07493667e67628996f8cd907fd7a4717024e4d09a43a"
url = "https://sourceforge.net/projects/aros/files/nightly2/20260814/Binaries/AROS-20260814-amiga-m68k-boot-iso.zip/download"

[machine]
cpu = "68020"

Every source is pinned by exact URL and checksum — rebuilding from this lockfile later fetches exactly the same bytes, or fails loudly if they ever changed.

3. Build it

amibake build re-runs resolve internally, then fetches every source (verifying its checksum), extracts and layers it into an internal tree, runs the recipe's [verify] checks, and emits every requested output format:

$ amibake build manifests/aros68k.toml --assets assets
built manifests/aros68k.toml: base=aros68k, packages=[(none)]
wrote manifests/aros68k.hdf
wrote manifests/aros68k
  • --assets assets points at a directory of user-supplied proprietary media (ROMs, OS install disks) — the AROS base doesn't need any, but most manifests eventually will, so it's worth getting in the habit of passing it.
  • Downloads are cached content-addressed under .amibake-cache/ (see --cache) — a second build of the same manifest, or a different manifest sharing the same base/packages, reuses the cache instead of re-fetching or re-extracting.
  • manifests/aros68k.hdf is a bootable RDB/partitioned hard-disk image (mountable directly by Copperline/Amiberry/WinUAE, or written to a CompactFlash card for real hardware); manifests/aros68k/ is the same content as a plain host directory tree.

4. Emit a ready-to-boot emulator config

Add emit to the manifest (or pass a variant of it) and AmiBake writes a Copperline/Amiberry/WinUAE config pointed straight at the build:

base     = "aros68k"
machine  = { cpu = "68020" }
output   = ["hdf", "dir"]
emit     = ["copperline", "amiberry"]

$ amibake build manifests/aros68k.toml --assets assets
built manifests/aros68k.toml: base=aros68k, packages=[(none)]
wrote manifests/aros68k.hdf
wrote manifests/aros68k
wrote manifests/aros68k.copperline.toml
wrote manifests/aros68k-amiberry.uae

emit needs a dir output (no hardfile/RDB mount support in the config emitters yet — see Emulator Configs) and a Kickstart ROM at assets/roms/kickstart-{version}.rom under the --assets root; AROS ships its own ROM as part of its base build, so this works with no user-supplied ROM at all.

Where to go next

  • CLI Reference for every flag, including lint (validate without resolving), --no-cache, and --allow-hooks.
  • Manifest Format for the full base/machine/ packages/output/emit schema, including constraint syntax ("amissl = 5.20", "picasso96-3 >= 3.2") and typed package options.
  • Recipe Library to see what's available to add to packages.
  • Emulator Configs for what Copperline/Amiberry/ WinUAE configs actually contain, and how a recipe contributes to one.