Type not found during @:build macro expansion

Direct Answers

1. Order guarantee: No. The Haxe compiler does not guarantee that code generated by an @:build macro can see forward declarations later in the same file. Macro expansion runs during the typing phase before the rest of the module is fully typed, so generated code only sees types that have already been typed or imported.

2. Preserving generic instantiations: A macro must emit a real usage (field, variable, return type, or @:keep metadata) that the dead‑code eliminator (DCE) recognizes as live. Compiler.require alone does not preserve generic parameters; the generated AST must explicitly construct the TypeParameter instances and the type must be used in a way DCE cannot remove.

Why This Happens (Likely Explanation)

• @:build macros execute while the containing module is being typed. The typer processes the file top‑to‑bottom; types declared after the macro‑annotated class are not yet in the typing context.
• The compiler does not perform a second resolution pass for macro‑generated AST against later declarations in the same compilation unit. Forward references from generated code to types defined later in the same file typically fail with "Type not found".
• Compiler.require("TypeName") forces a type to be loaded in the current typing context. If the type is only referenced in generated code and not yet typed, require may trigger premature typing or crash if the required type transitively depends on the macro’s own output.
• Generic instantiations (e.g., Map<String, Int>) that appear only in macro‑generated expressions are stripped by DCE unless they are part of a retained declaration.

Confirmed Workarounds

1. Split the forward‑referenced type into a separate module that is imported before the @:build macro runs. This moves the type into an already‑typed context.
2. Use @:autoBuild on a helper class that runs after the target types exist, or move the macro to a different compilation unit.
3. Preserve generics: In the generated AST, create a concrete usage (e.g., a private field of the generic type) and annotate the generated class with @:keep if DCE might otherwise remove it.
4. Avoid Compiler.require for same‑file forward refs; it cannot see types that haven’t been typed yet.

Version Assumptions

Behavior described applies to Haxe 4.0 and later. Earlier versions had stricter macro typing order limitations. The DCE behavior is target‑agnostic but most visible on --js and --cpp outputs.

One Diagnostic Detail Needed

What Haxe version and target platform are you compiling for? The exact typing order and DCE aggressiveness can vary between versions (e.g., 4.2 vs 4.3) and targets, which may change whether a workaround like @:keep is sufficient or if a separate module is required.