Repository navigation
Documentation: Clarify codegen environment rules for top-level const and function bindings #89
Description
Activity
- added 4 commits that reference this issue
on May 11, 2026 - added a commit that references this issue
on May 11, 2026 Resolved by PR #91 (merged as c392e49).
The SPEC.md changes:
- Section 2.1 (Program Structure):
top_levelproduction now listsconst_decl,extern_fn_decl, andextern_type_declalongsidefn_declso the grammar matches what the parser actually accepts after PR feat: typed-wasm xmod + Node backend + extern + VS Code (#35, #42) #90 landed extern support. - Section 2.9 (Constant Declarations): new EBNF and prose noting that const initializers must reduce to Wasm constant expressions, with a forward-reference to section 8 for the codegen environment encoding.
- Section 2.10 (Extern Declarations): new EBNF for
extern fn/extern type, with the runtime contract (extern fn →(import "env" "<name>" ...), extern type → no Wasm artifact). - Section 8 (Codegen Module Environment): new section documenting the
func_indices : (string * int) listtable. Positivek ≥ 0is a Wasm function index (defined functions or extern-imported functions); negativek < 0encodes-(global_idx + 1)for top-level constants. Includes per-casegen_declbehaviour forTopFn(defined),TopFnwithFnExternbody, andTopConst. Explicitly notes the call-siteExprApplookup currently emitscall kunconditionally — decoding the negative sentinel back toglobal.getis the implementation half tracked under Codegen.UnboundVariable for top-levelconstbindings (typecheck OK, compile fails) #73.
The companion
lib/codegen.mldoc-comment on thefunc_indicesfield was updated to mention bothTopFnpaths (defined and extern) and that insertion is in source declaration order.Note: PR #94 introduces a more detailed
docs/specs/codegen-environment.adocthat goes deeper on cross-module threading and non-WASM target behaviour. That landing will subsume the SPEC.md §8 content here; this issue is resolved at the level it asked for (clarify that both consts and fns must be present in the codegen environment, document the population rules).- Section 2.1 (Program Structure):
Describe the bug
Documentation needs to clarify that both top-level consts and fns must be present in the codegen environment. Current docs may only discuss top-level fns.
To Reproduce
Look for existing documentation on module environment in codegen.
Expected behavior
Section covering environment population rules for codegen makes explicit how top-level const and function bindings are represented and threaded.
Additional context
constbindings (typecheck OK, compile fails) #73.