Skip to content

Historical CLI Migrations (pre-0.5 and 0.5-era)

Upgrading from the latest published release? Start elsewhere.

Upgrading from 0.5 to 0.6 is the authoritative migration guide and the only page that describes the current CLI. This page is a historical record of the two earlier resets, kept for anyone migrating a command line written against 0.4.x or earlier. Every mapping below is labelled with the release that made it, and a replacement named here may itself have been superseded by 0.6 — always cross-check the 0.6 guide before adopting one.

abicheck's CLI went through two rounds of change before 0.6: a 0.5.0 flag reset that reshaped compare's flags, and a 0.5-era command-surface reset that removed or folded most of the standalone companion commands. This page is the combined map for those two: which commands survived them, which became flags, which were gone by 0.5, and which flags/inputs were renamed.

Removed commands

Running any of these now just fails with Click's normal "No such command" error. Where a library function survives for programmatic/Python API use, that's noted — none of these are documented as a public CLI path anymore.

Deleted command Status
baseline (registry group: push/pull/list/delete) No replacement command. Use compare OLD NEW for point-in-time comparisons, or keep JSON snapshots yourself (plain files, your own storage/naming convention). See Baseline Management.
collect, merge, recommend-collect-mode Gone from the CLI. dump --sources/--build-info auto-collects build/source evidence inline; compare auto-ingests each side's embedded build-source pack, or an out-of-band pack via --build-info old=PATH/--build-info new=PATH (auto-detects abicheck_inputs/ packs too). Library functions survive for internal/programmatic use only.
debian-symbols No CLI replacement. Library functions still exist in abicheck/debian_symbols.py (generate_symbols_file, validate_symbols, diff_symbols_files, parse_symbols_file, etc.) for programmatic/Python API use only. See Debian Symbols.
doctor No replacement command.
config (scaffolding subcommand: config validate, config show-effective) No replacement command. Config loading is strict now (unknown keys, wrong types, bad enum values are hard errors, exit 64), so validate is less necessary; there is no show-effective equivalent.
init No replacement command — no more .abicheck.yml scaffolding generator. Write the file by hand; see Config File Reference for the schema/keys.
surface-report No replacement command.
graph compare / graph explain No replacement command.
pr-comment Moved off the public CLI. Now invoked only as python -m abicheck.cli_pr_comment, used internally by the GitHub Action — not a documented end-user command.
suggest-suppressions No replacement command.
probe (probe run, etc.) No replacement command, and no CLI to generate a probe matrix any more. A previously captured matrix snapshot is consumed as one of --build-info's transports (compare --build-info m.json); the separate --probe-matrix spelling that once did this was itself removed in 0.6 — see Upgrading to 0.6 §C4.

Folded into compare flags

Two of the old standalone commands became scoping flags on compare instead of separate commands — the full library comparison still runs once, and its own result is always this run's primary verdict/exit code; the supplied consumer's/host's own confirmed/potential/unresolved impact is reported alongside it, informational only, never in place of it.

Old command New flag What it scopes to
appcompat compare --used-by APP (repeatable) An application binary's actual imports/required symbol versions. Mutually exclusive with --required-symbol.
plugin-check compare --required-symbol SYM (repeatable) / --required-symbol @FILE (one symbol per line, # comments ignored) An explicit plugin-host entrypoint contract instead of the full diff. Mutually exclusive with --used-by. 
# Was: abicheck appcompat --app myapp old.so new.so
abicheck compare old.so new.so -H include/ --used-by build/myapp

# Was: abicheck plugin-check --required-symbol foo_init old.so new.so
abicheck compare old.so new.so -H include/ --required-symbol foo_init

See Application Compatibility and Plugin & Host Systems for the full guides — treat their command-line examples as the ones that matter, this page only summarizes the mapping.

Removed scan axes (s0…s6, --mode, --source-method, --max)

scan itself no longer exists

The scan command was retired outright in 0.6. abicheck scan exits 64. The table below is a historical evidence-axis mapping, useful for reading an old command line; its --depth right-hand column is still the live spelling, but it now belongs to compare. See Upgrading to 0.6 §A1.

Earlier releases let you pick evidence in two other ways. As of the pre-1.0 CLI reset, both were removed outright, not deprecated — scan stopped accepting --mode/--source-method/--max at all; passing any of them was a plain "no such option" usage error (exit 64), same as any other unrecognized flag. There is no warn-and-map compatibility shim: this table is here only for anyone migrating an old command line, not as a live alias list. The internal s0…s6 vocabulary still exists inside the engine (model/evidence_depth_levels.py; the --mode presets themselves went with scan), but it has no public entry point beyond .abicheck.yml's source.method — the typed ScanRequest that used to accept it was removed in 0.6 — and it must never leak into the public CLI, --help, reports, the config schema, or GitHub Action inputs. Prefer --depth.

--source-method s0…s6 (the old "how it gathers evidence" axis):

Removed Was Use instead
s0 / s3 diff classifier / lexical pattern scan (compiler-free) --depth binary (or headers for +L2)
s1 compile-DB / build-flag scan (L3) --depth build
s2 preprocessor macro/include capture folded into --depth build (runs when clang -E + a compile DB are present)
s4 symbol/reference index → the cheap L5 structural graph (no L4 replay, no call edges) no user-facing --depth rung: the graph-only level is internal. --depth source gives L5 edges but pays for the L4 replay; there is no cheap graph-only depth
s5 semantic AST replay of changed TUs (L4) --depth source
s6 full AST replay of all TUs (L4) --depth source — the old full rung collapsed into source; they only ever differed in replay scope, and --depth source with no --since/--changed-path seed already analyses the whole target, matching what s6/full used to give

--mode presets:

Removed Was Use instead
pr diff-seeded L4 replay (per-PR gate) --depth source --since <ref> — pin the rung; omitting --depth resolves to headers and collects no L4 evidence at all
pr-deep pr + the whole-library L5 reachability graph (GRAPH) no exact --depth equivalent — the full graph is internal-only. --depth source gives the change-scoped edges; the full-graph preset is reachable only via the internal Python service API now
baseline whole-library replay of a release --depth source with no --since/--changed-path seed (resolves to TARGET scope — the whole current library target)
audit intra-version hygiene lint, no baseline compare --no-baseline NEW (the old standalone --audit flag was removed as redundant in the pre-1.0 CLI reset; scan with no --against then took its place, and 0.6 moved that onto compare). Note the gate change: --severity-preset is now required to make the audit gate — see Upgrading to 0.6 §A2

--source-method auto's risk-driven escalation is gone, not relocated: 0.6 retired it along with --risk-rules. Omitting --depth still means auto, but auto resolves to the fixed headers rung — the same default compare uses — so a workflow that relied on a high-risk diff escalating itself to build/source must pin that rung explicitly.

Still commands today

Some of the old companion functionality survives as a command:

Command What it does
deps tree Resolve one binary's dependency closure and symbol bindings.
deps compare Diff a binary's full dependency stack across two environments (was stack-check).

The root surface today is dump, compare, deps, aggregate and project — scan and compat were retired in 0.6. None of the orchestration commands (aggregate, the project group) are part of the companion-command consolidation this page describes; see the CLI Reference for the full current command tree, and Upgrading to 0.6 for what changed most recently.

deps tree

abicheck deps tree ./build/libfoo.so
abicheck deps tree /usr/bin/myapp -o json=deps.json
abicheck deps tree ./app --sysroot /path/to/container/rootfs

With no --sysroot, the analysis runs against the current host filesystem (/). That is a fallback, not a deployment environment anyone selected, so the resolved plan (--dry-run) and the report both label the root defaulted — an explicitly given --sysroot / is a choice and is never labelled that way.

Exit codes: 0 all dependencies resolved, 1 missing dependencies/symbols.

deps compare

abicheck deps compare usr/bin/myapp --old-root /old-root --new-root /new-root
abicheck deps compare usr/lib/libfoo.so.1 \
  --old-root ./image-v1 --new-root ./image-v2 -o json=-

--old-root/--new-root (each default /) point at the two sysroots to compare BINARY across. A root left at its default is reported as defaulted — in the resolved plan, and in the JSON (baseline_env_defaulted/candidate_env_defaulted), Markdown and HTML reports — so / beside a named image root cannot be misread as a second environment someone chose. Exit codes: 0 PASS, 1 WARN (loads but ABI risk), 4 FAIL (load failure or binary ABI break).

Renamed/restructured flags (0.5.0)

Before the command-surface reset above, 0.5.0 reshaped compare's (and, at the time, appcompat's) flags. Two kinds of change affect scripts still written against a pre-0.5.0 invocation:

Side-aware flags

Each concept below is now a single repeatable flag. Scope a value to one side with an old= / new= prefix, repeating the flag per side; a bare value applies to both. There is no alias window for the removed spellings — update scripts before upgrading.

Removed (0.4.x) Replacement (0.5.0+)
--old-header v1/f.h --new-header v2/f.h --header old=v1/f.h --header new=v2/f.h
--old-include i1 --new-include i2 --include old=i1 --include new=i2
--old-version 1.0 --new-version 2.0 --version old=1.0 --version new=2.0
--old-sources src1 --new-sources src2 --sources old=src1 --sources new=src2
--old-build-info b1 --new-build-info b2 --build-info old=b1 --build-info new=b2
--old-pdb-path a.pdb --new-pdb-path b.pdb --pdb-path old=a.pdb --pdb-path new=b.pdb
--debug-root1 d1 --debug-root2 d2 --debug-info old=d1 --debug-info new=d2
--debug-info1 x --debug-info2 y --debug-info old=x --debug-info new=y
--devel-pkg1 p --devel-pkg2 q -H old=p -H new=q
--probe-matrix-old m1 --probe-matrix-new m2 --build-info old=m1 --build-info new=m2

The last three rows changed target in plan Phase 7n, which gave each evidence role one input: a debug directory, a detached debug file and a debug package are three transports of --debug-info; a development package is one of -H/--header's; and a probe-matrix snapshot is one of --build-info's. The old spellings --debug-root, --devel-pkg and --probe-matrix exit 64 with no alias. Which transport an operand is comes from its content — a package under a name with no suffix, or a matrix snapshot called build.json, is still recognised.

Notes:

  • Repeat the flag, don't chain values: --header old=a new=b is wrong (the second token is not a value). Write --header old=a --header new=b.
  • -H / -I are unchanged and still mean "both sides"; use them for the common case where the same header/include applies to both versions.
  • both= is an escape hatch for a path that literally begins old= / new= (rare): --header both=old=weird.h.
  • The version flag defaults per side stay old / new — pass --version only when your .so files need explicit labels.
  • The --ast-frontend per-side overrides (--ast-frontend old= / --ast-frontend new=) are gone (Phase 7, CONFIG class, no CLI override survives on any command). See "Config removal (Phase 7)" below.

Config removal (Phase 7)

These flags are no longer in compare --help or dump --help, and no CLI override survives — .abicheck.yml is each field's only source now (a hidden-but-accepted flag still counts as public surface, so once a setting is fully config-backed the CLI spelling is removed outright rather than left hidden). See the config-file reference and its compile: section.

Was a flag Now a config key only (block → key)
--debug-format dwarf debug.format: dwarf
--dwarf-only debug.dwarf_only: true
--debuginfod debug.debuginfod: true
--debuginfod-url URL debug.debuginfod_url: URL
dump --pdb-path debug.pdb_path: PATH. No --pdb-path survives on any command, and the config key is a single value — there is no per-side PDB input.
--ast-frontend compile.frontend: castxml\|clang\|hybrid\|auto
--allow-ast-frontend-fallback compile.ast_frontend_fallback: true
--allow-unsupported-castxml compile.allow_unsupported_castxml: true
--compiler / --compiler-prefix compile.compiler: (one merged key — a trailing - is treated as a prefix, otherwise a full compiler path)
--compiler-option (repeatable) compile.options: (a YAML list)
--sysroot compile.sysroot:
--nostdinc compile.nostdinc: true
--frontend-context compile.frontend_context: host\|device
--lang compile.lang: c++\|c

Example .abicheck.yml:

debug:
  format: auto
  dwarf_only: false
compile:
  frontend: clang
  sysroot: /opt/sysroots/aarch64
  nostdinc: true
  options: [-march=armv8-a]
scope:
  show_redundant: false

None of these have a CLI override any more — there is no --no-dwarf-only, no --ast-frontend, nothing to pass on the command line to win over the config value. A script that still passes one of the removed flags exits 64 ("No such option") -- rewrite it to set the equivalent debug.*/compile.* key in .abicheck.yml instead. --show-redundant was retired the same way earlier and has no CLI spelling left either.

Not demoted (still visible flags): --debug-info (the coarse per-run debug-artifact override, side-aware, and since Phase 7n the whole separate-debug-info role — see the table above). --scope-public-headers / --no-scope-public-headers were listed here too until one-comparison-product Phase 9b deleted them: public-header scoping stays on by default, --contract all turns it off for one run, and .abicheck.yml's scope.public: false turns it off project-wide.

Run profiles: added, then removed

--profile {ci-gate,release-cut,quick} briefly bundled a workflow's common defaults into one token. It was removed outright in 0.6: it bundled evidence depth, report rendering, and CI gate policy behind one word, and a rendering choice may never carry a gate setting. There is no direct config-key replacement — state --depth, -o, and --severity-preset (or .abicheck.yml's severity: block) independently. quick's one-line summary survives as the first-class -o oneline=... choice; see Output Formats.

GitHub Action

The Action's per-side inputs (old-header, new-header, old-version, new-version, debug-info1, devel-pkg1, …) were unaffected by the side-aware-flags change above — the wrapper maps them to the new side-aware flags internally. No workflow edits were needed for Action users at the time.