Acquire a JIT-compilation context.Release the context. After this call, it's no longer valid to use the ctxt.Options present in the initial release of libgccjit. These were handled using enums. Options taking string values.Options taking int values.Options taking boolean values. These all default to "false".

Set a string option on the given context.

  The context takes a copy of the string, so the
  (const char *) buffer is not needed anymore after the call
  returns.

Set an int option on the given context.

Set a boolean option on the given context.

Zero is "false" (the default), non-zero is "true".

Options added after the initial release of libgccjit.
  These are handled by providing an entrypoint per option,
  rather than by extending the enum gcc_jit_*_option,
  so that client code that use these new options can be identified
  from binary metadata.
By default, libgccjit will issue an error about unreachable blocks
  within a function.

  This option can be used to disable that error.

  This entrypoint was added in LIBGCCJIT_ABI_2; you can test for
  its presence using
    #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks

Pre-canned feature macro to indicate the presence of gcc_jit_context_set_bool_allow_unreachable_blocks. This can be tested for with #ifdef.

By default, libgccjit will print errors to stderr.

This option can be used to disable the printing.

This entrypoint was added in LIBGCCJIT_ABI_23; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_print_errors_to_stderr

Pre-canned feature macro to indicate the presence of gcc_jit_context_set_bool_print_errors_to_stderr. This can be tested for with #ifdef.

Implementation detail: libgccjit internally generates assembler, and uses "driver" code for converting it to other formats (e.g. shared libraries).

By default, libgccjit will use an embedded copy of the driver code.

This option can be used to instead invoke an external driver executable as a subprocess.

This entrypoint was added in LIBGCCJIT_ABI_5; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver

Pre-canned feature macro to indicate the presence of gcc_jit_context_set_bool_use_external_driver. This can be tested for with #ifdef.

Add an arbitrary gcc command-line option to the context.
  The context takes a copy of the string, so the
  (const char *) optname is not needed anymore after the call
  returns.

  Note that only some options are likely to be meaningful; there is no
  "frontend" within libgccjit, so typically only those affecting
  optimization and code-generation are likely to be useful.

  This entrypoint was added in LIBGCCJIT_ABI_1; you can test for
  its presence using
  #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option

Pre-canned feature-test macro for detecting the presence of gcc_jit_context_add_command_line_option within libgccjit.h.

Add an arbitrary gcc driver option to the context.
  The context takes a copy of the string, so the
  (const char *) optname is not needed anymore after the call
  returns.

  Note that only some options are likely to be meaningful; there is no
  "frontend" within libgccjit, so typically only those affecting
  assembler and linker are likely to be useful.

  This entrypoint was added in LIBGCCJIT_ABI_11; you can test for
  its presence using
  #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option

Pre-canned feature-test macro for detecting the presence of gcc_jit_context_add_driver_option within libgccjit.h.

Compile the context to in-memory machine code.

This can be called more that once on a given context, although any errors that occur will block further compilation.

Kinds of ahead-of-time compilation, for use with gcc_jit_context_compile_to_file.

Compile the context to a file of the given kind.

This can be called more that once on a given context, although any errors that occur will block further compilation.

To help with debugging: dump a C-like representation to the given path, describing what's been set up on the context.

If "update_locations" is true, then also set up gcc_jit_location information throughout the context, pointing at the dump file as if it were a source file. This may be of use in conjunction with GCC_JIT_BOOL_OPTION_DEBUGINFO to allow stepping through the code in a debugger.

To help with debugging; enable ongoing logging of the context's
  activity to the given FILE *.

  The caller remains responsible for closing "logfile".

  Params "flags" and "verbosity" are reserved for future use, and
  must both be 0 for now.

To be called after any API call, this gives the first error message that occurred on the context.

The returned string is valid for the rest of the lifetime of the context.

If no errors occurred, this will be NULL.

To be called after any API call, this gives the last error message that occurred on the context.

If no errors occurred, this will be NULL.

If non-NULL, the returned string is only guaranteed to be valid until the next call to libgccjit relating to this context.

Locate a given function within the built machine code. This will need to be cast to a function pointer of the correct type before it can be called.

Locate a given global within the built machine code.
  It must have been created using GCC_JIT_GLOBAL_EXPORTED.
  This is a ptr to the global, so e.g. for an int this is an int *.

Once we're done with the code, this unloads the built .so file. This cleans up the result; after calling this, it's no longer valid to use the result.

********************************************************************
 Functions for creating "contextual" objects.

 All objects created by these functions share the lifetime of the context
 they are created within, and are automatically cleaned up for you when
 you call gcc_jit_context_release on the context.

 Note that this means you can't use references to them after you've
 released their context.

 All (const char *) string arguments passed to these functions are
 copied, so you don't need to keep them around.

 You create code by adding a sequence of statements to blocks.
********************************************************************
********************************************************************
 The base class of "contextual" object.
********************************************************************
 Which context is "obj" within?

Get a human-readable description of this object. The string buffer is created the first time this is called on a given object, and persists until the object's context is released.

Debugging information.

Creating source code locations for use by the debugger. Line and column numbers are 1-based.

Upcasting from location to object.

Types.

Upcasting from type to object.

Access to specific types.Get the integer type of the given size and signedness.

Constructing new types.
Given type "T", get type "T*".

Given type "T", get type "const T".Given type "T", get type "volatile T".Given type "T", get type "restrict T". This API entrypoint was added in LIBGCCJIT_ABI_25; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_restrictGiven types LTYPE and RTYPE, return non-zero if they are compatible. This API entrypoint was added in LIBGCCJIT_ABI_20; you can test for its presence using #ifdef LIBGCCJIT_HAVE_SIZED_INTEGERSGiven type "T", get its size. This API entrypoint was added in LIBGCCJIT_ABI_20; you can test for its presence using #ifdef LIBGCCJIT_HAVE_SIZED_INTEGERSGiven type "T", get type "TN" (for a constant N).Struct-handling. Create a field, for use within a struct or union.

Create a bit field, for use within a struct or union.

This API entrypoint was added in LIBGCCJIT_ABI_12; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield

Upcasting from field to object.Create a struct type from an array of fields.Create an opaque struct type.Upcast a struct to a type.Populating the fields of a formerly-opaque struct type. This can only be called once on a given struct type.Get a field by index.Get the number of fields.Unions work similarly to structs.Function pointers.

Constructing functions.

Create a function param.

Upcasting from param to object.Upcasting from param to lvalue.Upcasting from param to rvalue.Kinds of function.Thread local storage model.Create a function.Create a reference to a builtin function (sometimes called intrinsic functions).Upcasting from function to object.Get a specific param of a function by index.Emit the function in graphviz format.

Create a block.

The name can be NULL, or you can give it a meaningful name, which may show up in dumps of the internal representation, and in error messages.

Upcasting from block to object.Which function is this block within?

lvalues, rvalues and expressions.

Create a constructor for a struct as an rvalue.

Returns NULL on error. The two parameter arrays are copied and do not have to outlive the context.

type specifies what the constructor will build and has to be a struct.

num_values specifies the number of elements in values.

fields need to have the same length as values, or be NULL.

If fields is null, the values are applied in definition order.

Otherwise, each field in fields specifies which field in the struct to set to the corresponding value in values. fields and values are paired by index.

Each value has to have the same unqualified type as the field it is applied to.

A NULL value element in values is a shorthand for zero initialization of the corresponding field.

The fields in fields have to be in definition order, but there can be gaps. Any field in the struct that is not specified in fields will be zeroed.

The fields in fields need to be the same objects that were used to create the struct.

If num_values is 0, the array parameters will be ignored and zero initialization will be used.

The constructor rvalue can be used for assignment to locals. It can be used to initialize global variables with gcc_jit_global_set_initializer_rvalue. It can also be used as a temporary value for function calls and return values.

The constructor can contain nested constructors.

This entrypoint was added in LIBGCCJIT_ABI_19; you can test for its presence using: #ifdef LIBGCCJIT_HAVE_CTORS

Create a constructor for a union as an rvalue.

Returns NULL on error.

type specifies what the constructor will build and has to be an union.

field specifies which field to set. If it is NULL, the first field in the union will be set. field need to be the same object that were used to create the union.

value specifies what value to set the corresponding field to. If value is NULL, zero initialization will be used.

Each value has to have the same unqualified type as the field it is applied to.

field need to be the same objects that were used to create the union.

The constructor can contain nested constructors.

This entrypoint was added in LIBGCCJIT_ABI_19; you can test for its presence using: #ifdef LIBGCCJIT_HAVE_CTORS

Create a constructor for an array as an rvalue.

Returns NULL on error. values are copied and do not have to outlive the context.

type specifies what the constructor will build and has to be an array.

num_values specifies the number of elements in values and it can't have more elements than the array type.

Each value in values sets the corresponding value in the array. If the array type itself has more elements than values, the left-over elements will be zeroed.

Each value in values need to be the same unqualified type as the array type's element type.

If num_values is 0, the values parameter will be ignored and zero initialization will be used.

Note that a string literal rvalue can't be used to construct a char array. It needs one rvalue for each char.

This entrypoint was added in LIBGCCJIT_ABI_19; you can test for its presence using: #ifdef LIBGCCJIT_HAVE_CTORS

Set the initial value of a global of any type with an rvalue.

The rvalue needs to be a constant expression, e.g. no function calls.

The global can't have the 'kind' GCC_JIT_GLOBAL_IMPORTED.

Use together with gcc_jit_context_new_constructor () to initialize structs, unions and arrays.

On success, returns the 'global' parameter unchanged. Otherwise, NULL.

'values' is copied and does not have to outlive the context.

This entrypoint was added in LIBGCCJIT_ABI_19; you can test for its presence using: #ifdef LIBGCCJIT_HAVE_CTORS

Set an initial value for a global, which must be an array of integral type. Return the global itself.

This API entrypoint was added in LIBGCCJIT_ABI_14; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_global_set_initializer

Upcasting.Integer constants.Floating-point constants.Pointers.

Generates an rvalue that is equal to the size of type.

This API entrypoint was added in LIBGCCJIT_ABI_27; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_sizeof

String literals.(Comparisons are treated as separate from "binary_op" to save you having to specify the result_type).Function calls. Call of a specific function.Call through a function pointer.

Type-coercion.

Currently only a limited set of conversions are possible: int <-> float int <-> bool

Reinterpret a value as another type.

The types must be of the same size.

This API entrypoint was added in LIBGCCJIT_ABI_21; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitcast

Set the alignment of a variable.

This API entrypoint was added in LIBGCCJIT_ABI_24; you can test for its presence using #ifdef LIBGCCJIT_HAVE_ALIGNMENT

Get the alignment of a variable.

This API entrypoint was added in LIBGCCJIT_ABI_24; you can test for its presence using #ifdef LIBGCCJIT_HAVE_ALIGNMENT

Field access is provided separately for both lvalues and rvalues. Accessing a field of an lvalue of struct type, analogous to: (EXPR).field = ...; in C.Accessing a field of an rvalue of struct type, analogous to: (EXPR).field in C.

Accessing a field of an rvalue of pointer type, analogous to:
     (EXPR)->field
  in C, itself equivalent to (*EXPR).FIELD

Dereferencing a pointer; analogous to: (EXPR) Taking the address of an lvalue; analogous to: &(EXPR) in C.

Set the thread-local storage model of a global variable

This API entrypoint was added in LIBGCCJIT_ABI_17; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_tls_model

Set the link section of a global variable; analogous to: __attribute__((section(".section_name"))) in C.

This API entrypoint was added in LIBGCCJIT_ABI_18; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_link_section

Make this variable a register variable and set its register name.

This API entrypoint was added in LIBGCCJIT_ABI_22; you can test for its presence using #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_register_name

Statement-creation.

Add evaluation of an rvalue, discarding the result (e.g. a function call that "returns" void).

This is equivalent to this C code:

(void)expression;

Add evaluation of an rvalue, assigning the result to the given lvalue.

This is roughly equivalent to this C code:

lvalue = rvalue;

Add evaluation of an rvalue, using the result to modify an
  lvalue.

  This is analogous to "+=" and friends:

    lvalue += rvalue;
    lvalue *= rvalue;
    lvalue /= rvalue;
  etc

Add a no-op textual comment to the internal representation of the code. It will be optimized away, but will be visible in the dumps seen via GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE and GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, and thus may be of use when debugging how your project's internal representation gets converted to the libgccjit IR.

Terminate a block by adding evaluation of an rvalue, branching on the result to the appropriate successor block.

This is roughly equivalent to this C code:

if (boolval) goto on_true; else goto on_false;

block, boolval, on_true, and on_false must be non-NULL.

Terminate a block by adding a jump to the given target block.

This is roughly equivalent to this C code:

goto target;

Terminate a block by adding evaluation of an rvalue, returning the value.

This is roughly equivalent to this C code:

return expression;

Terminate a block by adding a valueless return, for use within a function with "void" return type.

This is equivalent to this C code:

return;

Create a new gcc_jit_case instance for use in a switch statement. min_value and max_value must be constants of integer type.

This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its presence using #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS

Upcasting from case to object.

This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its presence using #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS

Terminate a block by adding evalation of an rvalue, then performing a multiway branch.

This is roughly equivalent to this C code:

switch (expr) { default: goto default_block;

case C0.min_value ... C0.max_value: goto C0.dest_block;

case C1.min_value ... C1.max_value: goto C1.dest_block;

...etc...

case CN - 1.min_value ... CN - 1.max_value: goto CN - 1.dest_block;

}

block, expr, default_block and cases must all be non-NULL.

expr must be of the same integer type as all of the min_value and max_value within the cases.

num_cases must be >= 0.

The ranges of the cases must not overlap (or have duplicate values).

This API entrypoint was added in LIBGCCJIT_ABI_3; you can test for its presence using #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS

Pre-canned feature macro to indicate the presence of gcc_jit_block_end_with_switch, gcc_jit_case_as_object, and gcc_jit_context_new_case.

This can be tested for with #ifdef.

Nested contexts.

Given an existing JIT context, create a child context.

The child inherits a copy of all option-settings from the parent.

The child can reference objects created within the parent, but not vice-versa.

The lifetime of the child context must be bounded by that of the parent: you should release a child context before releasing the parent context.

If you use a function from a parent context within a child context, you have to compile the parent context before you can compile the child context, and the gcc_jit_result of the parent context must outlive the gcc_jit_result of the child context.

This allows caching of shared initializations. For example, you could create types and declarations of global functions in a parent context once within a process, and then create child contexts whenever a function or loop becomes hot. Each such child context can be used for JIT-compiling just one function or loop, but can reference types and helper functions created within the parent context.

Contexts can be arbitrarily nested, provided the above rules are followed, but it's probably not worth going above 2 or 3 levels, and there will likely be a performance hit for such nesting.

Implementation support.

Write C source code into "path" that can be compiled into a self-contained executable (i.e. with libgccjit as the only dependency). The generated code will attempt to replay the API calls that have been made into the given context.

This may be useful when debugging the library or client code, for reducing a complicated recipe for reproducing a bug into a simpler form.

Typically you need to supply the option "-Wno-unused-variable" when compiling the generated file (since the result of each API call is assigned to a unique variable within the generated C source, and not all are necessarily then used).

Enable the dumping of a specific set of internal state from the
  compilation, capturing the result in-memory as a buffer.

  Parameter "dumpname" corresponds to the equivalent gcc command-line
  option, without the "-fdump-" prefix.
  For example, to get the equivalent of "-fdump-tree-vrp1", supply
  "tree-vrp1".
  The context directly stores the dumpname as a (const char *), so the
  passed string must outlive the context.

  gcc_jit_context_compile and gcc_jit_context_to_file
  will capture the dump as a dynamically-allocated buffer, writing
  it to ``*out_ptr``.

  The caller becomes responsible for calling
     free (*out_ptr)
  each time that gcc_jit_context_compile or gcc_jit_context_to_file
  are called.  *out_ptr will be written to, either with the address of a
  buffer, or with NULL if an error occurred.

  This API entrypoint is likely to be less stable than the others.
  In particular, both the precise dumpnames, and the format and content
  of the dumps are subject to change.

  It exists primarily for writing the library's own test suite.

Timing support.

The timing API was added in LIBGCCJIT_ABI_4; you can test for its presence using #ifdef LIBGCCJIT_HAVE_TIMING_API

Create a gcc_jit_timer instance, and start timing.