Inlining in the compiler: current state and proposed changes

[cknitt]

"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	How it's written	What it means	Stored in	Rewatch notices a change?
A	Inline constants	@inline let x = 1 / @inline(1) let x: int	Changes the interface: the value is part of the signature	.cmi	✅ (the .cmi changes)
B	Externals	external f: … = "…"	The FFI call is emitted directly at each call site	.cmi	✅
C	Function inlining inside one module	Automatic, or @inline / @inline(never) on a function	Optimization hint	Nowhere; happens during compilation	n/a
D	Cross-module value and function inlining	Automatic (true/false/null/undefined); functions only with -bs-cross-module-opt	Optimization	.cmj	❌ can go stale

Feature A is handled by a frontend rewrite rather than a real AST node. Feature D has a correctness bug in incremental builds. The call-site attribute @inlined is accepted but does nothing. #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.

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").
• Call sites: @inlined at a call site is parsed into Lapply.ap_inlined (translcore, translmod for functor application). However, no pass in compiler/core reads ap_inlined; its only use in lam_pass_remove_alias.ml is commented out. The attribute is checked and then ignored.
• 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.

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

File	Inlining-related contents	Rewatch rebuilds dependents when it changes?
.cmi	Types, plus Val_prim descriptions: the full FFI spec for externals (B) and the literal for @inline constants (A). Also declaration locations.	Yes. This is the only signal rewatch uses today: compile.rs sets is_clean from the .cmi digest alone.
.cmj	Per exported value: arity, plus an optional persistent_closed_lambda (D: always-exported bool/null/undefined constants, plus small or @inline closed functions under the flag). Also effect information and hoisted exports.	No on master. #8689 adds this.
.js	The generated code. @inline constants and externals produce no binding.	n/a

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.

It's mostly hidden in practice because the .cmi stores declaration locations, so most edits shift something and trigger the rebuild by accident. #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 @inlined at call sites does nothing

It's parsed into ap_inlined and then ignored.

2.6 @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.7 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.

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.

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". The bool/null/undefined constants that are always exported could stay, since proposal 1 makes them safe.

5. Remove or implement @inlined. It's currently parsed and ignored. Either delete it (with a deprecation warning) or make ok_to_inline_fun_when_app respect ap_inlined.

6. 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?