cli-reference.md

title	CLI reference
description	The complete, authoritative list of every elephc command-line flag, its accepted values, default, and environment-variable override.
sidebar	order 3

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.
--strict-php	—	off	Reject every elephc extension; accept only PHP-compatible constructs. See Strict PHP mode.
--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.
--php-version VERSION	8.2, 8.3, 8.4, 8.5	8.5	Select the maintained PHP compatibility profile for version-dependent behavior. Sessions use it for PHP 8.4 deprecations/validation and PHP 8.5 CHIPS/option semantics.
--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, eval, 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-eval force-links Magician but is not required for normal eval() use; eligible literal eval can remain bridge-free. --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).

Strict PHP mode

Flag	Values	Default	Description
--strict-php	—	off	Accept only PHP-compatible constructs: every elephc extension becomes a compile error.

Under --strict-php the compiler rejects the beyond-PHP extensions at the source level:

• extension syntax — ifdef blocks, packed class, extern declarations, ptr_cast<T>(...), buffer_new<T>(...), typed local variable declarations (int $x = 5;), and ptr/buffer<T> type annotations — is reported with a rejected by --strict-php diagnostic, one error per violation, wherever the construct appears (statement bodies, closures, class members, and PHP attribute arguments alike);
• extension builtins (ptr_*, zval_*, buffer_*, class_attribute_*) behave as if they did not exist, exactly as under the PHP interpreter: function_exists() returns false for them, calling one is an undefined function (the diagnostic names the disabled extension), and user code may declare its own functions with those names;
• names prefixed with __elephc_ are reserved for the compiler and rejected in user code.

The audit covers the main file plus every include/required and autoloaded user file. Compiler-injected preludes (PDO, timezone, image, web, …) are exempt, so programs using those PHP-level APIs keep compiling in strict mode.

Strict mode also reaches eval(), matching PHP's runtime semantics for eval'd code: the compiled binary marks the eval bridge as strict, so extension builtins do not exist inside eval'd fragments either — calling one is a runtime fatal (like any unknown function in eval), function_exists()/is_callable() report them as missing, and extension syntax in a fragment is a runtime parse error. Fragments are never rejected at compile time: PHP only fails eval'd code when it actually executes, and strict mode preserves that. User functions that shadow extension names remain callable from eval'd code.

--strict-php cannot be combined with --define: defines only feed the ifdef extension, which strict mode rejects.

Strict mode guarantees that the constructs used are PHP-compatible; it does not change elephc's static-subset semantics. A strict-valid program can still be rejected by the type checker in places where the PHP interpreter would run it.

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=