Projects

A project is a folder with a cuarzo.toml, its manifest. The manifest says what the project is made of, so the commands need no file:

cuarzo build            build every program
cuarzo run              build and run the first program
cuarzo check            check every program and library, for each platform it is for
cuarzo test             run the tests the manifest names

They work anywhere in the project's folder: a command given a file uses the manifest in the file's folder or the nearest folder above it, and a command given none uses the one of the current folder. The editor's language server reads the same manifest.

The manifest

[project]
name = "notes"
version = "1.2.0"
platforms = ["linux", "macos", "windows"]

[[program]]
main = "src/notes.cz"

[[program]]
name = "notes-gui"
main = "src/gui.cz"
gui = true

[[library]]
main = "src/markdown.cz"

[tests]
paths = ["tests"]

[profile.debug]
options = ["--check-overflow"]
defines = { LOG_LEVEL = "debug" }

[profile.release]
defines = { LOG_LEVEL = "warn" }

[commands]
serve = "build/notes --serve 8080"
docs = ["cuarzo", "run", "tools/docs.cz", "--out", "build/docs"]

Paths are from the manifest's folder.

[project]

[[program]] and [[library]]

Each [[program]] is a program, and each [[library]] a module that programs import, which is checked and not built.

Programs, libraries, and commands each have a name of their own.

[tests]

paths lists the files and folders that cuarzo test looks in for *_test.cz files when it is given none; the project's folder unless given.

[profile.<name>]

A profile adds options and constants to those of the command line. The debug profile is used unless --release chooses release, or --profile <name> another one; the command line's own options win over a profile's. release always has --release, which optimizes the program and leaves out its symbols.

[commands]

A command is a program and its arguments, as text, split at spaces except within quotes, or as an array of its words. cuarzo run <name> [args...] runs it in the manifest's folder, with the arguments after its own. A command that starts with cuarzo runs the compiler that runs it.

The commands

Given a .cz file, the commands build, run, or check that file, with the options and constants of the profile.

What is wrong with a manifest is reported before anything is built, every problem at once, each at its line, with codes E0434 to E0443; a misspelled key gets a suggestion:

[ERROR E0435] cuarzo.toml:8:1: Unknown key 'mian' in [[program]]; did you mean 'main'?
[ERROR E0438] cuarzo.toml:11:1: No file 'src/nothing.cz' for the program 'nothing'

cuarzo check --json gives them as JSON. The language server reports them on cuarzo.toml, checks the program that starts in the document opened or else the project's first, with the constants of the debug profile, and reads the manifest again when the editor says it changed.

Bundles

cuarzo bundle makes a program into the application each system installs, and into installers for it:

[bundle]
name = "Notes"
identifier = "com.example.notes"
publisher = "Example Ltd"
description = "Take notes"
copyright = "Copyright 2026 Example Ltd"
category = "productivity"
icon = "assets/icon.png"
resources = ["assets/help"]
formats = ["dmg", "msix", "deb"]
url_schemes = ["notes"]

[[bundle.file_types]]
extensions = ["note"]
name = "Notes document"
mime = "application/x-notes"

[bundle.macos]
minimum_system = "11.0"
universal = true

[bundle.linux]
maintainer = "Ana <ana@example.com>"
depends = ["libgtk-3-0"]

cuarzo bundle                     the application, and the formats of [bundle]
cuarzo bundle --format deb,rpm    and these formats too
cuarzo bundle path/to/project     the project of another folder
cuarzo bundle --sign              signed, as the environment says
cuarzo bundle --notarize          on macOS, signed and notarized by Apple

It builds the program with the release profile, unless the options choose another, and puts what it makes in build/bundle/<system>:

The packages for Linux install the program and its resources in /usr/lib/<name>, a link to it in /usr/bin, the desktop entry, the icons at every size of the hicolor theme, a shared-mime-info file for the kinds of files, and AppStream metainfo. The installers for Windows install for the current user, with a Start menu shortcut, the kinds of files, and the URL schemes. Icons of every size each system wants come from the one PNG: square, best at 1024 pixels. A format whose tool is not installed is an error that says where to get it; formats of another system are left out of those in the manifest, and an error on the command line.

[bundle]

Each [[bundle.file_types]] is a kind of file it opens: extensions, without the dot, and name (required), its mime type, and role, editor (the default) or viewer. [bundle.macos] has minimum_system, as "11.0", universal, to build for both arm64 and x86_64, and entitlements, a file for signing. [bundle.windows] has publisher_subject, the subject of the certificate an MSIX is signed with, CN=<publisher> unless given. [bundle.linux] has maintainer, as "Name <mail>", and what the package depends on (Debian) and requires (RPM).

What is wrong with [bundle] is reported with the rest of the manifest, with codes E0435 to E0438 and E0450 and E0451.

Signing

--sign signs what cuarzo bundle makes, with what the environment gives: secrets come from environment variables, as a CI service's secrets are given, and never from files in the repository.

--notarize, on macOS, also sends the disk image, or else the application in a zip, to Apple's notary service with notarytool, waits for it, and staples the ticket to what was sent and to the .app. It takes the credentials of CUARZO_NOTARY_PROFILE, a profile that notarytool store-credentials keeps in the keychain; or of an App Store Connect API key, CUARZO_NOTARY_KEY (the .p8 file's text), CUARZO_NOTARY_KEY_ID, and CUARZO_NOTARY_ISSUER; or of an Apple ID, CUARZO_APPLE_ID, CUARZO_APPLE_PASSWORD (an app-specific password), and CUARZO_APPLE_TEAM_ID. A secret that a tool reads from a file, as a PFX or a key, is written to a temporary file and deleted after the tool is done. An MSIX's publisher, [bundle.windows] publisher_subject, must be the subject of the certificate it is signed with.

Releases from CI

cuarzo ci writes .github/workflows/release.yml: a GitHub Actions workflow that, for a tag that starts with v, builds Cuarzo from its repository's seed on Linux, macOS, and Windows, runs cuarzo bundle on each, signing when the repository's secrets say how, and attaches what it made to the tag's release, the folders zipped. Its secrets are the variables of Signing, with MACOS_CERTIFICATE (a Developer ID certificate as a .p12 in base64) and MACOS_CERTIFICATE_PASSWORD, which it imports into a keychain, and GPG_PRIVATE_KEY, which it imports for GnuPG. --ref chooses the version of Cuarzo it builds with, main unless given; it installs the tools of the formats [bundle] names, and --force writes the workflow again after cuarzo.toml changes.

Dependencies

Dependencies come with the package manager of phase 23.