CLabel is an abstract type that supports the following operations:

• Pretty printing
• In a C file, does it need to be declared before use? (i.e. is it guaranteed to be already in scope in the places we need to refer to it?)
• If it needs to be declared, what type (code or data) should it be declared to have?
• Is it visible outside this object file or not?
• Is it "dynamic" (see details below)
• Eq and Ord, so that we can make sets of CLabels (currently only used in outputting C as far as I can tell, to avoid generating more than one declaration for any given label).
• Converting an info table label into an entry label.

CLabel usage is a bit messy in GHC as they are used in a number of different contexts:

• By the C-- AST to identify labels
• By the unregisterised C code generator ("PprC") for naming functions (hence the name CLabel)
• By the native and LLVM code generators to identify labels

For extra fun, each of these uses a slightly different subset of constructors (e.g. AsmTempLabel and AsmTempDerivedLabel are used only in the NCG and LLVM backends).

In general, we use IdLabel to represent Haskell things early in the pipeline. However, later optimization passes will often represent blocks they create with LocalBlockLabel where there is no obvious Name to hang off the label.

Indicate if GHC.CmmToC has to generate an extern declaration for the label (e.g. "extern StgWordArray(foo)"). The type is fixed to StgWordArray.

Symbols from the RTS don't need "extern" declarations because they are exposed via "rtsincludeStg.h" with the appropriate type. See needsCDecl.

The fixed StgWordArray type led to "conflicting types" issues with user provided Cmm files (not in the RTS) that declare data of another type (#15467 and test for #17920). Hence the Cmm parser considers that labels in data sections don't need the "extern" declaration (just add one explicitly if you need it).

See https://gitlab.haskell.org/ghc/ghc/-/wikis/commentary/compiler/backends/ppr-c#prototypes for why extern declaration are needed at all.

Record where a foreign label is stored.

Which module is the info table from, and which number was it.

Decides between external and local labels based on the names externality.

A label indicating the end of a procedure.

Construct a label for a DWARF Debug Information Entity (DIE) describing another symbol.

A standard string unpacking thunk. See Note [unpack_cstring closures] in StgStdThunks.cmm.

A standard string unpacking thunk. See Note [unpack_cstring closures] in StgStdThunks.cmm.

Make a foreign label

Info Table Provenance Entry See Note [Mapping Info Tables to Source Positions]

If a label is a local block label then return just its BlockId, otherwise Nothing.

Is a CLabel visible outside this object file or not? From the point of view of the code generator, a name is externally visible if it has to be declared as exported in the .o file's symbol table; that is, made non-static.

Check whether a label corresponds to a C function that has a prototype in a system header somewhere, or is built-in to the C compiler. For these labels we avoid generating our own C prototypes.

Does a CLabel need dynamic linkage?

When referring to data in code, we need to know whether that data resides in a DLL or not. [Win32 only.] labelDynamic returns True if the label is located in a DLL, be it a data reference or not.

Is a CLabel defined in the current module being compiled?

Sometimes we can optimise references within a compilation unit in ways that we couldn't for inter-module references. This provides a conservative estimate of whether a CLabel lives in the current module.

Whether label is points to some kind of info table

Whether label points to an info table defined in Cmm

Whether label is points to constructor info table

Whether label is a top-level string literal

Whether label is a non-haskell label (defined in C code)

Whether label is a .rodata label

Whether label is a static closure label (can come from haskell or cmm)

Generate a CmmProc delimiter label from the actual entry label.

This delimiter label might be the entry label itself, except when the entry label is a LocalBlockLabel. If we reused the entry label to delimit the proc, we would generate redundant labels (see #22792)

Style of label pretty-printing.

When we produce C sources or headers, we have to take into account that C compilers transform C labels when they convert them into symbols. For example, they can add prefixes (e.g., "_" on Darwin). So we provide two ways to pretty-print CLabels: C style or Asm style.

For debugging problems with the CLabel representation. We can't make a Show instance for CLabel because lots of its components don't have instances. The regular Outputable instance only shows the label name, and not its other info.

Generate a label for a procedure internal to a module (if Opt_ExposeAllSymbols is enabled). See Note [Internal proc labels].

This type encodes the subset of CLabel that occurs in C stubs of foreign declarations for the purpose of serializing to interface files.

See Note [Foreign stubs and TH bytecode linking]

Project the constructor ModuleLabel out of CLabel if it is an initializer or finalizer.

Inject a CStubLabel into a CLabel as a ModuleLabel.

A utility for renaming uniques in CLabels to produce deterministic object. Note that not all Uniques are mapped over. Only those that can be safely alpha renamed, e.g. uniques of local symbols, but not of external ones. See Note [Renaming uniques deterministically].