Command reference

Every manticore command, its options and exit codes. The text under each command is the declared help (manticore <command> --help); tests/cli/help.txt pins it.

Invocation#

manticore <command> [options...]

• manticore, manticore help, manticore --help, manticore -h print the command list and exit 0. An unknown command prints unknown command: <name> to stderr, then the same list, and exits 0.
• manticore <command> --help (or -h) prints that command's summary, usage and options and exits 0. Help is detected after option parsing, so compile -o --help x treats --help as the value of -o.
• manticore --version is manticore version.
• Options and positionals may be interleaved (compile prog.php -o prog). Accepted forms: -o out, -O2, --memory=rc, --memory rc, --deep. An unknown option or a missing value prints <command>: unknown flag: … / missing value for … and exits 64.

Commands#

compile#

manticore compile [options] <files…|manifest.json> -o <out>

Exit codes:

manticore compile hello.php -o hello && ./hello
manticore compile src/ -o app -O2 -j 0

build#

manticore build [options] <manticore.json>

Takes the compile options above (except --analyze, --analyze-strict) plus:

--libs-only and --apps-only are mutually exclusive (64). Exit codes: 0 ok; 64 usage; 65 manifest conflict between targets (e.g. a class defined in two libraries); 66 manifest, entry point or target sources cannot be read, or an unknown extension is wanted; 75 clang failed; 76 link failed. Manifest format: modules.md.

manticore build manticore.json --timings

analyze#

manticore analyze [options] [paths…]

Takes the shared options -o, --memory, --backend, -O, --prelude, --effects, --emit-library, --runtime, --allow-undefined-traps, --keep-ir, -j (declared for parity, as in the help) plus:

Exit codes: 0 no error-severity findings (with --only: no surviving finding); 1 an error finding (with --only: any surviving finding); 64 usage; 73 cannot write the --generate-baseline file.

manticore analyze src --only undefined.,parse.error

dump-* and split-ir#

dump-llvm, dump-ast, dump-mir, dump-llvm-mir and dump-sig take [options] [files…] and the same shared options as compile up to -j (--prelude and --effects are the ones that matter here). dump-llvm reads PHP from stdin. They print to stdout.

Exit codes: 0 ok; 64 usage; 66 input cannot be read; 65 the stage failed.

The dump-* commands do not link the stdlib: a call into it resolves as unknown, and a bug in that path can vanish from the dump. Read the final binary when that matters.

manticore dump-mir --effects prog.php | less

split-ir is a dev tool:

manticore split-ir <module.ll> <parts> <outbase>

Exit codes: 0 ok; 64 usage; 66 module unreadable; 65 split failed.

version, upgrade#

manticore version [--check]
manticore upgrade [--check] [--version X]

version prints manticore <X.Y.Z>.

--check prints installed A / latest B followed by update available, up to date or installed is newer. Exit codes of --check: 0 current (or newer), 1 update available, 2 cannot check.

upgrade without --check runs the installed install.sh ($MANTICORE_HOME/share/install.sh) with MANTICORE_STRICT=1:

• already at the target version: says so, exit 0;
• installed is newer than the latest release and no --version given: nothing to do, exit 0;
• --version older than installed: prints downgrading A -> B and proceeds;
• otherwise the exit code is install.sh's.

Foreign installs. upgrade and version --check refuse to touch a compiler that install.sh did not install (no share/install.sh beside bin/). They print which installer owns it (Homebrew, a system package manager, the container image, or "an unknown installer"), say nothing was changed, and exit 2.

install.sh in strict mode (MANTICORE_STRICT=1, which upgrade sets): a miss is fatal and never falls back to a source build. Exit codes:

install.sh --check prints latest=<ver> and platform=<os>-<arch> and installs nothing. Install methods: install.md.

doctor#

manticore doctor [--offline] [--no-smoke]

Prints one line per check, [ OK ], [WARN] or [FAIL], then N ok, N warnings, N failures. A hint line follows every non-OK result that has one. Exit 1 if any check failed, else 0; warnings never fail.

completions#

manticore completions <bash|zsh|fish>

Prints the script to stdout. Any other argument prints completions: expected one of bash, zsh, fish and exits 64.

manticore completions bash > ~/.local/share/bash-completion/completions/manticore
manticore completions zsh  > ~/.zfunc/_manticore     # ~/.zfunc must be in fpath before compinit
manticore completions fish > ~/.config/fish/completions/manticore.fish

The scripts are generated from the command and option declarations, so they match the installed compiler; regenerate them after an upgrade.

Build progress#

compile and build report progress on stderr only; stdout is never touched.

auto: with --quiet, off. Otherwise live when stderr is a terminal; plain when it is not but CI is set to a non-empty value; off otherwise, so piped builds stay silent. --quiet silences progress and timings; diagnostics are still printed. --timings appends the 15 slowest stages, longest first.

Counters: files, functions and, for a split build (MANTICORE_SPLIT_JOBS with -j 0), clang (parts compiled so far / total, cache hits included).

Colour is on only if every rule passes, first match wins: --color=never off; NO_COLOR set and non-empty off; TERM=dumb off; --color=always on; otherwise on exactly when stderr is a terminal. json is never coloured; plain is coloured only with --color=always.

plain (manticore compile h.php -o h --progress=plain, middle of the list elided):

      files 1/1
[ 1] stdlib .sig -> extern decls  0.0s
[ 2] prelude-demand (re-lex)  0.0s
[ 3] parse  0.0s
[ 4] prelude read (all files)  0.0s
[ 5] LowerFromAst  0.0s
…
[33] property scan  0.0s
      functions 1887/1887
[34] emit preamble  0.0s
[35] hoist allocas  0.0s
[36] prune IR  0.0s
[37] EmitLlvm  0.0s
[38] clang -O2 -c whole module  0.2s
[39] link  0.0s
done in 0.7s

json events (--progress=json --timings):

{"event":"counter","label":"files","done":1,"total":1}
{"event":"stage_start","name":"stdlib .sig -> extern decls","t_ms":119}
{"event":"stage_end","name":"stdlib .sig -> extern decls","ms":6,"fns":1820}
{"event":"stage_start","name":"prelude-demand (re-lex)","t_ms":126}
{"event":"stage_end","name":"prelude-demand (re-lex)","ms":0}
…
{"event":"timing","name":"InferTypes #3","ms":4}

--timings in plain:

done in 0.7s
timings (longest first):
     298ms  clang -O2 -c whole module
      49ms  link
      28ms  EmitLlvm
…

Environment#

See also#

• install.md: install methods, upgrade, completions
• ../README.md: overview and usage
• modules.md: manticore.json and manticore build

Edit this page on GitHub