Documentation

The differences between various versions of the llvm textual AST.

This type encapsulates the ability to convert an object into Doc format. Using this abstraction allows for a consolidated representation of the declaration. Most pretty-printing for LLVM elements will have a Fmt a function signature for that element.

The value used to specify the LLVM major version. The LLVM text format (i.e. assembly code) changes with different versions of LLVM, so this value is used to select the version the output should be generated for.

At the current time, changes primarily occur when the LLVM major version changes, and this is expected to be the case going forward, so it is sufficient to reference the LLVM version by the single major version number. There is one exception and one possible future exception to this approach:

1. During LLVM v3, there were changes in 3.5, 3.6, 3.7, and 3.8. There are explicit ppLLVMnn function entry points for those versions, but in the event that a numerical value is needed, we note the serendipitous fact that prior to LLVM 4, there are exactly 4 versions we need to differentiate and can therefore assign the values of 0, 1, 2, and 3 to those versions (and we have no intention of supporting any other pre-4.0 versions at this point).
2. If at some future date, there are text format changes associated with a minor version, then the LLVM version designation here will need to be enhanced and made more sophisticated. At the present time, the likelihood of that is small enough that the current simple implementation is a benefit over a more complex mechanism that might not be needed.

This value should be updated when support is added for new LLVM versions; this is used for defaulting and otherwise reporting the maximum LLVM version known to be supported.

Helpers for specifying the LLVM versions prior to v4

Helpers for specifying the LLVM versions prior to v4

Helpers for specifying the LLVM versions prior to v4

Helpers for specifying the LLVM versions prior to v4

The LLVMPretty class has instances for most AST elements. It allows the conversion of an AST element (and its sub-elements) into a Doc assembly format by simply using the llvmPP method rather than needing to explicitly invoke the specific pretty-printing function for that element.

Pretty print a TargetTriple

Pretty print a data layout specification.

Pretty print a single layout specification.

Pretty-print the inline assembly block.

Pretty-print Global Attributes (usually associated with a global variable declaration). The first argument to ppGlobalAttrs indicates whether there is a value associated with this global declaration: a global declaration with a value should not be identified as "external" and "default" visibility, whereas one without a value may have those attributes.

Many of the pretty printing functions (based on Pretty) in this module are written for the monomorphized BlockLabel version of the AST objects, but some (those ending with a "tick" or single-quote) support the parameterized form.

When the parameterized label type is known to be BlockLabel, then ppLabel can be passed as this first argument to those pretty printing functions.

When the parameterized label type is not known (e.g. when implementing other libraries that utilize llvm-pretty), the library may need to invoke the pretty printer without passing an explicit label printer, and can instead use the following class as a constraint for an instance that will be resolved later.

For example:

data Something lab = Something { ..., val :: Value' lab, ... }

instance PrettyLabel lab => Pretty Something where
  pretty s = .... <> ppValue' ppLabel' <>

Note that the PrettyLabel class is very similar to the Pretty class, but unlike the latter's pretty method, the PrettyLabel returns the Fmt object that allows the pretty-printing to be affected by the implicit Config parameter; this aligns the PrettyLabel usage to the other pretty-printing functions in this module.

Note that the textual syntax changed in LLVM 10 (callbr was introduced in LLVM 9).

Print out the ty|fnty fnptrval portion of a call, callbr, or invoke instruction, where:

• ty is the return type.
• fnty is the overall function type.
• fnptrval is a pointer value, where the memory it points to is treated as a value of type fnty.

The LLVM Language Reference Manual indicates that either ty or fnty can be used, but in practice, ty is typically preferred unless the function type involves varargs. We adopt the same convention here.

See writeDISubprogram in the LLVM source, in the file AsmWriter.cpp

Note that the textual syntax changed in LLVM 7, as the retainedNodes field was called variables in previous LLVM versions.

This is an auxiliary pretty printer for showing just part of a module: the part corresponding to a specific source file and line in the source file (whereas ppModule or even ppDefine will show the *entire* module or definition/function). A range of lines can be displayed by iterative calls over multiple lines.

putStrLn $ ppLLVM llvmVlatest $ ppModuleAtLine "foo.c" 23 llvmModule

The above example shows all the lines in llvmModule that correspond to line 23 of the "foo.c" source file.

Build a variable-argument argument list.

Print a ValMd' value as a plain signed integer (Int64) if possible. If the ValMd' is not representable as an Int64, defer to ValMd' printing (if canFallBack is True) or print nothing (for when a ValMd is not a valid representation).

Print the size or offset of a type-related metadata node. This value can either be an integer literal (in which case the bare literal is printed), or in LLVM 21 or later, it can be a more complicated metadata expression (in which case the metadata is pretty-printed).

Throw an error if the ?config version is older than the given version. The String indicates which constructor is unavailable in the error message.

Throw an error if the ?config version is older than the given version. The String indicates which constructor is unavailable in the error message.