Program Structure

Compilation Inputs

Project compilation through the Clef Compiler Service (CCS) and Composer uses the following inputs:

• Implementation files, with extension .clef. These conform to grammar element implementation-file in § Implementation Files.
• Library dependencies specified in the project file (.fidproj) and resolved at compile time from source packages or pre-compiled native libraries.
• Compiler directives such as #nowarn.

Clef scripts use the .clefx extension and the clefx interactive CLI, as specified in Interactive Development.

NORMATIVE: Clef does not recognize separate signature files, including F# .fsi files. Module signatures, when present, are declared inline within the implementation file using signature ... end blocks (see §).

The FIDELITY compilation symbol is defined for input that CCS has processed.

Compilation Pipeline

CCS processes source files through the following pipeline:

1. Decoding. Each file is decoded into a stream of UTF-8 Unicode characters.

2. Tokenization. The character stream is broken into a token stream by the lexical analysis described in § Lexical Analysis.

3. Lexical Filtering. The token stream is filtered by the offside-rule state machine described in § Lexical Filtering. Indentation determines structure.

4. Parsing. The augmented token stream is parsed according to the grammar specification in this document.

5. Dependency Analysis. Before type checking, CCS performs a syntactic dependency-analysis pass over all parsed files: it builds an export map of declared names per file, resolves cross-file identifier references against that map, and computes strongly-connected components of the file-level reference graph. The result is a topological order of compilation units, where each unit is either a single file or a mutually-recursive group of files.

   NORMATIVE: CCS SHALL compute compilation order by syntactic dependency analysis. Source files MAY be presented to the compiler in any order; the developer SHALL NOT need to declare file order.

6. Importing. Library dependencies are resolved from source packages or pre-compiled native libraries and added to the initial name resolution environment (§ Name Resolution).

   Clef Note: Clef does not use CLI assemblies. Type providers are not available in native compilation.

7. Checking. The dependency-ordered compilation units are type-checked. Checking involves Name Resolution, Constraint Solving (§ Generalization), and Generalization, as well as the application of other rules described in this specification. After processing of all compilation units is complete, all type-inference variables have been either generalized or resolved.

8. Elaboration. One result of checking is an elaborated program graph that contains elaborated declarations, expressions, and types. The elaborated graph is the Program Semantic Graph (PSG, §) handed to downstream stages of the Composer pipeline for native code generation.

   Clef Note: Clef does not support runtime reflection. Elaborated forms are used for native code generation, not CLI metadata emission.

9. Execution. The native AOT pathway produces a binary whose static initializers run at startup in topological dependency order (§ Program Execution). Native interactive execution uses the same semantic and lowering contracts before LLVM JIT invocation (§ Execution Model).