CLI reference

Commands

Detailed command contracts are listed below. Stability labels are taken from the executable.

supported; offline

help

Show concise help, a detailed command/topic reference, or JSON help.

Help requests are handled before operational parsing and only read embedded documentation. Use a command path or topic name; help --all prints the complete reference. JSON is deterministic and has an explicit help_schema_version.

Arguments

Options

Inputs

• Only embedded command and topic reference data.

Generated output

• Help text or JSON on stdout; no terminal control sequences.

Side effects

• Read-only; does not load a project or start tools.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Run `macmake help topics` to list topic names and aliases.

Known limitations

• Help is specific to the installed binary version.

Related commands

• schema manifest --json

Examples

macmake help

macmake help build

macmake help sdk add

macmake help manifest --json

macmake help --all

supported

version

Print the installed macMAKE version.

Prints the product version embedded in this binary. It does not contact an update service.

Inputs

• No input.

Generated output

• macMAKE VERSION on stdout.

Side effects

• Read-only; no network request or update check.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• If the version is unexpected, check `command -v macmake` and PATH order.

Known limitations

• Reports this binary's product version; it does not query a remote release.

Related commands

• help

Examples

macmake --version

supported

update check

Check GitHub for a newer stable macMAKE release.

Makes an explicit HTTPS request to the public macMAKE GitHub Releases API and compares numeric stable versions. It reports the release page; it never downloads, installs, or replaces macMAKE.

Inputs

• Public GitHub latest-release metadata over HTTPS; curl must be available.

Generated output

• Current-version status or a newer release version and release URL.

Side effects

• Contacts api.github.com; GitHub receives ordinary request metadata such as IP address and User-Agent. No local files are changed.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Check network access and curl if the release API cannot be reached.

Known limitations

• Checks stable numeric x.y.z releases only; it does not install updates.

Related commands

• update enable
• update disable
• --version

Examples

macmake update check

supported; opt-in and disabled by default

update enable

Opt in to occasional interactive update notices.

Stores a per-user preference. When enabled, macMAKE checks at most once per 24 hours during interactive CLI use and prints a notice only when a newer stable release exists. Network errors do not interrupt commands.

Environment variables

• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for update preference storage.", "used_when": "Used when set; otherwise $HOME/.config is used."}
• {"name": "HOME", "purpose": "Fallback configuration directory.", "used_when": "Used when XDG_CONFIG_HOME is unset."}
• {"name": "MACMAKE_DISABLE_UPDATE_CHECK", "purpose": "Suppress automatic update checks for one invocation when set to 1.", "used_when": "Read by the interactive notification path; explicit checks remain available."}

Inputs

• No network input; writes the user's local preference file.

Generated output

• Confirmation on stdout.

Side effects

• Creates or updates $XDG_CONFIG_HOME/macmake/update-check.json, or $HOME/.config/macmake/update-check.json.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Set XDG_CONFIG_HOME or HOME if macMAKE cannot locate a configuration directory.

Known limitations

• Only interactive CLI invocations check automatically; no background process or automatic update is installed.

Related commands

• update check
• update disable

Examples

macmake update enable

supported

update disable

Opt out of automatic update checks.

Stores a per-user preference disabling occasional interactive update checks. An explicitly requested `macmake update check` still performs a check.

Environment variables

• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for update preference storage.", "used_when": "Used when set; otherwise $HOME/.config is used."}
• {"name": "HOME", "purpose": "Fallback configuration directory.", "used_when": "Used when XDG_CONFIG_HOME is unset."}

Inputs

• No network input; writes the user's local preference file.

Generated output

• Confirmation on stdout.

Side effects

• Creates or updates the per-user update preference file.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Set XDG_CONFIG_HOME or HOME if macMAKE cannot locate a configuration directory.

Known limitations

• An explicit `macmake update check` remains available and contacts GitHub.

Related commands

• update check
• update enable

Examples

macmake update disable

supported; schema versioned independently from the help response

schema manifest

Print the manifest JSON Schema supported by this binary.

Emits the machine-readable structural schema for this installed version's macmake.toml parser. Cross-field and filesystem checks are documented in `macmake help manifest`; the schema is not a separate project model.

Options

Inputs

• Embedded schema corresponding to the installed manifest deserializer.

Generated output

• JSON Schema on stdout; no files are written.

Side effects

• Read-only; no project, SDK catalog, or toolchain is loaded.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Use `macmake help manifest` for path and cross-field semantic constraints.

Known limitations

• JSON Schema describes manifest structure; it cannot verify external files, SDK capabilities, provider availability, or all semantic combinations.

Related commands

• help manifest
• inspect

Examples

macmake schema manifest --json

supported

inspect

Read and summarize a project manifest.

Loads the TOML manifest, validates its semantic model, and prints the project and target membership. This is a diagnostic read; it does not compile sources or create build outputs.

Arguments

Inputs

• The selected macmake.toml and no build inputs.

Generated output

• Human-readable project and target summary on stdout.

Side effects

• Reads the manifest and prints its validated summary.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• If the manifest is invalid, use the field-specific diagnostic and `macmake help manifest` to correct its TOML.

Known limitations

• Does not prove that external compiler, SDK, library, or source files are available; use doctor or build for those checks.

Related commands

• help manifest
• build
• doctor

Examples

macmake inspect .

macmake inspect examples/first-app/macmake.toml

supported

inspect-artifact

Validate and report a Classic executable and its metadata.

Reads a data fork, resource fork, Finder metadata, and caller-supplied four-character creator/type codes. Reports PEF/CFM structure and application resources; --json selects machine-readable output. This command does not modify the artifact.

Arguments

Options

Inputs

• Data fork, resource fork, Finder-info sidecar, creator and file-type expectations.

Generated output

• Text or JSON structural report on stdout; no files are written.

Side effects

• Reads the supplied files only.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 1, "meaning": "The command ran but reported an unresolved item, unavailable configuration, or failed artifact validation."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Creator and file type must each be exactly four printable ASCII characters.
• If validation fails, preserve all three fork/metadata inputs and read the structural finding; do not infer Mac OS 9 runtime success from host-side structure checks.

Known limitations

• Host-side structural validation does not launch the application in Mac OS 9.

Related commands

• build
• stage
• verify
• help output

Examples

macmake inspect-artifact build/HelloPPC.pef \
  --resource-fork build/HelloPPC.rsrc \
  --finder-info build/.finf/HelloPPC.APPL --creator HmPP --file-type APPL

macmake inspect-artifact build/HelloPPC.pef \
  --resource-fork build/HelloPPC.rsrc \
  --finder-info build/.finf/HelloPPC.APPL --creator HmPP --file-type APPL --json

supported

stage

Write a Classic application to a Netatalk-compatible destination.

Materializes either a MacBinary II input or raw data/resource fork files at a Classic-file destination and verifies the result. This writes the destination and uses the configured Netatalk `ad` utility.

Arguments

Options

Environment variables

• {"name": "MACMAKE_NETATALK_AD", "purpose": "Select the Netatalk `ad` executable.", "used_when": "Used by stage and clone-classic; defaults to `ad` from PATH."}

Inputs

• A MacBinary II file, or a data fork plus both --resource-fork and --finder-info.

Generated output

• The destination Classic file, resource fork and Finder metadata; a verification report on stdout.

Side effects

• Creates or replaces the destination's file contents and Classic metadata.
• Invokes the Netatalk `ad` program; ensure the destination is the intended mounted share.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Raw fork mode requires --resource-fork and --finder-info together.
• If `ad` is missing or the destination lacks Netatalk metadata support, install/configure Netatalk or set MACMAKE_NETATALK_AD to its executable path.

Known limitations

• This writes a Classic file to a destination; it does not copy through an unverified legacy share or prove guest runtime behavior.

Related commands

• verify
• clone-classic
• inspect-artifact
• help classic-files

Examples

macmake stage build/HelloPPC.bin --destination /srv/macfiles/HelloPPC

macmake stage build/HelloPPC.pef \
  --resource-fork build/HelloPPC.rsrc \
  --finder-info build/.finf/HelloPPC.APPL --destination /srv/macfiles/HelloPPC

supported

clone-classic

Copy an existing live Classic file while preserving its metadata representation.

Uses Netatalk `ad cp -p -v` to copy a live Classic file, then verifies data, resource-fork records, full FinderInfo, and relevant POSIX attributes. The destination must not already exist.

Arguments

Options

Environment variables

• {"name": "MACMAKE_NETATALK_AD", "purpose": "Select the Netatalk `ad` executable.", "used_when": "Defaults to `ad` from PATH."}

Inputs

• A regular live Classic file with readable data fork and metadata.

Generated output

• A metadata-preserving copy at the destination and a verification report.

Side effects

• Creates a new destination file and invokes `ad cp`; it refuses an existing destination.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Use a fresh destination path.
• If metadata verification fails, do not use the clone as a release transport copy; retain the source and diagnostic output.

Known limitations

• Requires Netatalk-compatible metadata and the `ad` command.

Related commands

• stage
• verify
• help classic-files

Examples

macmake clone-classic /srv/macfiles/ExistingApp --destination /srv/macfiles/ExistingApp-copy

supported

verify

Read and verify a previously staged Classic file.

Compares a MacBinary II or raw-fork application description against the file already present at the destination. It does not intentionally modify the destination.

Arguments

Options

Inputs

• Expected MacBinary II or data/resource/Finder-info files and an existing destination Classic file.

Generated output

• A comparison report on stdout; no destination writes.

Side effects

• Reads source and destination data/fork/metadata.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• For raw-fork input provide both sidecars.
• A mismatch means the staged destination is not the expected transport copy; run stage again only when replacement is intended.

Known limitations

• Requires a readable destination on a filesystem exposing Classic metadata to macMAKE.

Related commands

• stage
• clone-classic
• help classic-files

Examples

macmake verify build/HelloPPC.bin --destination /srv/macfiles/HelloPPC

experimental

import-cw-xml

Import a CodeWarrior project XML export as macmake.toml.

Reads a CodeWarrior XML project export, selects one target when requested, and writes a native macMAKE TOML manifest plus a .cw-import.json evidence sidecar. Both output paths must be new; existing files are refused. Import results can contain unsupported or approximate settings; inspect and validate the result before building.

Arguments

Options

Inputs

• A CodeWarrior XML project export and optionally a local CodeWarrior tree for path resolution.

Generated output

• A TOML manifest at --output, a sibling <output>.cw-import.json evidence file, and an import report.

Side effects

• Creates the new manifest and evidence sidecar atomically; it refuses to replace either existing file.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 1, "meaning": "The command ran but reported an unresolved item, unavailable configuration, or failed artifact validation."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Export XML from CodeWarrior; the command does not parse the proprietary binary .mcp format.
• When --target is supplied, --codewarrior-root is required and --output must be beside the XML file so relative project paths stay valid.
• Status 1 means a partial import; the manifest and evidence sidecar were still written. Review the evidence before building.
• After import, run `macmake inspect macmake.toml` and correct unsupported settings using `macmake help manifest`.

Known limitations

• Import is experimental and does not establish complete CodeWarrior project or compiler compatibility.

Related commands

• inspect
• build
• help manifest
• help compatibility

Examples

macmake import-cw-xml Export.xml --output macmake.toml

macmake import-cw-xml Export.xml --target "Classic PPC" --codewarrior-root "/authorized/CW8" --output macmake.toml

supported

resolve-header

Show how a target resolves one include name.

Uses a project's access paths and selected SDK catalog to report the header candidate for an include from a source file. This is a read-only diagnostic and does not compile the source.

Arguments

Options

Environment variables

• {"name": "MACMAKE_SDK_CATALOG", "purpose": "Override the per-user SDK catalog path.", "used_when": "Used when --catalog or --sdk-catalog is not supplied."}
• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for the default SDK catalog.", "used_when": "When MACMAKE_SDK_CATALOG is unset, catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json."}
• {"name": "HOME", "purpose": "Fallback base directory for per-user configuration.", "used_when": "When MACMAKE_SDK_CATALOG and XDG_CONFIG_HOME are unset, catalog is $HOME/.config/macmake/sdk-catalog.json."}

Inputs

• Manifest, source path, include name, declared access paths, and the selected SDK files.

Generated output

• Resolution path/report on stdout; unresolved include is status 1.

Side effects

• Reads project, catalog, and candidate header paths only.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 1, "meaning": "The command ran but reported an unresolved item, unavailable configuration, or failed artifact validation."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Use `macmake help access-paths` to understand anchor and order behavior.
• If the header is absent, register an authorized SDK and check its declared capabilities with `macmake sdk verify`.

Known limitations

• Resolves one header path; it does not prove that the compiler accepts the header or that its declarations link.

Related commands

• inspect
• doctor
• sdk list
• sdk verify
• help access-paths

Examples

macmake resolve-header examples/first-app --target "Classic PPC C" --from src/main.c Carbon.h

qualified for Linux x86-64 to Classic Mac OS PowerPC CFM/PEF C applications; the bounded native M68000 application profile is experimental; other profiles are experimental or legacy

build

Compile, link, validate, and package one project target.

Builds the selected target and its target dependency closure using the provider and runtime configured by the manifest. The command may invoke compiler, assembler, linker, resource, and packaging tools. --explain adds build-decision evidence; it is not a dry run.

Arguments

Options

Environment variables

• {"name": "MACMAKE_SDK_CATALOG", "purpose": "Override the per-user SDK catalog path.", "used_when": "Used when --catalog or --sdk-catalog is not supplied."}
• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for the default SDK catalog.", "used_when": "When MACMAKE_SDK_CATALOG is unset, catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json."}
• {"name": "HOME", "purpose": "Fallback base directory for per-user configuration.", "used_when": "When MACMAKE_SDK_CATALOG and XDG_CONFIG_HOME are unset, catalog is $HOME/.config/macmake/sdk-catalog.json."}
• {"name": "MACMAKE_TOOLCHAIN_ROOT", "purpose": "Default root for the selected compiler/provider tools.", "used_when": "Used when --toolchain-root is not supplied."}
• {"name": "MACMAKE_PPC_GCC", "purpose": "Override the native PowerPC GCC executable.", "used_when": "Used by the native provider when configured; doctor probes it too."}
• {"name": "MACMAKE_PPC_AS", "purpose": "Override the native PowerPC assembler executable.", "used_when": "Used by native provider resolution and doctor when configured."}

Inputs

• Manifest and explicitly listed sources, resources, libraries, SDK files, provider tools, and runtime inputs.

Generated output

• Target-dependent outputs under the project's build/ directory, including native objects, link/evidence reports, PEF, resource fork, Finder metadata, and MacBinary for supported application targets.

Side effects

• Creates/updates generated build outputs and incremental state.
• Runs configured compiler/provider and native link/resource/package stages.
• A structural artifact validation failure returns status 1; configuration or process errors return status 2.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 1, "meaning": "The command ran but reported an unresolved item, unavailable configuration, or failed artifact validation."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Run `macmake inspect PROJECT` then `macmake doctor PROJECT --target TARGET`.
• For a missing SDK capability, register the authorized SDK with `macmake sdk add ROOT --id ID` and inspect `macmake sdk verify ID`.
• For an unresolved header, run `macmake resolve-header PROJECT --target TARGET --from SOURCE HEADER`.
• For unresolved imports, check `[[target.libraries]]`, SDK import capabilities, and provider/runtime availability.

Known limitations

• --explain still performs requested build work.
• The v0.1.1 candidate's M68000 profile is limited to C89, one bounded CODE 1 segment, no external libraries, and a documented resource subset; it does not claim broad 68K, C++ runtime, macOS-host, Mac OS X, Rust-target, or complete CodeWarrior compatibility.

Related commands

• inspect
• doctor
• compile
• clean
• inspect-artifact
• help manifest
• help incremental

Examples

macmake doctor examples/first-app --target "Classic PPC C"

macmake build examples/first-app --target "Classic PPC C"

macmake build examples/first-app --target "Classic PPC C" --explain

supported, manual runtime smoke-test workflow; Linux x86-64; QEMU Mac OS 9.2.2 only

run

Run a previously staged application in a user-owned QEMU Macintosh guest.

Starts the single supported guest profile (QEMU mac99/G4 with Mac OS 9.2.2) from a user-owned disk image through a disposable copy-on-write overlay. You launch the application manually in Finder and confirm each checkpoint; QEMU process startup alone is never reported as an application pass. The host artifact is recorded and hashed but is not copied into the guest disk.

Arguments

Options

Environment variables

• {"name": "HOME", "purpose": "Fallback location for run evidence under ~/.local/state/macmake/runs.", "used_when": "When XDG_STATE_HOME is unset."}
• {"name": "XDG_STATE_HOME", "purpose": "Base directory for persistent run evidence and copy-on-write disks.", "used_when": "When set, evidence is stored beneath $XDG_STATE_HOME/macmake/runs."}

Inputs

• A JSON profile, existing raw/qcow2 Mac OS 9.2.2 disk image, and optional host MacBinary artifact plus matching macMAKE build-evidence JSON.
• QEMU PowerPC emulator, qemu-img, and a GTK or SDL display.

Generated output

• A persistent qcow2 overlay, QEMU/serial logs, and run.json schema 2. Each QMP screenshot record names its checkpoint, .ppm path, P6 PPM format, dimensions, and SHA-256.

Side effects

• Starts QEMU and writes only to a new copy-on-write overlay; the configured base image is hashed before and after.
• Writes run evidence under the per-user state directory; does not copy an artifact into the guest or alter the base image.
• Marks artifact construction verified only when supplied macMAKE build evidence has a matching MacBinary hash.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 1, "meaning": "The command ran but reported an unresolved item, unavailable configuration, or failed artifact validation."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Install qemu-system-ppc and qemu-utils; check `qemu-system-ppc --version` and `qemu-img --version`.
• The application must already be present in the guest image at the profile's guest_path; stage it with a Mac-aware transfer method first.
• A `guest_boot_confirmed` or `application_launch_confirmed` value of null means that stage was not observed; inspect run.json and qemu.log.

Known limitations

• Only QEMU mac99/G4, Mac OS 9.2.2, and GTK/SDL interactive display are supported initially.
• OS version, Finder boot, application launch, visible state, and normal exit are explicitly user-confirmed; this command is not an autonomous guest test harness. Screenshots are validated QEMU P6 PPM files. Identical boot/application captures are retained as duplicate evidence and prevent runtime-state success.
• The built host artifact is identified and hashed but not injected into the guest. No ROM or operating-system image is included.

Related commands

• build
• inspect-artifact
• stage
• verify
• help emulator

Examples

macmake run ./qemu.json --artifact ./app.bin --build-evidence ./app.build-evidence.json

macmake run ./qemu-macos-9.2.2.json --timeout 900 --json

supported for the same project/provider subset as build; other profiles are experimental or legacy

compile

Compile the selected target closure without linking or packaging.

Compiles every translation unit in the selected target and its prerequisite closure. It does not execute link, resource, or application packaging stages. Compiler outputs and compile-census evidence are written into the build tree.

Arguments

Options

Environment variables

• {"name": "MACMAKE_SDK_CATALOG", "purpose": "Override the per-user SDK catalog path.", "used_when": "Used when --catalog or --sdk-catalog is not supplied."}
• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for the default SDK catalog.", "used_when": "When MACMAKE_SDK_CATALOG is unset, catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json."}
• {"name": "HOME", "purpose": "Fallback base directory for per-user configuration.", "used_when": "When MACMAKE_SDK_CATALOG and XDG_CONFIG_HOME are unset, catalog is $HOME/.config/macmake/sdk-catalog.json."}
• {"name": "MACMAKE_TOOLCHAIN_ROOT", "purpose": "Default root for the selected compiler/provider tools.", "used_when": "Used when --toolchain-root is not supplied."}
• {"name": "MACMAKE_PPC_GCC", "purpose": "Override the native PowerPC GCC executable.", "used_when": "Used by the native provider when configured; doctor probes it too."}
• {"name": "MACMAKE_PPC_AS", "purpose": "Override the native PowerPC assembler executable.", "used_when": "Used by native provider resolution and doctor when configured."}

Inputs

• Manifest, transitive target sources, headers, libraries needed by compilation, SDK, and compiler/provider.

Generated output

• Compiler outputs and compile-census report under the project's build/ directory.

Side effects

• Creates/updates compile outputs and incremental state; does not link, build resources, or package an application.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 1, "meaning": "The command ran but reported an unresolved item, unavailable configuration, or failed artifact validation."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Use doctor first for provider/SDK checks; use resolve-header for a specific include.

Known limitations

• A successful compile-only pass does not prove link closure, PEF structure, resources, MacBinary, or Mac OS 9 runtime behavior.

Related commands

• build
• doctor
• clean
• help incremental

Examples

macmake compile examples/first-app --target "Classic PPC C"

supported

clean

Delete generated outputs and incremental state for a target closure.

Removes recorded outputs and known target products for the selected target and its dependencies. Review the project and selected target before running; this command is destructive to generated build files.

Arguments

Options

Inputs

• Project manifest and its current incremental state.

Generated output

• No build outputs. It removes generated files and state for the selected closure.

Side effects

• Deletes generated objects, reports, PEF/resource/MacBinary products, and incremental state for the selected target closure.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• If you need to preserve evidence, copy the relevant build/ reports before cleaning.

Known limitations

• Only outputs known to macMAKE's target build tree are intended to be removed; do not point the project at valuable generated inputs.

Related commands

• build
• compile
• help incremental

Examples

macmake clean examples/first-app --target "Classic PPC C"

supported for diagnostics of configured providers; reports unsupported runtime profiles explicitly

doctor

Check whether one target's runtime, SDK, tools, and libraries are ready.

Loads and resolves the target, verifies registered SDK package content and capabilities, probes provider tools, and checks required library inputs. This is a read-only diagnostic and does not build.

Arguments

Options

Environment variables

• {"name": "MACMAKE_SDK_CATALOG", "purpose": "Override the per-user SDK catalog path.", "used_when": "Used when --catalog or --sdk-catalog is not supplied."}
• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for the default SDK catalog.", "used_when": "When MACMAKE_SDK_CATALOG is unset, catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json."}
• {"name": "HOME", "purpose": "Fallback base directory for per-user configuration.", "used_when": "When MACMAKE_SDK_CATALOG and XDG_CONFIG_HOME are unset, catalog is $HOME/.config/macmake/sdk-catalog.json."}
• {"name": "MACMAKE_TOOLCHAIN_ROOT", "purpose": "Default root for the selected compiler/provider tools.", "used_when": "Used when --toolchain-root is not supplied."}
• {"name": "MACMAKE_PPC_GCC", "purpose": "Override the native PowerPC GCC executable.", "used_when": "Used by the native provider when configured; doctor probes it too."}
• {"name": "MACMAKE_PPC_AS", "purpose": "Override the native PowerPC assembler executable.", "used_when": "Used by native provider resolution and doctor when configured."}

Inputs

• Manifest, SDK catalog and registered SDK files, toolchain executables, runtime inputs, and project libraries.

Generated output

• Readiness diagnostics on stdout; NOT READY returns status 1.

Side effects

• Reads files and may execute provider version/target probes; does not compile or modify SDK registration.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 1, "meaning": "The command ran but reported an unresolved item, unavailable configuration, or failed artifact validation."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• For a missing provider, supply the installed toolchain root.
• For SDK resolution errors, run `macmake sdk list`, `macmake sdk inspect ID`, or `macmake sdk verify ID`.
• A NOT READY report names the missing provider, capability, or library; use that message to correct registration or manifest inputs.

Known limitations

• A READY result checks declared availability and provider probes; it does not guarantee successful compilation, structural validity, or runtime behavior.

Related commands

• sdk list
• sdk add
• sdk verify
• resolve-header
• build
• help sdk

Examples

macmake doctor examples/first-app --target "Classic PPC C" --toolchain-root ./toolchain

experimental; outside the v0.1 supported release target

system-extension

Assemble a mixed Macintosh system-extension target.

Experimental orchestration for projects containing a 68K target and a PowerPC provider target. It can invoke external architecture tools and writes generated extension artifacts.

Arguments

Options

Environment variables

• {"name": "MACMAKE_SDK_CATALOG", "purpose": "Override the per-user SDK catalog path.", "used_when": "Used when --catalog or --sdk-catalog is not supplied."}
• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for the default SDK catalog.", "used_when": "When MACMAKE_SDK_CATALOG is unset, catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json."}
• {"name": "HOME", "purpose": "Fallback base directory for per-user configuration.", "used_when": "When MACMAKE_SDK_CATALOG and XDG_CONFIG_HOME are unset, catalog is $HOME/.config/macmake/sdk-catalog.json."}
• {"name": "MACMAKE_TOOLCHAIN_ROOT", "purpose": "Default root for the selected compiler/provider tools.", "used_when": "Used when --toolchain-root is not supplied."}
• {"name": "MACMAKE_PPC_GCC", "purpose": "Override the native PowerPC GCC executable.", "used_when": "Used by the native provider when configured; doctor probes it too."}
• {"name": "MACMAKE_PPC_AS", "purpose": "Override the native PowerPC assembler executable.", "used_when": "Used by native provider resolution and doctor when configured."}
• {"name": "MACMAKE_M68K_TOOLCHAIN_ROOT", "purpose": "Default root for the experimental 68K provider.", "used_when": "Used when --m68k-toolchain-root is not supplied."}

Inputs

• Experimental manifest, SDK catalog, 68K/PPC providers, sources, and declared libraries.

Generated output

• Generated extension/build artifacts under the project build directory.

Side effects

• Runs external build tools and writes build outputs.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Check provider roots and SDK/tool inputs with the diagnostics printed by the operation.

Known limitations

• This mixed extension command is separate from the experimental native 68K application profile selected through `macmake build`; it does not qualify the extension output for a target OS.

Related commands

• build
• doctor
• help compatibility

Examples

macmake system-extension path/to/extension.toml --m68k-toolchain-root /opt/m68k --toolchain-root /opt/ppc

supported

sdk list

List registered local SDK packages.

Reads the SDK catalog and prints each package identity, root, and detected capability count.

Options

Environment variables

• {"name": "MACMAKE_SDK_CATALOG", "purpose": "Override the per-user SDK catalog path.", "used_when": "Used when --catalog or --sdk-catalog is not supplied."}
• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for the default SDK catalog.", "used_when": "When MACMAKE_SDK_CATALOG is unset, catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json."}
• {"name": "HOME", "purpose": "Fallback base directory for per-user configuration.", "used_when": "When MACMAKE_SDK_CATALOG and XDG_CONFIG_HOME are unset, catalog is $HOME/.config/macmake/sdk-catalog.json."}

Inputs

• SDK catalog JSON.

Generated output

• Package list on stdout.

Side effects

• Read-only; does not hash all package contents.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• An empty list means register an authorized SDK with `macmake sdk add ROOT --id ID`.

Known limitations

• Listing alone does not verify catalog freshness or package contents.

Related commands

• sdk add
• sdk inspect
• sdk verify
• doctor

Examples

macmake sdk list

supported; network and Git required

sdk fetch

Fetch the minimal Classic PowerPC C SDK inputs.

Uses Git sparse checkout over HTTPS to fetch the minimal first-app PowerPC C header, import-library, and MSL inputs from mplsllc/macMAKELibs at the pinned revision recorded in minimal-classic-ppc-c-v1.json. It verifies the selected archive and import-stub hashes. It does not register an SDK or copy libraries into a project. Existing destination directories are preserved and must already match the pinned revision.

Options

Environment variables

• {"name": "XDG_DATA_HOME", "purpose": "Base directory for the default fetched SDK path.", "used_when": "Used when --destination is omitted and XDG_DATA_HOME is set."}
• {"name": "HOME", "purpose": "Fallback base directory for the default fetched SDK path.", "used_when": "Used when --destination and XDG_DATA_HOME are unset."}

Inputs

• Pinned GitHub repository https://github.com/mplsllc/macMAKELibs.git revision 65b3201d352079010cabaeb57a81824b307ed22d, described by the versioned minimal SDK manifest.
• Git executable and HTTPS network access.

Generated output

• Sparse checkout containing selected MSL headers/archives and Universal Interfaces headers/import stubs.

Side effects

• Creates a user-selected SDK directory and downloads files; does not modify SDK catalog or project files.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• If Git is missing or the network is unavailable, follow the manual sparse-checkout instructions in `macmake help sdk`.
• If the destination contains another revision or mismatched files, it is left untouched; choose a new --destination.

Known limitations

• Fetches only the first-app C PowerPC dependency subset, not a complete CodeWarrior SDK or C++ toolchain.
• The user is responsible for having rights to use the retrieved third-party files.
• Pinned Git commit and file hashes establish content identity over GitHub HTTPS; they do not grant rights or provide a detached publisher signature.

Related commands

• sdk add
• sdk inspect
• sdk verify
• doctor
• help sdk

Examples

macmake sdk fetch --minimal

macmake sdk fetch --minimal --destination "$HOME/SDKs/macMAKELibs"

macmake sdk add "$HOME/.local/share/macmake/macMAKELibs/Universal" --id macos9-sdk

examples/first-app/setup-user-msl.sh "$HOME/.local/share/macmake/macMAKELibs"

supported

sdk add

Register an SDK directory in the local catalog.

Scans a user-supplied SDK root, detects supported headers/import libraries/Rez definitions, fingerprints the package, and writes its registration to the SDK catalog. Registration stores a path and metadata; it does not copy SDK files.

Arguments

Options

Environment variables

• {"name": "MACMAKE_SDK_CATALOG", "purpose": "Override the per-user SDK catalog path.", "used_when": "Used when --catalog or --sdk-catalog is not supplied."}
• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for the default SDK catalog.", "used_when": "When MACMAKE_SDK_CATALOG is unset, catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json."}
• {"name": "HOME", "purpose": "Fallback base directory for per-user configuration.", "used_when": "When MACMAKE_SDK_CATALOG and XDG_CONFIG_HOME are unset, catalog is $HOME/.config/macmake/sdk-catalog.json."}

Inputs

• Readable SDK directory tree.

Generated output

• Updated catalog file and a package registration summary.

Side effects

• Writes local SDK registration state atomically; does not redistribute SDK contents.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• Use `sdk inspect ID` to see detected capabilities, then `sdk verify ID` to hash and check current files.
• Do not register or distribute material you are not authorized to use.

Known limitations

• The toolchain archive excludes proprietary Apple/Metrowerks SDKs; users must provide authorized materials.

Related commands

• sdk list
• sdk inspect
• sdk verify
• doctor
• help sdk

Examples

macmake sdk add "$HOME/SDKs/CodeWarrior/MacOS Support/Universal" --id macos9-sdk

supported

sdk inspect

Show an SDK package's identity, roots, capabilities, and indexed files.

Reads one registered package record and prints detected metadata and import-library mappings. It does not recompute all file hashes.

Arguments

Options

Environment variables

• {"name": "MACMAKE_SDK_CATALOG", "purpose": "Override the per-user SDK catalog path.", "used_when": "Used when --catalog or --sdk-catalog is not supplied."}
• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for the default SDK catalog.", "used_when": "When MACMAKE_SDK_CATALOG is unset, catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json."}
• {"name": "HOME", "purpose": "Fallback base directory for per-user configuration.", "used_when": "When MACMAKE_SDK_CATALOG and XDG_CONFIG_HOME are unset, catalog is $HOME/.config/macmake/sdk-catalog.json."}

Inputs

• SDK catalog.

Generated output

• Package details on stdout.

Side effects

• Read-only catalog access.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• If the ID is unknown, run `macmake sdk list`; if capabilities are incomplete, register the correct SDK root.

Known limitations

• For current content integrity, use `sdk verify`.

Related commands

• sdk list
• sdk add
• sdk verify
• doctor

Examples

macmake sdk inspect macos9-sdk

supported

sdk verify

Recheck an SDK package's indexed content and fingerprint.

Hashes indexed SDK files and validates the registered package's content identity against the files present now.

Arguments

Options

Environment variables

• {"name": "MACMAKE_SDK_CATALOG", "purpose": "Override the per-user SDK catalog path.", "used_when": "Used when --catalog or --sdk-catalog is not supplied."}
• {"name": "XDG_CONFIG_HOME", "purpose": "Base directory for the default SDK catalog.", "used_when": "When MACMAKE_SDK_CATALOG is unset, catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json."}
• {"name": "HOME", "purpose": "Fallback base directory for per-user configuration.", "used_when": "When MACMAKE_SDK_CATALOG and XDG_CONFIG_HOME are unset, catalog is $HOME/.config/macmake/sdk-catalog.json."}

Inputs

• SDK catalog and package files at their registered root.

Generated output

• Verification summary and content fingerprint.

Side effects

• Reads and hashes registered SDK files; does not modify them or the catalog.

Exit statuses

• {"code": 0, "meaning": "Command completed successfully."}
• {"code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error."}

Troubleshooting

• If verification is stale, rerun `macmake sdk add ROOT --id ID` after confirming the registered root is the intended SDK.

Known limitations

• Verifies indexed content, not the legal authorization or completeness of the SDK for an application.

Related commands

• sdk inspect
• sdk add
• doctor

Examples

macmake sdk verify macos9-sdk

quick start

Quick start

macMAKE v0.1.1 targets Linux x86-64. Its qualified application workflow builds Classic PowerPC CFM/PEF C applications. The candidate also contains an experimental, bounded native M68000 segmented C application profile; see macmake help targets and macmake help compatibility before selecting it. This profile is not a claim of general 68K, CFM-68K, or System 6–9 support. The installed executable carries this reference offline.

1. Check the installation

macmake --version
macmake help

The distributed toolchain contains its compiler, assembler, native linker and packaging tools. It does not contain proprietary Apple Universal Interfaces, Metrowerks MSL archives, or other historical SDK material.

From the extracted release directory, select its toolchain before building:

export MACMAKE_TOOLCHAIN_ROOT="$PWD/toolchain"

For a per-user installation, set this variable to the installed release's toolchain directory. macmake help toolchain explains the provider options.

2. Register authorized SDK material

macmake sdk add "$HOME/SDKs/CodeWarrior/MacOS Support/Universal" --id macos9-sdk
macmake sdk inspect macos9-sdk
macmake sdk verify macos9-sdk
cd examples/first-app
./setup-user-msl.sh "$HOME/SDKs/CodeWarrior"

The catalog records the root and fingerprints; it does not copy SDK files. The helper copies only authorized MSL archives into the sample's ignored sdk/ directory and prints their input hashes.

3. Inspect and build

macmake inspect .
macmake doctor . --target "Classic PPC C"
macmake build . --target "Classic PPC C"

The sample manifest explicitly declares two C sources, the CodeWarrior MSL runtime profile, libraries, SDK capabilities, application metadata and CFM fragment settings. Read macmake help manifest and macmake help examples.

4. Inspect the host-side output

The application target produces .pef, .rsrc, .finf/<name>.APPL, and .bin files under the project's build/ directory. A one-target project writes products directly there; multi-target projects may use target-specific subdirectories. Inspect the components with the exact paths printed or discovered in that build directory:

find build -maxdepth 6 -type f -print
macmake inspect-artifact PATH/APP.pef --resource-fork PATH/APP.rsrc \
  --finder-info PATH/.finf/APP.APPL --creator HmPP --file-type APPL --json

PEF/resource/Finder/MacBinary validation is Linux build evidence. It does not launch the application. Copy the MacBinary file to a suitable Classic Mac filesystem and confirm launch behavior in a user-controlled Mac OS 9 guest.

For first failures, run macmake doctor, then macmake help troubleshooting.

project manifest reference

macmake.toml manifest reference

TOML is the native project format. This binary also exposes the structural schema as JSON Schema Draft 2020-12:

macmake schema manifest --json

The schema describes fields, types, required values and enums. Its x-macmake-manifest-schema-version is 0.1.1; this revision adds the bounded experimental native M68000 application profile accepted by this binary. The loader also validates path safety, four-character codes, duplicate membership, target/provider combinations, and references between tables. Those rules are listed below. A valid schema shape is not by itself proof that the selected toolchain or SDK can build a target.

Top level and project

[project]
name = "HelloPPC"
default_target = "Classic PPC C" # optional; target selection for build/clean

[[target]]
# one table per target, kept in declaration order

[project] is required. name is required. default_target is optional. At least one [[target]] must be present. Unknown fields are rejected by this version's TOML loader. There is no top-level manifest version key in v0.1; schema evolution is tied to the installed macMAKE version, and the machine-readable schema reports its own version fields.

Target fields

Every target requires:

Optional target fields are kind, runtime_profile, custom_runtime, language, resources, libraries, subtargets, link_order, access_paths, compiler, source_compiler_settings, linker, application, shared_library, cfm_fragment, resource_output, sdk, backend, and compiler_target. macmake schema manifest --json gives the full nested field shape and enumerations.

Defaults applied during loading: kind = "application", runtime_profile = "retro68-newlib", language = "c", backend = "retro68"; empty resources/libraries/subtargets/link order/access paths/defines are allowed. These legacy defaults do not make Retro68 the v0.1 release provider. For the packaged native application flow, set backend = "macmake-classic" and use the tested target/runtime profile combination shown in the real examples/first-app/macmake.toml.

For the experimental native M68000 application path, use the exact classic-68k-segmented-app-c-v1 compiler target and macmake-classic-m68k-c-v1 runtime profile pair. The included examples/first-app/hello-window-68k/macmake.toml is the working manifest reference; the profile is bounded and is not general 68K compatibility.

Complete supported application example

This is the shipped first-app project's core manifest. The source, SDK and archive paths must exist locally; users provide authorized SDK/MSL material. The repository copy contains additional explanatory comments and the exact CarbonLib fragment extents for its documented SDK input.

[project]
name = "HelloPPC"
default_target = "Classic PPC C"

[[target]]
name = "Classic PPC C"
kind = "application"
platform = "classic-mac-os"
architecture = "powerpc"
api = "carbon-lib"
runtime = "cfm"
runtime_profile = "codewarrior-msl-compatible"
executable = "pef"
language = "c"
backend = "macmake-classic"
compiler_target = "classic-ppc-xcoff-c-v1"
sources = ["src/main.c", "src/value.c"]

[target.compiler]
standard = "c89"

[target.application]
creator = "HmPP"
file_type = "APPL"
output_name = "HelloPPC"

[target.application.memory]
preferred_heap_bytes = 4194304
minimum_heap_bytes = 2097152
application_stack_bytes = 32768
size_flags = 22720

[target.cfm_fragment]
output_name = "HelloPPC"
fragment_name = "HelloPPC"
main = "__start"
creator = "HmPP"
file_type = "APPL"
current_version = 0
share_data = false
exports = "pragma"

[[target.libraries]]
name = "MSL_C_Carbon"
kind = "archive"
path = "sdk/MSL_C_Carbon.Lib"

[[target.libraries]]
name = "MSL_Runtime_PPC_D"
kind = "archive"
path = "sdk/MSL_Runtime_PPC_D.Lib"

[[target.libraries]]
name = "MSL_Extras_Carbon"
kind = "archive"
path = "sdk/MSL_Extras_Carbon.Lib"

[[target.libraries]]
name = "MathLib"
kind = "system-import"

[[target.libraries]]
name = "CarbonLib"
kind = "system-import"
pef_fragments = [
  { fragment_name = "CarbonLib", offset = 0, length = 80688, weak_import = false },
  { fragment_name = "CarbonLib", offset = 80688, length = 91808, weak_import = true },
  { fragment_name = "Apple;Carbon;Multimedia", offset = 172496, length = 74960, weak_import = true },
  { fragment_name = "Apple;Carbon;Networking", offset = 247456, length = 5464, weak_import = true },
]

[target.sdk]
packages = ["macos9-sdk"]
requires = [
  "classic.universal-interfaces.headers",
  "classic.carbon.headers",
  "classic.carbon.imports",
  "classic.math.imports",
]

The fragment extents above match the sample CodeWarrior 8 CarbonLib data fork only. Use the actual checked-in example for the complete manifest and verify that offsets match the exact SDK file you supply. macmake inspect examples/first-app validates the whole manifest.

Sources, compiler and per-source settings

sources is an explicit ordered list; macMAKE does not infer project source membership from a directory scan. Paths are project-relative, absolute paths and backslashes are rejected, and duplicate entries are rejected. Parent components are preserved; see the path rules below before using ...

language accepts c, c++, or mixed; omitted means c. compiler supports:

• standard: c89 (default) or c99.
• structure_alignment: power or mac68k.
• char_signedness: signed or unsigned.
• source_compatibility: native or codewarrior-classic.
• prefix_header: project-relative path.
• defines: [[target.compiler.defines]] rows with required name and

optional string value.

• optimization_level: integer 0 through 3.
• include_search: optional table with source_directory_first,

access_path_order = "user-first", and always_search_user_paths.

• CodeWarrior compatibility booleans and C++ switches shown in the schema.

[[target.source_compiler_settings]] selects an existing member by its source path and can add per-source defines and prefix_headers. It may not name a source absent from sources; a source may have at most one such row. C++ flags are not a claim of complete C++ runtime/ABI support.

Access paths and SDK references

[[target.access_paths]]
class = "user"       # user | system
path = "include"
anchor = "project"   # project | project-relative | sdk
recursive = false

anchor defaults to project, recursive to false. ProjectRelativePath normalizes . components and forward slashes, rejects absolute paths and backslashes, and preserves ... Project and SDK anchors refuse lexical escape; the explicit project-relative anchor permits parent components.

The default include policy has source_directory_first = false, access_path_order = "user-first", and always_search_user_paths = true. Quoted includes check their source directory first only when configured; angle-bracket includes never check that source directory. User paths precede system paths. See macmake help access-paths.

[target.sdk] accepts optional name, packages and requires arrays. Use packages for new manifests. When both name and packages are present, they must agree; name is retained as a compatibility form. An empty request resolves to automatic package selection. Capability names are strings resolved against registered packages; see macmake help sdk for registration and discovery.

Libraries and link ordering

[[target.libraries]] rows are ordered. Kinds:

• system-import (default): logical CFM system library, no path.
• runtime: provider/runtime input, no path.
• vendor, object, archive, cfm-merge: require a project-relative

path.

weak_import defaults false. pef_fragments is only allowed on system-import; each row has fragment_name, offset, positive length, and optional weak_import. See macmake help libraries for ordering and fragment rules.

subtargets contain target and optional link_against_output (default true). link_order can explicitly interleave entries with kind = "source" and path, kind = "library" and zero-based index, or kind = "subtarget" and target. Each entry must refer to a declared source, library or subtarget. Avoid link_order unless the target requires a measured non-default order.

Resources and output metadata

resources accepts path strings (default kind rez-source) or tables with path and optional kind = "rez-source" | "precompiled-fork". [target.application] requires printable four-character creator and file_type; it may set output_name and [target.application.memory]. Memory requires positive minimum_heap_bytes and preferred_heap_bytes >= minimum_heap_bytes; optional stack size must be positive. size_flags is a 16-bit integer.

[target.cfm_fragment] describes an application fragment; [target.shared_library] is for shared-library targets. They are mutually exclusive and require output_name, creator, file_type, and exports (none, pragma, explicit-list, all). [target.resource_output] is required by resource-collection, and may be used by static-library; it requires output name, creator, file type, and copy_fragments.

Path and semantic validation

• Manifest paths must be non-empty, anchor-relative paths using /; absolute

paths and backslashes are rejected. .. is preserved and may be rejected by Project/SDK anchor escape checks; explicit project-relative anchors may point at intentional adjacent project files.

• Output names for application, resource-output, and fragment settings must

be filenames, not directory paths.

• Finder codes are exactly four printable ASCII characters.
• Duplicate source/resource entries and duplicate exports are rejected.
• shared_library and cfm_fragment cannot both be present.
• resource_output and custom_runtime have target-kind/profile constraints.
• Runtime/provider/platform/API combinations must be coherent.
• SDK package names must match local catalog IDs; required capabilities must

be present in the selected registered package(s).

• A schema-valid manifest can still fail because a file, provider, library,

or capability is unavailable. Run inspect, then doctor.

Use macmake schema manifest --json to retrieve the complete field and enum list programmatically. Use macmake help targets, help access-paths, help libraries, and help sdk for the cross-field behavior.

targets and target types

Targets and output kinds

Each [[target]] table names a build node with an explicit source/resource/ library membership and a platform, architecture, API, runtime, executable, backend, and optional compiler target profile.

Target kinds accepted by the manifest

• application (default): application/fragment outputs; the qualified v0.1.1

workflow is Classic PowerPC CFM/PEF C. The candidate also has a bounded, experimental native M68000 application profile described below.

• static-library: project archive-style target. Support depends on the

selected backend and runtime; inspect the target diagnostics.

• shared-library: CFM shared-library target with shared_library settings;

advanced and not the v0.1 application support promise.

• resource-collection: merge resource inputs into a configured resource

output; requires resource_output.

• code-resource: flat code intended for a Classic resource fork; advanced

or experimental in this release.

The manifest parser accepts more combinations than the v0.1 product has qualified. The current supported application profile is Linux x86-64 host to Classic Mac OS PowerPC, CarbonLib/Classic API as declared, CFM, PEF, C89/C, the macmake-classic backend with a supported compiler target, registered user SDK inputs and required runtime libraries. The exact first-app manifest is the working reference.

Compiler and runtime profile identifiers

compiler_target is optional unless backend = "macmake-classic". The parser recognizes these identifiers:

• classic-ppc-xcoff-c-v1: Classic PowerPC XCOFF C compiler contract.
• classic-ppc-xcoff-cxx-preview-v1: corresponding C++ preview contract.
• classic-68k-code-resource-c-v1: experimental 68K code-resource compiler.
• classic-68k-segmented-app-c-v1: experimental, bounded native M68000

segmented application contract; requires runtime_profile = "macmake-classic-m68k-c-v1".

• cw8-os9-carbon-ppc-c-v1-preview: native PowerPC C compiler contract used

by the v0.1 Classic runtime profile and diagnostic probes.

runtime_profile defaults to retro68-newlib. Accepted values:

• retro68-newlib: legacy Retro68/Newlib provider profile; not the packaged

native provider.

• codewarrior-msl-compatible: user supplied MSL runtime inputs with the

native v0.1 C application path. The first-app manifest is the reference.

• project-custom: explicit startup objects, runtime libraries, header paths

and defines in [target.custom_runtime]; advanced.

• macmake-classic-c-v1: macMAKE native Classic C runtime profile.
• macmake-classic-m68k-c-v1: experimental native M68000 application startup,

Toolbox ABI, and single-segment CODE-resource profile.

• macmake-classic-entry-probe-v1: diagnostic entry-only profile.
• macmake-classic-direct-entry-probe-v1: diagnostic direct-entry profile.
• macmake-classic-raw-entry-probe-v1: diagnostic hand-written entry profile.
• macmake-classic-raw-entry-probe-no-empty-data-v1: diagnostic PEF

structure comparison.

• macmake-classic-startup-probe-v1: diagnostic startup instrumentation.

The *-probe-* profiles are experimental test fixtures, not application templates. For a supported C application, copy the relevant settings from examples/first-app/macmake.toml and change its project-specific source, access-path, SDK, library and application metadata inputs.

The v0.1.1 candidate includes a normal macmake build route for the exact M68000 profile above. It is limited to C89, one near-model CODE 1 segment, bounded PC-relative code and globals, no external libraries, and the documented in-process Rez subset. It is experimental and does not provide a general 68K application ABI, CFM-68K, or broad OS compatibility. The parser also accepts macos-x, dyld, mach-o, C++, and mixed-language values in other retained or experimental combinations; those values do not establish macOS-host or Mac OS X target support. The system-extension command is separately marked experimental.

platform accepts classic-mac-os or macos-x; architecture accepts powerpc or m68k; api accepts classic, carbon-lib, or carbon-framework; runtime accepts cfm or dyld; executable accepts pef or mach-o. These are parser values, not a claim that each cross product is implemented for the released host.

Selection and dependencies

macmake build PROJECT chooses project.default_target when present. If no default is configured, a project with one selectable target can be built without --target; otherwise pass the exact --target NAME. Target names are case-sensitive strings.

Subtargets form a dependency graph. macMAKE builds prerequisite targets before the selected target. link_against_output = false builds a prerequisite without adding its output as a link input; its default is true.

Use:

macmake inspect PROJECT
macmake doctor PROJECT --target "TARGET NAME"
macmake build PROJECT --target "TARGET NAME"

Unknown targets are errors. Check exact names with inspect; do not guess target names from output filenames.

Stability labels

The command reference labels stable supported behavior, diagnostic operations, and experimental/import/legacy surfaces. macmake system-extension, XML import, probe runtime profiles, and Mac OS X combinations are outside the qualified v0.1.1 application workflow. See macmake help compatibility.

header and access path resolution

Header and access path resolution

Access paths are target-declared locations used for includes and project inputs. They are not implicit recursive scans of the entire SDK or project.

[[target.access_paths]]
class = "user"          # user | system
path = "include"
anchor = "project"      # default; project | project-relative | sdk
recursive = false       # default

Paths are declared in the manifest and resolved according to their anchor. project is relative to the manifest directory and refuses lexical escape above that root. sdk is relative to an SDK root and refuses escape above that root. project-relative preserves historical project-relative lookup and permits parent components such as ../shared; use it only when those adjacent files are intentional.

The default compiler.include_search policy has source_directory_first = false, access_path_order = "user-first", and always_search_user_paths = true. When enabled, source_directory_first checks the including source's directory before access paths for quoted includes; it does not apply to angle-bracket includes. User paths precede system paths regardless of table declaration order. Angle-bracket includes also search user paths by default; set always_search_user_paths = false to limit them to system paths. recursive = true searches beneath the declared root. Resolved SDK header roots are appended after declared access paths.

Diagnose one include without building:

macmake resolve-header PROJECT --target TARGET --from src/main.c Carbon.h

The source path must be a project member/resolvable path. The command reports the selected candidate; status 1 means it found no matching header. The accepted --sdk-root option is deprecated; supplying it returns an error. Register SDKs and use [target.sdk]. Use macmake sdk inspect ID to see registered header roots and macmake sdk verify ID to recheck package files.

An unresolved header can mean the wrong source include spelling, an omitted [[target.access_paths]], a wrong anchor, a missing SDK registration, or an SDK package without the needed headers. A resolved header does not prove that the compiler accepts its declarations or that referenced symbols link.

libraries, imports, and link order

Libraries, CFM imports, and link order

Libraries are declared in [[target.libraries]] rows in semantic order. They may describe SDK system imports, runtime inputs, project archives or objects, vendor inputs, or CFM fragment merging.

[[target.libraries]]
name = "CarbonLib"
kind = "system-import"

[[target.libraries]]
name = "MSL_C_Carbon"
kind = "archive"
path = "sdk/MSL_C_Carbon.Lib"

Kinds and path rules:

• system-import: logical CFM import library, resolved through the declared

SDK. It has no project path.

• runtime: runtime/provider library, selected according to the runtime

profile; no project path.

• vendor, object, archive, cfm-merge: require a project-relative

path to a file.

Libraries are ordered. Classic archive extraction and CFM import resolution can depend on order. Preserve measured CodeWarrior order; avoid sorting the list alphabetically.

weak_import = true marks the library's CFM imports weak where supported. pef_fragments can describe concatenated PEF fragment extents on a system-import data fork:

pef_fragments = [
  { fragment_name = "CarbonLib", offset = 0, length = 80688, weak_import = false },
]

Offsets and lengths are bytes in that data fork. Fragment names and extents must match the exact SDK file; do not copy example offsets to another file.

subtargets express target prerequisites. link_order can explicitly interleave source, library (zero-based index into libraries), and subtarget entries. Each reference must point to declared membership. This advanced override should only be used when the required sequence is known.

If the linker reports unresolved CFM imports, verify that the logical import library is declared, SDK capabilities map it, and the correct import library is registered. If a runtime symbol is unresolved, identify its provider and runtime archive; do not silently substitute an unrelated runtime. Run macmake doctor for provider and library availability, and inspect the build evidence for the exact unresolved symbol.

SDK registration and capabilities

SDK registration and capabilities

macMAKE does not redistribute proprietary Apple Universal Interfaces, Metrowerks SDK archives, or historical import libraries. Supply SDK material you are authorized to use. Registration references the directory in place; it does not copy it into the project or macMAKE installation.

For a minimal Classic PowerPC C setup, sdk fetch --minimal performs a Git sparse checkout of selected headers and libraries from mplsllc/macMAKELibs, pinned to the revision and selected-file checksums in the installed CLI's minimal-classic-ppc-c-v1.json manifest. It requires Git and network access, does not register the SDK, and does not fetch unrelated CodeWarrior trees or C++ runtime material:

macmake sdk fetch --minimal
macmake sdk add "$HOME/.local/share/macmake/macMAKELibs/Universal" --id macos9-sdk

The fetched MSL headers and archives remain in the same checkout. For a custom location, pass --destination PATH and register its Universal subdirectory. The command refuses to overwrite an existing path from a different revision or with mismatched required archive hashes. To copy the three MSL archives into the packaged first-app example, run its setup helper with the fetched checkout as its root:

examples/first-app/setup-user-msl.sh "$HOME/.local/share/macmake/macMAKELibs"

The checkout contains separately supplied historical headers and runtime libraries. The macMAKE archive does not contain them. The repository and manifest establish where the files came from and their content identity; they do not grant rights to use or redistribute them. Confirm your authorization before fetching or using these materials.

macmake sdk add "$HOME/SDKs/CodeWarrior/MacOS Support/Universal" --id macos9-sdk
macmake sdk list
macmake sdk inspect macos9-sdk
macmake sdk verify macos9-sdk

The default catalog is $XDG_CONFIG_HOME/macmake/sdk-catalog.json when XDG_CONFIG_HOME is set, otherwise $HOME/.config/macmake/sdk-catalog.json. MACMAKE_SDK_CATALOG overrides it; --catalog takes precedence over the environment variable.

The catalog records package identity, root, detected architectures/runtimes, header/import/Rez roots, capabilities, and content fingerprints. The default catalog is per-user. --catalog PATH selects a different catalog for every SDK subcommand and supported build/diagnostic command.

Targets request SDK inputs with [target.sdk]:

[target.sdk]
packages = ["macos9-sdk"]
requires = ["classic.universal-interfaces.headers", "classic.carbon.imports"]

Capabilities are detected from the supplied package and matched by exact identifier. APIs and declared system-import libraries can add required capabilities during target resolution. Consult sdk inspect ID for what a package currently advertises.

The catalog currently recognizes these capability identifiers:

• classic.universal-interfaces.headers
• classic.carbon.headers, classic.carbon.imports
• classic.interface.imports, classic.math.imports
• classic.open-transport.headers, classic.open-transport.imports,

classic.open-transport.internet.imports

• classic.navigation-services.headers,

classic.navigation-services.imports

• classic.appearance.headers, classic.appearance.imports
• classic.quicktime.headers, classic.quicktime.imports
• classic.rez.system-definitions

The registered catalog is authoritative for which of these a particular SDK actually provides. Listing a capability in a project does not create or redistribute that SDK component.

sdk fetch downloads pinned files into the chosen destination. sdk add writes user registration state. sdk list and sdk inspect read the catalog. sdk verify reads and hashes indexed package contents; it does not change them. A stale package can be re-registered after checking that the root is correct.

Common recovery:

• No package registered: macmake sdk add ROOT --id ID.
• Target requests a capability not found: register the complete authorized

SDK component, inspect it, then use the package ID in the manifest.

• Stale fingerprints: verify the SDK files and re-register the intended root.
• Wrong package selected: set packages explicitly instead of using

automatic selection.

The catalog is a local path/fingerprint index, not a license check or proof that a package is legally redistributable. Keep proprietary inputs out of public release archives.

compiler and provider setup

Compiler and provider setup

For the v0.1.1 Linux candidate, the supported host is Linux x86-64. The distributable toolchain contains the PowerPC provider, resource and inspection/package tools, and their redistributable support files. The qualified application path builds Classic PowerPC CFM/PEF C applications. The candidate also includes an experimental independent M68000 GNU provider and macMAKE-controlled segmented-application output. It is limited to the exact profile pair documented by macmake help targets; it does not provide general 68K, CFM-68K, or universal System 6–9 compatibility.

Set the toolchain root to the extracted toolchain directory, or pass the same path to a command:

export MACMAKE_TOOLCHAIN_ROOT="$HOME/.local/share/macmake/current/toolchain"
macmake doctor PROJECT --target TARGET
macmake build PROJECT --target TARGET

--toolchain-root overrides MACMAKE_TOOLCHAIN_ROOT. Native provider diagnostics also recognize MACMAKE_PPC_GCC and MACMAKE_PPC_AS as direct compiler/assembler executable overrides; use these only when intentionally selecting and validating a different tool. system-extension accepts MACMAKE_M68K_TOOLCHAIN_ROOT is available for the experimental native M68000 application provider. Normal macmake build selects it only when the manifest uses both compiler_target = "classic-68k-segmented-app-c-v1" and runtime_profile = "macmake-classic-m68k-c-v1" with the required classic M68000 application fields. system-extension is a separate experimental workflow and does not select this application profile.

doctor checks the compiler target triple, compiler runtime availability, assembler, declared SDK package/capabilities, and library inputs. It may run small version/identity probes, but it does not compile the project.

Missing-tool recovery:

1. Run macmake --version to confirm which binary is running.
2. Locate the installed toolchain directory from the release layout.
3. Pass --toolchain-root PATH or set MACMAKE_TOOLCHAIN_ROOT.
4. Run macmake doctor PROJECT --target TARGET again.

Do not point the native release workflow at Retro68 to mask a missing native tool. Provider choice comes from the manifest backend; see macmake help manifest and macmake help compatibility.

build graph and commands

Build graph and command behavior

macmake build PROJECT [--target NAME] loads and validates macmake.toml, selects the requested/default target, walks its target dependency closure, then executes the required compilation and link/resource/package steps. The target graph is explicit: source membership, libraries, resources, access paths and subtargets come from the manifest.

Use these operations in order on an unfamiliar project:

macmake inspect PROJECT
macmake doctor PROJECT --target TARGET
macmake compile PROJECT --target TARGET
macmake build PROJECT --target TARGET

inspect reads the manifest. doctor checks declared provider and SDK availability. compile compiles the transitive source closure without linking or packaging. build performs a full build. clean deletes generated outputs and incremental state for a selected closure.

--explain on build emits build decisions and evidence while continuing with actual build operations. It is not a dry-run guarantee.

Most command failures use exit 2 for invalid command/configuration/process errors. Status 1 is a completed diagnostic/build operation that found an unresolved item or failed structural validation. Check both stdout and stderr and preserve build evidence before cleaning.

Use macmake help <command> for exact command arguments and side effects.

incremental builds and cleaning

Incremental builds

macMAKE records build nodes and fingerprints their declared inputs and toolchain identities. An unchanged repeat build checks the graph and should reuse current outputs without invoking unnecessary compile/link/package stages.

macmake build PROJECT --target TARGET
macmake build PROJECT --target TARGET

Use --explain to print decisions while building; it does not promise a side-effect-free preview. Compiler, assembler, resource, link, and packaging nodes may become stale when a source/header/library/resource/manifest or provider input changes. A dependency change invalidates dependent nodes in the graph.

macmake compile runs source compilation without linking/package work. macmake clean PROJECT --target TARGET removes generated files and state for the target closure. Preserve build/ reports before cleaning if they are needed for diagnosis or release evidence.

For a safe invalidation check, copy a project into a disposable directory, change a test input there, build, restore the copied input and build again. Do not alter original application sources for an incremental experiment.

If a node unexpectedly rebuilds, inspect build evidence for the changed input/tool identity. If a stale output remains, run clean for the exact target and rebuild. Do not delete unrelated project files or manually edit build state as a first diagnostic step.

build outputs and inspection

Build outputs and artifact inspection

Output names and target kind come from the manifest. Generated products live under the project's build/ directory. Single-target projects place outputs directly there; multi-target projects may have target-specific subdirectories. Use find build -type f to locate exact outputs.

For the supported Classic application profile, expected product classes are:

• Native compiler object files for source members.
• Link map/build evidence and target PEF executable fragment.
• Resource fork containing application and CFM metadata/resources.
• Finder-info sidecar containing creator/type metadata.
• MacBinary II .bin transport package containing data fork, resource fork,

and Finder information.

The manifest's [target.application] requires four-character creator and file_type; optional output_name controls the application output name. Memory requirements are encoded by the optional nested memory table.

Inspect an application using the actual files:

macmake inspect-artifact APP.pef --resource-fork APP.rsrc \
  --finder-info .finf/APP.APPL --creator HmPP --file-type APPL --json

The data fork argument can be a PEF file. Resource fork and Finder-info must be supplied separately. The four-character values are expected metadata and must be printable ASCII. Status 1 means structural validation did not pass; status 2 is an input/argument/operational error.

Host artifact inspection verifies structure and metadata. Mac OS 9 launch, startup, UI and runtime behavior must be checked separately in a guest or physical Mac. Preserve the exact MacBinary hash when transferring a candidate.

Macintosh file forks and staging

Classic Macintosh forks and staging

A Classic Macintosh application can consist of a data fork, resource fork, and Finder metadata. macMAKE's application build packages these into MacBinary II (.bin) for transport. Raw build files are useful for inspection but are not equivalent to a fork-preserving transport container by themselves.

Use the MacBinary package when transferring the app:

macmake stage build/HelloPPC.bin --destination /path/on/classic-share/HelloPPC
macmake verify build/HelloPPC.bin --destination /path/on/classic-share/HelloPPC

For raw forks, stage and verify require both --resource-fork and --finder-info. A single sidecar is rejected. Stage writes the destination and invokes Netatalk ad; verify reads and compares. clone-classic copies an existing live file through Netatalk while preserving complete observed metadata, and requires a fresh destination.

Set MACMAKE_NETATALK_AD when the ad program is not found through PATH. Check that the destination filesystem exposes Netatalk resource fork and Finder metadata support before staging. Do not use a legacy share whose fork behavior has not been verified.

Staging to a host share verifies transport representation, not Mac OS 9 execution. The user must unpack/launch the file in the guest and report the runtime result separately.

diagnostics and recovery

Troubleshooting and recovery

Start with non-mutating diagnostics:

macmake --version
macmake inspect PROJECT
macmake doctor PROJECT --target TARGET
macmake sdk list
macmake sdk inspect ID

Manifest or target errors

Read the field and target named in the diagnostic. Use macmake schema manifest --json for field shape and macmake help manifest for semantic rules. inspect reports available target names. Pass the exact name with --target.

SDK package or capability missing

Register the authorized SDK root, inspect what was detected, and verify its content:

macmake sdk add "$HOME/SDKs/Authorized/Universal" --id macos9-sdk
macmake sdk inspect macos9-sdk
macmake sdk verify macos9-sdk

Then ensure the manifest's packages and requires match the catalog. macMAKE does not supply proprietary SDK files.

Compiler or assembler unavailable

Use the archive's toolchain directory with --toolchain-root or set MACMAKE_TOOLCHAIN_ROOT. Run doctor again. Do not substitute another toolchain without validating its target triple, compiler runtime, assembler, and output format.

Header not resolved

Run macmake resolve-header PROJECT --target TARGET --from SOURCE HEADER. Check source-relative spelling, access-path class, anchor, root path, SDK package header capability and file existence.

Runtime library or import unresolved

Check [[target.libraries]] kind and order. A system import needs a matching SDK import library/capability; a project archive needs an existing project-relative path; runtime libraries come from the selected provider profile. Preserve the exact unresolved symbol and build evidence. Do not silently fall back to unrelated archives.

Compilation, link or artifact validation failed

Retain command line, stdout, stderr, manifest, macMAKE version, provider identity, and build/ evidence. build --explain prints decisions but still runs the build. Use inspect-artifact only with the exact data, resource and Finder inputs.

Linux artifact works but Mac OS 9 does not launch

Host structural checks do not prove guest runtime behavior. Preserve the original MacBinary, checksums, guest OS version, file-transfer method, and launch evidence. Do not report runtime success based on a host-side command that only opens and exits without expected UI if the application is supposed to display a UI.

supported scope and limitations

Compatibility and supported scope

The v0.1.1 Linux candidate has a qualified PowerPC C application workflow: Linux x86-64 host, Classic Mac OS PowerPC target (validated on Mac OS 9), CFM/PEF output, declared user-supplied SDK/runtime inputs, native macMAKE compiler and linker path, resources/Finder metadata, and MacBinary II packaging. It also includes an experimental independent native M68000 C application workflow selected by the exact classic-68k-segmented-app-c-v1 and macmake-classic-m68k-c-v1 profile pair. That profile creates one bounded CODE 1 segment, CODE 0 startup/jump-table resources, Finder metadata, and MacBinary II output through the ordinary macmake build command.

The toolchain archive excludes proprietary Apple Universal Interfaces, Metrowerks MSL libraries and other nonredistributable historical materials. Users supply SDK/runtime files they are authorized to use.

The experimental 68K profile is not a general 68K compatibility promise. It is currently limited to C89, one near-model CODE 1 segment, bounded PC-relative code and globals, no external linked libraries, and a documented in-process Rez subset. Multiple segments, general A5-relative application globals, C++ runtime support, CFM-68K, and broad System 6/7 compatibility are not provided. The exact macMAKE v0.1.1 RC6 Linux candidate built makePAD, and the resulting MacBinary was observed running in QEMU 8.2.2 with a Mac OS 9.2.2 mac99/G4 guest. The operator observed text entry, an unsaved-changes dialog, and exit to Finder. This is one RC6 candidate/application result, not a test of the corrected RC7 screenshot implementation, every application, or another OS version. RC7's screenshot behavior is host-tested with QEMU-style PPM output; a corrected RC7 real-guest capture remains pending. Earlier development observations for makePAD and HelloWindow remain application-specific.

The following are not release claims: complete CodeWarrior Pro replacement, complete .mcp import, arbitrary compiler-option equivalence, unrestricted C++ ABI/runtime parity, macOS-host builds, Mac OS X output, a bundled Rust compiler or direct Rust-source compilation by macmake build, or universal Rez compatibility. A separate pinned Rust toolchain can emit a PowerPC XCOFF object consumed by the ordinary macMAKE linker/package workflow; the bundled interop sample has build and structural evidence, not a runtime test of that exact sample on a Classic Mac. The parser may retain additional experimental or legacy shapes for research and fixtures; the command/topic stability labels identify them.

import-cw-xml is experimental and accepts XML exports rather than arbitrary binary project files. system-extension, diagnostic runtime probes, and some library target kinds are outside the application workflows.

Three kinds of evidence are separate:

1. Linux command/build and structural artifact validation.
2. Mac OS 9 load/startup/runtime behavior in the guest.
3. Application-level behavior such as UI, network or user-data handling.

Passing one level does not prove the next. A successful build or artifact inspection is not a Mac OS 9 runtime test.

working project examples

Examples

The examples/first-app directory is the supported C application example. It has two C89 sources and a native macmake.toml. The user must provide authorized Universal Interfaces and Metrowerks MSL archives as explained in its README.

cd examples/first-app
export MACMAKE_TOOLCHAIN_ROOT="${MACMAKE_TOOLCHAIN_ROOT:-../../toolchain}"
./setup-user-msl.sh "$HOME/SDKs/Authorized/CodeWarrior"
macmake sdk add "$HOME/SDKs/Authorized/CodeWarrior/MacOS Support/Universal" --id macos9-sdk
macmake inspect .
macmake doctor . --target "Classic PPC C"
macmake build . --target "Classic PPC C"

The helper copies only user-supplied local libraries into the example's ignored sdk/ directory and reports hashes. The example's manifest records exact system-import/library inputs and output metadata. Run macmake help manifest before authoring variants.

Other repository fixtures cover experimental and historical semantics; they are not all release examples. Check macmake help compatibility before selecting a non-application target profile.

optional QEMU Macintosh runtime testing

Optional QEMU Macintosh runtime smoke test

macmake run supports one interactive profile: QEMU's mac99 PowerPC machine with a G4 CPU and a user-owned Mac OS 9.2.2 disk image. It does not bundle a ROM, operating-system image, or emulator.

The command creates a new qcow2 copy-on-write overlay and attaches that overlay to QEMU. QEMU writes to the overlay; the configured base disk is SHA-256 hashed before and after the run. The overlay and evidence are retained under $XDG_STATE_HOME/macmake/runs/ or ~/.local/state/macmake/runs/.

Profile

Create a JSON file with paths to an authorized disk image and an application already staged inside that image using a Mac-aware transfer method:

{
  "schema_version": 1,
  "emulator": "qemu-system-ppc",
  "qemu_img": "qemu-img",
  "machine": "mac99",
  "cpu": "g4",
  "memory_mib": 1024,
  "display": "gtk",
  "guest_os": "Mac OS 9.2.2",
  "base_disk": "$HOME/MacOS-9.2.2.qcow2",
  "application": {
    "name": "HelloPPC",
    "guest_path": "Macintosh HD:Applications:HelloPPC"
  }
}

The initial profile accepts only mac99, g4, Mac OS 9.2.2, and a GTK or SDL display. The guest path and OS identity are labels for the operator; the command does not inspect the HFS volume or infer the guest's installed OS. --artifact records and hashes a host-side MacBinary file but does not copy it into the disk image.

Run and checkpoints

macmake run ./qemu-macos-9.2.2.json \
  --artifact ./build/HelloPPC/ClassicPPCC/HelloPPC.bin \
  --build-evidence ./build/HelloPPC/ClassicPPCC/HelloPPC.build-evidence.json

The QEMU window opens. Boot Finder and check About This Computer to identify the guest OS. Before answering yes to the boot checkpoint, close About This Computer and any other dialog so the boot capture shows Finder. Launch the configured application manually. Before answering yes to the launch checkpoint, bring its main window to the front and dismiss unrelated Finder or About This Computer dialogs. The application-state capture is taken immediately after that answer. The CLI asks separately whether the captured application state is correct and whether the application exited normally. These are operator-confirmed observations, not automated guest assertions.

QEMU 8.2.2 writes binary P6 PPM data for QMP screendump; macMAKE saves it as guest_boot.ppm or application_state.ppm, validates the PPM header and pixel length, and records the actual format, dimensions, SHA-256, path, and named checkpoint in run.json schema 2. A failed or truncated capture is a test failure. If the two captures are byte-identical, both are retained and labeled, but the run cannot claim runtime-state confirmation from duplicate visual evidence. Separate screenshots supplement the operator's checkpoint answers; they do not independently prove that an application works.

The host artifact is recorded and hashed but is not copied into the guest disk. When --build-evidence is supplied, the CLI verifies that the evidence record's MacBinary SHA-256 matches before setting artifact_constructed to true. If no matching record is supplied, construction is marked unverified; the CLI never infers a build from file existence alone.

Use --timeout SECONDS to bound the interactive session or --json to print the final structured result. Each run directory contains run.json, qemu.log, serial.log, the qcow2 overlay, and validated PPM screenshots when captured. The JSON keeps emulator startup, guest boot, OS confirmation, application launch, visible state, normal exit, timeout, and QEMU exit status separate. Screenshot records are objects with checkpoint, path, format, sha256, width, height, and distinct_from_prior_checkpoint fields. Exit code 0 means the guest OS, application launch, and visible state were confirmed; code 1 means a checkpoint failed, was not confirmed, or timed out.

To keep the test reproducible, retain the profile, base-disk hash, run record, screenshots, and host artifact hash together. Do not share system images or ROM files unless their redistribution is authorized.

Limits

This is an interactive QEMU smoke-test workflow for the single named guest profile. It does not inject a host artifact into a Macintosh disk, automate Finder, verify application output independently, or prove physical Quadra hardware behavior. Basilisk II, SheepShaver, other QEMU machines, other OS versions, headless runs, and automatic test-result channels are unsupported by this command. Structural artifact inspection remains a separate host-side check.

offline workflows for coding agents

Offline workflow for coding agents

The installed macMAKE executable is the authoritative reference for its own version. Use these commands before editing or running project operations:

macmake help --json
macmake help manifest --json
macmake schema manifest --json
macmake inspect PROJECT
macmake help targets
macmake doctor PROJECT --target TARGET

Recommended sequence:

1. Discover commands with macmake help; query JSON when structured parsing

is useful.

1. Inspect the project and list exact target names.
2. Check toolchain, SDK packages/capabilities and declared libraries with

doctor, sdk list, sdk inspect, and sdk verify.

1. Read relevant offline topics: manifest, access-paths, libraries, toolchain,

output and compatibility.

1. Diagnose a missing header with resolve-header; correct the manifest or

register an authorized SDK. Diagnose imports from doctor and build evidence.

1. Run the requested build with explicit project and target arguments.
2. Inspect the exact generated components using inspect-artifact --json.
3. Summarize the command, version, status, artifacts and retained evidence.
4. If transport is requested, stage the MacBinary to the explicitly selected

Classic filesystem destination, then verify it.

1. Report Linux build/structure checks separately from Mac OS 9 guest

launch and application behavior.

Recovery patterns:

• Unknown target: macmake inspect PROJECT, copy the exact target name,

then rerun doctor/build with --target "exact name".

• Missing SDK: macmake sdk list; register authorized material with

macmake sdk add ROOT --id ID; inspect and verify it; update [target.sdk].

• Unresolved import: read the exact symbol/provider diagnostic, inspect

[[target.libraries]] and required SDK capabilities, run sdk verify, correct the actual missing input, and rebuild. Do not fabricate symbols or substitute an unrelated runtime.

Read-only discovery commands include help, inspect, doctor, sdk list, sdk inspect, sdk verify, resolve-header, and inspect-artifact. build and compile create build outputs; clean deletes them; sdk add changes the user's registration catalog; import-cw-xml writes a manifest; stage and clone-classic write destination files.

This guide requires no particular LLM provider or agent framework. Do not claim Mac OS 9 execution based on Linux build or artifact evidence.