Output formats and diagnostics

By default elephc produces a native executable. These flags change the output artifact or stop the pipeline early to inspect an intermediate stage, plus the diagnostics that instrument a compile or the resulting program.

Output artifacts

--emit

Selects the kind of artifact to produce.

elephc --emit executable app.php   # default: a native binary
elephc --emit cdylib lib.php       # a C-ABI shared library
elephc --emit staticlib lib.php    # a C-ABI static archive

Accepted values and aliases:

Value	Aliases	Produces
executable	exe, bin	A standalone native binary.
cdylib	dylib, shared	A C-ABI shared library (.dylib/.so).
staticlib	static, lib	A C-ABI static archive (.a).

The inline forms such as --emit=cdylib also work. --emit lib is an alias of staticlib, not cdylib. Both library kinds emit the same C-ABI exports and generated header; see Shared Libraries (cdylib) for the boundary contract and the static-linking distinction.

--emit-asm

Writes the generated assembly next to the source instead of assembling and linking a binary. Useful for inspecting exactly what the backend produced.

elephc --emit-asm hello.php

--emit-ir

Prints the EIR (elephc’s intermediate representation) textual form to stdout and stops before code generation. Because it runs after the EIR optimization passes, it reflects the optimized IR; combine with --no-ir-opt to see the unoptimized form.

elephc --emit-ir hello.php
elephc --emit-ir --no-ir-opt hello.php

See The EIR Design for how to read the output.

--check

Runs lexing, parsing, name resolution, and type checking, then reports errors and warnings without writing assembly or a binary. When the source contains #[Export], it additionally lowers EIR and runs the cdylib call-graph safety validator, so --check cannot report a false success for a library whose export reaches a fatal or opaque path.

elephc --check hello.php

--emit-ir, --emit-asm, and --check are mutually exclusive.

--source-map

Emits a .map sidecar file next to the generated assembly, mapping assembly back to PHP source positions. The sidecar is a versioned JSON document with function ranges, assembly labels, opcode-tagged line mappings, and a PHP-line inverse index — see Source maps for the schema contract.

elephc --emit-asm --source-map hello.php

--debug-info

Embeds DWARF debug information in the generated assembly — a line table and one DW_TAG_subprogram per PHP function, derived from the same source markers that drive --source-map. Standard debuggers (lldb, gdb) and profilers then map compiled code back to PHP lines without any custom tooling. On macOS a .dSYM bundle is produced next to the binary:

elephc --debug-info hello.php
lldb ./hello   # breakpoints and backtraces resolve to hello.php lines

--debug-info and --source-map compose: the first serves standard DWARF consumers, the second serves tools that want the richer JSON schema.

Compile-time diagnostics

On an interactive terminal, each compilation phase starts as a spinner. When the phase finishes, elephc keeps its action-oriented label with a checkmark and elapsed time, then starts the next phase on a new line. Non-interactive output and --quiet keep the compact plain output without progress lines.

--quiet / -q

Disables live and completed progress lines and forces unstyled plain output. It does not suppress compiler errors, warnings, or the final success line. Timing tables requested with --timings still print, using ASCII borders.

elephc --quiet hello.php

--timings

Prints a bordered timing table to stderr in addition to the interactive completed-phase lines. It uses friendly phase labels, adaptive millisecond or second durations, percentage shares, and a total row. Interactive terminals use Unicode box drawing; non-interactive output and --quiet use ASCII borders without styling.

elephc --timings hello.php

Compiler timings
┌────────────────────────────────┬───────────┬────────┐
│ Phase                          │  Duration │  Share │
├────────────────────────────────┼───────────┼────────┤
│ Reading source                 │   0.54 ms │   0.0% │
│ Checking types                 │ 155.70 ms │   1.4% │
│ ...                            │       ... │    ... │
│ Optimizing EIR                 │    2.78 s │  25.1% │
│ Generating native code         │    6.66 s │  60.1% │
├────────────────────────────────┼───────────┼────────┤
│ Total                          │   11.08 s │ 100.0% │
└────────────────────────────────┴───────────┴────────┘

--mascotte

Prints elephc’s built-in ASCII mascot and one randomly selected quote before normal help, diagnostic, or compilation output.

elephc --mascotte hello.php

Runtime diagnostics

These flags instrument the compiled program, not the compiler.

--gc-stats

Compiles the program so it prints allocation and free counters to stderr when it exits — useful when debugging reference-counting and ownership behavior.

elephc --gc-stats heavy.php
./heavy

Combined with --web, the server never reaches the process-exit report, so the counters are printed to stderr after every handled request instead. In default worker isolation, a growing allocs - frees gap across requests handled by the same worker indicates a per-request leak. In pool, the counters belong to each persistent handler child and lines from several children may interleave. In request, each disposable child exits after one response, so compare the single-request result rather than looking for a cross-request trend.

--heap-debug

Enables runtime heap verification in the compiled program: double-free detection, bad-refcount checks, and free-list corruption checks. Slower, but invaluable when chasing memory bugs.

elephc --heap-debug heavy.php
./heavy

See Memory Model and The Runtime for what these report on.