Command Reference¶

用法：antel [OPTIONS] COMMAND [ARGS]...

All commands except init, install, and uninstall accept --file / -f to specify the configuration file name, which defaults to antel, corresponding to antel.json:

antel rebuild -f gcc
antel build --file release

Build artifacts live under .antel/build/<project name>_<configuration name>/ (for example, the default config writes to .antel/build/<projectName>_antel/), so the same source tree can produce different targets with different configurations without any interference.

fetch-ref¶

Prepare the configured ref repositories without compiling or linking:

antel fetch-ref
antel fetch-ref -f release

References are downloaded under .antel/refs/; subsequent build and rebuild commands reuse these checkouts. The first download requires Git and network access.

build and rebuild¶

antel build      # compile only what changed; does nothing if nothing changed
antel rebuild    # wipe obj/ and log/, full rebuild

How build decides what to compile is described in Incremental Build: a source file is recompiled only when it or one of its dependencies has changed, or when its object file or dependency file is missing. When nothing differs, it only prints 「项目没有改动」 and does nothing else.

Use rebuild for the first build, after clean, or whenever you suspect the incremental state is off.

install¶

Reads install.json from the current directory and scans the build JSON configs in that directory to install existing targets. It does not build, fetch refs, or run hooks, and does not require the original compilation dependencies.

{
    "install_path": "/usr/local",
    "projectName": "libpng"
}

install_path is required. Absolute paths, paths relative to the current directory, and ~ are supported. Required projectName names the new isolated installation directory. The example installs entirely inside /usr/local/libpng/, not the system bin/lib/share directories. Optional projects accepts one build project name or a nonempty array, such as ["png16", "pngviewer"]. Omit it to install all built projects. Explicitly selected projects must have artifacts.

antel install

• Executables go to <install_path>/<projectName>/bin/; static and shared libraries go to lib/ within that isolated directory.
• File permissions and versioned library symlinks are preserved. Reinstalling updates existing files. Conflicting artifacts from different configurations cause an error before copying starts.
• Deployed data_files go to share/<project name>_<config name>/, preserving relative paths. Applications must support this resource layout; the installer does not rewrite resource paths or RPATH in binaries.
• Source, headers, objects, logs, and reports are not copied. Invalid configs, missing resources, and permission failures exit nonzero.

An .antel-install manifest records installed files and their owning projects for repeat installs. Existing unmanaged directories and escaping symlinks are rejected. Run sudo antel install yourself if the parent requires administrator privileges. The installer does not register system PATH entries or library caches. Use an RPATH such as $ORIGIN/../lib or set LD_LIBRARY_PATH for an individual launch.

Installation Manifest¶

.antel-install is a JSON manifest generated by the installer. Example entries:

{
    "version": 1,
    "files": {
        "bin/pngviewer": "pngviewer",
        "lib/libpng16.so.16.60.git": "png16",
        "lib/libpng16.so.16": "png16",
        "share/pngviewer_pngviewer/testdata/antel-logo.png": "pngviewer"
    }
}

version describes the manifest format, not the software release. Keys in files are paths relative to the isolated package directory; values identify the owning build project, not the package directory name in install.json. Successful copies are recorded individually. Repeat installs retain previous records; uninstall uses these records and the optional projects filter, even without a build tree.

The manifest is not required to run programs, but do not delete or edit it: it identifies managed directories and files. If uninstall preserves added user files, it also keeps an empty manifest to support reinstalling and repeat uninstall. See the next section for upgrading legacy empty markers.

uninstall¶

Reads the same install.json from the current directory and removes files recorded in the isolated installation's .antel-install manifest:

antel uninstall

install_path and projectName identify the installation directory. Optional projects removes only records owned by those build projects; omit it to remove all records. Neither build configs nor original build artifacts are required.

Only recorded files and symlinks are removed. Empty directories are cleaned up; manually added files are preserved. The isolated directory is deleted only when empty, never its parent. An absent installation directory is a successful no-op. Invalid manifests, escaping paths, and permission failures exit nonzero and can be retried after the problem is corrected.

Legacy empty .antel-install markers must first be upgraded by rerunning antel install. Uninstall does not clean files from the former system-wide bin/lib/share layout or run ldconfig. Run sudo antel uninstall yourself when administrator privileges are needed.

Temporary legacy system cleanup¶

For earlier installs directly into <install_path>/bin, lib, and share without a manifest, explicitly opt into legacy cleanup:

antel uninstall --legacy-system --dry-run
sudo antel uninstall --legacy-system

This does not uninstall the isolated <install_path>/<projectName> directory. Current build configs and surviving artifacts determine the old paths. Every existing candidate must match the local file bytes or symlink target; any mismatch prevents all deletion. The projects filter still applies; absent old files are skipped. Preview first, and do not clean or rebuild the original artifacts first. Only matching files and empty project resource directories are removed; system bin/lib/share directories and unrelated files remain. If ldconfig was used previously, run sudo ldconfig yourself after removing the old shared libraries.

clean¶

Deletes the entire build output directory (.antel/build/<project name>_<configuration name>/), including generated targets, object files, logs, and the hash baseline. Since the baseline is deleted too, running antel build right after clean performs a full build — no need for rebuild first.

link¶

Links only, without compiling. Use it to confirm that the link flags and library dependencies are correct, or to regenerate targets after manually adding object files to obj/.

analyze¶

Generates a visual analysis report: a report.html in the output directory (a self-contained single-file HTML with inline CSS and no external dependencies — just open it in a browser). The report covers 10 analysis dimensions:

antel analyze

The report automatically covers every source file in the configuration, with no configuration field required. Generating it automatically after a successful build is enabled with report: true (see Configuration); both paths produce an identical report.

run¶

Valid only for projects whose target_type is exe; it directly executes the generated executable:

antel run

If the target type is not exe, or the executable does not exist yet, it reports a clear error and exits with a non-zero exit code.

Exit codes¶

There is a single convention: an exit code of 0 means the step really succeeded. If compilation or linking fails, it does not continue, nor does it print success messages like 「链接完毕」, so the command can be chained directly with && or used in CI.

antel rebuild && antel run

Common combinations¶

# full build, then run immediately
antel rebuild && antel run

# build with an alternative config producing a shared library
antel rebuild -f shared

# debug linking: relink only, then check the link script and link output
antel link -f release
cat release_release/log/*_link.sh
cat release_release/log/linkInfor