erlc

Compilation can be stopped at intermediate stages to inspect output:

to_core

produces foo.core (Core Erlang).

'P'

produces foo.P (post-preprocessing source).

'E'

produces foo.E (post all source transformations).

'S'

produces foo.S (human-readable BEAM assembly).

Combined with binary, these return the internal Erlang-term representation instead of writing a file (e.g. [to_core, binary]), which can be pretty-printed (e.g. with core_pp:format/1).

• Compilation can also resume from an intermediate stage, e.g. erlc foo.core or c(foo, [from_core]), or by passing terms straight back into compile:forms/2.
• A compiled binary can be loaded directly with code:load_binary(Mod, Path, Bin), without ever touching disk.

Walks through compiling an example module (world.erl, using an included macro) at each stage:

• 'P' output shows the code after preprocessing (macros/includes expanded, -file annotations inserted).
• 'E' output shows code after all source-level transforms: records expanded, imports resolved to remote calls, and generated module_info/0,1 functions added.
• 'S' output shows final BEAM assembly as Erlang terms — module name, version, exports, attributes, label count, and per-function instructions (func_info, move, return, call_ext_only, etc.). This .S file can be read back with file:consult/1 and is very useful for understanding what the VM actually does with your code.

The compilation starts with tokenization (or scanning) and preprocessing. The preprocessor epp reads a file and calls the tokenizer erl_scan to expand the text into a sequence of separate tokens rather than characters, discarding whitespace and comments. It then processes macro definitions and conditional compilation directives, and substitutes uses of macros.

(Stenman 2025, chap. 2 part.2.4.1)

• Works at the token level (like C's cpp), not raw text (unlike m4), so macros can't create arbitrary custom syntax.

The parser erl_parse gets the final token sequence from the preprocessor and checks it against the Erlang grammar, producing an abstract syntax tree or AST (…) representing the programas a data structure instead of as a sequential text.

(Stenman 2025, chap. 2 part.2.4.2)

A parse transform is a function that works on the AST. After the compiler has done the initial tokenization, preprocessing and parsing, and assuming there were no errors so far, it will call the parse transform function if one has been declared, passing it the current AST and expecting to get a modified AST back.

(Stenman 2025, chap. 2 part.2.4.3)

• User-supplied functions (Mod:parse_transform/2) that rewrite the AST after parsing but before linting.
• Declared via -compile({parse_transform, Mod}), multiple transforms run in order.
• Can't change Erlang's surface syntax, but can change semantics arbitrarily. Used by MNESIA's QLC, EUnit, Merl, etc.

• The main correctness/style checking pass (undefined vars/functions, suspicious code like export_all), parse transforms must produce output the linter accepts.

• If debug_info is requested, the (pre-optimization) AST is stored in the .beam file for debugging/stepping.
• Since it's saved before optimizations, interpreted debug behavior can diverge from compiled/optimized behavior.

• Lowers source-level constructs:
  • Records become tuple ops.
  • Imports become explicit remote calls.
  • Adds module_info/1,2.

Core Erlang is a strict functional language suitable for compiler optimizations. It makes code transformations easier by reducing the number of ways to express the same operation. One way it does this is by introducing let and letrec expressions to make scoping more explicit. The compiler does several passes on the core level.

Core Erlang can be a good target for a language you want to run in ERTS. It changes very seldom and it contains all aspects of Erlang in a clean way. If you target the BEAM instruction set directly, you will have to deal with many more details, and that instruction set usually changes slightly between each major release of ERTS. If you on the other hand target Erlang directly you will be more restricted in what you can describe, and you may also have to deal with more details, since Core Erlang is a cleaner language.

(Stenman 2025, chap. 2 part.2.4.7)

• Accessible via to_core / from_core.

1> c(world, to_core).
2> c(world, from_core).

• A flattened form of Core Erlang (unique variable names, function-wide scope, pattern matching lowered to primitives), format is internal/unstable.

• Final generic instruction sequence as Erlang terms.
• Dead-code elimination and peephole optimizations happen here.

• Assembly is packed into the binary .beam transport format (loadable from file, network, or memory).

• Syntax Tools is a library set for manipulating Erlang ASTs.
• Merl, included in Syntax Tools, is a metaprogramming utility that makes it much easier to construct/match ASTs and write parse transforms than doing it by hand.

• Elixir is another front end targeting the BEAM: it compiles down through the Erlang abstract syntax tree.
• Elixir's defmacro facility lets users build their own DSLs directly in Elixir, analogous to Erlang parse transforms but built into the language.