CLI reference

This page lists every flag the elephc command accepts. Topical pages (optimization, output, linking) explain the why; this page is the exhaustive what.

Synopsis

elephc [OPTIONS] <source.php>

Exactly one positional argument is required: the path to the PHP source file. The binary is written next to it, named after the source without its extension.

Input and output

Flag	Values	Default	Description
<source.php>	path	—	Required. The PHP file to compile.
--emit KIND / --emit=KIND	executable (exe, bin), cdylib (dylib, shared)	executable	Output artifact kind. cdylib builds a C-ABI shared library.
--emit-asm	—	off	Write generated assembly instead of a binary.
--emit-ir	—	off	Print the EIR textual form and stop.
--check	—	off	Run front-end checks only; write nothing.
--source-map	—	off	Emit a .map JSON sidecar next to the assembly (schema).
--debug-info	—	off	Embed DWARF .file/.loc line directives in the assembly for lldb/gdb/profilers.
--web	—	off	Compile a prefork HTTP server binary instead of a CLI executable. See Web Server.

--emit-ir, --emit-asm, and --check are mutually exclusive. --web cannot be combined with --check, --emit cdylib, --emit-asm, or --emit-ir. See Output formats and diagnostics.

Web server binary runtime arguments

When a program is compiled with --web, the produced binary accepts these runtime arguments (not elephc compiler flags):

Argument	Required	Default	Description
--listen host:port	Yes	—	Address and port to bind. Missing --listen prints an error to stderr and exits non-zero.
--workers N	No	CPU count	Number of prefork worker processes. Minimum 1.
--max-body-size N	No	8388608 (8 MiB)	Max request body in bytes (0 = unlimited); oversized bodies get 413.
--max-requests N	No	0 (never)	Recycle each worker after N requests (bounds memory growth).
--access-log	No	off	Log one line per request to stderr.
--help, --version	No	—	Print usage / version and exit.

elephc --web app.php
./app --listen 127.0.0.1:8080
./app --listen 0.0.0.0:8080 --workers 4 --max-body-size 1048576 --access-log

The served program also receives $_COOKIE, $_REQUEST, and $_ENV, and can emit cookies with setcookie(). The server shuts down cleanly on SIGINT/SIGTERM and respawns workers that die.

The served program receives the HTTP request through the standard superglobals $_SERVER, $_GET, $_POST, and php://input, and controls the response status and headers with http_response_code() and header(). See Web Server.

Targets

Flag	Values	Default	Description
--target TARGET / --target=TARGET	macos-aarch64, linux-aarch64, linux-x86_64 (plus alias spellings; recognized future targets produce an unsupported-backend diagnostic)	host platform	Select the compilation target.

See Targets and cross-compilation for the full list of accepted spellings.

Optimization and code generation

Flag	Values	Default	Env override	Description
--ir-opt=on|off	on, off	on	ELEPHC_IR_OPT	Toggle the EIR optimization passes: identity folding, peepholes, constant folding, common-subexpression elimination, loop-invariant code motion, dead-instruction elimination, dead-store elimination, branch simplification, and the cross-function small-function inliner — run to a module-level fixed point.
--no-ir-opt	—	—	ELEPHC_IR_OPT=off	Shorthand for --ir-opt=off.
--regalloc=linear|stack	linear, stack	linear	ELEPHC_REGALLOC	Register allocator: linear-scan, or stack-only fallback.
--null-repr=sentinel|tagged	sentinel, tagged	tagged	ELEPHC_NULL_REPR	Representation for null-capable scalar slots.

See Optimization and codegen controls.

Linking and FFI

Flag	Values	Default	Description
--link LIB / -l LIB / -lLIB	library name	—	Link an extra native library (repeatable).
--link-path DIR / -L DIR / -LDIR	directory	—	Add a library search path (repeatable).
--framework NAME	framework name	—	Link a macOS framework (repeatable).
--with-CRATE	pdo, tls, crypto, phar, tz, image, web	—	Force-enable a bridge crate regardless of feature auto-detection (repeatable). Force-links the staticlib (whole-archived, so it is not dead-stripped) and, for crates with a PHP-surface prelude (pdo, tz, image), force-injects that prelude so the API is available. --with-web is an alias for --web. An unknown crate name is an error.

See Linking, heap, and conditional compilation.

Memory and conditional compilation

Flag	Values	Default	Description
--heap-size=BYTES	integer ≥ 65536	8388608 (8 MB)	Size of the program’s runtime heap.
--define SYMBOL / --define=SYMBOL	symbol name	—	Define a compile-time symbol for ifdef (repeatable).

Diagnostics and debugging

Flag	Values	Default	Description
--timings	—	off	Print per-phase compiler timings to stderr.
--gc-stats	—	off	Print allocation/free counters at exit.
--heap-debug	—	off	Enable runtime heap verification (double-free, bad refcount, free-list corruption).

See Output formats and diagnostics.

Environment variables

Three environment variables provide defaults that the matching flag overrides. They exist mainly so a whole test run or benchmark can flip a default without changing every invocation:

Variable	Values	Equivalent flag
ELEPHC_IR_OPT	on, off	--ir-opt=
ELEPHC_REGALLOC	linear, stack	--regalloc=
ELEPHC_NULL_REPR	tagged, sentinel	--null-repr=