Module Gccjit

Compilation Contexts

A context encapsulates the state of a compilation. You can set up options on it, add types, functions and code, using the API below.

Invoking Context.compile on it gives you a result, representing in-memory machine-code.

You can call Context.compile repeatedly on one context, giving multiple independent results.

Similarly, you can call Context.compile_to_file on a context to compile to disk.

Eventually you can call Context.release to clean up the context; any in-memory results created from it are still usable.

Fields

A field encapsulates a field within a struct; it is used when creating a struct type (using Struct.create). Fields cannot be shared between structs.

Structure Types

A struct_ encapsulates a struct type, either one that we have the layout for, or an opaque type.

You can model C struct types by creating struct_ and field instances, in either order:

• by creating the fields, then the structure. For example, to model:

  struct coord {double x; double y; };

  you could call:

  let field_x = Field.create ctx double_type "x" in
  let field_y = Field.create ctx double_type "y" in
  let coord = Struct.create ctx "coord" [ field_x ; field_y ]

• by creating the structure, then populating it with fields, typically to allow modelling self-referential structs such as:

  struct node { int m_hash; struct node *m_next; };

  like this:

  let node = Struct.create_opaque ctx "node" in
  let node_ptr = Type.pointer node in
  let field_hash = Field.create ctx int_type "m_hash" in
  let field_next = Field.create ctx node_ptr "m_next" in
  Struct.set_fields node [ field_hash; field_next ]

Types

Rvalues

A rvalue is an expression that can be computed.

It can be simple, e.g.:

• an integer value e.g. 0 or 42
• a string literal e.g. "Hello world"
• a variable e.g. i. These are also lvalues (see below).

or compound e.g.:

• a unary expression e.g. !cond
• a binary expression e.g. (a + b)
• a function call e.g. get_distance (&player_ship, &target)
• etc.

Every rvalue has an associated type, and the API will check to ensure that types match up correctly (otherwise the context will emit an error).

Lvalues

An lvalue is something that can of the left-hand side of an assignment: a storage area (such as a variable). It is also usable as an rvalue, where the rvalue is computed by reading from the storage area.

Parameters

A value of type param represents a parameter to a function.

Functions

A values of type function_ encapsulates a function: either one that you're creating yourself, or a reference to one that you're dynamically linking to within the rest of the process.

Basic Blocks

A block encapsulates a basic block of statements within a function (i.e. with one entry point and one exit point).

• Every block within a function must be terminated with a conditional, a branch, or a return.
• The blocks within a function form a directed graph.
• The entrypoint to the function is the first block created within it.
• All of the blocks in a function must be reachable via some path from the first block.
• It's OK to have more than one return from a function (i.e., multiple blocks that terminate by returning.

Source Locations

A location encapsulates a source code location, so that you can (optionally) associate locations in your language with statements in the JIT-compiled code, allowing the debugger to single-step through your language.

• location instances are optional: you can always omit them to any API entrypoint accepting one.
• You can construct them using Location.create.
• You need to enable Debuginfo on the context for these locations to actually be usable by the debugger.

Faking it

If you don't have source code for your internal representation, but need to debug, you can generate a C-like representation of the functions in your context using Context.dump_to_file. This will dump C-like code to the given path. If the update_locations argument is true, this will also set up location information throughout the context, pointing at the dump file as if it were a source file, giving you something you can step through in the debugger.

In-memory compilation