{ "commands": [ { "description": "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.", "environment_variables": [], "examples": [ "macmake help", "macmake help build", "macmake help sdk add", "macmake help manifest --json", "macmake help --all" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "Only embedded command and topic reference data." ], "limitations": [ "Help is specific to the installed binary version." ], "options": [ { "allowed_values": [], "default": "false", "description": "Print all command references and topic documents.", "duplicate_behavior": "idempotent", "flag": "--all", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": null }, { "allowed_values": [], "default": "false", "description": "Emit deterministic JSON instead of formatted terminal text.", "duplicate_behavior": "idempotent", "flag": "--json", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": null }, { "allowed_values": [], "default": "false", "description": "Show the top-level help index.", "duplicate_behavior": "idempotent", "flag": "--help", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": null } ], "outputs": [ "Help text or JSON on stdout; no terminal control sequences." ], "path": [ "help" ], "positional_arguments": [ { "description": "Command path such as build or sdk, or topic such as manifest.", "name": "command-or-topic", "required": false }, { "description": "Nested command such as sdk add.", "name": "subcommand", "required": false } ], "related_commands": [ "schema manifest --json" ], "side_effects": [ "Read-only; does not load a project or start tools." ], "stability": "supported; offline", "summary": "Show concise help, a detailed command/topic reference, or JSON help.", "syntax": "macmake help [command-or-topic [subcommand]] [--all] [--json]", "troubleshooting": [ "Run `macmake help topics` to list topic names and aliases." ] }, { "description": "Prints the product version embedded in this binary. It does not contact an update service.", "environment_variables": [], "examples": [ "macmake --version" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "No input." ], "limitations": [ "Reports this binary's product version; it does not query a remote release." ], "options": [], "outputs": [ "macMAKE VERSION on stdout." ], "path": [ "version" ], "positional_arguments": [], "related_commands": [ "help" ], "side_effects": [ "Read-only; no network request or update check." ], "stability": "supported", "summary": "Print the installed macMAKE version.", "syntax": "macmake --version (alias: -V)", "troubleshooting": [ "If the version is unexpected, check `command -v macmake` and PATH order." ] }, { "description": "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.", "environment_variables": [], "examples": [ "macmake update check" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "Public GitHub latest-release metadata over HTTPS; curl must be available." ], "limitations": [ "Checks stable numeric x.y.z releases only; it does not install updates." ], "options": [], "outputs": [ "Current-version status or a newer release version and release URL." ], "path": [ "update", "check" ], "positional_arguments": [], "related_commands": [ "update enable", "update disable", "--version" ], "side_effects": [ "Contacts api.github.com; GitHub receives ordinary request metadata such as IP address and User-Agent. No local files are changed." ], "stability": "supported", "summary": "Check GitHub for a newer stable macMAKE release.", "syntax": "macmake update check", "troubleshooting": [ "Check network access and curl if the release API cannot be reached." ] }, { "description": "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." } ], "examples": [ "macmake update enable" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "No network input; writes the user's local preference file." ], "limitations": [ "Only interactive CLI invocations check automatically; no background process or automatic update is installed." ], "options": [], "outputs": [ "Confirmation on stdout." ], "path": [ "update", "enable" ], "positional_arguments": [], "related_commands": [ "update check", "update disable" ], "side_effects": [ "Creates or updates $XDG_CONFIG_HOME/macmake/update-check.json, or $HOME/.config/macmake/update-check.json." ], "stability": "supported; opt-in and disabled by default", "summary": "Opt in to occasional interactive update notices.", "syntax": "macmake update enable", "troubleshooting": [ "Set XDG_CONFIG_HOME or HOME if macMAKE cannot locate a configuration directory." ] }, { "description": "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." } ], "examples": [ "macmake update disable" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "No network input; writes the user's local preference file." ], "limitations": [ "An explicit `macmake update check` remains available and contacts GitHub." ], "options": [], "outputs": [ "Confirmation on stdout." ], "path": [ "update", "disable" ], "positional_arguments": [], "related_commands": [ "update check", "update enable" ], "side_effects": [ "Creates or updates the per-user update preference file." ], "stability": "supported", "summary": "Opt out of automatic update checks.", "syntax": "macmake update disable", "troubleshooting": [ "Set XDG_CONFIG_HOME or HOME if macMAKE cannot locate a configuration directory." ] }, { "description": "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.", "environment_variables": [], "examples": [ "macmake schema manifest --json" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "Embedded schema corresponding to the installed manifest deserializer." ], "limitations": [ "JSON Schema describes manifest structure; it cannot verify external files, SDK capabilities, provider availability, or all semantic combinations." ], "options": [ { "allowed_values": [], "default": null, "description": "Required. Emit JSON Schema Draft 2020-12 to stdout.", "duplicate_behavior": "idempotent", "flag": "--json", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": null } ], "outputs": [ "JSON Schema on stdout; no files are written." ], "path": [ "schema", "manifest" ], "positional_arguments": [], "related_commands": [ "help manifest", "inspect" ], "side_effects": [ "Read-only; no project, SDK catalog, or toolchain is loaded." ], "stability": "supported; schema versioned independently from the help response", "summary": "Print the manifest JSON Schema supported by this binary.", "syntax": "macmake schema manifest --json", "troubleshooting": [ "Use `macmake help manifest` for path and cross-field semantic constraints." ] }, { "description": "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.", "environment_variables": [], "examples": [ "macmake inspect .", "macmake inspect examples/first-app/macmake.toml" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "The selected macmake.toml and no build inputs." ], "limitations": [ "Does not prove that external compiler, SDK, library, or source files are available; use doctor or build for those checks." ], "options": [], "outputs": [ "Human-readable project and target summary on stdout." ], "path": [ "inspect" ], "positional_arguments": [ { "description": "A macmake.toml path or a directory containing macmake.toml.", "name": "project", "required": true } ], "related_commands": [ "help manifest", "build", "doctor" ], "side_effects": [ "Reads the manifest and prints its validated summary." ], "stability": "supported", "summary": "Read and summarize a project manifest.", "syntax": "macmake inspect ", "troubleshooting": [ "If the manifest is invalid, use the field-specific diagnostic and `macmake help manifest` to correct its TOML." ] }, { "description": "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.", "environment_variables": [], "examples": [ "macmake inspect-artifact build/HelloPPC.pef \\\n --resource-fork build/HelloPPC.rsrc \\\n --finder-info build/.finf/HelloPPC.APPL --creator HmPP --file-type APPL", "macmake inspect-artifact build/HelloPPC.pef \\\n --resource-fork build/HelloPPC.rsrc \\\n --finder-info build/.finf/HelloPPC.APPL --creator HmPP --file-type APPL --json" ], "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." } ], "inputs": [ "Data fork, resource fork, Finder-info sidecar, creator and file-type expectations." ], "limitations": [ "Host-side structural validation does not launch the application in Mac OS 9." ], "options": [ { "allowed_values": [], "default": null, "description": "Resource fork file to inspect.", "duplicate_behavior": "last value wins", "flag": "--resource-fork", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "Finder-info sidecar containing the four-byte file type and creator.", "duplicate_behavior": "last value wins", "flag": "--finder-info", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "Expected Finder creator code.", "duplicate_behavior": "last value wins", "flag": "--creator", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "four printable ASCII characters" }, { "allowed_values": [], "default": null, "description": "Expected Finder file type code.", "duplicate_behavior": "last value wins", "flag": "--file-type", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "four printable ASCII characters" }, { "allowed_values": [], "default": "false", "description": "Print a JSON inspection report instead of the text report.", "duplicate_behavior": "idempotent", "flag": "--json", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": null } ], "outputs": [ "Text or JSON structural report on stdout; no files are written." ], "path": [ "inspect-artifact" ], "positional_arguments": [ { "description": "Path to the executable data fork, commonly a .pef or raw application data fork.", "name": "data-fork", "required": true } ], "related_commands": [ "build", "stage", "verify", "help output" ], "side_effects": [ "Reads the supplied files only." ], "stability": "supported", "summary": "Validate and report a Classic executable and its metadata.", "syntax": "macmake inspect-artifact --resource-fork --finder-info --creator <4cc> --file-type <4cc> [--json]", "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." ] }, { "description": "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.", "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." } ], "examples": [ "macmake stage build/HelloPPC.bin --destination /srv/macfiles/HelloPPC", "macmake stage build/HelloPPC.pef \\\n --resource-fork build/HelloPPC.rsrc \\\n --finder-info build/.finf/HelloPPC.APPL --destination /srv/macfiles/HelloPPC" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "A MacBinary II file, or a data fork plus both --resource-fork and --finder-info." ], "limitations": [ "This writes a Classic file to a destination; it does not copy through an unverified legacy share or prove guest runtime behavior." ], "options": [ { "allowed_values": [], "default": null, "description": "Destination Classic file path on a mounted/served filesystem that supports the expected Netatalk metadata operations.", "duplicate_behavior": "last value wins", "flag": "--destination", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "Resource-fork input for raw-fork mode.", "duplicate_behavior": "last value wins", "flag": "--resource-fork", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [ "--finder-info" ], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "Finder-info sidecar for raw-fork mode.", "duplicate_behavior": "last value wins", "flag": "--finder-info", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [ "--resource-fork" ], "value_type": "path" } ], "outputs": [ "The destination Classic file, resource fork and Finder metadata; a verification report on stdout." ], "path": [ "stage" ], "positional_arguments": [ { "description": "MacBinary II file, or a raw data-fork file when both sidecars are supplied.", "name": "macbinary-or-data-fork", "required": true } ], "related_commands": [ "verify", "clone-classic", "inspect-artifact", "help classic-files" ], "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." ], "stability": "supported", "summary": "Write a Classic application to a Netatalk-compatible destination.", "syntax": "macmake stage --destination [--resource-fork --finder-info ]", "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." ] }, { "description": "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.", "environment_variables": [ { "name": "MACMAKE_NETATALK_AD", "purpose": "Select the Netatalk `ad` executable.", "used_when": "Defaults to `ad` from PATH." } ], "examples": [ "macmake clone-classic /srv/macfiles/ExistingApp --destination /srv/macfiles/ExistingApp-copy" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "A regular live Classic file with readable data fork and metadata." ], "limitations": [ "Requires Netatalk-compatible metadata and the `ad` command." ], "options": [ { "allowed_values": [], "default": null, "description": "New Classic file path.", "duplicate_behavior": "last value wins", "flag": "--destination", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "path" } ], "outputs": [ "A metadata-preserving copy at the destination and a verification report." ], "path": [ "clone-classic" ], "positional_arguments": [ { "description": "Existing regular Classic file on a Netatalk-compatible filesystem.", "name": "live-classic-file", "required": true } ], "related_commands": [ "stage", "verify", "help classic-files" ], "side_effects": [ "Creates a new destination file and invokes `ad cp`; it refuses an existing destination." ], "stability": "supported", "summary": "Copy an existing live Classic file while preserving its metadata representation.", "syntax": "macmake clone-classic --destination ", "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." ] }, { "description": "Compares a MacBinary II or raw-fork application description against the file already present at the destination. It does not intentionally modify the destination.", "environment_variables": [], "examples": [ "macmake verify build/HelloPPC.bin --destination /srv/macfiles/HelloPPC" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "Expected MacBinary II or data/resource/Finder-info files and an existing destination Classic file." ], "limitations": [ "Requires a readable destination on a filesystem exposing Classic metadata to macMAKE." ], "options": [ { "allowed_values": [], "default": null, "description": "Existing Classic file to verify.", "duplicate_behavior": "last value wins", "flag": "--destination", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "Resource-fork expectation for raw-fork mode.", "duplicate_behavior": "last value wins", "flag": "--resource-fork", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [ "--finder-info" ], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "Finder-info expectation for raw-fork mode.", "duplicate_behavior": "last value wins", "flag": "--finder-info", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [ "--resource-fork" ], "value_type": "path" } ], "outputs": [ "A comparison report on stdout; no destination writes." ], "path": [ "verify" ], "positional_arguments": [ { "description": "MacBinary II input, or raw data fork when both sidecars are supplied.", "name": "macbinary-or-data-fork", "required": true } ], "related_commands": [ "stage", "clone-classic", "help classic-files" ], "side_effects": [ "Reads source and destination data/fork/metadata." ], "stability": "supported", "summary": "Read and verify a previously staged Classic file.", "syntax": "macmake verify --destination [--resource-fork --finder-info ]", "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." ] }, { "description": "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.", "environment_variables": [], "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" ], "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." } ], "inputs": [ "A CodeWarrior XML project export and optionally a local CodeWarrior tree for path resolution." ], "limitations": [ "Import is experimental and does not establish complete CodeWarrior project or compiler compatibility." ], "options": [ { "allowed_values": [], "default": null, "description": "New destination TOML manifest path; existing output or evidence files are refused.", "duplicate_behavior": "last value wins", "flag": "--output", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "Select the named imported target/library when the XML contains more than one.", "duplicate_behavior": "last value wins", "flag": "--target", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [ "--codewarrior-root" ], "value_type": "string" }, { "allowed_values": [], "default": null, "description": "Root used to resolve CodeWarrior-relative inputs during import.", "duplicate_behavior": "last value wins", "flag": "--codewarrior-root", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "A TOML manifest at --output, a sibling .cw-import.json evidence file, and an import report." ], "path": [ "import-cw-xml" ], "positional_arguments": [ { "description": "CodeWarrior XML project export; this is not an arbitrary binary .mcp file.", "name": "project.xml", "required": true } ], "related_commands": [ "inspect", "build", "help manifest", "help compatibility" ], "side_effects": [ "Creates the new manifest and evidence sidecar atomically; it refuses to replace either existing file." ], "stability": "experimental", "summary": "Import a CodeWarrior project XML export as macmake.toml.", "syntax": "macmake import-cw-xml --output [--target ] [--codewarrior-root ]", "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`." ] }, { "description": "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.", "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." } ], "examples": [ "macmake resolve-header examples/first-app --target \"Classic PPC C\" --from src/main.c Carbon.h" ], "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." } ], "inputs": [ "Manifest, source path, include name, declared access paths, and the selected SDK files." ], "limitations": [ "Resolves one header path; it does not prove that the compiler accepts the header or that its declarations link." ], "options": [ { "allowed_values": [], "default": null, "description": "Target whose access paths and SDK requirements are used.", "duplicate_behavior": "last value wins", "flag": "--target", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "string" }, { "allowed_values": [], "default": null, "description": "Source file from which the include is resolved.", "duplicate_behavior": "last value wins", "flag": "--from", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "project-relative path" }, { "allowed_values": [], "default": null, "description": "Deprecated argument retained by the parser; supplying it returns an actionable error. Register SDKs with `macmake sdk add` and use [target.sdk].", "duplicate_behavior": "last value wins", "flag": "--sdk-root", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "SDK catalog override; defaults to the user catalog.", "duplicate_behavior": "last value wins", "flag": "--sdk-catalog", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "Resolution path/report on stdout; unresolved include is status 1." ], "path": [ "resolve-header" ], "positional_arguments": [ { "description": "Manifest path or project directory.", "name": "project", "required": true }, { "description": "Include spelling, for example Carbon.h or .", "name": "include", "required": true } ], "related_commands": [ "inspect", "doctor", "sdk list", "sdk verify", "help access-paths" ], "side_effects": [ "Reads project, catalog, and candidate header paths only." ], "stability": "supported", "summary": "Show how a target resolves one include name.", "syntax": "macmake resolve-header --target --from [--sdk-root ] [--sdk-catalog ]", "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`." ] }, { "description": "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.", "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." } ], "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" ], "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." } ], "inputs": [ "Manifest and explicitly listed sources, resources, libraries, SDK files, provider tools, and runtime inputs." ], "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." ], "options": [ { "allowed_values": [], "default": null, "description": "Target name. If omitted, uses project.default_target; if that is absent, target selection follows the project's single-target rule.", "duplicate_behavior": "last value wins", "flag": "--target", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "string" }, { "allowed_values": [], "default": null, "description": "Toolchain root. Overrides MACMAKE_TOOLCHAIN_ROOT.", "duplicate_behavior": "last value wins", "flag": "--toolchain-root", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "Deprecated input retained for compatibility; build reports an error and asks you to register the SDK with `macmake sdk add`.", "duplicate_behavior": "last value wins", "flag": "--sdk-root", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "SDK catalog override; defaults to the user catalog.", "duplicate_behavior": "last value wins", "flag": "--sdk-catalog", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": "false", "description": "Emit build graph/provider decision evidence while performing the build.", "duplicate_behavior": "idempotent", "flag": "--explain", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": null } ], "outputs": [ "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." ], "path": [ "build" ], "positional_arguments": [ { "description": "A macmake.toml path or a directory containing one.", "name": "project", "required": true } ], "related_commands": [ "inspect", "doctor", "compile", "clean", "inspect-artifact", "help manifest", "help incremental" ], "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." ], "stability": "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", "summary": "Compile, link, validate, and package one project target.", "syntax": "macmake build [--target ] [--toolchain-root ] [--sdk-catalog ] [--explain]", "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." ] }, { "description": "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.", "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." } ], "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" ], "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." } ], "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." ], "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." ], "options": [ { "allowed_values": [], "default": null, "description": "Optional built Macintosh artifact to identify and SHA-256 in the run record; it is not staged into the guest.", "duplicate_behavior": "last value wins", "flag": "--artifact", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "Optional macMAKE build-evidence JSON. When supplied with --artifact, its recorded MacBinary SHA-256 must match before the artifact is marked constructed.", "duplicate_behavior": "last value wins", "flag": "--build-evidence", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": "1800", "description": "Maximum interactive test duration after QEMU starts; timeout ends the guest process and records incomplete checkpoints.", "duplicate_behavior": "last value wins", "flag": "--timeout", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "seconds" }, { "allowed_values": [], "default": "false", "description": "Print the final structured run result as JSON.", "duplicate_behavior": "idempotent", "flag": "--json", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": null } ], "outputs": [ "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." ], "path": [ "run" ], "positional_arguments": [ { "description": "Strict version-1 JSON profile with a user-owned base disk and application identity.", "name": "profile.json", "required": true } ], "related_commands": [ "build", "inspect-artifact", "stage", "verify", "help emulator" ], "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." ], "stability": "supported, manual runtime smoke-test workflow; Linux x86-64; QEMU Mac OS 9.2.2 only", "summary": "Run a previously staged application in a user-owned QEMU Macintosh guest.", "syntax": "macmake run [--artifact ] [--build-evidence ] [--timeout ] [--json]", "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." ] }, { "description": "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.", "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." } ], "examples": [ "macmake compile examples/first-app --target \"Classic PPC C\"" ], "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." } ], "inputs": [ "Manifest, transitive target sources, headers, libraries needed by compilation, SDK, and compiler/provider." ], "limitations": [ "A successful compile-only pass does not prove link closure, PEF structure, resources, MacBinary, or Mac OS 9 runtime behavior." ], "options": [ { "allowed_values": [], "default": null, "description": "Target name; defaults as for build.", "duplicate_behavior": "last value wins", "flag": "--target", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "string" }, { "allowed_values": [], "default": null, "description": "Toolchain root; overrides MACMAKE_TOOLCHAIN_ROOT.", "duplicate_behavior": "last value wins", "flag": "--toolchain-root", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "SDK catalog override.", "duplicate_behavior": "last value wins", "flag": "--sdk-catalog", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "Compiler outputs and compile-census report under the project's build/ directory." ], "path": [ "compile" ], "positional_arguments": [ { "description": "Manifest path or project directory.", "name": "project", "required": true } ], "related_commands": [ "build", "doctor", "clean", "help incremental" ], "side_effects": [ "Creates/updates compile outputs and incremental state; does not link, build resources, or package an application." ], "stability": "supported for the same project/provider subset as build; other profiles are experimental or legacy", "summary": "Compile the selected target closure without linking or packaging.", "syntax": "macmake compile [--target ] [--toolchain-root ] [--sdk-catalog ]", "troubleshooting": [ "Use doctor first for provider/SDK checks; use resolve-header for a specific include." ] }, { "description": "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.", "environment_variables": [], "examples": [ "macmake clean examples/first-app --target \"Classic PPC C\"" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "Project manifest and its current incremental state." ], "limitations": [ "Only outputs known to macMAKE's target build tree are intended to be removed; do not point the project at valuable generated inputs." ], "options": [ { "allowed_values": [], "default": null, "description": "Target name; omitted target selection follows build defaults.", "duplicate_behavior": "last value wins", "flag": "--target", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "string" } ], "outputs": [ "No build outputs. It removes generated files and state for the selected closure." ], "path": [ "clean" ], "positional_arguments": [ { "description": "Manifest path or project directory.", "name": "project", "required": true } ], "related_commands": [ "build", "compile", "help incremental" ], "side_effects": [ "Deletes generated objects, reports, PEF/resource/MacBinary products, and incremental state for the selected target closure." ], "stability": "supported", "summary": "Delete generated outputs and incremental state for a target closure.", "syntax": "macmake clean [--target ]", "troubleshooting": [ "If you need to preserve evidence, copy the relevant build/ reports before cleaning." ] }, { "description": "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.", "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." } ], "examples": [ "macmake doctor examples/first-app --target \"Classic PPC C\" --toolchain-root ./toolchain" ], "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." } ], "inputs": [ "Manifest, SDK catalog and registered SDK files, toolchain executables, runtime inputs, and project libraries." ], "limitations": [ "A READY result checks declared availability and provider probes; it does not guarantee successful compilation, structural validity, or runtime behavior." ], "options": [ { "allowed_values": [], "default": null, "description": "Target to diagnose.", "duplicate_behavior": "last value wins", "flag": "--target", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": "string" }, { "allowed_values": [], "default": null, "description": "Toolchain root; overrides MACMAKE_TOOLCHAIN_ROOT.", "duplicate_behavior": "last value wins", "flag": "--toolchain-root", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "SDK catalog override; defaults to the user catalog.", "duplicate_behavior": "last value wins", "flag": "--sdk-catalog", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "Readiness diagnostics on stdout; NOT READY returns status 1." ], "path": [ "doctor" ], "positional_arguments": [ { "description": "Manifest path or project directory.", "name": "project", "required": true } ], "related_commands": [ "sdk list", "sdk add", "sdk verify", "resolve-header", "build", "help sdk" ], "side_effects": [ "Reads files and may execute provider version/target probes; does not compile or modify SDK registration." ], "stability": "supported for diagnostics of configured providers; reports unsupported runtime profiles explicitly", "summary": "Check whether one target's runtime, SDK, tools, and libraries are ready.", "syntax": "macmake doctor --target [--toolchain-root ] [--sdk-catalog ]", "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." ] }, { "description": "Experimental orchestration for projects containing a 68K target and a PowerPC provider target. It can invoke external architecture tools and writes generated extension artifacts.", "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." } ], "examples": [ "macmake system-extension path/to/extension.toml --m68k-toolchain-root /opt/m68k --toolchain-root /opt/ppc" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "Experimental manifest, SDK catalog, 68K/PPC providers, sources, and declared libraries." ], "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." ], "options": [ { "allowed_values": [], "default": null, "description": "68K toolchain root; overrides MACMAKE_M68K_TOOLCHAIN_ROOT.", "duplicate_behavior": "last value wins", "flag": "--m68k-toolchain-root", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "PowerPC provider root.", "duplicate_behavior": "last value wins", "flag": "--toolchain-root", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" }, { "allowed_values": [], "default": null, "description": "SDK catalog override.", "duplicate_behavior": "last value wins", "flag": "--sdk-catalog", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "Generated extension/build artifacts under the project build directory." ], "path": [ "system-extension" ], "positional_arguments": [ { "description": "Manifest describing the experimental extension target composition.", "name": "project", "required": true } ], "related_commands": [ "build", "doctor", "help compatibility" ], "side_effects": [ "Runs external build tools and writes build outputs." ], "stability": "experimental; outside the v0.1 supported release target", "summary": "Assemble a mixed Macintosh system-extension target.", "syntax": "macmake system-extension [--m68k-toolchain-root ] [--toolchain-root ] [--sdk-catalog ]", "troubleshooting": [ "Check provider roots and SDK/tool inputs with the diagnostics printed by the operation." ] }, { "description": "Reads the SDK catalog and prints each package identity, root, and detected capability count.", "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." } ], "examples": [ "macmake sdk list" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "SDK catalog JSON." ], "limitations": [ "Listing alone does not verify catalog freshness or package contents." ], "options": [ { "allowed_values": [], "default": null, "description": "Use this SDK catalog instead of the per-user default.", "duplicate_behavior": "last value wins", "flag": "--catalog", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "Package list on stdout." ], "path": [ "sdk", "list" ], "positional_arguments": [], "related_commands": [ "sdk add", "sdk inspect", "sdk verify", "doctor" ], "side_effects": [ "Read-only; does not hash all package contents." ], "stability": "supported", "summary": "List registered local SDK packages.", "syntax": "macmake sdk list [--catalog ]", "troubleshooting": [ "An empty list means register an authorized SDK with `macmake sdk add ROOT --id ID`." ] }, { "description": "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.", "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." } ], "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\"" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "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." ], "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." ], "options": [ { "allowed_values": [], "default": null, "description": "Fetch only the C PowerPC headers and libraries used by the supported first-app profile.", "duplicate_behavior": "idempotent", "flag": "--minimal", "mutually_exclusive_with": [], "repeatable": false, "required": true, "requires_with": [], "value_type": null }, { "allowed_values": [], "default": null, "description": "Install the sparse checkout here; defaults to $XDG_DATA_HOME/macmake/macMAKELibs or ~/.local/share/macmake/macMAKELibs.", "duplicate_behavior": "last value wins", "flag": "--destination", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "Sparse checkout containing selected MSL headers/archives and Universal Interfaces headers/import stubs." ], "path": [ "sdk", "fetch" ], "positional_arguments": [], "related_commands": [ "sdk add", "sdk inspect", "sdk verify", "doctor", "help sdk" ], "side_effects": [ "Creates a user-selected SDK directory and downloads files; does not modify SDK catalog or project files." ], "stability": "supported; network and Git required", "summary": "Fetch the minimal Classic PowerPC C SDK inputs.", "syntax": "macmake sdk fetch --minimal [--destination ]", "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." ] }, { "description": "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.", "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." } ], "examples": [ "macmake sdk add \"$HOME/SDKs/CodeWarrior/MacOS Support/Universal\" --id macos9-sdk" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "Readable SDK directory tree." ], "limitations": [ "The toolchain archive excludes proprietary Apple/Metrowerks SDKs; users must provide authorized materials." ], "options": [ { "allowed_values": [], "default": null, "description": "Logical package ID referenced by target.sdk.packages. If omitted, an ID is derived from the package.", "duplicate_behavior": "last value wins", "flag": "--id", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "string" }, { "allowed_values": [], "default": null, "description": "Catalog file to update; defaults to the per-user catalog.", "duplicate_behavior": "last value wins", "flag": "--catalog", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "Updated catalog file and a package registration summary." ], "path": [ "sdk", "add" ], "positional_arguments": [ { "description": "Existing directory containing authorized SDK materials.", "name": "root", "required": true } ], "related_commands": [ "sdk list", "sdk inspect", "sdk verify", "doctor", "help sdk" ], "side_effects": [ "Writes local SDK registration state atomically; does not redistribute SDK contents." ], "stability": "supported", "summary": "Register an SDK directory in the local catalog.", "syntax": "macmake sdk add [--id ] [--catalog ]", "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." ] }, { "description": "Reads one registered package record and prints detected metadata and import-library mappings. It does not recompute all file hashes.", "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." } ], "examples": [ "macmake sdk inspect macos9-sdk" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "SDK catalog." ], "limitations": [ "For current content integrity, use `sdk verify`." ], "options": [ { "allowed_values": [], "default": null, "description": "SDK catalog override.", "duplicate_behavior": "last value wins", "flag": "--catalog", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "Package details on stdout." ], "path": [ "sdk", "inspect" ], "positional_arguments": [ { "description": "Registered SDK package ID.", "name": "logical-id", "required": true } ], "related_commands": [ "sdk list", "sdk add", "sdk verify", "doctor" ], "side_effects": [ "Read-only catalog access." ], "stability": "supported", "summary": "Show an SDK package's identity, roots, capabilities, and indexed files.", "syntax": "macmake sdk inspect [--catalog ]", "troubleshooting": [ "If the ID is unknown, run `macmake sdk list`; if capabilities are incomplete, register the correct SDK root." ] }, { "description": "Hashes indexed SDK files and validates the registered package's content identity against the files present now.", "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." } ], "examples": [ "macmake sdk verify macos9-sdk" ], "exit_statuses": [ { "code": 0, "meaning": "Command completed successfully." }, { "code": 2, "meaning": "Malformed arguments, invalid project/configuration, missing input, or an operational error." } ], "inputs": [ "SDK catalog and package files at their registered root." ], "limitations": [ "Verifies indexed content, not the legal authorization or completeness of the SDK for an application." ], "options": [ { "allowed_values": [], "default": null, "description": "SDK catalog override.", "duplicate_behavior": "last value wins", "flag": "--catalog", "mutually_exclusive_with": [], "repeatable": false, "required": false, "requires_with": [], "value_type": "path" } ], "outputs": [ "Verification summary and content fingerprint." ], "path": [ "sdk", "verify" ], "positional_arguments": [ { "description": "Registered SDK package ID.", "name": "logical-id", "required": true } ], "related_commands": [ "sdk inspect", "sdk add", "doctor" ], "side_effects": [ "Reads and hashes registered SDK files; does not modify them or the catalog." ], "stability": "supported", "summary": "Recheck an SDK package's indexed content and fingerprint.", "syntax": "macmake sdk verify [--catalog ]", "troubleshooting": [ "If verification is stale, rerun `macmake sdk add ROOT --id ID` after confirming the registered root is the intended SDK." ] } ], "global_options": [ { "aliases": [ "-V" ], "flag": "--version" }, { "aliases": [ "-h" ], "flag": "--help" } ], "help_schema_version": "1.0.0", "kind": "all", "topics": [ { "aliases": [ "first-build", "getting-started" ], "markdown": "# Quick start\n\nmacMAKE v0.1.1 targets Linux x86-64. Its qualified application workflow\nbuilds Classic PowerPC CFM/PEF C applications. The candidate also contains an\nexperimental, bounded native M68000 segmented C application profile; see\n`macmake help targets` and `macmake help compatibility` before selecting it.\nThis profile is not a claim of general 68K, CFM-68K, or System 6–9 support.\nThe installed executable carries this reference offline.\n\n## 1. Check the installation\n\n```sh\nmacmake --version\nmacmake help\n```\n\nThe distributed toolchain contains its compiler, assembler, native linker and\npackaging tools. It does not contain proprietary Apple Universal Interfaces,\nMetrowerks MSL archives, or other historical SDK material.\n\nFrom the extracted release directory, select its toolchain before building:\n\n```sh\nexport MACMAKE_TOOLCHAIN_ROOT=\"$PWD/toolchain\"\n```\n\nFor a per-user installation, set this variable to the installed release's\n`toolchain` directory. `macmake help toolchain` explains the provider options.\n\n## 2. Register authorized SDK material\n\n```sh\nmacmake sdk add \"$HOME/SDKs/CodeWarrior/MacOS Support/Universal\" --id macos9-sdk\nmacmake sdk inspect macos9-sdk\nmacmake sdk verify macos9-sdk\ncd examples/first-app\n./setup-user-msl.sh \"$HOME/SDKs/CodeWarrior\"\n```\n\nThe catalog records the root and fingerprints; it does not copy SDK files.\nThe helper copies only authorized MSL archives into the sample's ignored\n`sdk/` directory and prints their input hashes.\n\n## 3. Inspect and build\n\n```sh\nmacmake inspect .\nmacmake doctor . --target \"Classic PPC C\"\nmacmake build . --target \"Classic PPC C\"\n```\n\nThe sample manifest explicitly declares two C sources, the CodeWarrior MSL\nruntime profile, libraries, SDK capabilities, application metadata and CFM\nfragment settings. Read `macmake help manifest` and `macmake help examples`.\n\n## 4. Inspect the host-side output\n\nThe application target produces `.pef`, `.rsrc`, `.finf/.APPL`, and\n`.bin` files under the project's `build/` directory. A one-target project\nwrites products directly there; multi-target projects may use target-specific\nsubdirectories. Inspect the components with the exact paths printed or\ndiscovered in that build directory:\n\n```sh\nfind build -maxdepth 6 -type f -print\nmacmake inspect-artifact PATH/APP.pef --resource-fork PATH/APP.rsrc \\\n --finder-info PATH/.finf/APP.APPL --creator HmPP --file-type APPL --json\n```\n\nPEF/resource/Finder/MacBinary validation is Linux build evidence. It does not\nlaunch the application. Copy the MacBinary file to a suitable Classic Mac\nfilesystem and confirm launch behavior in a user-controlled Mac OS 9 guest.\n\nFor first failures, run `macmake doctor`, then `macmake help troubleshooting`.\n", "name": "quickstart", "title": "quick start" }, { "aliases": [ "project", "toml" ], "markdown": "# `macmake.toml` manifest reference\n\nTOML is the native project format. This binary also exposes the structural\nschema as JSON Schema Draft 2020-12:\n\n```sh\nmacmake schema manifest --json\n```\n\nThe schema describes fields, types, required values and enums. Its\n`x-macmake-manifest-schema-version` is `0.1.1`; this revision adds the bounded\nexperimental native M68000 application profile accepted by this binary. The loader\nalso validates path safety, four-character codes, duplicate membership,\ntarget/provider combinations, and references between tables. Those rules\nare listed below. A valid schema shape is not by itself proof that the\nselected toolchain or SDK can build a target.\n\n## Top level and project\n\n```toml\n[project]\nname = \"HelloPPC\"\ndefault_target = \"Classic PPC C\" # optional; target selection for build/clean\n\n[[target]]\n# one table per target, kept in declaration order\n```\n\n`[project]` is required. `name` is required. `default_target` is optional.\nAt least one `[[target]]` must be present. Unknown fields are rejected by\nthis version's TOML loader. There is no top-level manifest `version` key in\nv0.1; schema evolution is tied to the installed macMAKE version, and the\nmachine-readable schema reports its own version fields.\n\n## Target fields\n\nEvery target requires:\n\n| Field | Type / values | Meaning |\n| --- | --- | --- |\n| `name` | non-empty string | Project-local target name. |\n| `platform` | `classic-mac-os`, `macos-x` | OS family. |\n| `architecture` | `powerpc`, `m68k` | Target architecture. |\n| `api` | `classic`, `carbon-lib`, `carbon-framework` | API environment. |\n| `runtime` | `cfm`, `dyld` | Linkage/runtime model. |\n| `executable` | `pef`, `mach-o` | Executable format. |\n| `sources` | array of project-relative paths | Explicit translation-unit membership. |\n\nOptional target fields are `kind`, `runtime_profile`, `custom_runtime`,\n`language`, `resources`, `libraries`, `subtargets`, `link_order`,\n`access_paths`, `compiler`, `source_compiler_settings`, `linker`,\n`application`, `shared_library`, `cfm_fragment`, `resource_output`, `sdk`,\n`backend`, and `compiler_target`. `macmake schema manifest --json` gives the\nfull nested field shape and enumerations.\n\nDefaults applied during loading: `kind = \"application\"`,\n`runtime_profile = \"retro68-newlib\"`, `language = \"c\"`, `backend = \"retro68\"`;\nempty resources/libraries/subtargets/link order/access paths/defines are\nallowed. These legacy defaults do not make Retro68 the v0.1 release provider.\nFor the packaged native application flow, set `backend = \"macmake-classic\"`\nand use the tested target/runtime profile combination shown in the real\n`examples/first-app/macmake.toml`.\n\nFor the experimental native M68000 application path, use the exact\n`classic-68k-segmented-app-c-v1` compiler target and\n`macmake-classic-m68k-c-v1` runtime profile pair. The included\n`examples/first-app/hello-window-68k/macmake.toml` is the working manifest\nreference; the profile is bounded and is not general 68K compatibility.\n\n## Complete supported application example\n\nThis is the shipped first-app project's core manifest. The source, SDK and\narchive paths must exist locally; users provide authorized SDK/MSL material.\nThe repository copy contains additional explanatory comments and the exact\nCarbonLib fragment extents for its documented SDK input.\n\n```toml\n[project]\nname = \"HelloPPC\"\ndefault_target = \"Classic PPC C\"\n\n[[target]]\nname = \"Classic PPC C\"\nkind = \"application\"\nplatform = \"classic-mac-os\"\narchitecture = \"powerpc\"\napi = \"carbon-lib\"\nruntime = \"cfm\"\nruntime_profile = \"codewarrior-msl-compatible\"\nexecutable = \"pef\"\nlanguage = \"c\"\nbackend = \"macmake-classic\"\ncompiler_target = \"classic-ppc-xcoff-c-v1\"\nsources = [\"src/main.c\", \"src/value.c\"]\n\n[target.compiler]\nstandard = \"c89\"\n\n[target.application]\ncreator = \"HmPP\"\nfile_type = \"APPL\"\noutput_name = \"HelloPPC\"\n\n[target.application.memory]\npreferred_heap_bytes = 4194304\nminimum_heap_bytes = 2097152\napplication_stack_bytes = 32768\nsize_flags = 22720\n\n[target.cfm_fragment]\noutput_name = \"HelloPPC\"\nfragment_name = \"HelloPPC\"\nmain = \"__start\"\ncreator = \"HmPP\"\nfile_type = \"APPL\"\ncurrent_version = 0\nshare_data = false\nexports = \"pragma\"\n\n[[target.libraries]]\nname = \"MSL_C_Carbon\"\nkind = \"archive\"\npath = \"sdk/MSL_C_Carbon.Lib\"\n\n[[target.libraries]]\nname = \"MSL_Runtime_PPC_D\"\nkind = \"archive\"\npath = \"sdk/MSL_Runtime_PPC_D.Lib\"\n\n[[target.libraries]]\nname = \"MSL_Extras_Carbon\"\nkind = \"archive\"\npath = \"sdk/MSL_Extras_Carbon.Lib\"\n\n[[target.libraries]]\nname = \"MathLib\"\nkind = \"system-import\"\n\n[[target.libraries]]\nname = \"CarbonLib\"\nkind = \"system-import\"\npef_fragments = [\n { fragment_name = \"CarbonLib\", offset = 0, length = 80688, weak_import = false },\n { fragment_name = \"CarbonLib\", offset = 80688, length = 91808, weak_import = true },\n { fragment_name = \"Apple;Carbon;Multimedia\", offset = 172496, length = 74960, weak_import = true },\n { fragment_name = \"Apple;Carbon;Networking\", offset = 247456, length = 5464, weak_import = true },\n]\n\n[target.sdk]\npackages = [\"macos9-sdk\"]\nrequires = [\n \"classic.universal-interfaces.headers\",\n \"classic.carbon.headers\",\n \"classic.carbon.imports\",\n \"classic.math.imports\",\n]\n```\n\nThe fragment extents above match the sample CodeWarrior 8 CarbonLib data fork\nonly. Use the actual checked-in example for the complete manifest and verify\nthat offsets match the exact SDK file you supply. `macmake inspect\nexamples/first-app` validates the whole manifest.\n\n## Sources, compiler and per-source settings\n\n`sources` is an explicit ordered list; macMAKE does not infer project source\nmembership from a directory scan. Paths are project-relative, absolute paths\nand backslashes are rejected, and duplicate entries are rejected. Parent\ncomponents are preserved; see the path rules below before using `..`.\n\n`language` accepts `c`, `c++`, or `mixed`; omitted means `c`. `compiler`\nsupports:\n\n- `standard`: `c89` (default) or `c99`.\n- `structure_alignment`: `power` or `mac68k`.\n- `char_signedness`: `signed` or `unsigned`.\n- `source_compatibility`: `native` or `codewarrior-classic`.\n- `prefix_header`: project-relative path.\n- `defines`: `[[target.compiler.defines]]` rows with required `name` and\n optional string `value`.\n- `optimization_level`: integer 0 through 3.\n- `include_search`: optional table with `source_directory_first`,\n `access_path_order = \"user-first\"`, and `always_search_user_paths`.\n- CodeWarrior compatibility booleans and C++ switches shown in the schema.\n\n`[[target.source_compiler_settings]]` selects an existing member by its\n`source` path and can add per-source `defines` and `prefix_headers`. It may\nnot name a source absent from `sources`; a source may have at most one such\nrow. C++ flags are not a claim of complete C++ runtime/ABI support.\n\n## Access paths and SDK references\n\n```toml\n[[target.access_paths]]\nclass = \"user\" # user | system\npath = \"include\"\nanchor = \"project\" # project | project-relative | sdk\nrecursive = false\n```\n\n`anchor` defaults to `project`, `recursive` to false. `ProjectRelativePath`\nnormalizes `.` components and forward slashes, rejects absolute paths and\nbackslashes, and preserves `..`. Project and SDK anchors refuse lexical\nescape; the explicit project-relative anchor permits parent components.\n\nThe default include policy has `source_directory_first = false`,\n`access_path_order = \"user-first\"`, and `always_search_user_paths = true`.\nQuoted includes check their source directory first only when configured;\nangle-bracket includes never check that source directory. User paths precede\nsystem paths. See `macmake help access-paths`.\n\n`[target.sdk]` accepts optional `name`, `packages` and `requires` arrays.\nUse `packages` for new manifests. When both `name` and `packages` are\npresent, they must agree; `name` is retained as a compatibility form. An\nempty request resolves to automatic package selection. Capability names are\nstrings resolved against registered packages; see `macmake help sdk` for\nregistration and discovery.\n\n## Libraries and link ordering\n\n`[[target.libraries]]` rows are ordered. Kinds:\n\n- `system-import` (default): logical CFM system library, no `path`.\n- `runtime`: provider/runtime input, no `path`.\n- `vendor`, `object`, `archive`, `cfm-merge`: require a project-relative\n `path`.\n\n`weak_import` defaults false. `pef_fragments` is only allowed on\n`system-import`; each row has `fragment_name`, `offset`, positive `length`,\nand optional `weak_import`. See `macmake help libraries` for ordering and\nfragment rules.\n\n`subtargets` contain `target` and optional `link_against_output` (default\ntrue). `link_order` can explicitly interleave entries with `kind = \"source\"`\nand `path`, `kind = \"library\"` and zero-based `index`, or\n`kind = \"subtarget\"` and `target`. Each entry must refer to a declared source,\nlibrary or subtarget. Avoid `link_order` unless the target requires a measured\nnon-default order.\n\n## Resources and output metadata\n\n`resources` accepts path strings (default kind `rez-source`) or tables with\n`path` and optional `kind = \"rez-source\" | \"precompiled-fork\"`.\n`[target.application]` requires printable four-character `creator` and\n`file_type`; it may set `output_name` and `[target.application.memory]`.\nMemory requires positive `minimum_heap_bytes` and\n`preferred_heap_bytes >= minimum_heap_bytes`; optional stack size must be\npositive. `size_flags` is a 16-bit integer.\n\n`[target.cfm_fragment]` describes an application fragment; `[target.shared_library]`\nis for shared-library targets. They are mutually exclusive and require\n`output_name`, `creator`, `file_type`, and `exports` (`none`, `pragma`,\n`explicit-list`, `all`). `[target.resource_output]` is required by\n`resource-collection`, and may be used by `static-library`; it requires\noutput name, creator, file type, and `copy_fragments`.\n\n## Path and semantic validation\n\n- Manifest paths must be non-empty, anchor-relative paths using `/`; absolute\n paths and backslashes are rejected. `..` is preserved and may be rejected\n by Project/SDK anchor escape checks; explicit project-relative anchors may\n point at intentional adjacent project files.\n- Output names for application, resource-output, and fragment settings must\n be filenames, not directory paths.\n- Finder codes are exactly four printable ASCII characters.\n- Duplicate source/resource entries and duplicate exports are rejected.\n- `shared_library` and `cfm_fragment` cannot both be present.\n- `resource_output` and `custom_runtime` have target-kind/profile constraints.\n- Runtime/provider/platform/API combinations must be coherent.\n- SDK package names must match local catalog IDs; required capabilities must\n be present in the selected registered package(s).\n- A schema-valid manifest can still fail because a file, provider, library,\n or capability is unavailable. Run `inspect`, then `doctor`.\n\nUse `macmake schema manifest --json` to retrieve the complete field and enum\nlist programmatically. Use `macmake help targets`, `help access-paths`,\n`help libraries`, and `help sdk` for the cross-field behavior.\n", "name": "manifest", "title": "project manifest reference" }, { "aliases": [ "target" ], "markdown": "# Targets and output kinds\n\nEach `[[target]]` table names a build node with an explicit source/resource/\nlibrary membership and a platform, architecture, API, runtime, executable,\nbackend, and optional compiler target profile.\n\n## Target kinds accepted by the manifest\n\n- `application` (default): application/fragment outputs; the qualified v0.1.1\n workflow is Classic PowerPC CFM/PEF C. The candidate also has a bounded,\n experimental native M68000 application profile described below.\n- `static-library`: project archive-style target. Support depends on the\n selected backend and runtime; inspect the target diagnostics.\n- `shared-library`: CFM shared-library target with `shared_library` settings;\n advanced and not the v0.1 application support promise.\n- `resource-collection`: merge resource inputs into a configured resource\n output; requires `resource_output`.\n- `code-resource`: flat code intended for a Classic resource fork; advanced\n or experimental in this release.\n\nThe manifest parser accepts more combinations than the v0.1 product has\nqualified. The current supported application profile is Linux x86-64 host to\nClassic Mac OS PowerPC, CarbonLib/Classic API as declared, CFM, PEF, C89/C,\nthe `macmake-classic` backend with a supported compiler target, registered\nuser SDK inputs and required runtime libraries. The exact first-app manifest\nis the working reference.\n\n## Compiler and runtime profile identifiers\n\n`compiler_target` is optional unless `backend = \"macmake-classic\"`. The\nparser recognizes these identifiers:\n\n- `classic-ppc-xcoff-c-v1`: Classic PowerPC XCOFF C compiler contract.\n- `classic-ppc-xcoff-cxx-preview-v1`: corresponding C++ preview contract.\n- `classic-68k-code-resource-c-v1`: experimental 68K code-resource compiler.\n- `classic-68k-segmented-app-c-v1`: experimental, bounded native M68000\n segmented application contract; requires `runtime_profile = \"macmake-classic-m68k-c-v1\"`.\n- `cw8-os9-carbon-ppc-c-v1-preview`: native PowerPC C compiler contract used\n by the v0.1 Classic runtime profile and diagnostic probes.\n\n`runtime_profile` defaults to `retro68-newlib`. Accepted values:\n\n- `retro68-newlib`: legacy Retro68/Newlib provider profile; not the packaged\n native provider.\n- `codewarrior-msl-compatible`: user supplied MSL runtime inputs with the\n native v0.1 C application path. The first-app manifest is the reference.\n- `project-custom`: explicit startup objects, runtime libraries, header paths\n and defines in `[target.custom_runtime]`; advanced.\n- `macmake-classic-c-v1`: macMAKE native Classic C runtime profile.\n- `macmake-classic-m68k-c-v1`: experimental native M68000 application startup,\n Toolbox ABI, and single-segment CODE-resource profile.\n- `macmake-classic-entry-probe-v1`: diagnostic entry-only profile.\n- `macmake-classic-direct-entry-probe-v1`: diagnostic direct-entry profile.\n- `macmake-classic-raw-entry-probe-v1`: diagnostic hand-written entry profile.\n- `macmake-classic-raw-entry-probe-no-empty-data-v1`: diagnostic PEF\n structure comparison.\n- `macmake-classic-startup-probe-v1`: diagnostic startup instrumentation.\n\nThe `*-probe-*` profiles are experimental test fixtures, not application\ntemplates. For a supported C application, copy the relevant settings from\n`examples/first-app/macmake.toml` and change its project-specific source,\naccess-path, SDK, library and application metadata inputs.\n\nThe v0.1.1 candidate includes a normal `macmake build` route for the exact\nM68000 profile above. It is limited to C89, one near-model CODE 1 segment,\nbounded PC-relative code and globals, no external libraries, and the\ndocumented in-process Rez subset. It is experimental and does not provide a\ngeneral 68K application ABI, CFM-68K, or broad OS compatibility. The parser\nalso accepts `macos-x`, `dyld`, `mach-o`, C++, and mixed-language values in\nother retained or experimental combinations; those values do not establish\nmacOS-host or Mac OS X target support. The `system-extension` command is\nseparately marked experimental.\n\n`platform` accepts `classic-mac-os` or `macos-x`; `architecture` accepts\n`powerpc` or `m68k`; `api` accepts `classic`, `carbon-lib`, or\n`carbon-framework`; `runtime` accepts `cfm` or `dyld`; `executable` accepts\n`pef` or `mach-o`. These are parser values, not a claim that each cross\nproduct is implemented for the released host.\n\n## Selection and dependencies\n\n`macmake build PROJECT` chooses `project.default_target` when present. If no\ndefault is configured, a project with one selectable target can be built\nwithout `--target`; otherwise pass the exact `--target NAME`. Target names\nare case-sensitive strings.\n\nSubtargets form a dependency graph. macMAKE builds prerequisite targets\nbefore the selected target. `link_against_output = false` builds a prerequisite\nwithout adding its output as a link input; its default is true.\n\nUse:\n\n```sh\nmacmake inspect PROJECT\nmacmake doctor PROJECT --target \"TARGET NAME\"\nmacmake build PROJECT --target \"TARGET NAME\"\n```\n\nUnknown targets are errors. Check exact names with `inspect`; do not guess\ntarget names from output filenames.\n\n## Stability labels\n\nThe command reference labels stable supported behavior, diagnostic operations,\nand experimental/import/legacy surfaces. `macmake system-extension`, XML\nimport, probe runtime profiles, and Mac OS X combinations are outside the\nqualified v0.1.1 application workflow. See `macmake help compatibility`.\n", "name": "targets", "title": "targets and target types" }, { "aliases": [ "headers", "include-paths" ], "markdown": "# Header and access path resolution\n\nAccess paths are target-declared locations used for includes and project\ninputs. They are not implicit recursive scans of the entire SDK or project.\n\n```toml\n[[target.access_paths]]\nclass = \"user\" # user | system\npath = \"include\"\nanchor = \"project\" # default; project | project-relative | sdk\nrecursive = false # default\n```\n\nPaths are declared in the manifest and resolved according to their anchor.\n`project` is relative to the manifest directory and refuses lexical escape\nabove that root. `sdk` is relative to an SDK root and refuses escape above\nthat root. `project-relative` preserves historical project-relative lookup\nand permits parent components such as `../shared`; use it only when those\nadjacent files are intentional.\n\nThe default `compiler.include_search` policy has\n`source_directory_first = false`, `access_path_order = \"user-first\"`, and\n`always_search_user_paths = true`. When enabled, `source_directory_first`\nchecks the including source's directory before access paths for quoted\nincludes; it does not apply to angle-bracket includes. User paths precede\nsystem paths regardless of table declaration order. Angle-bracket includes\nalso search user paths by default; set `always_search_user_paths = false` to\nlimit them to system paths. `recursive = true` searches beneath the declared\nroot. Resolved SDK header roots are appended after declared access paths.\n\nDiagnose one include without building:\n\n```sh\nmacmake resolve-header PROJECT --target TARGET --from src/main.c Carbon.h\n```\n\nThe source path must be a project member/resolvable path. The command reports\nthe selected candidate; status 1 means it found no matching header. The\naccepted `--sdk-root` option is deprecated; supplying it returns an error.\nRegister SDKs and use `[target.sdk]`. Use\n`macmake sdk inspect ID` to see registered header roots and\n`macmake sdk verify ID` to recheck package files.\n\nAn unresolved header can mean the wrong source include spelling, an omitted\n`[[target.access_paths]]`, a wrong anchor, a missing SDK registration, or an\nSDK package without the needed headers. A resolved header does not prove that\nthe compiler accepts its declarations or that referenced symbols link.\n", "name": "access-paths", "title": "header and access path resolution" }, { "aliases": [ "linking", "cfm" ], "markdown": "# Libraries, CFM imports, and link order\n\nLibraries are declared in `[[target.libraries]]` rows in semantic order.\nThey may describe SDK system imports, runtime inputs, project archives or\nobjects, vendor inputs, or CFM fragment merging.\n\n```toml\n[[target.libraries]]\nname = \"CarbonLib\"\nkind = \"system-import\"\n\n[[target.libraries]]\nname = \"MSL_C_Carbon\"\nkind = \"archive\"\npath = \"sdk/MSL_C_Carbon.Lib\"\n```\n\nKinds and path rules:\n\n- `system-import`: logical CFM import library, resolved through the declared\n SDK. It has no project `path`.\n- `runtime`: runtime/provider library, selected according to the runtime\n profile; no project `path`.\n- `vendor`, `object`, `archive`, `cfm-merge`: require a project-relative\n `path` to a file.\n\nLibraries are ordered. Classic archive extraction and CFM import resolution\ncan depend on order. Preserve measured CodeWarrior order; avoid sorting the\nlist alphabetically.\n\n`weak_import = true` marks the library's CFM imports weak where supported.\n`pef_fragments` can describe concatenated PEF fragment extents on a\n`system-import` data fork:\n\n```toml\npef_fragments = [\n { fragment_name = \"CarbonLib\", offset = 0, length = 80688, weak_import = false },\n]\n```\n\nOffsets and lengths are bytes in that data fork. Fragment names and extents\nmust match the exact SDK file; do not copy example offsets to another file.\n\n`subtargets` express target prerequisites. `link_order` can explicitly\ninterleave `source`, `library` (zero-based index into `libraries`), and\n`subtarget` entries. Each reference must point to declared membership. This\nadvanced override should only be used when the required sequence is known.\n\nIf the linker reports unresolved CFM imports, verify that the logical import\nlibrary is declared, SDK capabilities map it, and the correct import library\nis registered. If a runtime symbol is unresolved, identify its provider and\nruntime archive; do not silently substitute an unrelated runtime. Run\n`macmake doctor` for provider and library availability, and inspect the build\nevidence for the exact unresolved symbol.\n", "name": "libraries", "title": "libraries, imports, and link order" }, { "aliases": [], "markdown": "# SDK registration and capabilities\n\nmacMAKE does not redistribute proprietary Apple Universal Interfaces,\nMetrowerks SDK archives, or historical import libraries. Supply SDK material\nyou are authorized to use. Registration references the directory in place;\nit does not copy it into the project or macMAKE installation.\n\nFor a minimal Classic PowerPC C setup, `sdk fetch --minimal` performs a Git\nsparse checkout of selected headers and libraries from\n`mplsllc/macMAKELibs`, pinned to the revision and selected-file checksums in\nthe installed CLI's `minimal-classic-ppc-c-v1.json` manifest. It requires Git\nand network access, does not register the SDK, and does not fetch unrelated\nCodeWarrior trees or C++ runtime material:\n\n```sh\nmacmake sdk fetch --minimal\nmacmake sdk add \"$HOME/.local/share/macmake/macMAKELibs/Universal\" --id macos9-sdk\n```\n\nThe fetched MSL headers and archives remain in the same checkout. For a\ncustom location, pass `--destination PATH` and register its `Universal`\nsubdirectory. The command refuses to overwrite an existing path from a\ndifferent revision or with mismatched required archive hashes. To copy the\nthree MSL archives into the packaged first-app example, run its setup helper\nwith the fetched checkout as its root:\n\n```sh\nexamples/first-app/setup-user-msl.sh \"$HOME/.local/share/macmake/macMAKELibs\"\n```\n\nThe checkout contains separately supplied historical headers and runtime\nlibraries. The macMAKE archive does not contain them. The repository and\nmanifest establish where the files came from and their content identity; they\ndo not grant rights to use or redistribute them. Confirm your authorization\nbefore fetching or using these materials.\n\n```sh\nmacmake sdk add \"$HOME/SDKs/CodeWarrior/MacOS Support/Universal\" --id macos9-sdk\nmacmake sdk list\nmacmake sdk inspect macos9-sdk\nmacmake sdk verify macos9-sdk\n```\n\nThe default catalog is `$XDG_CONFIG_HOME/macmake/sdk-catalog.json` when\n`XDG_CONFIG_HOME` is set, otherwise `$HOME/.config/macmake/sdk-catalog.json`.\n`MACMAKE_SDK_CATALOG` overrides it; `--catalog` takes precedence over the\nenvironment variable.\n\nThe catalog records package identity, root, detected architectures/runtimes,\nheader/import/Rez roots, capabilities, and content fingerprints. The default\ncatalog is per-user. `--catalog PATH` selects a different catalog for every\nSDK subcommand and supported build/diagnostic command.\n\nTargets request SDK inputs with `[target.sdk]`:\n\n```toml\n[target.sdk]\npackages = [\"macos9-sdk\"]\nrequires = [\"classic.universal-interfaces.headers\", \"classic.carbon.imports\"]\n```\n\nCapabilities are detected from the supplied package and matched by exact\nidentifier. APIs and declared system-import libraries can add required\ncapabilities during target resolution. Consult `sdk inspect ID` for what a\npackage currently advertises.\n\nThe catalog currently recognizes these capability identifiers:\n\n- `classic.universal-interfaces.headers`\n- `classic.carbon.headers`, `classic.carbon.imports`\n- `classic.interface.imports`, `classic.math.imports`\n- `classic.open-transport.headers`, `classic.open-transport.imports`,\n `classic.open-transport.internet.imports`\n- `classic.navigation-services.headers`,\n `classic.navigation-services.imports`\n- `classic.appearance.headers`, `classic.appearance.imports`\n- `classic.quicktime.headers`, `classic.quicktime.imports`\n- `classic.rez.system-definitions`\n\nThe registered catalog is authoritative for which of these a particular SDK\nactually provides. Listing a capability in a project does not create or\nredistribute that SDK component.\n\n`sdk fetch` downloads pinned files into the chosen destination. `sdk add` writes user\nregistration state. `sdk list` and `sdk inspect` read the catalog. `sdk verify`\nreads and hashes indexed package contents; it does not change them. A stale\npackage can be re-registered after checking that the root is correct.\n\nCommon recovery:\n\n- No package registered: `macmake sdk add ROOT --id ID`.\n- Target requests a capability not found: register the complete authorized\n SDK component, inspect it, then use the package ID in the manifest.\n- Stale fingerprints: verify the SDK files and re-register the intended root.\n- Wrong package selected: set `packages` explicitly instead of using\n automatic selection.\n\nThe catalog is a local path/fingerprint index, not a license check or proof\nthat a package is legally redistributable. Keep proprietary inputs out of\npublic release archives.\n", "name": "sdk", "title": "SDK registration and capabilities" }, { "aliases": [ "compiler", "provider" ], "markdown": "# Compiler and provider setup\n\nFor the v0.1.1 Linux candidate, the supported host is Linux x86-64. The\ndistributable toolchain contains the PowerPC provider, resource and\ninspection/package tools, and their redistributable support files. The\nqualified application path builds Classic PowerPC CFM/PEF C applications.\nThe candidate also includes an experimental independent M68000 GNU provider\nand macMAKE-controlled segmented-application output. It is limited to the\nexact profile pair documented by `macmake help targets`; it does not provide\ngeneral 68K, CFM-68K, or universal System 6–9 compatibility.\n\nSet the toolchain root to the extracted `toolchain` directory, or pass the\nsame path to a command:\n\n```sh\nexport MACMAKE_TOOLCHAIN_ROOT=\"$HOME/.local/share/macmake/current/toolchain\"\nmacmake doctor PROJECT --target TARGET\nmacmake build PROJECT --target TARGET\n```\n\n`--toolchain-root` overrides `MACMAKE_TOOLCHAIN_ROOT`. Native provider\ndiagnostics also recognize `MACMAKE_PPC_GCC` and `MACMAKE_PPC_AS` as direct\ncompiler/assembler executable overrides; use these only when intentionally\nselecting and validating a different tool. `system-extension` accepts\n`MACMAKE_M68K_TOOLCHAIN_ROOT` is available for the experimental native\nM68000 application provider. Normal `macmake build` selects it only when the\nmanifest uses both `compiler_target = \"classic-68k-segmented-app-c-v1\"` and\n`runtime_profile = \"macmake-classic-m68k-c-v1\"` with the required classic\nM68000 application fields. `system-extension` is a separate experimental\nworkflow and does not select this application profile.\n\n`doctor` checks the compiler target triple, compiler runtime availability,\nassembler, declared SDK package/capabilities, and library inputs. It may run\nsmall version/identity probes, but it does not compile the project.\n\nMissing-tool recovery:\n\n1. Run `macmake --version` to confirm which binary is running.\n2. Locate the installed `toolchain` directory from the release layout.\n3. Pass `--toolchain-root PATH` or set `MACMAKE_TOOLCHAIN_ROOT`.\n4. Run `macmake doctor PROJECT --target TARGET` again.\n\nDo not point the native release workflow at Retro68 to mask a missing native\ntool. Provider choice comes from the manifest `backend`; see\n`macmake help manifest` and `macmake help compatibility`.\n", "name": "toolchain", "title": "compiler and provider setup" }, { "aliases": [ "build-graph" ], "markdown": "# Build graph and command behavior\n\n`macmake build PROJECT [--target NAME]` loads and validates `macmake.toml`,\nselects the requested/default target, walks its target dependency closure,\nthen executes the required compilation and link/resource/package steps. The\ntarget graph is explicit: source membership, libraries, resources, access\npaths and subtargets come from the manifest.\n\nUse these operations in order on an unfamiliar project:\n\n```sh\nmacmake inspect PROJECT\nmacmake doctor PROJECT --target TARGET\nmacmake compile PROJECT --target TARGET\nmacmake build PROJECT --target TARGET\n```\n\n`inspect` reads the manifest. `doctor` checks declared provider and SDK\navailability. `compile` compiles the transitive source closure without\nlinking or packaging. `build` performs a full build. `clean` deletes generated\noutputs and incremental state for a selected closure.\n\n`--explain` on `build` emits build decisions and evidence while continuing\nwith actual build operations. It is not a dry-run guarantee.\n\nMost command failures use exit 2 for invalid command/configuration/process\nerrors. Status 1 is a completed diagnostic/build operation that found an\nunresolved item or failed structural validation. Check both stdout and\nstderr and preserve build evidence before cleaning.\n\nUse `macmake help ` for exact command arguments and side effects.\n", "name": "build-system", "title": "build graph and commands" }, { "aliases": [ "cache", "rebuild" ], "markdown": "# Incremental builds\n\nmacMAKE records build nodes and fingerprints their declared inputs and\ntoolchain identities. An unchanged repeat build checks the graph and should\nreuse current outputs without invoking unnecessary compile/link/package\nstages.\n\n```sh\nmacmake build PROJECT --target TARGET\nmacmake build PROJECT --target TARGET\n```\n\nUse `--explain` to print decisions while building; it does not promise a\nside-effect-free preview. Compiler, assembler, resource, link, and packaging\nnodes may become stale when a source/header/library/resource/manifest or\nprovider input changes. A dependency change invalidates dependent nodes in\nthe graph.\n\n`macmake compile` runs source compilation without linking/package work.\n`macmake clean PROJECT --target TARGET` removes generated files and state for\nthe target closure. Preserve `build/` reports before cleaning if they\nare needed for diagnosis or release evidence.\n\nFor a safe invalidation check, copy a project into a disposable directory,\nchange a test input there, build, restore the copied input and build again.\nDo not alter original application sources for an incremental experiment.\n\nIf a node unexpectedly rebuilds, inspect build evidence for the changed\ninput/tool identity. If a stale output remains, run clean for the exact target\nand rebuild. Do not delete unrelated project files or manually edit build\nstate as a first diagnostic step.\n", "name": "incremental", "title": "incremental builds and cleaning" }, { "aliases": [ "pef", "macbinary", "artifacts" ], "markdown": "# Build outputs and artifact inspection\n\nOutput names and target kind come from the manifest. Generated products live\nunder the project's `build/` directory. Single-target projects place outputs\ndirectly there; multi-target projects may have target-specific subdirectories.\nUse `find build -type f` to locate exact outputs.\n\nFor the supported Classic application profile, expected product classes are:\n\n- Native compiler object files for source members.\n- Link map/build evidence and target PEF executable fragment.\n- Resource fork containing application and CFM metadata/resources.\n- Finder-info sidecar containing creator/type metadata.\n- MacBinary II `.bin` transport package containing data fork, resource fork,\n and Finder information.\n\nThe manifest's `[target.application]` requires four-character `creator` and\n`file_type`; optional `output_name` controls the application output name.\nMemory requirements are encoded by the optional nested `memory` table.\n\nInspect an application using the actual files:\n\n```sh\nmacmake inspect-artifact APP.pef --resource-fork APP.rsrc \\\n --finder-info .finf/APP.APPL --creator HmPP --file-type APPL --json\n```\n\nThe data fork argument can be a PEF file. Resource fork and Finder-info must\nbe supplied separately. The four-character values are expected metadata and\nmust be printable ASCII. Status 1 means structural validation did not pass;\nstatus 2 is an input/argument/operational error.\n\nHost artifact inspection verifies structure and metadata. Mac OS 9 launch,\nstartup, UI and runtime behavior must be checked separately in a guest or\nphysical Mac. Preserve the exact MacBinary hash when transferring a candidate.\n", "name": "output", "title": "build outputs and inspection" }, { "aliases": [ "forks", "file-staging" ], "markdown": "# Classic Macintosh forks and staging\n\nA Classic Macintosh application can consist of a data fork, resource fork,\nand Finder metadata. macMAKE's application build packages these into\nMacBinary II (`.bin`) for transport. Raw build files are useful for inspection\nbut are not equivalent to a fork-preserving transport container by themselves.\n\nUse the MacBinary package when transferring the app:\n\n```sh\nmacmake stage build/HelloPPC.bin --destination /path/on/classic-share/HelloPPC\nmacmake verify build/HelloPPC.bin --destination /path/on/classic-share/HelloPPC\n```\n\nFor raw forks, `stage` and `verify` require both `--resource-fork` and\n`--finder-info`. A single sidecar is rejected. Stage writes the destination\nand invokes Netatalk `ad`; verify reads and compares. `clone-classic` copies an\nexisting live file through Netatalk while preserving complete observed\nmetadata, and requires a fresh destination.\n\nSet `MACMAKE_NETATALK_AD` when the `ad` program is not found through PATH.\nCheck that the destination filesystem exposes Netatalk resource fork and\nFinder metadata support before staging. Do not use a legacy share whose fork\nbehavior has not been verified.\n\nStaging to a host share verifies transport representation, not Mac OS 9\nexecution. The user must unpack/launch the file in the guest and report the\nruntime result separately.\n", "name": "classic-files", "title": "Macintosh file forks and staging" }, { "aliases": [ "errors" ], "markdown": "# Troubleshooting and recovery\n\nStart with non-mutating diagnostics:\n\n```sh\nmacmake --version\nmacmake inspect PROJECT\nmacmake doctor PROJECT --target TARGET\nmacmake sdk list\nmacmake sdk inspect ID\n```\n\n## Manifest or target errors\n\nRead the field and target named in the diagnostic. Use\n`macmake schema manifest --json` for field shape and\n`macmake help manifest` for semantic rules. `inspect` reports available\ntarget names. Pass the exact name with `--target`.\n\n## SDK package or capability missing\n\nRegister the authorized SDK root, inspect what was detected, and verify its\ncontent:\n\n```sh\nmacmake sdk add \"$HOME/SDKs/Authorized/Universal\" --id macos9-sdk\nmacmake sdk inspect macos9-sdk\nmacmake sdk verify macos9-sdk\n```\n\nThen ensure the manifest's `packages` and `requires` match the catalog.\nmacMAKE does not supply proprietary SDK files.\n\n## Compiler or assembler unavailable\n\nUse the archive's `toolchain` directory with `--toolchain-root` or set\n`MACMAKE_TOOLCHAIN_ROOT`. Run doctor again. Do not substitute another\ntoolchain without validating its target triple, compiler runtime, assembler,\nand output format.\n\n## Header not resolved\n\nRun `macmake resolve-header PROJECT --target TARGET --from SOURCE HEADER`.\nCheck source-relative spelling, access-path `class`, `anchor`, root path,\nSDK package header capability and file existence.\n\n## Runtime library or import unresolved\n\nCheck `[[target.libraries]]` kind and order. A system import needs a matching\nSDK import library/capability; a project archive needs an existing\nproject-relative `path`; runtime libraries come from the selected provider\nprofile. Preserve the exact unresolved symbol and build evidence. Do not\nsilently fall back to unrelated archives.\n\n## Compilation, link or artifact validation failed\n\nRetain command line, stdout, stderr, manifest, macMAKE version, provider\nidentity, and `build/` evidence. `build --explain` prints decisions\nbut still runs the build. Use `inspect-artifact` only with the exact data,\nresource and Finder inputs.\n\n## Linux artifact works but Mac OS 9 does not launch\n\nHost structural checks do not prove guest runtime behavior. Preserve the\noriginal MacBinary, checksums, guest OS version, file-transfer method, and\nlaunch evidence. Do not report runtime success based on a host-side command\nthat only opens and exits without expected UI if the application is supposed\nto display a UI.\n", "name": "troubleshooting", "title": "diagnostics and recovery" }, { "aliases": [ "support" ], "markdown": "# Compatibility and supported scope\n\nThe v0.1.1 Linux candidate has a qualified PowerPC C application workflow:\nLinux x86-64 host, Classic Mac OS PowerPC target (validated on Mac OS 9),\nCFM/PEF output, declared user-supplied SDK/runtime inputs, native macMAKE\ncompiler and linker path, resources/Finder metadata, and MacBinary II\npackaging. It also includes an experimental independent native M68000 C\napplication workflow selected by the exact `classic-68k-segmented-app-c-v1`\nand `macmake-classic-m68k-c-v1` profile pair. That profile creates one\nbounded CODE 1 segment, CODE 0 startup/jump-table resources, Finder metadata,\nand MacBinary II output through the ordinary `macmake build` command.\n\nThe toolchain archive excludes proprietary Apple Universal Interfaces,\nMetrowerks MSL libraries and other nonredistributable historical materials.\nUsers supply SDK/runtime files they are authorized to use.\n\nThe experimental 68K profile is not a general 68K compatibility promise. It\nis currently limited to C89, one near-model CODE 1 segment, bounded\nPC-relative code and globals, no external linked libraries, and a documented\nin-process Rez subset. Multiple segments, general A5-relative application\nglobals, C++ runtime support, CFM-68K, and broad System 6/7 compatibility are\nnot provided. The exact macMAKE v0.1.1 RC6 Linux candidate built makePAD, and\nthe resulting MacBinary was observed running in QEMU 8.2.2 with a Mac OS 9.2.2\n`mac99`/G4 guest. The operator observed text entry, an unsaved-changes dialog,\nand exit to Finder. This is one RC6 candidate/application result, not a test of\nthe corrected RC7 screenshot implementation, every application, or another OS\nversion. RC7's screenshot behavior is host-tested with QEMU-style PPM output;\na corrected RC7 real-guest capture remains pending. Earlier development\nobservations for makePAD and HelloWindow remain application-specific.\n\nThe following are not release claims: complete CodeWarrior Pro replacement,\ncomplete `.mcp` import, arbitrary compiler-option equivalence, unrestricted\nC++ ABI/runtime parity, macOS-host builds, Mac OS X output, a bundled Rust\ncompiler or direct Rust-source compilation by `macmake build`, or universal\nRez compatibility. A separate pinned Rust toolchain can emit a PowerPC XCOFF\nobject consumed by the ordinary macMAKE linker/package workflow; the bundled\ninterop sample has build and structural evidence, not a runtime test of that\nexact sample on a Classic Mac. The parser may retain additional experimental\nor legacy shapes for research and fixtures; the command/topic stability\nlabels identify them.\n\n`import-cw-xml` is experimental and accepts XML exports rather than arbitrary\nbinary project files. `system-extension`, diagnostic runtime probes, and\nsome library target kinds are outside the application workflows.\n\nThree kinds of evidence are separate:\n\n1. Linux command/build and structural artifact validation.\n2. Mac OS 9 load/startup/runtime behavior in the guest.\n3. Application-level behavior such as UI, network or user-data handling.\n\nPassing one level does not prove the next. A successful build or artifact\ninspection is not a Mac OS 9 runtime test.\n", "name": "compatibility", "title": "supported scope and limitations" }, { "aliases": [ "samples" ], "markdown": "# Examples\n\nThe `examples/first-app` directory is the supported C application example.\nIt has two C89 sources and a native `macmake.toml`. The user must provide\nauthorized Universal Interfaces and Metrowerks MSL archives as explained in\nits README.\n\n```sh\ncd examples/first-app\nexport MACMAKE_TOOLCHAIN_ROOT=\"${MACMAKE_TOOLCHAIN_ROOT:-../../toolchain}\"\n./setup-user-msl.sh \"$HOME/SDKs/Authorized/CodeWarrior\"\nmacmake sdk add \"$HOME/SDKs/Authorized/CodeWarrior/MacOS Support/Universal\" --id macos9-sdk\nmacmake inspect .\nmacmake doctor . --target \"Classic PPC C\"\nmacmake build . --target \"Classic PPC C\"\n```\n\nThe helper copies only user-supplied local libraries into the example's\nignored `sdk/` directory and reports hashes. The example's manifest records\nexact system-import/library inputs and output metadata. Run\n`macmake help manifest` before authoring variants.\n\nOther repository fixtures cover experimental and historical semantics; they\nare not all release examples. Check `macmake help compatibility` before\nselecting a non-application target profile.\n", "name": "examples", "title": "working project examples" }, { "aliases": [ "qemu", "runtime-testing" ], "markdown": "# Optional QEMU Macintosh runtime smoke test\n\n`macmake run` supports one interactive profile: QEMU's `mac99` PowerPC\nmachine with a G4 CPU and a user-owned Mac OS 9.2.2 disk image. It does not\nbundle a ROM, operating-system image, or emulator.\n\nThe command creates a new qcow2 copy-on-write overlay and attaches that\noverlay to QEMU. QEMU writes to the overlay; the configured base disk is\nSHA-256 hashed before and after the run. The overlay and evidence are retained\nunder `$XDG_STATE_HOME/macmake/runs/` or `~/.local/state/macmake/runs/`.\n\n## Profile\n\nCreate a JSON file with paths to an authorized disk image and an application\nalready staged inside that image using a Mac-aware transfer method:\n\n```json\n{\n \"schema_version\": 1,\n \"emulator\": \"qemu-system-ppc\",\n \"qemu_img\": \"qemu-img\",\n \"machine\": \"mac99\",\n \"cpu\": \"g4\",\n \"memory_mib\": 1024,\n \"display\": \"gtk\",\n \"guest_os\": \"Mac OS 9.2.2\",\n \"base_disk\": \"$HOME/MacOS-9.2.2.qcow2\",\n \"application\": {\n \"name\": \"HelloPPC\",\n \"guest_path\": \"Macintosh HD:Applications:HelloPPC\"\n }\n}\n```\n\nThe initial profile accepts only `mac99`, `g4`, `Mac OS 9.2.2`, and a GTK or\nSDL display. The guest path and OS identity are labels for the operator; the\ncommand does not inspect the HFS volume or infer the guest's installed OS.\n`--artifact` records and hashes a host-side MacBinary file but does not copy\nit into the disk image.\n\n## Run and checkpoints\n\n```sh\nmacmake run ./qemu-macos-9.2.2.json \\\n --artifact ./build/HelloPPC/ClassicPPCC/HelloPPC.bin \\\n --build-evidence ./build/HelloPPC/ClassicPPCC/HelloPPC.build-evidence.json\n```\n\nThe QEMU window opens. Boot Finder and check About This Computer to identify\nthe guest OS. Before answering yes to the boot checkpoint, close About This\nComputer and any other dialog so the boot capture shows Finder. Launch the\nconfigured application manually. Before answering yes to the launch\ncheckpoint, bring its main window to the front and dismiss unrelated Finder or\nAbout This Computer dialogs. The application-state capture is taken\nimmediately after that answer. The CLI asks separately whether the captured\napplication state is correct and whether the application exited normally.\nThese are operator-confirmed observations, not automated guest assertions.\n\nQEMU 8.2.2 writes binary P6 PPM data for QMP `screendump`; macMAKE saves it as\n`guest_boot.ppm` or `application_state.ppm`, validates the PPM header and pixel\nlength, and records the actual format, dimensions, SHA-256, path, and named\ncheckpoint in `run.json` schema 2. A failed or truncated capture is a test\nfailure. If the two captures are byte-identical, both are retained and labeled,\nbut the run cannot claim runtime-state confirmation from duplicate visual\nevidence. Separate screenshots supplement the operator's checkpoint answers;\nthey do not independently prove that an application works.\n\nThe host artifact is recorded and hashed but is not copied into the guest disk.\nWhen `--build-evidence` is supplied, the CLI verifies that the evidence\nrecord's MacBinary SHA-256 matches before setting `artifact_constructed` to\ntrue. If no matching record is supplied, construction is marked unverified;\nthe CLI never infers a build from file existence alone.\n\nUse `--timeout SECONDS` to bound the interactive session or `--json` to print\nthe final structured result. Each run directory contains `run.json`,\n`qemu.log`, `serial.log`, the qcow2 overlay, and validated PPM screenshots\nwhen captured. The JSON keeps emulator startup, guest boot, OS confirmation,\napplication launch, visible state, normal exit, timeout, and QEMU exit status\nseparate. Screenshot records are objects with `checkpoint`, `path`, `format`,\n`sha256`, `width`, `height`, and `distinct_from_prior_checkpoint` fields.\nExit code 0 means the guest OS, application launch, and visible state were\nconfirmed; code 1 means a checkpoint failed, was not confirmed, or timed out.\n\nTo keep the test reproducible, retain the profile, base-disk hash, run record,\nscreenshots, and host artifact hash together. Do not share system images or\nROM files unless their redistribution is authorized.\n\n## Limits\n\nThis is an interactive QEMU smoke-test workflow for the single named guest\nprofile. It does not inject a host artifact into a Macintosh disk, automate\nFinder, verify application output independently, or prove physical Quadra\nhardware behavior. Basilisk II, SheepShaver, other QEMU machines, other OS\nversions, headless runs, and automatic test-result channels are unsupported\nby this command. Structural artifact inspection remains a separate host-side\ncheck.\n", "name": "emulator", "title": "optional QEMU Macintosh runtime testing" }, { "aliases": [ "agents", "automation" ], "markdown": "# Offline workflow for coding agents\n\nThe installed macMAKE executable is the authoritative reference for its own\nversion. Use these commands before editing or running project operations:\n\n```sh\nmacmake help --json\nmacmake help manifest --json\nmacmake schema manifest --json\nmacmake inspect PROJECT\nmacmake help targets\nmacmake doctor PROJECT --target TARGET\n```\n\nRecommended sequence:\n\n1. Discover commands with `macmake help`; query JSON when structured parsing\n is useful.\n2. Inspect the project and list exact target names.\n3. Check toolchain, SDK packages/capabilities and declared libraries with\n `doctor`, `sdk list`, `sdk inspect`, and `sdk verify`.\n4. Read relevant offline topics: manifest, access-paths, libraries, toolchain,\n output and compatibility.\n5. Diagnose a missing header with `resolve-header`; correct the manifest or\n register an authorized SDK. Diagnose imports from `doctor` and build\n evidence.\n6. Run the requested build with explicit project and target arguments.\n7. Inspect the exact generated components using `inspect-artifact --json`.\n8. Summarize the command, version, status, artifacts and retained evidence.\n9. If transport is requested, stage the MacBinary to the explicitly selected\n Classic filesystem destination, then verify it.\n10. Report Linux build/structure checks separately from Mac OS 9 guest\n launch and application behavior.\n\nRecovery patterns:\n\n- **Unknown target:** `macmake inspect PROJECT`, copy the exact target name,\n then rerun doctor/build with `--target \"exact name\"`.\n- **Missing SDK:** `macmake sdk list`; register authorized material with\n `macmake sdk add ROOT --id ID`; inspect and verify it; update `[target.sdk]`.\n- **Unresolved import:** read the exact symbol/provider diagnostic, inspect\n `[[target.libraries]]` and required SDK capabilities, run `sdk verify`,\n correct the actual missing input, and rebuild. Do not fabricate symbols or\n substitute an unrelated runtime.\n\nRead-only discovery commands include `help`, `inspect`, `doctor`, `sdk list`,\n`sdk inspect`, `sdk verify`, `resolve-header`, and `inspect-artifact`.\n`build` and `compile` create build outputs; `clean` deletes them; `sdk add`\nchanges the user's registration catalog; `import-cw-xml` writes a manifest;\n`stage` and `clone-classic` write destination files.\n\nThis guide requires no particular LLM provider or agent framework. Do not\nclaim Mac OS 9 execution based on Linux build or artifact evidence.\n", "name": "agent-workflows", "title": "offline workflows for coding agents" } ] }