diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6dd66b82a6..fbc27d0ef1 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -48,6 +48,8 @@ Before submitting: `./build.sh -c Release --testcoreclr` .fs: implementation .fsi: declarations, API docs, context comments +Abbreviations (`ad`, `cenv`, `m`, `tcref`, `eenv`, `cgbuf`, `ncenv`, `tau`, …): see `docs/coding-standards.md` for the canonical glossary before guessing what a short identifier means. + ## Rules Public API change → update .fsi diff --git a/docs/coding-standards.md b/docs/coding-standards.md index 45056e91dc..aa0bb2e0b1 100644 --- a/docs/coding-standards.md +++ b/docs/coding-standards.md @@ -27,41 +27,90 @@ The compiler codebase uses various abbreviations. Here are some of the most comm | `arg` | Argument (parameter) | | `argty` | Argument (parameter) type | | `arginfo` | Argument (parameter) metadata | -| `ccu` | Reference to an F# compilation unit = an F# DLL (possibly including the DLL being compiled) | +| `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. | -| `cpath` | Compilation path, meaning A.B.C for the overall names containing a type or module definition | +| `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 | -| `lid` | Long Identifier | -| `m` | A source code range marker | -| `mimpl` | IL interface method implementation | +| `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 | -| `modul` | a Typed Tree structure for a namespace or F# module | +| `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` | The scope of a reference in IL metadata, either assembly, `.netmodule` or local | +| `scoref` | Scope reference (`ILScopeRef`) for an IL metadata reference: `Local`, `Module` of `ILModuleRef`, `Assembly` of `ILAssemblyRef`, or `PrimaryAssembly` | +| `sm` | Resumable state machine (a `byref>`) passed through CE builder methods, tasks and resumable code; also `byref>` 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 | -| `tcref` | Type constructor reference (an `EntityRef`) | +| `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 | -| `tys` (not: `typs`) | List of types, usually Typed Tree types | +| `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 | -| `vref` | Value reference, a reference to a Typed Tree node for a value | +| `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 synonyms** — `ValInfo` 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 | |:------------------------------|:-----------|