Logo F# Compiler Guide

Coding standards and idioms

The F# compiler code base is slowly being updated to better coding standards. There is a long way to go.

The future work includes

Abbreviations

The compiler codebase uses various abbreviations. Here are some of the most common ones.

Abbreviation

Meaning

ad

Accessor domain, meaning the permissions the accessing code has to access other constructs

amap

Assembly map, saying how to map IL references to F# CCUs

arg

Argument (parameter)

argty

Argument (parameter) type

arginfo

Argument (parameter) metadata

boxity

IL boxity (ILBoxity = AsObject \| AsValue), the IL-level marker distinguishing the reference (boxed) and value-type forms of a type

ccont

Cancellation continuation in the Async CPS model: OperationCanceledException -> AsyncReturn, invoked when an async computation is cancelled

ccu

Reference to a compilation unit (CcuThunk): any referenced assembly (F# or otherwise; CcuData.IsFSharp distinguishes), possibly the assembly currently being compiled

celem

Custom attribute element

cenv

Compilation environment. Means different things in different contexts, but usually a parameter for a single compilation state object being passed through a set of related functions in a single phase. The compilation state is often mutable.

cgbuf

Code-generation buffer (CodeGenBuffer): the mutable buffer accumulating IL instructions, locals, exception clauses and sequence points for one method body in IlxGen

cloc

Compile location (CompileLocation): IL scope + top-level impl name + namespace + enclosing-type path (+ source-file qualified name and range) used to place a generated IL entity

cloinfo

IL closure information (IlxClosureInfo): the IlxGen descriptor for an emitted F# closure (free variables, formal signature, IL type)

cont

Continuation. In FSharp.Core async, the success continuation cont<'T> = 'T -> AsyncReturn (async.fs). In compiler lowering passes (LowerCalls, LowerComputedCollections, LowerStateMachines), the conventional name for a generic CPS-style callback (typically Expr -> Expr / Expr -> Expr option)

cpath

Compilation path (CompilationPath = CompPath of ILScopeRef * SyntaxAccess * (string * ModuleOrNamespaceKind) list): the IL scope + access + enclosing module/namespace path (the A.B.C container) for a type or module definition

css

Constraint solver state.

ctok

Compilation thread token (CompilationThreadToken): a phantom token witnessing that code runs on the single compilation thread; gates access to the (partially mutable) TAST/TcImports data, type-provider resolution and SourceCodeServices/IncrementalBuild caches

ctxt

Context (spelled ctxt rather than the more common ctx): in ilread.fs this is an ILMetadataReader threaded through the seekRead* helpers when parsing .NET metadata; elsewhere it can be a different context type (e.g. ExecutionContext in IlxGen.LookupGeneratedValue)

csenv

Constraint solver environment (ConstraintSolverEnv): the per-call solver context (range, equivalence env, display env, suspicion/trace state). Threaded through every Solve*/Add* helper in ConstraintSolver.fs; distinct from the mutable css (ConstraintSolverState)

cuspec

Compiled-union spec (IlxUnionSpec): the IL-level descriptor of a discriminated union (type ref, generic args, cases) used by EraseUnions

denv

Display Environment. Parameters guiding the formatting of types

dtree

Decision tree (DecisionTree, with cases TDSwitch/TDSuccess/TDBind): the compiled pattern-match tree, carried as the decision field of Expr.Match

einfo

An info object for an event (whether a .NET event, an F# event or a provided event)

e

Expression

econt

Exception continuation in the Async CPS model: ExceptionDispatchInfo -> AsyncReturn, invoked when an async computation faults

eenv

IlxGen emit environment (IlxGenEnv): the threaded code-generation context carrying ValStorage mappings (valsInScope), witnesses-in-scope, type-parameter representation env (tyenv), CompileLocation (cloc), live-locals set and IL-emit flags during IL emission

emenv

Reflection.Emit / dynamic-assembly emit env (ILDynamicAssemblyEmitEnv, in code spelled emEnv): maps compiler IL refs to live System.Reflection.Emit types/methods/fields (used by FSI dynamic codegen)

env

Environment. Means different things in different contexts, but usually immutable state being passed and adjusted through a set of related functions in a single phase.

eref

Entity reference (EntityRef): a reference to a TypedTree Entity (Tycon/Module). Common bindings: let eref = ERefNonLocalPreResolved … (IlxGen), (eref: EntityRef) parameters in TypedTree helpers, the Parent eref case of ParentRef

fdef

IL field definition (ILFieldDef); also commonly spelled fd in AbstractIL helpers — these are synonyms

finfo

An info object for a field (whether a .NET field or a provided field)

fref

A reference to an ILFieldRef Abstract IL node for a field reference. Would normally be modernized to ilFieldRef

fspec

Field spec — usually an ILFieldSpec in IL emit/read code, also a RecdField (record/class field declaration) in TypedTree code paths. These are distinct types, not synonyms — the name collision is historical

fvs

Free variables (FreeVars): the structured record of variables/typars free in an expression (computed by freeInExpr/accFreevars*), used by DetupleArgs, closure conversion and InnerLambdasToTopLevelFuncs

g

The TcGlobals value

hier

Visual Studio hierarchy (IVsHierarchy): the VS shell projection of a project tree (project nodes + items)

id

Identifier

ilg

IL globals (ILGlobals): cached well-known IL types/primitives (typ_Object, typ_Int32, …); the AbsIL counterpart of TcGlobals, usually reached as g.ilg

itemid

Visual Studio item id (VSITEMID, a uint32) identifying a node within an IVsHierarchy, with sentinels VSITEMID_ROOT/_NIL/_SELECTION

lid

Long Identifier (LongIdent = Ident list); SyntaxTree DU fields conventionally use the full-form synonym longId

m

A source code range (file-and-position span). Not to be confused with Mark, the IL code-label type in IlxGen

mdef

Usually an IL method definition (ILMethodDef) being emitted, also frequently spelled md — these are synonyms. In some IlxGen module walks mdef is also a module body (ModuleOrNamespaceContents/ILModuleDef) — distinct types

mgbuf

Module/assembly generation buffer (the IlxGen AssemblyBuilder): collects type defs, method defs, anonymous-record types and resources for the whole assembly being emitted

mimpl

In IL emit/morph code, an ILMethodImplDef (an explicit method-implementation override, often for an interface). In the Symbols layer (Symbols/Exprs.fs), the parameter name for a CheckedImplFile (a typed implementation file). These are distinct types, not synonyms

minfo

An info object for a method (whether a .NET method, an F# method or a provided method)

minst

Method instantiation — in TypedTree code a TypeInst (TType list) of method type arguments (the per-method analogue of tinst); in AbstractIL method specs an ILGenericArgs

mk

Means make in old fashioned F#/OCaml coding style

modref

Module or namespace reference — usually ModuleOrNamespaceRef (an alias for EntityRef, the parallel of tcref/vref); in AbstractIL ILScopeRef.Module patterns it is an ILModuleRef

modul

In TypedTree contexts a ModuleOrNamespace (the typed structure for a namespace or F# module). In AbstractIL contexts (ilread/ilwrite/ilprint/ilmorph/ilreflect), the same name is used for an ILModuleDef (the IL/CLI module being read or emitted; also spelled ilModule). These are distinct types, not synonyms

mref

IL method reference (ILMethodRef): the IL-level identity of an uninstantiated method (declaring type ref, calling convention, name, generic arity, argument types, return type)

mspec

Usually an ILMethodSpec (IL-level descriptor of an instantiated method) in IL emit code; also ModuleOrNamespace in TypedTree module-binding code (ModuleOrNamespaceBinding.Module(mspec, …)) and related IlxGen module-location helpers. These are distinct types, not synonyms

mty

Module type (ModuleOrNamespaceType, also spelled mtyp — these are synonyms): the signature/contents (sub-modules, types, vals) of a module or namespace — used both for the type-checked contents of an implementation and for the declared contents of a signature

ncenv

Name resolver (NameResolver): the cenv-style state object (globals/amap/infoReader) threaded through name resolution

nenv

Name resolution environment (NameResolutionEnv): the in-scope name → Item lookup tables active at a program point

nleref

Non-local entity reference (NonLocalEntityRef of CcuThunk * string[]): an in-memory path-indexed reference into the namespace/module structure of a CCU (often another assembly, but possibly the CCU being compiled)

nlr

Non-local reference — usually NonLocalEntityRef (as the nlr field of EntityRef), occasionally NonLocalValOrMemberRef (the nlr field of ValRef). Distinct types, not synonyms — different reference layers

pat

Pattern, a syntactic AST node representing part of a pattern in a pattern match

pc

Program counter — the int state label allocated per resumption point in LowerSequences/LowerStateMachines

penv

Pass environment — a pass-local cenv-style record threaded through an Optimizer pass (e.g. penv in DetupleArgs.fs, RewriteContext in InnerLambdasToTopLevelFuncs.fs)

pinfo

An info object for a property (whether a .NET property, an F# property or a provided property)

plid

Partial long identifier (a string list): the dotted prefix typed so far during IDE completion (the "Foo.Bar." path)

q

In FSharp.Core (Linq.fs, Query.fs, query/quotation transforms), an F# quotation value (Quotations.Expr or Quotations.Expr<'T>) being inspected or transformed; occasionally a parser/matcher function in quotation helpers

rdt

Running Document Table (IVsRunningDocumentTable): the Visual Studio service that tracks all open documents and their buffers

reqdty

Required type (reqdTy, a TType): the expected/target type flowed into expression type checking

rfinfo

Record/class field info (RecdFieldInfo): an rfref together with the enclosing type's instantiation (i.e. a field viewed through a concrete type)

rfref

Record or class field reference, a reference to a Typed Tree node for a record or class field

scoref

Scope reference (ILScopeRef) for an IL metadata reference: Local, Module of ILModuleRef, Assembly of ILAssemblyRef, or PrimaryAssembly

sm

Resumable state machine (a byref<ResumableStateMachine<_>>) passed through CE builder methods, tasks and resumable code; also byref<TaskStateMachine<_>> in task-specific paths

sp

Sequence points or debug points

spat

Simple Pattern, a syntactic AST node representing part of a pattern in a pattern match

tau

A type with the "forall" nodes stripped off (i.e. the nodes which represent generic type parameters). Comes from the notation 𝛕 used in type theory

tcaug

Type constructor augmentation (TyconAugmentation, accessed via tcref.TypeContents): the mutable bag of interfaces, members and compiler-synthesized overrides (Compare/Equals/Hash) added to a Tycon

tcref

Type constructor reference (TyconRef, an alias for EntityRef; long-form synonym tyconRef is also used): the parallel of modref/vref/eref for class/record/union/exception/abbreviation/measure type constructors

tdef

IL type definition (ILTypeDef); also commonly spelled td in AbstractIL helpers — these are synonyms

tinst

Type instantiation

tpenv

Type parameter environment, tracks the type parameters in scope during type checking

tps

Type parameter list (Typars = Typar list; long-form synonym typars is also used): the typars paired with tau in TType_forall(tps, tau) / Expr.TyChoose(tps, …)

tpsorig

Original typars (spelled tpsorig in code, a Typar list): the user-written typars before freshening/renaming, paired with the copied set (tps)

traitinfo

Trait constraint info (TraitConstraintInfo, spelled traitInfo): the SRTP "method-like" constraint (support types, name, argument types, return type)

tref

IL type reference (ILTypeRef): Scope (ILScopeRef) + Enclosing (string list of enclosing type names) + Name. For non-nested types the namespace is encoded in Name; nested types use Enclosing

ty (not: typ)

Type, usually a Typed Tree type

tycon

Type constructor (Tycon, an alias for Entity): a type or exception definition (class/record/union/abbreviation/exception/measure) in the TypedTree; tcref.Deref returns one. Modules and namespaces use the parallel alias ModuleOrNamespace

typar

Type Parameter

tys (not: typs)

List of types, usually Typed Tree types

tyvar

Type Variable, usually referring to an IL type variable, the compiled form of an F# type parameter

ucref

Union case reference, a reference to a Typed Tree node for a union case

vinfo

Value info — in the Optimizer, the abstract value of an expression: ExprValueInfo (the DU with cases UnknownValue/SizeValue/ValValue/TupleValue/RecdValue/UnionCaseValue/ConstValue/CurriedLambdaValue/…) or the per-binding wrapper ValInfo (ValMakesNoCriticalTailcalls + ValExprInfo). Distinct types, not synonymsValInfo wraps an ExprValueInfo

vref

Value reference (ValRef; long-form synonym valRef is also used): a reference to a Typed Tree node for a value

vspec

Val "spec" — a Val (the underlying definition behind a vref, typically obtained via vref.Deref). Often shortened to just v in tight scopes

Phase Abbreviation

Meaning

Syn

Abstract Syntax Tree

Tc

Type-checker

IL

Abstract IL = F# representation of .NET IL

Ilx

Extended Abstract IL = .NET IL plus a couple of constructs that get erased

Type something to start searching.