Module Gccjit

module Gccjit: sig .. end

OCaml bindings for libgccjit.

See GCC wiki page for more information.

exception Error of string

This exception (containing an explanatory string) is raised if an error occurs.

type context

The type of compilation contexts. See Compilation Contexts.

type result

A Gccjit.result encapsulates the result of an in-memory compilation.

type location

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

type param

A Gccjit.param is a function parameter. See Parameters.

type lvalue

An Gccjit.lvalue is something that can of the left-hand side of an assignment. See Lvalues.

type rvalue

A rvalue is an expression within your code, with some type. See RValues.

type field

The type of fields of structs and unions. See Fields.

type struct_

The type of structure types. See Structure Types.

type type_

The type of C types, e.g. int or a struct foo*. See Types.

type function_

The type of functios. See Functions.

type block

The type of basic blocks. See Basic Blocks.

type unary_op =

`\|`	`Negate`
`\|`	`Bitwise_negate`
`\|`	`Logical_negate`

type binary_op =

`\|`	`Plus`
`\|`	`Minus`
`\|`	`Mult`
`\|`	`Divide`
`\|`	`Modulo`
`\|`	`Bitwise_and`
`\|`	`Bitwise_xor`
`\|`	`Bitwise_or`
`\|`	`Logical_and`
`\|`	`Logical_or`

type comparison =

`\|`	`Eq`
`\|`	`Ne`
`\|`	`Lt`
`\|`	`Le`
`\|`	`Gt`
`\|`	`Ge`

Compilation Contexts

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

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

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

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

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

module Context: sig .. end

Fields

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

module Field: sig .. end

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 ]

module Struct: sig .. end

Types

module Type: sig .. end

Rvalues

A Gccjit.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 Gccjit.rvalue has an associated type, and the API will check to ensure that types match up correctly (otherwise the context will emit an error).

module RValue: sig .. end

Lvalues

An Gccjit.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 Gccjit.rvalue, where the Gccjit.rvalue is computed by reading from the storage area.

module LValue: sig .. end

Parameters

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

module Param: sig .. end

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.

module Function: sig .. end

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.

module Block: sig .. end

Source Locations

A Gccjit.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.

Gccjit.location instances are optional: you can always omit them to any API entrypoint accepting one.
You can construct them using Gccjit.Location.create.
You need to enable Debuginfo on the Gccjit.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 Gccjit.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 Gccjit.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.

module Location: sig .. end

In-memory compilation

module Result: sig .. end