Inlining in the compiler: current state and proposed changes #8733

"Inlining" in the compiler covers four different features that share one attribute name (@inline). They move through the pipeline in different ways and are stored in different build files. This issue describes how each works today, lists the problems found, and proposes what to change, as context for #8689 and the @inline item in #8624.

TL;DR

Feature A is handled by a frontend rewrite rather than a real AST node. Feature D has a correctness bug in incremental builds. #8689 extends D with an explicit opt-in. Before extending it, we should agree on the model.

1. How the pipeline works today

A. Inline constants (@inline let / @inline(lit) let)

1. Parser: @inline is kept as a plain attribute. In an implementation the value is the right-hand side (@inline let x = 1). In an interface it's the attribute payload (@inline(1) let x: int).
2. Frontend rewrite (compiler/frontend/bs_builtin_ppx.ml, signature_item_mapper and structure_item_mapper):
   • When the expression is a literal, the binding is rewritten into an external-like declaration (Pstr_primitive / Psig_value) with pval_prim = Some (Prim_inline_const c).
   • The implementation side gets a made-up type annotation (Ast_literal.type_int etc.).
   • pval_attributes is set to [].
   • There are two hand-written copies of this logic, one per side, with about five branches each.
3. Type checker: Primitive.parse_declaration turns Prim_inline_const c into Val_prim {prim_kind = Kind_inline_const c}.
4. Translation: translcore (transl_external_application) replaces each use with Lconst (lambda_of_inline_const c).
5. Build files:
   • .cmi: the constant itself, inside the value's Val_prim primitive description. Any change to the value changes the .cmi, so dependents are rebuilt correctly.
   • JS: nothing. A primitive doesn't produce a JS binding, so @inline constants are not exported from the generated module (for example, tests/tests/src/inline_const.mjs doesn't export f, f1, f5, f6). JS or genType consumers can't import them.
6. Interface matching: Primitive.coercible requires the same kind. An interface @inline(1) let x: int can only be satisfied by an @inline implementation with the same value. A plain let x = 1 doesn't match it, while an @inline implementation can be hidden behind a plain let x: int. It then gets a normal JS binding, and dependents use A.x instead of the constant: for A, the .resi decides what is inlined.

B. Externals

These follow the same path as A, with Prim_ffi → Kind_external spec. The full FFI spec is stored in the .cmi, so every call site emits the JS call directly.

Exception: when an external's module path is package-relative (@module("./foo")), Ast_external_process sets no_inline_cross_module. The interface then gets a plain val, and the implementation is wrapped in include (… : sig val … end). Other modules call through an ordinary exported binding, because the relative path only works from the declaring file.

C. Function inlining inside one module

• Attributes: Translattribute reads @inline / @inline(always) / @inline(never) on a function expression or binding and stores it as Lfunction.attr.inline (Always_inline | Never_inline | Default_inline). @inline on anything that isn't a function gives warning 53 ("misplaced attribute").
• Optimizer: Lam_pass_remove_alias does the beta reduction (substituting the arguments into the function body). Lam_analysis.ok_to_inline_fun_when_app decides when:
  • Always_inline → always inline; Never_inline → never.
  • Default_inline → inline when the body size is under 5 (small_inline_size), when the call can be resolved statically via destruct_pattern, or when all arguments are constants, the size is under 10, and the body has no side effects.
  • Async functions and functions with a directive are never inlined (lfunction_can_be_inlined).

D. Cross-module inlining via .cmj

Export (Lam_stats_export.values_of_export). For each exported value, the .cmj stores {name; arity; persistent_closed_lambda}, where the last field is a Lambda term (the compiler's intermediate representation) that callers can copy:

• true / false / null / undefined constants are always exported, whatever the flags.

• Everything else is only exported when -bs-cross-module-opt is set (off by default; can be set through compiler-flags). Even then, only values that pass safe_to_inline are exported:

  • functions;
  • constant constructors and polymorphic variants, booleans, undefined.

  Ints and strings are never exported. Functions qualify under one of two rules:

  • @inline functions and functors: exported only when closed (Lam_closure.is_closed), i.e. they don't capture any surrounding local values.
  • Other functions: exported when the size is under 5 and there are no free variables.

• Js_cmj_format.get_result filters again when the .cmj is read: unless the flag is set, everything except the four constants is dropped.

• None of this depends on the interface. With an A.resi declaring let flag: bool, dependents still get true copied in. The .resi only decides which values are exported; their stored bodies come from the implementation. The same holds for functions under -bs-cross-module-opt.

Use. Lam_compile_env.query_external_id_info looks up the other module's .cmj entry:

• Lam_pass_remove_alias beta-reduces A.f(args) with the stored body.
• Lam_compile.compile_external_field emits stored non-function constants directly.
• compile_external_field_apply inlines stored functions during code generation.

Format. The .cmj is a 16-byte digest header followed by the marshalled data. to_file ~check_exists skips rewriting the file when its content is unchanged.

Observed with a two-module rewatch project (B uses A's values):

• With no flags, let flag = true in A is copied into B as let f = true. let num = 1 and all functions are referenced as A.num / A.g(3), even @inline let g = ….
• With -bs-cross-module-opt, both @inline let g = x => x + 1 and the unannotated let h = x => x * 2 were inlined (let a = 4; let b = 6).

Summary: what each build file stores

2. Problems

2.1 Stale JS after incremental builds (bug on master)

A dependent copies values from A's .cmj, but rewatch only checks A's .cmi.

Repro 1 (no flags):

// A.res
let flag =  true   // two spaces, so the edit below keeps every location
let num = 2

// B.res
let f = A.flag

Build, then change A to let flag = false and build again. Only A is recompiled. A's .cmi is byte-identical, A.mjs has let flag = false, but B.mjs still has let f = true.

Repro 2 ("compiler-flags": ["-bs-cross-module-opt"]):

// A.res
let h = x => x * 2

// B.res
let b = A.h(3)

Build, then change the body to x * 3. Only A is recompiled, and B.mjs still has let b = 6.

Repro 3 (any module with a .resi, no flags):

// A.resi
let flag: bool

// A.res
let flag = true

// B.res
let f = A.flag

Build, then change A.res to let flag = false. A.cmi is built from the .resi alone, so it stays byte-identical even when every line of A.res moves. B is never rebuilt and keeps let f = true.

For modules without an interface, the bug is mostly hidden in practice because the .cmi stores declaration locations, so most edits shift something and trigger the rebuild by accident. Modules with a .resi don't have this safety net: every change of such a value leaves dependents stale. #8689's .cmj digest check fixes this as a side effect.

2.2 @inline means three things

@inline is a signature-level constant (A), an optimization hint (C), and with #8689 an opt-in for cross-module inlining (D). Which one applies depends on whether the right-hand side is a literal, which is easy to get wrong. For example, @inline let x: int = 3 silently becomes an ordinary value with warning 53.

2.3 Inline constants are a frontend rewrite, not part of the AST

Also tracked in #8624.

• Implementations and interfaces disagree. Interfaces accept bigint; implementations don't. So @inline(12n) let x: bigint in an interface can't be implemented.
• A type annotation disables inlining.
• Other attributes on the binding are dropped (pval_attributes = []).
• The frontend makes up a type annotation instead of letting the type checker compute the literal's type.
• Prim_inline_const lives in the parsetree only to carry the result of the rewrite.
• (The inverted bigint sign in this encoding was fixed in Fix the sign of @inline bigint constants #8732.)

2.4 @inline constants are missing from the JS output

That's expected for externals, but surprising for something written as let, and it limits interop.

2.5 @inline on a function does nothing across modules by default

Without the global flag nothing is exported to .cmj. The global flag, meanwhile, inlines every small closed function, opted-in or not.

2.6 The global -bs-cross-module-opt flag isn't a clear contract

It applies per compiler invocation, its export rules are an internal heuristic (size < 5), and nothing documents it. #8689 makes cross-module inlining an explicit per-function choice, which would make the global flag largely redundant.

2.7 The .cmj constants bypass the interface

true/false/null/undefined values are copied into dependents even when the .resi only promises a type, so let flag: bool in an interface doesn't keep the value abstract. It's also always on: no attribute or flag enables or disables it. @inline(value) in a .resi is the explicit, interface-level way to do the same thing.

3. Related work

• Add opt-in cross-module inlining for Option helpers #8689 (open): adds @inline(crossModule) → Cross_module_inline.
  • The body is exported to .cmj regardless of the flag (it must be closed, not async, and have no directive) and is always inlined at call sites.
  • Rewatch also rebuilds dependents when the .cmj digest changes.
  • Applied to Option.map, flatMap, getOr, etc. in the stdlib.
• Stamp parsetree v1: what remains before the AST can be frozen for PPXs #8624 (parsetree v1): lists "@inline constants: give them a structural form".
• Fix the sign of @inline bigint constants #8732 (merged): fixed the inverted bigint sign in inline constants.
• Resolve FFI externals during type checking #8728 (open): removes Prim_inline_const from the parsetree by resolving externals during type checking. Inline constants become external x: T = "#rescript-inline" with the @inline(<literal>) attribute kept, which overlaps with proposal 2.

4. Proposals

1. Fix stale dependents independently of Add opt-in cross-module inlining for Option helpers #8689. Rebuild dependents when the .cmj digest changes, which is the rewatch part of Add opt-in cross-module inlining for Option helpers #8689. Land it on its own, or first in the stack, since it fixes a bug that exists today. It also removes the need for the accidental "locations in .cmi" safety net.

2. Give inline constants a structural form (feature A):

   • primitive_repr = Prim_name of string | Prim_inline of inline_literal loc, using the literal's source spelling, the same pattern as the @as change.
   • The parser produces it for @inline(lit) let x: t and for @inline let x(: t)? = lit.
   • The type checker types the literal and builds Kind_inline_const.
   • The v0 bridge turns it back into the attribute for existing PPXs.
   • This removes the frontend rewrite and fixes the bigint, type-annotation and dropped-attribute problems.

3. Separate the meanings of @inline. Possible shape:

   • @inline on a literal binding = signature constant (A);
   • @inline / @inline(never) on a function = optimization hint (C);
   • cross-module opt-in (D) = Add opt-in cross-module inlining for Option helpers #8689's @inline(crossModule), or just "@inline on an exported function exports its body".

   The last option would make @inline mean the same thing inside and across modules. The open question is whether exporting bodies by default for every @inline function is acceptable, given the extra rebuilds.

4. Decide what happens to -bs-cross-module-opt. Once there's an explicit opt-in, either remove it or document it as "also export small closed functions automatically". For the bool/null/undefined constants that are always exported, either keep them, since proposal 1 makes them safe (though they still bypass the interface, see 2.7), or stop exporting them, at least when an interface hides the value, and leave interface-visible constants to @inline(value).

5. Decide whether @inline constants should be exported to JS (for example, also emit export const x = 1), so JS and genType consumers can use them.

5. Open questions

• Should cross-module inlining of functions be opt-in per function only, or also available as a project-wide setting?
• Is rebuilding dependents on any .cmj change acceptable? Add opt-in cross-module inlining for Option helpers #8689 notes that unrelated .cmj changes also trigger rebuilds, and stored Lambda bodies include locations.
• Should closed @inline functors keep their special export path?