@copying
@quotation
-libgccjit 5.0.0 (experimental 20141209), December 09, 2014
+libgccjit 5.0.0 (experimental 20141210), December 10, 2014
David Malcolm
@c along with this program. If not, see
@c <http://www.gnu.org/licenses/>.
+This document describes libgccjit@footnote{http://gcc.gnu.org/wiki/JIT}, an API
+for embedding GCC inside programs and libraries.
+
+Note that libgccjit is currently of "Alpha" quality;
+the APIs are not yet set in stone, and they shouldn't be used in
+production yet.
+
+There are actually two APIs for the library:
+
+
+@itemize *
+
+@item
+a pure C API: @code{libgccjit.h}
+
+@item
+a C++ wrapper API: @code{libgccjit++.h}. This is a collection of "thin"
+wrapper classes around the C API, to save typing.
+@end itemize
+
Contents:
@c Copyright (C) 2014 Free Software Foundation, Inc.
@menu
* Tutorial::
* Topic Reference::
+* C++ bindings for libgccjit::
* Internals::
* Indices and tables::
* Index::
* Faking it::
+C++ bindings for libgccjit
+
+* Tutorial: Tutorial<2>.
+* Topic Reference: Topic Reference<2>.
+
+Tutorial
+
+* Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>.
+* Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
+* Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
+* Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
+
+Tutorial part 2: Creating a trivial machine code function
+
+* Options: Options<3>.
+* Full example: Full example<3>.
+
+Tutorial part 3: Loops and variables
+
+* Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
+* Control flow: Control flow<2>.
+* Visualizing the control flow graph: Visualizing the control flow graph<2>.
+* Full example: Full example<4>.
+
+Tutorial part 4: Adding JIT-compilation to a toy interpreter
+
+* Our toy interpreter: Our toy interpreter<2>.
+* Compiling to machine code: Compiling to machine code<2>.
+* Setting things up: Setting things up<2>.
+* Populating the function: Populating the function<2>.
+* Verifying the control flow graph: Verifying the control flow graph<2>.
+* Compiling the context: Compiling the context<2>.
+* Single-stepping through the generated code: Single-stepping through the generated code<2>.
+* Examining the generated code: Examining the generated code<2>.
+* Putting it all together: Putting it all together<2>.
+* Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
+
+Behind the curtain: How does our code get optimized?
+
+* Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
+* Elimination of tail recursion: Elimination of tail recursion<2>.
+
+Topic Reference
+
+* Compilation contexts: Compilation contexts<2>.
+* Objects: Objects<2>.
+* Types: Types<2>.
+* Expressions: Expressions<2>.
+* Creating and using functions: Creating and using functions<2>.
+* Source Locations: Source Locations<2>.
+* Compilation results: Compilation results<2>.
+
+Compilation contexts
+
+* Lifetime-management: Lifetime-management<2>.
+* Thread-safety: Thread-safety<2>.
+* Error-handling: Error-handling<3>.
+* Debugging: Debugging<2>.
+* Options: Options<4>.
+
+Options
+
+* Boolean options: Boolean options<2>.
+* Integer options: Integer options<2>.
+
+Types
+
+* Standard types: Standard types<2>.
+* Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
+* Structures and unions: Structures and unions<2>.
+
+Expressions
+
+* Rvalues: Rvalues<2>.
+* Lvalues: Lvalues<2>.
+* Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
+
+Rvalues
+
+* Simple expressions: Simple expressions<2>.
+* Unary Operations: Unary Operations<2>.
+* Binary Operations: Binary Operations<2>.
+* Comparisons: Comparisons<2>.
+* Function calls: Function calls<2>.
+* Type-coercion: Type-coercion<2>.
+
+Lvalues
+
+* Global variables: Global variables<2>.
+
+Creating and using functions
+
+* Params: Params<2>.
+* Functions: Functions<2>.
+* Blocks: Blocks<2>.
+* Statements: Statements<2>.
+
+Source Locations
+
+* Faking it: Faking it<2>.
+
Internals
* Working on the JIT library::
typedef int (*fn_type) (int);
fn_type square = (fn_type)fn_ptr;
- printf ("result: %d", square (5));
+ printf ("result: %d\n", square (5));
error:
if (ctxt)
@c along with this program. If not, see
@c <http://www.gnu.org/licenses/>.
-@node Topic Reference,Internals,Tutorial,Top
+@node Topic Reference,C++ bindings for libgccjit,Tutorial,Top
@anchor{topics/index doc}@anchor{48}@anchor{topics/index topic-reference}@anchor{49}
@chapter Topic Reference
@subsection Thread-safety
-Instances of @pxref{e,,gcc_jit_object *} created via
+Instances of @pxref{8,,gcc_jit_context *} created via
@pxref{9,,gcc_jit_context_acquire()} are independent from each other:
only one thread may use a given context at once, but multiple threads
could each have their own contexts without needing locks.
@c along with this program. If not, see
@c <http://www.gnu.org/licenses/>.
-@node Internals,Indices and tables,Topic Reference,Top
-@anchor{internals/index internals}@anchor{c1}@anchor{internals/index doc}@anchor{c2}
-@chapter Internals
+@node C++ bindings for libgccjit,Internals,Topic Reference,Top
+@anchor{cp/index c-bindings-for-libgccjit}@anchor{c1}@anchor{cp/index doc}@anchor{c2}
+@chapter C++ bindings for libgccjit
-@menu
-* Working on the JIT library::
-* Running the test suite::
-* Environment variables::
-* Overview of code structure::
+This document describes the C++ bindings to
+libgccjit@footnote{http://gcc.gnu.org/wiki/JIT}, an API for embedding GCC
+inside programs and libraries.
-@end menu
+The C++ bindings consist of a single header file @code{libgccjit++.h}.
-@node Working on the JIT library,Running the test suite,,Internals
-@anchor{internals/index working-on-the-jit-library}@anchor{c3}
-@section Working on the JIT library
+This is a collection of "thin" wrapper classes around the C API.
+Everything is an inline function, implemented in terms of the C API,
+so there is nothing extra to link against.
+Note that libgccjit is currently of "Alpha" quality;
+the APIs are not yet set in stone, and they shouldn't be used in
+production yet.
-Having checked out the source code (to "src"), you can configure and build
-the JIT library like this:
+Contents:
-@example
-mkdir build
-mkdir install
-PREFIX=$(pwd)/install
-cd build
-../src/configure \
- --enable-host-shared \
- --enable-languages=jit \
- --disable-bootstrap \
- --enable-checking=release \
- --prefix=$PREFIX
-nice make -j4 # altering the "4" to however many cores you have
-@end example
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
-@noindent
+@menu
+* Tutorial: Tutorial<2>.
+* Topic Reference: Topic Reference<2>.
-This should build a libgccjit.so within jit/build/gcc:
+Tutorial
-@example
-[build] $ file gcc/libgccjit.so*
-gcc/libgccjit.so: symbolic link to `libgccjit.so.0'
-gcc/libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
-gcc/libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, not stripped
-@end example
+* Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>.
+* Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
+* Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
+* Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
-@noindent
+Tutorial part 2: Creating a trivial machine code function
-Here's what those configuration options mean:
+* Options: Options<3>.
+* Full example: Full example<3>.
-@geindex command line option; --enable-host-shared
-@anchor{internals/index cmdoption--enable-host-shared}@anchor{c4}
-@deffn {Option} --enable-host-shared
+Tutorial part 3: Loops and variables
-Configuring with this option means that the compiler is built as
-position-independent code, which incurs a slight performance hit,
-but it necessary for a shared library.
-@end deffn
+* Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
+* Control flow: Control flow<2>.
+* Visualizing the control flow graph: Visualizing the control flow graph<2>.
+* Full example: Full example<4>.
-@geindex command line option; --enable-languages=jit
-@anchor{internals/index cmdoption--enable-languages}@anchor{c5}
-@deffn {Option} --enable-languages=jit
+Tutorial part 4: Adding JIT-compilation to a toy interpreter
-This specifies which frontends to build. The JIT library looks like
-a frontend to the rest of the code.
-@end deffn
+* Our toy interpreter: Our toy interpreter<2>.
+* Compiling to machine code: Compiling to machine code<2>.
+* Setting things up: Setting things up<2>.
+* Populating the function: Populating the function<2>.
+* Verifying the control flow graph: Verifying the control flow graph<2>.
+* Compiling the context: Compiling the context<2>.
+* Single-stepping through the generated code: Single-stepping through the generated code<2>.
+* Examining the generated code: Examining the generated code<2>.
+* Putting it all together: Putting it all together<2>.
+* Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
-@geindex command line option; --disable-bootstrap
-@anchor{internals/index cmdoption--disable-bootstrap}@anchor{c6}
-@deffn {Option} --disable-bootstrap
+Behind the curtain: How does our code get optimized?
-For hacking on the "jit" subdirectory, performing a full
-bootstrap can be overkill, since it's unused by a bootstrap. However,
-when submitting patches, you should remove this option, to ensure that
-the compiler can still bootstrap itself.
-@end deffn
+* Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
+* Elimination of tail recursion: Elimination of tail recursion<2>.
-@geindex command line option; --enable-checking=release
-@anchor{internals/index cmdoption--enable-checking}@anchor{c7}
-@deffn {Option} --enable-checking=release
+Topic Reference
-The compile can perform extensive self-checking as it runs, useful when
-debugging, but slowing things down.
+* Compilation contexts: Compilation contexts<2>.
+* Objects: Objects<2>.
+* Types: Types<2>.
+* Expressions: Expressions<2>.
+* Creating and using functions: Creating and using functions<2>.
+* Source Locations: Source Locations<2>.
+* Compilation results: Compilation results<2>.
-For maximum speed, configure with @code{--enable-checking=release} to
-disable this self-checking.
-@end deffn
+Compilation contexts
-@node Running the test suite,Environment variables,Working on the JIT library,Internals
-@anchor{internals/index running-the-test-suite}@anchor{c8}
-@section Running the test suite
+* Lifetime-management: Lifetime-management<2>.
+* Thread-safety: Thread-safety<2>.
+* Error-handling: Error-handling<3>.
+* Debugging: Debugging<2>.
+* Options: Options<4>.
+Options
-@example
-[build] $ cd gcc
-[gcc] $ make check-jit RUNTESTFLAGS="-v -v -v"
-@end example
+* Boolean options: Boolean options<2>.
+* Integer options: Integer options<2>.
-@noindent
+Types
-A summary of the tests can then be seen in:
+* Standard types: Standard types<2>.
+* Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
+* Structures and unions: Structures and unions<2>.
-@example
-jit/build/gcc/testsuite/jit/jit.sum
-@end example
+Expressions
-@noindent
+* Rvalues: Rvalues<2>.
+* Lvalues: Lvalues<2>.
+* Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
-and detailed logs in:
+Rvalues
-@example
-jit/build/gcc/testsuite/jit/jit.log
-@end example
+* Simple expressions: Simple expressions<2>.
+* Unary Operations: Unary Operations<2>.
+* Binary Operations: Binary Operations<2>.
+* Comparisons: Comparisons<2>.
+* Function calls: Function calls<2>.
+* Type-coercion: Type-coercion<2>.
-@noindent
+Lvalues
-The test executables can be seen as:
+* Global variables: Global variables<2>.
-@example
-jit/build/gcc/testsuite/jit/*.exe
-@end example
+Creating and using functions
-@noindent
+* Params: Params<2>.
+* Functions: Functions<2>.
+* Blocks: Blocks<2>.
+* Statements: Statements<2>.
-which can be run independently.
+Source Locations
-You can compile and run individual tests by passing "jit.exp=TESTNAME" to RUNTESTFLAGS e.g.:
+* Faking it: Faking it<2>.
-@example
-[gcc] $ make check-jit RUNTESTFLAGS="-v -v -v jit.exp=test-factorial.c"
-@end example
+@end menu
-@noindent
-and once a test has been compiled, you can debug it directly:
+@node Tutorial<2>,Topic Reference<2>,,C++ bindings for libgccjit
+@anchor{cp/intro/index doc}@anchor{c3}@anchor{cp/intro/index tutorial}@anchor{c4}
+@section Tutorial
-@example
-[gcc] $ PATH=.:$PATH \
- LD_LIBRARY_PATH=. \
- LIBRARY_PATH=. \
- gdb --args \
- testsuite/jit/test-factorial.exe
-@end example
-@noindent
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
@menu
-* Running under valgrind::
+* Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>.
+* Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>.
+* Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>.
+* Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>.
@end menu
-@node Running under valgrind,,,Running the test suite
-@anchor{internals/index running-under-valgrind}@anchor{c9}
-@subsection Running under valgrind
+@node Tutorial part 1 "Hello world"<2>,Tutorial part 2 Creating a trivial machine code function<2>,,Tutorial<2>
+@anchor{cp/intro/tutorial01 doc}@anchor{c5}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{c6}
+@subsection Tutorial part 1: "Hello world"
-The jit testsuite detects if RUN_UNDER_VALGRIND is present in the
-environment (with any value). If it is present, it runs the test client
-code under valgrind@footnote{http://valgrind.org},
-specifcally, the default
-memcheck@footnote{http://valgrind.org/docs/manual/mc-manual.html}
-tool with
---leak-check=full@footnote{http://valgrind.org/docs/manual/mc-manual.html#opt.leak-check}.
+Before we look at the details of the API, let's look at building and
+running programs that use the library.
-It automatically parses the output from valgrind, injecting XFAIL results if
-any issues are found, or PASS results if the output is clean. The output
-is saved to @code{TESTNAME.exe.valgrind.txt}.
+Here's a toy "hello world" program that uses the library's C++ API to
+synthesize a call to @cite{printf} and uses it to write a message to stdout.
-For example, the following invocation verbosely runs the testcase
-@code{test-sum-of-squares.c} under valgrind, showing an issue:
+Don't worry about the content of the program for now; we'll cover
+the details in later parts of this tutorial.
+
+@quotation
@example
-$ RUN_UNDER_VALGRIND= \
- make check-jit \
- RUNTESTFLAGS="-v -v -v jit.exp=test-sum-of-squares.c"
+/* Smoketest example for libgccjit.so C++ API
+ Copyright (C) 2014 Free Software Foundation, Inc.
-(...verbose log contains detailed valgrind errors, if any...)
+This file is part of GCC.
- === jit Summary ===
+GCC is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3, or (at your option)
+any later version.
-# of expected passes 28
-# of expected failures 2
+GCC is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
-$ less testsuite/jit/jit.sum
-(...other results...)
-XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: definitely lost: 8 bytes in 1 blocks
-XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: unsuppressed errors: 1
-(...other results...)
+You should have received a copy of the GNU General Public License
+along with GCC; see the file COPYING3. If not see
+<http://www.gnu.org/licenses/>. */
-$ less testsuite/jit/test-sum-of-squares.exe.valgrind.txt
-(...shows full valgrind report for this test case...)
+#include <libgccjit++.h>
+
+#include <stdlib.h>
+#include <stdio.h>
+
+static void
+create_code (gccjit::context ctxt)
+@{
+ /* Let's try to inject the equivalent of this C code:
+ void
+ greet (const char *name)
+ @{
+ printf ("hello %s\n", name);
+ @}
+ */
+ gccjit::type void_type = ctxt.get_type (GCC_JIT_TYPE_VOID);
+ gccjit::type const_char_ptr_type =
+ ctxt.get_type (GCC_JIT_TYPE_CONST_CHAR_PTR);
+ gccjit::param param_name =
+ ctxt.new_param (const_char_ptr_type, "name");
+ std::vector<gccjit::param> func_params;
+ func_params.push_back (param_name);
+ gccjit::function func =
+ ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
+ void_type,
+ "greet",
+ func_params, 0);
+
+ gccjit::param param_format =
+ ctxt.new_param (const_char_ptr_type, "format");
+ std::vector<gccjit::param> printf_params;
+ printf_params.push_back (param_format);
+ gccjit::function printf_func =
+ ctxt.new_function (GCC_JIT_FUNCTION_IMPORTED,
+ ctxt.get_type (GCC_JIT_TYPE_INT),
+ "printf",
+ printf_params, 1);
+
+ gccjit::block block = func.new_block ();
+ block.add_eval (ctxt.new_call (printf_func,
+ ctxt.new_rvalue ("hello %s\n"),
+ param_name));
+ block.end_with_return ();
+@}
+
+int
+main (int argc, char **argv)
+@{
+ gccjit::context ctxt;
+ gcc_jit_result *result;
+
+ /* Get a "context" object for working with the library. */
+ ctxt = gccjit::context::acquire ();
+
+ /* Set some options on the context.
+ Turn this on to see the code being generated, in assembler form. */
+ ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 0);
+
+ /* Populate the context. */
+ create_code (ctxt);
+
+ /* Compile the code. */
+ result = ctxt.compile ();
+ if (!result)
+ @{
+ fprintf (stderr, "NULL result");
+ exit (1);
+ @}
+
+ ctxt.release ();
+
+ /* Extract the generated code from "result". */
+ typedef void (*fn_type) (const char *);
+ fn_type greet =
+ (fn_type)gcc_jit_result_get_code (result, "greet");
+ if (!greet)
+ @{
+ fprintf (stderr, "NULL greet");
+ exit (1);
+ @}
+
+ /* Now call the generated function: */
+ greet ("world");
+ fflush (stdout);
+
+ gcc_jit_result_release (result);
+ return 0;
+@}
+
+@end example
+
+@noindent
+@end quotation
+
+Copy the above to @cite{tut01-hello-world.cc}.
+
+Assuming you have the jit library installed, build the test program
+using:
+
+@example
+$ gcc \
+ tut01-hello-world.cc \
+ -o tut01-hello-world \
+ -lgccjit
+@end example
+
+@noindent
+
+You should then be able to run the built program:
+
+@example
+$ ./tut01-hello-world
+hello world
+@end example
+
+@noindent
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Tutorial part 2 Creating a trivial machine code function<2>,Tutorial part 3 Loops and variables<2>,Tutorial part 1 "Hello world"<2>,Tutorial<2>
+@anchor{cp/intro/tutorial02 doc}@anchor{c7}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{c8}
+@subsection Tutorial part 2: Creating a trivial machine code function
+
+
+Consider this C function:
+
+@example
+int square (int i)
+@{
+ return i * i;
+@}
+@end example
+
+@noindent
+
+How can we construct this at run-time using libgccjit's C++ API?
+
+First we need to include the relevant header:
+
+@example
+#include <libgccjit++.h>
+@end example
+
+@noindent
+
+All state associated with compilation is associated with a
+@code{gccjit::context}, which is a thin C++ wrapper around the C API's
+@pxref{8,,gcc_jit_context *}.
+
+Create one using @pxref{c9,,gccjit;;context;;acquire()}:
+
+@example
+gccjit::context ctxt;
+ctxt = gccjit::context::acquire ();
+@end example
+
+@noindent
+
+The JIT library has a system of types. It is statically-typed: every
+expression is of a specific type, fixed at compile-time. In our example,
+all of the expressions are of the C @cite{int} type, so let's obtain this from
+the context, as a @code{gccjit::type}, using
+@pxref{ca,,gccjit;;context;;get_type()}:
+
+@example
+gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
+@end example
+
+@noindent
+
+@code{gccjit::type} is an example of a "contextual" object: every
+entity in the API is associated with a @code{gccjit::context}.
+
+Memory management is easy: all such "contextual" objects are automatically
+cleaned up for you when the context is released, using
+@pxref{cb,,gccjit;;context;;release()}:
+
+@example
+ctxt.release ();
+@end example
+
+@noindent
+
+so you don't need to manually track and cleanup all objects, just the
+contexts.
+
+All of the C++ classes in the API are thin wrappers around pointers to
+types in the C API.
+
+The C++ class hierarchy within the @code{gccjit} namespace looks like this:
+
+@example
++- object
+ +- location
+ +- type
+ +- struct
+ +- field
+ +- function
+ +- block
+ +- rvalue
+ +- lvalue
+ +- param
+@end example
+
+@noindent
+
+One thing you can do with a @code{gccjit::object} is
+to ask it for a human-readable description as a @code{std::string}, using
+@pxref{cc,,gccjit;;object;;get_debug_string()}:
+
+@example
+printf ("obj: %s\n", obj.get_debug_string ().c_str ());
+@end example
+
+@noindent
+
+giving this text on stdout:
+
+@example
+obj: int
+@end example
+
+@noindent
+
+This is invaluable when debugging.
+
+Let's create the function. To do so, we first need to construct
+its single parameter, specifying its type and giving it a name,
+using @pxref{cd,,gccjit;;context;;new_param()}:
+
+@example
+gccjit::param param_i = ctxt.new_param (int_type, "i");
+@end example
+
+@noindent
+
+and we can then make a vector of all of the params of the function,
+in this case just one:
+
+@example
+std::vector<gccjit::param> params;
+params.push_back (param_i);
+@end example
+
+@noindent
+
+Now we can create the function, using
+@code{gccjit::context::new_function()}:
+
+@example
+gccjit::function func =
+ ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
+ int_type,
+ "square",
+ params,
+ 0);
+@end example
+
+@noindent
+
+To define the code within the function, we must create basic blocks
+containing statements.
+
+Every basic block contains a list of statements, eventually terminated
+by a statement that either returns, or jumps to another basic block.
+
+Our function has no control-flow, so we just need one basic block:
+
+@example
+gccjit::block block = func.new_block ();
+@end example
+
+@noindent
+
+Our basic block is relatively simple: it immediately terminates by
+returning the value of an expression.
+
+We can build the expression using @pxref{ce,,gccjit;;context;;new_binary_op()}:
+
+@example
+gccjit::rvalue expr =
+ ctxt.new_binary_op (
+ GCC_JIT_BINARY_OP_MULT, int_type,
+ param_i, param_i);
+@end example
+
+@noindent
+
+A @code{gccjit::rvalue} is another example of a
+@code{gccjit::object} subclass. As before, we can print it with
+@pxref{cc,,gccjit;;object;;get_debug_string()}.
+
+@example
+printf ("expr: %s\n", expr.get_debug_string ().c_str ());
+@end example
+
+@noindent
+
+giving this output:
+
+@example
+expr: i * i
+@end example
+
+@noindent
+
+Note that @code{gccjit::rvalue} provides numerous overloaded operators
+which can be used to dramatically reduce the amount of typing needed.
+We can build the above binary operation more directly with this one-liner:
+
+@example
+gccjit::rvalue expr = param_i * param_i;
+@end example
+
+@noindent
+
+Creating the expression in itself doesn't do anything; we have to add
+this expression to a statement within the block. In this case, we use it
+to build a return statement, which terminates the basic block:
+
+@example
+block.end_with_return (expr);
+@end example
+
+@noindent
+
+OK, we've populated the context. We can now compile it using
+@pxref{cf,,gccjit;;context;;compile()}:
+
+@example
+gcc_jit_result *result;
+result = ctxt.compile ();
+@end example
+
+@noindent
+
+and get a @pxref{16,,gcc_jit_result *}.
+
+We can now use @pxref{17,,gcc_jit_result_get_code()} to look up a specific
+machine code routine within the result, in this case, the function we
+created above.
+
+@example
+void *fn_ptr = gcc_jit_result_get_code (result, "square");
+if (!fn_ptr)
+ @{
+ fprintf (stderr, "NULL fn_ptr");
+ goto error;
+ @}
+@end example
+
+@noindent
+
+We can now cast the pointer to an appropriate function pointer type, and
+then call it:
+
+@example
+typedef int (*fn_type) (int);
+fn_type square = (fn_type)fn_ptr;
+printf ("result: %d", square (5));
+@end example
+
+@noindent
+
+@example
+result: 25
+@end example
+
+@noindent
+
+@menu
+* Options: Options<3>.
+* Full example: Full example<3>.
+
+@end menu
+
+@node Options<3>,Full example<3>,,Tutorial part 2 Creating a trivial machine code function<2>
+@anchor{cp/intro/tutorial02 options}@anchor{d0}
+@subsubsection Options
+
+
+To get more information on what's going on, you can set debugging flags
+on the context using @pxref{d1,,gccjit;;context;;set_bool_option()}.
+
+@c (I'm deliberately not mentioning
+@c :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think
+@c it's probably more of use to implementors than to users)
+
+Setting @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a
+C-like representation to stderr when you compile (GCC's "GIMPLE"
+representation):
+
+@example
+ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
+result = ctxt.compile ();
+@end example
+
+@noindent
+
+@example
+square (signed int i)
+@{
+ signed int D.260;
+
+ entry:
+ D.260 = i * i;
+ return D.260;
+@}
+@end example
+
+@noindent
+
+We can see the generated machine code in assembler form (on stderr) by
+setting @pxref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context
+before compiling:
+
+@example
+ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1);
+result = ctxt.compile ();
+@end example
+
+@noindent
+
+@example
+ .file "fake.c"
+ .text
+ .globl square
+ .type square, @@function
+square:
+.LFB6:
+ .cfi_startproc
+ pushq %rbp
+ .cfi_def_cfa_offset 16
+ .cfi_offset 6, -16
+ movq %rsp, %rbp
+ .cfi_def_cfa_register 6
+ movl %edi, -4(%rbp)
+.L14:
+ movl -4(%rbp), %eax
+ imull -4(%rbp), %eax
+ popq %rbp
+ .cfi_def_cfa 7, 8
+ ret
+ .cfi_endproc
+.LFE6:
+ .size square, .-square
+ .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
+ .section .note.GNU-stack,"",@@progbits
+@end example
+
+@noindent
+
+By default, no optimizations are performed, the equivalent of GCC's
+@cite{-O0} option. We can turn things up to e.g. @cite{-O3} by calling
+@pxref{d2,,gccjit;;context;;set_int_option()} with
+@pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
+
+@example
+ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
+@end example
+
+@noindent
+
+@example
+ .file "fake.c"
+ .text
+ .p2align 4,,15
+ .globl square
+ .type square, @@function
+square:
+.LFB7:
+ .cfi_startproc
+.L16:
+ movl %edi, %eax
+ imull %edi, %eax
+ ret
+ .cfi_endproc
+.LFE7:
+ .size square, .-square
+ .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-0.5.1920c315ff984892399893b380305ab36e07b455.fc20)"
+ .section .note.GNU-stack,"",@@progbits
+@end example
+
+@noindent
+
+Naturally this has only a small effect on such a trivial function.
+
+@node Full example<3>,,Options<3>,Tutorial part 2 Creating a trivial machine code function<2>
+@anchor{cp/intro/tutorial02 full-example}@anchor{d3}
+@subsubsection Full example
+
+
+Here's what the above looks like as a complete program:
+
+@quotation
+
+@example
+/* Usage example for libgccjit.so's C++ API
+ Copyright (C) 2014 Free Software Foundation, Inc.
+
+This file is part of GCC.
+
+GCC is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3, or (at your option)
+any later version.
+
+GCC is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GCC; see the file COPYING3. If not see
+<http://www.gnu.org/licenses/>. */
+
+#include <libgccjit++.h>
+
+#include <stdlib.h>
+#include <stdio.h>
+
+void
+create_code (gccjit::context ctxt)
+@{
+ /* Let's try to inject the equivalent of this C code:
+
+ int square (int i)
+ @{
+ return i * i;
+ @}
+ */
+ gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
+ gccjit::param param_i = ctxt.new_param (int_type, "i");
+ std::vector<gccjit::param> params;
+ params.push_back (param_i);
+ gccjit::function func = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
+ int_type,
+ "square",
+ params, 0);
+
+ gccjit::block block = func.new_block ();
+
+ gccjit::rvalue expr =
+ ctxt.new_binary_op (GCC_JIT_BINARY_OP_MULT, int_type,
+ param_i, param_i);
+
+ block.end_with_return (expr);
+@}
+
+int
+main (int argc, char **argv)
+@{
+ /* Get a "context" object for working with the library. */
+ gccjit::context ctxt = gccjit::context::acquire ();
+
+ /* Set some options on the context.
+ Turn this on to see the code being generated, in assembler form. */
+ ctxt.set_bool_option (
+ GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
+ 0);
+
+ /* Populate the context. */
+ create_code (ctxt);
+
+ /* Compile the code. */
+ gcc_jit_result *result = ctxt.compile ();
+
+ /* We're done with the context; we can release it: */
+ ctxt.release ();
+
+ if (!result)
+ @{
+ fprintf (stderr, "NULL result");
+ return 1;
+ @}
+
+ /* Extract the generated code from "result". */
+ void *fn_ptr = gcc_jit_result_get_code (result, "square");
+ if (!fn_ptr)
+ @{
+ fprintf (stderr, "NULL fn_ptr");
+ gcc_jit_result_release (result);
+ return 1;
+ @}
+
+ typedef int (*fn_type) (int);
+ fn_type square = (fn_type)fn_ptr;
+ printf ("result: %d\n", square (5));
+
+ gcc_jit_result_release (result);
+ return 0;
+@}
+
+@end example
+
+@noindent
+@end quotation
+
+Building and running it:
+
+@example
+$ gcc \
+ tut02-square.cc \
+ -o tut02-square \
+ -lgccjit
+
+# Run the built program:
+$ ./tut02-square
+result: 25
+@end example
+
+@noindent
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Tutorial part 3 Loops and variables<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>,Tutorial part 2 Creating a trivial machine code function<2>,Tutorial<2>
+@anchor{cp/intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{d4}@anchor{cp/intro/tutorial03 doc}@anchor{d5}
+@subsection Tutorial part 3: Loops and variables
+
+
+Consider this C function:
+
+@quotation
+
+@example
+int loop_test (int n)
+@{
+ int sum = 0;
+ for (int i = 0; i < n; i++)
+ sum += i * i;
+ return sum;
+@}
+@end example
+
+@noindent
+@end quotation
+
+This example demonstrates some more features of libgccjit, with local
+variables and a loop.
+
+To break this down into libgccjit terms, it's usually easier to reword
+the @cite{for} loop as a @cite{while} loop, giving:
+
+@quotation
+
+@example
+int loop_test (int n)
+@{
+ int sum = 0;
+ int i = 0;
+ while (i < n)
+ @{
+ sum += i * i;
+ i++;
+ @}
+ return sum;
+@}
+@end example
+
+@noindent
+@end quotation
+
+Here's what the final control flow graph will look like:
+
+@quotation
+
+
+@float Figure
+
+@image{sum-of-squares1,,,image of a control flow graph,png}
+
+@end float
+
+@end quotation
+
+As before, we include the libgccjit++ header and make a
+@code{gccjit::context}.
+
+@example
+#include <libgccjit++.h>
+
+void test (void)
+@{
+ gccjit::context ctxt;
+ ctxt = gccjit::context::acquire ();
+@end example
+
+@noindent
+
+The function works with the C @cite{int} type.
+
+In the previous tutorial we acquired this via
+
+@example
+gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_INT);
+@end example
+
+@noindent
+
+though we could equally well make it work on, say, @cite{double}:
+
+@example
+gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_DOUBLE);
+@end example
+
+@noindent
+
+For integer types we can use @code{gccjit::context::get_int_type}
+to directly bind a specific type:
+
+@example
+gccjit::type the_type = ctxt.get_int_type <int> ();
+@end example
+
+@noindent
+
+Let's build the function:
+
+@example
+gcc_jit_param n = ctxt.new_param (the_type, "n");
+std::vector<gccjit::param> params;
+params.push_back (n);
+gccjit::function func =
+ ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
+ return_type,
+ "loop_test",
+ params, 0);
+@end example
+
+@noindent
+
+@menu
+* Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>.
+* Control flow: Control flow<2>.
+* Visualizing the control flow graph: Visualizing the control flow graph<2>.
+* Full example: Full example<4>.
+
+@end menu
+
+@node Expressions lvalues and rvalues<2>,Control flow<2>,,Tutorial part 3 Loops and variables<2>
+@anchor{cp/intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{d6}
+@subsubsection Expressions: lvalues and rvalues
+
+
+The base class of expression is the @code{gccjit::rvalue},
+representing an expression that can be on the @emph{right}-hand side of
+an assignment: a value that can be computed somehow, and assigned
+@emph{to} a storage area (such as a variable). It has a specific
+@code{gccjit::type}.
+
+Anothe important class is @code{gccjit::lvalue}.
+A @code{gccjit::lvalue}. is something that can of the @emph{left}-hand
+side of an assignment: a storage area (such as a variable).
+
+In other words, every assignment can be thought of as:
+
+@example
+LVALUE = RVALUE;
+@end example
+
+@noindent
+
+Note that @code{gccjit::lvalue} is a subclass of
+@code{gccjit::rvalue}, where in an assignment of the form:
+
+@example
+LVALUE_A = LVALUE_B;
+@end example
+
+@noindent
+
+the @cite{LVALUE_B} implies reading the current value of that storage
+area, assigning it into the @cite{LVALUE_A}.
+
+So far the only expressions we've seen are from the previous tutorial:
+
+
+@enumerate
+
+@item
+the multiplication @cite{i * i}:
+@end enumerate
+
+@quotation
+
+@example
+gccjit::rvalue expr =
+ ctxt.new_binary_op (
+ GCC_JIT_BINARY_OP_MULT, int_type,
+ param_i, param_i);
+
+/* Alternatively, using operator-overloading: */
+gccjit::rvalue expr = param_i * param_i;
+@end example
+
+@noindent
+
+which is a @code{gccjit::rvalue}, and
+@end quotation
+
+
+@enumerate 2
+
+@item
+the various function parameters: @cite{param_i} and @cite{param_n}, instances of
+@code{gccjit::param}, which is a subclass of @code{gccjit::lvalue}
+(and, in turn, of @code{gccjit::rvalue}):
+we can both read from and write to function parameters within the
+body of a function.
+@end enumerate
+
+Our new example has a new kind of expression: we have two local
+variables. We create them by calling
+@pxref{d7,,gccjit;;function;;new_local()}, supplying a type and a name:
+
+@example
+/* Build locals: */
+gccjit::lvalue i = func.new_local (the_type, "i");
+gccjit::lvalue sum = func.new_local (the_type, "sum");
+@end example
+
+@noindent
+
+These are instances of @code{gccjit::lvalue} - they can be read from
+and written to.
+
+Note that there is no precanned way to create @emph{and} initialize a variable
+like in C:
+
+@example
+int i = 0;
+@end example
+
+@noindent
+
+Instead, having added the local to the function, we have to separately add
+an assignment of @cite{0} to @cite{local_i} at the beginning of the function.
+
+@node Control flow<2>,Visualizing the control flow graph<2>,Expressions lvalues and rvalues<2>,Tutorial part 3 Loops and variables<2>
+@anchor{cp/intro/tutorial03 control-flow}@anchor{d8}
+@subsubsection Control flow
+
+
+This function has a loop, so we need to build some basic blocks to
+handle the control flow. In this case, we need 4 blocks:
+
+
+@enumerate
+
+@item
+before the loop (initializing the locals)
+
+@item
+the conditional at the top of the loop (comparing @cite{i < n})
+
+@item
+the body of the loop
+
+@item
+after the loop terminates (@cite{return sum})
+@end enumerate
+
+so we create these as @code{gccjit::block} instances within the
+@code{gccjit::function}:
+
+@example
+gccjit::block b_initial = func.new_block ("initial");
+gccjit::block b_loop_cond = func.new_block ("loop_cond");
+gccjit::block b_loop_body = func.new_block ("loop_body");
+gccjit::block b_after_loop = func.new_block ("after_loop");
+@end example
+
+@noindent
+
+We now populate each block with statements.
+
+The entry block @cite{b_initial} consists of initializations followed by a jump
+to the conditional. We assign @cite{0} to @cite{i} and to @cite{sum}, using
+@pxref{d9,,gccjit;;block;;add_assignment()} to add
+an assignment statement, and using @pxref{da,,gccjit;;context;;zero()} to get
+the constant value @cite{0} for the relevant type for the right-hand side of
+the assignment:
+
+@example
+/* sum = 0; */
+b_initial.add_assignment (sum, ctxt.zero (the_type));
+
+/* i = 0; */
+b_initial.add_assignment (i, ctxt.zero (the_type));
+@end example
+
+@noindent
+
+We can then terminate the entry block by jumping to the conditional:
+
+@example
+b_initial.end_with_jump (b_loop_cond);
+@end example
+
+@noindent
+
+The conditional block is equivalent to the line @cite{while (i < n)} from our
+C example. It contains a single statement: a conditional, which jumps to
+one of two destination blocks depending on a boolean
+@code{gccjit::rvalue}, in this case the comparison of @cite{i} and @cite{n}.
+
+We could build the comparison using @pxref{db,,gccjit;;context;;new_comparison()}:
+
+@example
+gccjit::rvalue guard =
+ ctxt.new_comparison (GCC_JIT_COMPARISON_GE,
+ i, n);
+@end example
+
+@noindent
+
+and can then use this to add @cite{b_loop_cond}'s sole statement, via
+@pxref{dc,,gccjit;;block;;end_with_conditional()}:
+
+@example
+b_loop_cond.end_with_conditional (guard);
+@end example
+
+@noindent
+
+However @code{gccjit::rvalue} has overloaded operators for this, so we
+express the conditional as
+
+@example
+gccjit::rvalue guard = (i >= n);
+@end example
+
+@noindent
+
+and hence write the block more concisely as:
+
+@example
+b_loop_cond.end_with_conditional (
+ i >= n,
+ b_after_loop,
+ b_loop_body);
+@end example
+
+@noindent
+
+Next, we populate the body of the loop.
+
+The C statement @cite{sum += i * i;} is an assignment operation, where an
+lvalue is modified "in-place". We use
+@pxref{dd,,gccjit;;block;;add_assignment_op()} to handle these operations:
+
+@example
+/* sum += i * i */
+b_loop_body.add_assignment_op (sum,
+ GCC_JIT_BINARY_OP_PLUS,
+ i * i);
+@end example
+
+@noindent
+
+The @cite{i++} can be thought of as @cite{i += 1}, and can thus be handled in
+a similar way. We use @pxref{2f,,gcc_jit_context_one()} to get the constant
+value @cite{1} (for the relevant type) for the right-hand side
+of the assignment.
+
+@example
+/* i++ */
+b_loop_body.add_assignment_op (i,
+ GCC_JIT_BINARY_OP_PLUS,
+ ctxt.one (the_type));
+@end example
+
+@noindent
+
+@cartouche
+@quotation Note
+For numeric constants other than 0 or 1, we could use
+@pxref{de,,gccjit;;context;;new_rvalue()}, which has overloads
+for both @code{int} and @code{double}.
+@end quotation
+@end cartouche
+
+The loop body completes by jumping back to the conditional:
+
+@example
+b_loop_body.end_with_jump (b_loop_cond);
+@end example
+
+@noindent
+
+Finally, we populate the @cite{b_after_loop} block, reached when the loop
+conditional is false. We want to generate the equivalent of:
+
+@example
+return sum;
+@end example
+
+@noindent
+
+so the block is just one statement:
+
+@example
+/* return sum */
+b_after_loop.end_with_return (sum);
+@end example
+
+@noindent
+
+@cartouche
+@quotation Note
+You can intermingle block creation with statement creation,
+but given that the terminator statements generally include references
+to other blocks, I find it's clearer to create all the blocks,
+@emph{then} all the statements.
+@end quotation
+@end cartouche
+
+We've finished populating the function. As before, we can now compile it
+to machine code:
+
+@example
+gcc_jit_result *result;
+result = ctxt.compile ();
+
+ctxt.release ();
+
+if (!result)
+ @{
+ fprintf (stderr, "NULL result");
+ return 1;
+ @}
+
+typedef int (*loop_test_fn_type) (int);
+loop_test_fn_type loop_test =
+ (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
+if (!loop_test)
+ @{
+ fprintf (stderr, "NULL loop_test");
+ gcc_jit_result_release (result);
+ return 1;
+ @}
+printf ("result: %d", loop_test (10));
+@end example
+
+@noindent
+
+@example
+result: 285
+@end example
+
+@noindent
+
+@node Visualizing the control flow graph<2>,Full example<4>,Control flow<2>,Tutorial part 3 Loops and variables<2>
+@anchor{cp/intro/tutorial03 visualizing-the-control-flow-graph}@anchor{df}
+@subsubsection Visualizing the control flow graph
+
+
+You can see the control flow graph of a function using
+@pxref{e0,,gccjit;;function;;dump_to_dot()}:
+
+@example
+func.dump_to_dot ("/tmp/sum-of-squares.dot");
+@end example
+
+@noindent
+
+giving a .dot file in GraphViz format.
+
+You can convert this to an image using @cite{dot}:
+
+@example
+$ dot -Tpng /tmp/sum-of-squares.dot -o /tmp/sum-of-squares.png
+@end example
+
+@noindent
+
+or use a viewer (my preferred one is xdot.py; see
+@indicateurl{https://github.com/jrfonseca/xdot.py}; on Fedora you can
+install it with @cite{yum install python-xdot}):
+
+@quotation
+
+
+@float Figure
+
+@image{sum-of-squares1,,,image of a control flow graph,png}
+
+@end float
+
+@end quotation
+
+@node Full example<4>,,Visualizing the control flow graph<2>,Tutorial part 3 Loops and variables<2>
+@anchor{cp/intro/tutorial03 full-example}@anchor{e1}
+@subsubsection Full example
+
+
+@quotation
+
+@example
+/* Usage example for libgccjit.so's C++ API
+ Copyright (C) 2014 Free Software Foundation, Inc.
+
+This file is part of GCC.
+
+GCC is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3, or (at your option)
+any later version.
+
+GCC is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GCC; see the file COPYING3. If not see
+<http://www.gnu.org/licenses/>. */
+
+#include <libgccjit++.h>
+
+#include <stdlib.h>
+#include <stdio.h>
+
+void
+create_code (gccjit::context ctxt)
+@{
+ /*
+ Simple sum-of-squares, to test conditionals and looping
+
+ int loop_test (int n)
+ @{
+ int i;
+ int sum = 0;
+ for (i = 0; i < n ; i ++)
+ @{
+ sum += i * i;
+ @}
+ return sum;
+ */
+ gccjit::type the_type = ctxt.get_int_type <int> ();
+ gccjit::type return_type = the_type;
+
+ gccjit::param n = ctxt.new_param (the_type, "n");
+ std::vector<gccjit::param> params;
+ params.push_back (n);
+ gccjit::function func =
+ ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
+ return_type,
+ "loop_test",
+ params, 0);
+
+ /* Build locals: */
+ gccjit::lvalue i = func.new_local (the_type, "i");
+ gccjit::lvalue sum = func.new_local (the_type, "sum");
+
+ gccjit::block b_initial = func.new_block ("initial");
+ gccjit::block b_loop_cond = func.new_block ("loop_cond");
+ gccjit::block b_loop_body = func.new_block ("loop_body");
+ gccjit::block b_after_loop = func.new_block ("after_loop");
+
+ /* sum = 0; */
+ b_initial.add_assignment (sum, ctxt.zero (the_type));
+
+ /* i = 0; */
+ b_initial.add_assignment (i, ctxt.zero (the_type));
+
+ b_initial.end_with_jump (b_loop_cond);
+
+ /* if (i >= n) */
+ b_loop_cond.end_with_conditional (
+ i >= n,
+ b_after_loop,
+ b_loop_body);
+
+ /* sum += i * i */
+ b_loop_body.add_assignment_op (sum,
+ GCC_JIT_BINARY_OP_PLUS,
+ i * i);
+
+ /* i++ */
+ b_loop_body.add_assignment_op (i,
+ GCC_JIT_BINARY_OP_PLUS,
+ ctxt.one (the_type));
+
+ b_loop_body.end_with_jump (b_loop_cond);
+
+ /* return sum */
+ b_after_loop.end_with_return (sum);
+@}
+
+int
+main (int argc, char **argv)
+@{
+ gccjit::context ctxt;
+ gcc_jit_result *result = NULL;
+
+ /* Get a "context" object for working with the library. */
+ ctxt = gccjit::context::acquire ();
+
+ /* Set some options on the context.
+ Turn this on to see the code being generated, in assembler form. */
+ ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE,
+ 0);
+
+ /* Populate the context. */
+ create_code (ctxt);
+
+ /* Compile the code. */
+ result = ctxt.compile ();
+
+ ctxt.release ();
+
+ if (!result)
+ @{
+ fprintf (stderr, "NULL result");
+ return 1;
+ @}
+
+ /* Extract the generated code from "result". */
+ typedef int (*loop_test_fn_type) (int);
+ loop_test_fn_type loop_test =
+ (loop_test_fn_type)gcc_jit_result_get_code (result, "loop_test");
+ if (!loop_test)
+ @{
+ fprintf (stderr, "NULL loop_test");
+ gcc_jit_result_release (result);
+ return 1;
+ @}
+
+ /* Run the generated code. */
+ int val = loop_test (10);
+ printf("loop_test returned: %d\n", val);
+
+ gcc_jit_result_release (result);
+ return 0;
+@}
+
+@end example
+
+@noindent
+@end quotation
+
+Building and running it:
+
+@example
+$ gcc \
+ tut03-sum-of-squares.cc \
+ -o tut03-sum-of-squares \
+ -lgccjit
+
+# Run the built program:
+$ ./tut03-sum-of-squares
+loop_test returned: 285
+@end example
+
+@noindent
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>,,Tutorial part 3 Loops and variables<2>,Tutorial<2>
+@anchor{cp/intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{e2}@anchor{cp/intro/tutorial04 doc}@anchor{e3}
+@subsection Tutorial part 4: Adding JIT-compilation to a toy interpreter
+
+
+In this example we construct a "toy" interpreter, and add JIT-compilation
+to it.
+
+@menu
+* Our toy interpreter: Our toy interpreter<2>.
+* Compiling to machine code: Compiling to machine code<2>.
+* Setting things up: Setting things up<2>.
+* Populating the function: Populating the function<2>.
+* Verifying the control flow graph: Verifying the control flow graph<2>.
+* Compiling the context: Compiling the context<2>.
+* Single-stepping through the generated code: Single-stepping through the generated code<2>.
+* Examining the generated code: Examining the generated code<2>.
+* Putting it all together: Putting it all together<2>.
+* Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>.
+
+@end menu
+
+@node Our toy interpreter<2>,Compiling to machine code<2>,,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 our-toy-interpreter}@anchor{e4}
+@subsubsection Our toy interpreter
+
+
+It's a stack-based interpreter, and is intended as a (very simple) example
+of the kind of bytecode interpreter seen in dynamic languages such as
+Python, Ruby etc.
+
+For the sake of simplicity, our toy virtual machine is very limited:
+
+@quotation
+
+
+@itemize *
+
+@item
+The only data type is @cite{int}
+
+@item
+It can only work on one function at a time (so that the only
+function call that can be made is to recurse).
+
+@item
+Functions can only take one parameter.
+
+@item
+Functions have a stack of @cite{int} values.
+
+@item
+We'll implement function call within the interpreter by calling a
+function in our implementation, rather than implementing our own
+frame stack.
+
+@item
+The parser is only good enough to get the examples to work.
+@end itemize
+@end quotation
+
+Naturally, a real interpreter would be much more complicated that this.
+
+The following operations are supported:
+
+
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxx}
+@headitem
+
+Operation
+
+@tab
+
+Meaning
+
+@tab
+
+Old Stack
+
+@tab
+
+New Stack
+
+@item
+
+DUP
+
+@tab
+
+Duplicate top of stack.
+
+@tab
+
+@code{[..., x]}
+
+@tab
+
+@code{[..., x, x]}
+
+@item
+
+ROT
+
+@tab
+
+Swap top two elements
+of stack.
+
+@tab
+
+@code{[..., x, y]}
+
+@tab
+
+@code{[..., y, x]}
+
+@item
+
+BINARY_ADD
+
+@tab
+
+Add the top two elements
+on the stack.
+
+@tab
+
+@code{[..., x, y]}
+
+@tab
+
+@code{[..., (x+y)]}
+
+@item
+
+BINARY_SUBTRACT
+
+@tab
+
+Likewise, but subtract.
+
+@tab
+
+@code{[..., x, y]}
+
+@tab
+
+@code{[..., (x-y)]}
+
+@item
+
+BINARY_MULT
+
+@tab
+
+Likewise, but multiply.
+
+@tab
+
+@code{[..., x, y]}
+
+@tab
+
+@code{[..., (x*y)]}
+
+@item
+
+BINARY_COMPARE_LT
+
+@tab
+
+Compare the top two
+elements on the stack
+and push a nonzero/zero
+if (x<y).
+
+@tab
+
+@code{[..., x, y]}
+
+@tab
+
+@code{[..., (x<y)]}
+
+@item
+
+RECURSE
+
+@tab
+
+Recurse, passing the top
+of the stack, and
+popping the result.
+
+@tab
+
+@code{[..., x]}
+
+@tab
+
+@code{[..., fn(x)]}
+
+@item
+
+RETURN
+
+@tab
+
+Return the top of the
+stack.
+
+@tab
+
+@code{[x]}
+
+@tab
+
+@code{[]}
+
+@item
+
+PUSH_CONST @cite{arg}
+
+@tab
+
+Push an int const.
+
+@tab
+
+@code{[...]}
+
+@tab
+
+@code{[..., arg]}
+
+@item
+
+JUMP_ABS_IF_TRUE @cite{arg}
+
+@tab
+
+Pop; if top of stack was
+nonzero, jump to
+@code{arg}.
+
+@tab
+
+@code{[..., x]}
+
+@tab
+
+@code{[...]}
+
+@end multitable
+
+
+Programs can be interpreted, disassembled, and compiled to machine code.
+
+The interpreter reads @code{.toy} scripts. Here's what a simple recursive
+factorial program looks like, the script @code{factorial.toy}.
+The parser ignores lines beginning with a @cite{#}.
+
+@quotation
+
+@example
+# Simple recursive factorial implementation, roughly equivalent to:
+#
+# int factorial (int arg)
+# @{
+# if (arg < 2)
+# return arg
+# return arg * factorial (arg - 1)
+# @}
+
+# Initial state:
+# stack: [arg]
+
+# 0:
+DUP
+# stack: [arg, arg]
+
+# 1:
+PUSH_CONST 2
+# stack: [arg, arg, 2]
+
+# 2:
+BINARY_COMPARE_LT
+# stack: [arg, (arg < 2)]
+
+# 3:
+JUMP_ABS_IF_TRUE 9
+# stack: [arg]
+
+# 4:
+DUP
+# stack: [arg, arg]
+
+# 5:
+PUSH_CONST 1
+# stack: [arg, arg, 1]
+
+# 6:
+BINARY_SUBTRACT
+# stack: [arg, (arg - 1)
+
+# 7:
+RECURSE
+# stack: [arg, factorial(arg - 1)]
+
+# 8:
+BINARY_MULT
+# stack: [arg * factorial(arg - 1)]
+
+# 9:
+RETURN
+
+@end example
+
+@noindent
+@end quotation
+
+The interpreter is a simple infinite loop with a big @code{switch} statement
+based on what the next opcode is:
+
+@quotation
+
+@example
+
+int
+toyvm_function::interpret (int arg, FILE *trace)
+@{
+ toyvm_frame frame;
+#define PUSH(ARG) (frame.push (ARG))
+#define POP(ARG) (frame.pop ())
+
+ frame.frm_function = this;
+ frame.frm_pc = 0;
+ frame.frm_cur_depth = 0;
+
+ PUSH (arg);
+
+ while (1)
+ @{
+ toyvm_op *op;
+ int x, y;
+ assert (frame.frm_pc < fn_num_ops);
+ op = &fn_ops[frame.frm_pc++];
+
+ if (trace)
+ @{
+ frame.dump_stack (trace);
+ disassemble_op (op, frame.frm_pc, trace);
+ @}
+
+ switch (op->op_opcode)
+ @{
+ /* Ops taking no operand. */
+ case DUP:
+ x = POP ();
+ PUSH (x);
+ PUSH (x);
+ break;
+
+ case ROT:
+ y = POP ();
+ x = POP ();
+ PUSH (y);
+ PUSH (x);
+ break;
+
+ case BINARY_ADD:
+ y = POP ();
+ x = POP ();
+ PUSH (x + y);
+ break;
+
+ case BINARY_SUBTRACT:
+ y = POP ();
+ x = POP ();
+ PUSH (x - y);
+ break;
+
+ case BINARY_MULT:
+ y = POP ();
+ x = POP ();
+ PUSH (x * y);
+ break;
+
+ case BINARY_COMPARE_LT:
+ y = POP ();
+ x = POP ();
+ PUSH (x < y);
+ break;
+
+ case RECURSE:
+ x = POP ();
+ x = interpret (x, trace);
+ PUSH (x);
+ break;
+
+ case RETURN:
+ return POP ();
+
+ /* Ops taking an operand. */
+ case PUSH_CONST:
+ PUSH (op->op_operand);
+ break;
+
+ case JUMP_ABS_IF_TRUE:
+ x = POP ();
+ if (x)
+ frame.frm_pc = op->op_operand;
+ break;
+
+ default:
+ assert (0); /* unknown opcode */
+
+ @} /* end of switch on opcode */
+ @} /* end of while loop */
+
+#undef PUSH
+#undef POP
+@}
+
+
+@end example
+
+@noindent
+@end quotation
+
+@node Compiling to machine code<2>,Setting things up<2>,Our toy interpreter<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 compiling-to-machine-code}@anchor{e5}
+@subsubsection Compiling to machine code
+
+
+We want to generate machine code that can be cast to this type and
+then directly executed in-process:
+
+@quotation
+
+@example
+typedef int (*toyvm_compiled_func) (int);
+
+
+@end example
+
+@noindent
+@end quotation
+
+Our compiler isn't very sophisticated; it takes the implementation of
+each opcode above, and maps it directly to the operations supported by
+the libgccjit API.
+
+How should we handle the stack? In theory we could calculate what the
+stack depth will be at each opcode, and optimize away the stack
+manipulation "by hand". We'll see below that libgccjit is able to do
+this for us, so we'll implement stack manipulation
+in a direct way, by creating a @code{stack} array and @code{stack_depth}
+variables, local within the generated function, equivalent to this C code:
+
+@example
+int stack_depth;
+int stack[MAX_STACK_DEPTH];
+@end example
+
+@noindent
+
+We'll also have local variables @code{x} and @code{y} for use when implementing
+the opcodes, equivalent to this:
+
+@example
+int x;
+int y;
+@end example
+
+@noindent
+
+This means our compiler has the following state:
+
+@quotation
+
+@example
+
+ toyvm_function &toyvmfn;
+
+ gccjit::context ctxt;
+
+ gccjit::type int_type;
+ gccjit::type bool_type;
+ gccjit::type stack_type; /* int[MAX_STACK_DEPTH] */
+
+ gccjit::rvalue const_one;
+
+ gccjit::function fn;
+ gccjit::param param_arg;
+ gccjit::lvalue stack;
+ gccjit::lvalue stack_depth;
+ gccjit::lvalue x;
+ gccjit::lvalue y;
+
+ gccjit::location op_locs[MAX_OPS];
+ gccjit::block initial_block;
+ gccjit::block op_blocks[MAX_OPS];
+
+
+@end example
+
+@noindent
+@end quotation
+
+@node Setting things up<2>,Populating the function<2>,Compiling to machine code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 setting-things-up}@anchor{e6}
+@subsubsection Setting things up
+
+
+First we create our types:
+
+@quotation
+
+@example
+
+void
+compilation_state::create_types ()
+@{
+ /* Create types. */
+ int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
+ bool_type = ctxt.get_type (GCC_JIT_TYPE_BOOL);
+ stack_type = ctxt.new_array_type (int_type, MAX_STACK_DEPTH);
+
+
+@end example
+
+@noindent
+@end quotation
+
+along with extracting a useful @cite{int} constant:
+
+@quotation
+
+@example
+ const_one = ctxt.one (int_type);
+
+@}
+
+
+@end example
+
+@noindent
+@end quotation
+
+We'll implement push and pop in terms of the @code{stack} array and
+@code{stack_depth}. Here are helper functions for adding statements to
+a block, implementing pushing and popping values:
+
+@quotation
+
+@example
+
+void
+compilation_state::add_push (gccjit::block block,
+ gccjit::rvalue rvalue,
+ gccjit::location loc)
+@{
+ /* stack[stack_depth] = RVALUE */
+ block.add_assignment (
+ /* stack[stack_depth] */
+ ctxt.new_array_access (
+ stack,
+ stack_depth,
+ loc),
+ rvalue,
+ loc);
+
+ /* "stack_depth++;". */
+ block.add_assignment_op (
+ stack_depth,
+ GCC_JIT_BINARY_OP_PLUS,
+ const_one,
+ loc);
+@}
+
+void
+compilation_state::add_pop (gccjit::block block,
+ gccjit::lvalue lvalue,
+ gccjit::location loc)
+@{
+ /* "--stack_depth;". */
+ block.add_assignment_op (
+ stack_depth,
+ GCC_JIT_BINARY_OP_MINUS,
+ const_one,
+ loc);
+
+ /* "LVALUE = stack[stack_depth];". */
+ block.add_assignment (
+ lvalue,
+ /* stack[stack_depth] */
+ ctxt.new_array_access (stack,
+ stack_depth,
+ loc),
+ loc);
+@}
+
+
+@end example
+
+@noindent
+@end quotation
+
+We will support single-stepping through the generated code in the
+debugger, so we need to create @code{gccjit::location} instances, one
+per operation in the source code. These will reference the lines of
+e.g. @code{factorial.toy}.
+
+@quotation
+
+@example
+
+void
+compilation_state::create_locations ()
+@{
+ for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
+ @{
+ toyvm_op *op = &toyvmfn.fn_ops[pc];
+
+ op_locs[pc] = ctxt.new_location (toyvmfn.fn_filename,
+ op->op_linenum,
+ 0); /* column */
+ @}
+@}
+
+
+@end example
+
+@noindent
+@end quotation
+
+Let's create the function itself. As usual, we create its parameter
+first, then use the parameter to create the function:
+
+@quotation
+
+@example
+
+void
+compilation_state::create_function (const char *funcname)
+@{
+ std::vector <gccjit::param> params;
+ param_arg = ctxt.new_param (int_type, "arg", op_locs[0]);
+ params.push_back (param_arg);
+ fn = ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
+ int_type,
+ funcname,
+ params, 0,
+ op_locs[0]);
+
+
+@end example
+
+@noindent
+@end quotation
+
+We create the locals within the function.
+
+@quotation
+
+@example
+ stack = fn.new_local (stack_type, "stack");
+ stack_depth = fn.new_local (int_type, "stack_depth");
+ x = fn.new_local (int_type, "x");
+ y = fn.new_local (int_type, "y");
+
+
+@end example
+
+@noindent
+@end quotation
+
+@node Populating the function<2>,Verifying the control flow graph<2>,Setting things up<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 populating-the-function}@anchor{e7}
+@subsubsection Populating the function
+
+
+There's some one-time initialization, and the API treats the first block
+you create as the entrypoint of the function, so we need to create that
+block first:
+
+@quotation
+
+@example
+ initial_block = fn.new_block ("initial");
+
+
+@end example
+
+@noindent
+@end quotation
+
+We can now create blocks for each of the operations. Most of these will
+be consolidated into larger blocks when the optimizer runs.
+
+@quotation
+
+@example
+ for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
+ @{
+ char buf[16];
+ sprintf (buf, "instr%i", pc);
+ op_blocks[pc] = fn.new_block (buf);
+ @}
+
+
+@end example
+
+@noindent
+@end quotation
+
+Now that we have a block it can jump to when it's done, we can populate
+the initial block:
+
+@quotation
+
+@example
+
+ /* "stack_depth = 0;". */
+ initial_block.add_assignment (stack_depth,
+ ctxt.zero (int_type),
+ op_locs[0]);
+
+ /* "PUSH (arg);". */
+ add_push (initial_block,
+ param_arg,
+ op_locs[0]);
+
+ /* ...and jump to insn 0. */
+ initial_block.end_with_jump (op_blocks[0],
+ op_locs[0]);
+
+
+@end example
+
+@noindent
+@end quotation
+
+We can now populate the blocks for the individual operations. We loop
+through them, adding instructions to their blocks:
+
+@quotation
+
+@example
+ for (int pc = 0; pc < toyvmfn.fn_num_ops; pc++)
+ @{
+ gccjit::location loc = op_locs[pc];
+
+ gccjit::block block = op_blocks[pc];
+ gccjit::block next_block = (pc < toyvmfn.fn_num_ops
+ ? op_blocks[pc + 1]
+ : NULL);
+
+ toyvm_op *op;
+ op = &toyvmfn.fn_ops[pc];
+
+
+@end example
+
+@noindent
+@end quotation
+
+We're going to have another big @code{switch} statement for implementing
+the opcodes, this time for compiling them, rather than interpreting
+them. It's helpful to have macros for implementing push and pop, so that
+we can make the @code{switch} statement that's coming up look as much as
+possible like the one above within the interpreter:
+
+@example
+
+#define X_EQUALS_POP()\
+ add_pop (block, x, loc)
+#define Y_EQUALS_POP()\
+ add_pop (block, y, loc)
+#define PUSH_RVALUE(RVALUE)\
+ add_push (block, (RVALUE), loc)
+#define PUSH_X()\
+ PUSH_RVALUE (x)
+#define PUSH_Y() \
+ PUSH_RVALUE (y)
+
+
+@end example
+
+@noindent
+
+@cartouche
+@quotation Note
+A particularly clever implementation would have an @emph{identical}
+@code{switch} statement shared by the interpreter and the compiler, with
+some preprocessor "magic". We're not doing that here, for the sake
+of simplicity.
+@end quotation
+@end cartouche
+
+When I first implemented this compiler, I accidentally missed an edit
+when copying and pasting the @code{Y_EQUALS_POP} macro, so that popping the
+stack into @code{y} instead erroneously assigned it to @code{x}, leaving @code{y}
+uninitialized.
+
+To track this kind of thing down, we can use
+@pxref{e8,,gccjit;;block;;add_comment()} to add descriptive comments
+to the internal representation. This is invaluable when looking through
+the generated IR for, say @code{factorial}:
+
+@quotation
+
+@example
+
+ block.add_comment (opcode_names[op->op_opcode], loc);
+
+
+@end example
+
+@noindent
+@end quotation
+
+We can now write the big @code{switch} statement that implements the
+individual opcodes, populating the relevant block with statements:
+
+@quotation
+
+@example
+
+ switch (op->op_opcode)
+ @{
+ case DUP:
+ X_EQUALS_POP ();
+ PUSH_X ();
+ PUSH_X ();
+ break;
+
+ case ROT:
+ Y_EQUALS_POP ();
+ X_EQUALS_POP ();
+ PUSH_Y ();
+ PUSH_X ();
+ break;
+
+ case BINARY_ADD:
+ Y_EQUALS_POP ();
+ X_EQUALS_POP ();
+ PUSH_RVALUE (
+ ctxt.new_binary_op (
+ GCC_JIT_BINARY_OP_PLUS,
+ int_type,
+ x, y,
+ loc));
+ break;
+
+ case BINARY_SUBTRACT:
+ Y_EQUALS_POP ();
+ X_EQUALS_POP ();
+ PUSH_RVALUE (
+ ctxt.new_binary_op (
+ GCC_JIT_BINARY_OP_MINUS,
+ int_type,
+ x, y,
+ loc));
+ break;
+
+ case BINARY_MULT:
+ Y_EQUALS_POP ();
+ X_EQUALS_POP ();
+ PUSH_RVALUE (
+ ctxt.new_binary_op (
+ GCC_JIT_BINARY_OP_MULT,
+ int_type,
+ x, y,
+ loc));
+ break;
+
+ case BINARY_COMPARE_LT:
+ Y_EQUALS_POP ();
+ X_EQUALS_POP ();
+ PUSH_RVALUE (
+ /* cast of bool to int */
+ ctxt.new_cast (
+ /* (x < y) as a bool */
+ ctxt.new_comparison (
+ GCC_JIT_COMPARISON_LT,
+ x, y,
+ loc),
+ int_type,
+ loc));
+ break;
+
+ case RECURSE:
+ @{
+ X_EQUALS_POP ();
+ PUSH_RVALUE (
+ ctxt.new_call (
+ fn,
+ x,
+ loc));
+ break;
+ @}
+
+ case RETURN:
+ X_EQUALS_POP ();
+ block.end_with_return (x, loc);
+ break;
+
+ /* Ops taking an operand. */
+ case PUSH_CONST:
+ PUSH_RVALUE (
+ ctxt.new_rvalue (int_type, op->op_operand));
+ break;
+
+ case JUMP_ABS_IF_TRUE:
+ X_EQUALS_POP ();
+ block.end_with_conditional (
+ /* "(bool)x". */
+ ctxt.new_cast (x, bool_type, loc),
+ op_blocks[op->op_operand], /* on_true */
+ next_block, /* on_false */
+ loc);
+ break;
+
+ default:
+ assert(0);
+ @} /* end of switch on opcode */
+
+
+@end example
+
+@noindent
+@end quotation
+
+Every block must be terminated, via a call to one of the
+@code{gccjit::block::end_with_} entrypoints. This has been done for two
+of the opcodes, but we need to do it for the other ones, by jumping
+to the next block.
+
+@quotation
+
+@example
+ if (op->op_opcode != JUMP_ABS_IF_TRUE
+ && op->op_opcode != RETURN)
+ block.end_with_jump (next_block, loc);
+
+
+@end example
+
+@noindent
+@end quotation
+
+This is analogous to simply incrementing the program counter.
+
+@node Verifying the control flow graph<2>,Compiling the context<2>,Populating the function<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 verifying-the-control-flow-graph}@anchor{e9}
+@subsubsection Verifying the control flow graph
+
+
+Having finished looping over the blocks, the context is complete.
+
+As before, we can verify that the control flow and statements are sane by
+using @pxref{e0,,gccjit;;function;;dump_to_dot()}:
+
+@example
+fn.dump_to_dot ("/tmp/factorial.dot");
+@end example
+
+@noindent
+
+and viewing the result. Note how the label names, comments, and
+variable names show up in the dump, to make it easier to spot
+errors in our compiler.
+
+@quotation
+
+
+@float Figure
+
+@image{factorial1,,,image of a control flow graph,png}
+
+@end float
+
+@end quotation
+
+@node Compiling the context<2>,Single-stepping through the generated code<2>,Verifying the control flow graph<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 compiling-the-context}@anchor{ea}
+@subsubsection Compiling the context
+
+
+Having finished looping over the blocks and populating them with
+statements, the context is complete.
+
+We can now compile it, and extract machine code from the result:
+
+@quotation
+
+@example
+ gcc_jit_result *result = state.compile ();
+
+ return (toyvm_compiled_func)gcc_jit_result_get_code (result, funcname);
+
+@end example
+
+@noindent
+@end quotation
+
+We can now run the result:
+
+@quotation
+
+@example
+ toyvm_compiled_func code = fn->compile ();
+ printf ("compiler result: %d\n",
+ code (atoi (argv[2])));
+
+
+@end example
+
+@noindent
+@end quotation
+
+@node Single-stepping through the generated code<2>,Examining the generated code<2>,Compiling the context<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 single-stepping-through-the-generated-code}@anchor{eb}
+@subsubsection Single-stepping through the generated code
+
+
+It's possible to debug the generated code. To do this we need to both:
+
+@quotation
+
+
+@itemize *
+
+@item
+Set up source code locations for our statements, so that we can
+meaningfully step through the code. We did this above by
+calling @pxref{ec,,gccjit;;context;;new_location()} and using the
+results.
+
+@item
+Enable the generation of debugging information, by setting
+@pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
+@code{gccjit::context} via
+@pxref{d1,,gccjit;;context;;set_bool_option()}:
+
+@example
+ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
+@end example
+
+@noindent
+@end itemize
+@end quotation
+
+Having done this, we can put a breakpoint on the generated function:
+
+@example
+$ gdb --args ./toyvm factorial.toy 10
+(gdb) break factorial
+Function "factorial" not defined.
+Make breakpoint pending on future shared library load? (y or [n]) y
+Breakpoint 1 (factorial) pending.
+(gdb) run
+Breakpoint 1, factorial (arg=10) at factorial.toy:14
+14 DUP
+@end example
+
+@noindent
+
+We've set up location information, which references @code{factorial.toy}.
+This allows us to use e.g. @code{list} to see where we are in the script:
+
+@example
+(gdb) list
+9
+10 # Initial state:
+11 # stack: [arg]
+12
+13 # 0:
+14 DUP
+15 # stack: [arg, arg]
+16
+17 # 1:
+18 PUSH_CONST 2
+@end example
+
+@noindent
+
+and to step through the function, examining the data:
+
+@example
+(gdb) n
+18 PUSH_CONST 2
+(gdb) n
+22 BINARY_COMPARE_LT
+(gdb) print stack
+$5 = @{10, 10, 2, 0, -7152, 32767, 0, 0@}
+(gdb) print stack_depth
+$6 = 3
+@end example
+
+@noindent
+
+You'll see that the parts of the @code{stack} array that haven't been
+touched yet are uninitialized.
+
+@cartouche
+@quotation Note
+Turning on optimizations may lead to unpredictable results when
+stepping through the generated code: the execution may appear to
+"jump around" the source code. This is analogous to turning up the
+optimization level in a regular compiler.
+@end quotation
+@end cartouche
+
+@node Examining the generated code<2>,Putting it all together<2>,Single-stepping through the generated code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 examining-the-generated-code}@anchor{ed}
+@subsubsection Examining the generated code
+
+
+How good is the optimized code?
+
+We can turn up optimizations, by calling
+@pxref{d2,,gccjit;;context;;set_int_option()} with
+@pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
+
+@example
+ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3);
+@end example
+
+@noindent
+
+One of GCC's internal representations is called "gimple". A dump of the
+initial gimple representation of the code can be seen by setting:
+
+@example
+ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1);
+@end example
+
+@noindent
+
+With optimization on and source locations displayed, this gives:
+
+@c We'll use "c" for gimple dumps
+
+@example
+factorial (signed int arg)
+@{
+ <unnamed type> D.80;
+ signed int D.81;
+ signed int D.82;
+ signed int D.83;
+ signed int D.84;
+ signed int D.85;
+ signed int y;
+ signed int x;
+ signed int stack_depth;
+ signed int stack[8];
+
+ try
+ @{
+ initial:
+ stack_depth = 0;
+ stack[stack_depth] = arg;
+ stack_depth = stack_depth + 1;
+ goto instr0;
+ instr0:
+ /* DUP */:
+ stack_depth = stack_depth + -1;
+ x = stack[stack_depth];
+ stack[stack_depth] = x;
+ stack_depth = stack_depth + 1;
+ stack[stack_depth] = x;
+ stack_depth = stack_depth + 1;
+ goto instr1;
+ instr1:
+ /* PUSH_CONST */:
+ stack[stack_depth] = 2;
+ stack_depth = stack_depth + 1;
+ goto instr2;
+
+ /* etc */
+@end example
+
+@noindent
+
+You can see the generated machine code in assembly form via:
+
+@example
+ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1);
+result = ctxt.compile ();
+@end example
+
+@noindent
+
+which shows that (on this x86_64 box) the compiler has unrolled the loop
+and is using MMX instructions to perform several multiplications
+simultaneously:
+
+@example
+ .file "fake.c"
+ .text
+.Ltext0:
+ .p2align 4,,15
+ .globl factorial
+ .type factorial, @@function
+factorial:
+.LFB0:
+ .file 1 "factorial.toy"
+ .loc 1 14 0
+ .cfi_startproc
+.LVL0:
+.L2:
+ .loc 1 26 0
+ cmpl $1, %edi
+ jle .L13
+ leal -1(%rdi), %edx
+ movl %edx, %ecx
+ shrl $2, %ecx
+ leal 0(,%rcx,4), %esi
+ testl %esi, %esi
+ je .L14
+ cmpl $9, %edx
+ jbe .L14
+ leal -2(%rdi), %eax
+ movl %eax, -16(%rsp)
+ leal -3(%rdi), %eax
+ movd -16(%rsp), %xmm0
+ movl %edi, -16(%rsp)
+ movl %eax, -12(%rsp)
+ movd -16(%rsp), %xmm1
+ xorl %eax, %eax
+ movl %edx, -16(%rsp)
+ movd -12(%rsp), %xmm4
+ movd -16(%rsp), %xmm6
+ punpckldq %xmm4, %xmm0
+ movdqa .LC1(%rip), %xmm4
+ punpckldq %xmm6, %xmm1
+ punpcklqdq %xmm0, %xmm1
+ movdqa .LC0(%rip), %xmm0
+ jmp .L5
+ # etc - edited for brevity
+@end example
+
+@noindent
+
+This is clearly overkill for a function that will likely overflow the
+@code{int} type before the vectorization is worthwhile - but then again, this
+is a toy example.
+
+Turning down the optimization level to 2:
+
+@example
+ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 2);
+@end example
+
+@noindent
+
+yields this code, which is simple enough to quote in its entirety:
+
+@example
+ .file "fake.c"
+ .text
+ .p2align 4,,15
+ .globl factorial
+ .type factorial, @@function
+factorial:
+.LFB0:
+ .cfi_startproc
+.L2:
+ cmpl $1, %edi
+ jle .L8
+ movl $1, %edx
+ jmp .L4
+ .p2align 4,,10
+ .p2align 3
+.L6:
+ movl %eax, %edi
+.L4:
+.L5:
+ leal -1(%rdi), %eax
+ imull %edi, %edx
+ cmpl $1, %eax
+ jne .L6
+.L3:
+.L7:
+ imull %edx, %eax
+ ret
+.L8:
+ movl %edi, %eax
+ movl $1, %edx
+ jmp .L7
+ .cfi_endproc
+.LFE0:
+ .size factorial, .-factorial
+ .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2-%@{gcc_release@})"
+ .section .note.GNU-stack,"",@@progbits
+@end example
+
+@noindent
+
+Note that the stack pushing and popping have been eliminated, as has the
+recursive call (in favor of an iteration).
+
+@node Putting it all together<2>,Behind the curtain How does our code get optimized?<2>,Examining the generated code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 putting-it-all-together}@anchor{ee}
+@subsubsection Putting it all together
+
+
+The complete example can be seen in the source tree at
+@code{gcc/jit/docs/examples/tut04-toyvm/toyvm.cc}
+
+along with a Makefile and a couple of sample .toy scripts:
+
+@example
+$ ls -al
+drwxrwxr-x. 2 david david 4096 Sep 19 17:46 .
+drwxrwxr-x. 3 david david 4096 Sep 19 15:26 ..
+-rw-rw-r--. 1 david david 615 Sep 19 12:43 factorial.toy
+-rw-rw-r--. 1 david david 834 Sep 19 13:08 fibonacci.toy
+-rw-rw-r--. 1 david david 238 Sep 19 14:22 Makefile
+-rw-rw-r--. 1 david david 16457 Sep 19 17:07 toyvm.cc
+
+$ make toyvm
+g++ -Wall -g -o toyvm toyvm.cc -lgccjit
+
+$ ./toyvm factorial.toy 10
+interpreter result: 3628800
+compiler result: 3628800
+
+$ ./toyvm fibonacci.toy 10
+interpreter result: 55
+compiler result: 55
+@end example
+
+@noindent
+
+@node Behind the curtain How does our code get optimized?<2>,,Putting it all together<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
+@anchor{cp/intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{ef}
+@subsubsection Behind the curtain: How does our code get optimized?
+
+
+Our example is done, but you may be wondering about exactly how the
+compiler turned what we gave it into the machine code seen above.
+
+We can examine what the compiler is doing in detail by setting:
+
+@example
+state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING, 1);
+state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES, 1);
+@end example
+
+@noindent
+
+This will dump detailed information about the compiler's state to a
+directory under @code{/tmp}, and keep it from being cleaned up.
+
+The precise names and their formats of these files is subject to change.
+Higher optimization levels lead to more files.
+Here's what I saw (edited for brevity; there were almost 200 files):
+
+@example
+intermediate files written to /tmp/libgccjit-KPQbGw
+$ ls /tmp/libgccjit-KPQbGw/
+fake.c.000i.cgraph
+fake.c.000i.type-inheritance
+fake.c.004t.gimple
+fake.c.007t.omplower
+fake.c.008t.lower
+fake.c.011t.eh
+fake.c.012t.cfg
+fake.c.014i.visibility
+fake.c.015i.early_local_cleanups
+fake.c.016t.ssa
+# etc
+@end example
+
+@noindent
+
+The gimple code is converted into Static Single Assignment form,
+with annotations for use when generating the debuginfo:
+
+@example
+$ less /tmp/libgccjit-KPQbGw/fake.c.016t.ssa
+@end example
+
+@noindent
+
+@example
+;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
+
+factorial (signed int arg)
+@{
+ signed int stack[8];
+ signed int stack_depth;
+ signed int x;
+ signed int y;
+ <unnamed type> _20;
+ signed int _21;
+ signed int _38;
+ signed int _44;
+ signed int _51;
+ signed int _56;
+
+initial:
+ stack_depth_3 = 0;
+ # DEBUG stack_depth => stack_depth_3
+ stack[stack_depth_3] = arg_5(D);
+ stack_depth_7 = stack_depth_3 + 1;
+ # DEBUG stack_depth => stack_depth_7
+ # DEBUG instr0 => NULL
+ # DEBUG /* DUP */ => NULL
+ stack_depth_8 = stack_depth_7 + -1;
+ # DEBUG stack_depth => stack_depth_8
+ x_9 = stack[stack_depth_8];
+ # DEBUG x => x_9
+ stack[stack_depth_8] = x_9;
+ stack_depth_11 = stack_depth_8 + 1;
+ # DEBUG stack_depth => stack_depth_11
+ stack[stack_depth_11] = x_9;
+ stack_depth_13 = stack_depth_11 + 1;
+ # DEBUG stack_depth => stack_depth_13
+ # DEBUG instr1 => NULL
+ # DEBUG /* PUSH_CONST */ => NULL
+ stack[stack_depth_13] = 2;
+
+ /* etc; edited for brevity */
+@end example
+
+@noindent
+
+We can perhaps better see the code by turning off
+@pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG}
+statements, giving:
+
+@example
+$ less /tmp/libgccjit-1Hywc0/fake.c.016t.ssa
+@end example
+
+@noindent
+
+@example
+;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
+
+factorial (signed int arg)
+@{
+ signed int stack[8];
+ signed int stack_depth;
+ signed int x;
+ signed int y;
+ <unnamed type> _20;
+ signed int _21;
+ signed int _38;
+ signed int _44;
+ signed int _51;
+ signed int _56;
+
+initial:
+ stack_depth_3 = 0;
+ stack[stack_depth_3] = arg_5(D);
+ stack_depth_7 = stack_depth_3 + 1;
+ stack_depth_8 = stack_depth_7 + -1;
+ x_9 = stack[stack_depth_8];
+ stack[stack_depth_8] = x_9;
+ stack_depth_11 = stack_depth_8 + 1;
+ stack[stack_depth_11] = x_9;
+ stack_depth_13 = stack_depth_11 + 1;
+ stack[stack_depth_13] = 2;
+ stack_depth_15 = stack_depth_13 + 1;
+ stack_depth_16 = stack_depth_15 + -1;
+ y_17 = stack[stack_depth_16];
+ stack_depth_18 = stack_depth_16 + -1;
+ x_19 = stack[stack_depth_18];
+ _20 = x_19 < y_17;
+ _21 = (signed int) _20;
+ stack[stack_depth_18] = _21;
+ stack_depth_23 = stack_depth_18 + 1;
+ stack_depth_24 = stack_depth_23 + -1;
+ x_25 = stack[stack_depth_24];
+ if (x_25 != 0)
+ goto <bb 4> (instr9);
+ else
+ goto <bb 3> (instr4);
+
+instr4:
+/* DUP */:
+ stack_depth_26 = stack_depth_24 + -1;
+ x_27 = stack[stack_depth_26];
+ stack[stack_depth_26] = x_27;
+ stack_depth_29 = stack_depth_26 + 1;
+ stack[stack_depth_29] = x_27;
+ stack_depth_31 = stack_depth_29 + 1;
+ stack[stack_depth_31] = 1;
+ stack_depth_33 = stack_depth_31 + 1;
+ stack_depth_34 = stack_depth_33 + -1;
+ y_35 = stack[stack_depth_34];
+ stack_depth_36 = stack_depth_34 + -1;
+ x_37 = stack[stack_depth_36];
+ _38 = x_37 - y_35;
+ stack[stack_depth_36] = _38;
+ stack_depth_40 = stack_depth_36 + 1;
+ stack_depth_41 = stack_depth_40 + -1;
+ x_42 = stack[stack_depth_41];
+ _44 = factorial (x_42);
+ stack[stack_depth_41] = _44;
+ stack_depth_46 = stack_depth_41 + 1;
+ stack_depth_47 = stack_depth_46 + -1;
+ y_48 = stack[stack_depth_47];
+ stack_depth_49 = stack_depth_47 + -1;
+ x_50 = stack[stack_depth_49];
+ _51 = x_50 * y_48;
+ stack[stack_depth_49] = _51;
+ stack_depth_53 = stack_depth_49 + 1;
+
+ # stack_depth_1 = PHI <stack_depth_24(2), stack_depth_53(3)>
+instr9:
+/* RETURN */:
+ stack_depth_54 = stack_depth_1 + -1;
+ x_55 = stack[stack_depth_54];
+ _56 = x_55;
+ stack =@{v@} @{CLOBBER@};
+ return _56;
+
+@}
+@end example
+
+@noindent
+
+Note in the above how all the @code{gccjit::block} instances we
+created have been consolidated into just 3 blocks in GCC's internal
+representation: @code{initial}, @code{instr4} and @code{instr9}.
+
+@menu
+* Optimizing away stack manipulation: Optimizing away stack manipulation<2>.
+* Elimination of tail recursion: Elimination of tail recursion<2>.
+
+@end menu
+
+@node Optimizing away stack manipulation<2>,Elimination of tail recursion<2>,,Behind the curtain How does our code get optimized?<2>
+@anchor{cp/intro/tutorial04 optimizing-away-stack-manipulation}@anchor{f0}
+@subsubsection Optimizing away stack manipulation
+
+
+Recall our simple implementation of stack operations. Let's examine
+how the stack operations are optimized away.
+
+After a pass of constant-propagation, the depth of the stack at each
+opcode can be determined at compile-time:
+
+@example
+$ less /tmp/libgccjit-1Hywc0/fake.c.021t.ccp1
+@end example
+
+@noindent
+
+@example
+;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
+
+factorial (signed int arg)
+@{
+ signed int stack[8];
+ signed int stack_depth;
+ signed int x;
+ signed int y;
+ <unnamed type> _20;
+ signed int _21;
+ signed int _38;
+ signed int _44;
+ signed int _51;
+
+initial:
+ stack[0] = arg_5(D);
+ x_9 = stack[0];
+ stack[0] = x_9;
+ stack[1] = x_9;
+ stack[2] = 2;
+ y_17 = stack[2];
+ x_19 = stack[1];
+ _20 = x_19 < y_17;
+ _21 = (signed int) _20;
+ stack[1] = _21;
+ x_25 = stack[1];
+ if (x_25 != 0)
+ goto <bb 4> (instr9);
+ else
+ goto <bb 3> (instr4);
+
+instr4:
+/* DUP */:
+ x_27 = stack[0];
+ stack[0] = x_27;
+ stack[1] = x_27;
+ stack[2] = 1;
+ y_35 = stack[2];
+ x_37 = stack[1];
+ _38 = x_37 - y_35;
+ stack[1] = _38;
+ x_42 = stack[1];
+ _44 = factorial (x_42);
+ stack[1] = _44;
+ y_48 = stack[1];
+ x_50 = stack[0];
+ _51 = x_50 * y_48;
+ stack[0] = _51;
+
+instr9:
+/* RETURN */:
+ x_55 = stack[0];
+ x_56 = x_55;
+ stack =@{v@} @{CLOBBER@};
+ return x_56;
+
+@}
+@end example
+
+@noindent
+
+Note how, in the above, all those @code{stack_depth} values are now just
+constants: we're accessing specific stack locations at each opcode.
+
+The "esra" pass ("Early Scalar Replacement of Aggregates") breaks
+out our "stack" array into individual elements:
+
+@example
+$ less /tmp/libgccjit-1Hywc0/fake.c.024t.esra
+@end example
+
+@noindent
+
+@example
+;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
+
+Created a replacement for stack offset: 0, size: 32: stack$0
+Created a replacement for stack offset: 32, size: 32: stack$1
+Created a replacement for stack offset: 64, size: 32: stack$2
+
+Symbols to be put in SSA form
+@{ D.89 D.90 D.91 @}
+Incremental SSA update started at block: 0
+Number of blocks in CFG: 5
+Number of blocks to update: 4 ( 80%)
+
+
+factorial (signed int arg)
+@{
+ signed int stack$2;
+ signed int stack$1;
+ signed int stack$0;
+ signed int stack[8];
+ signed int stack_depth;
+ signed int x;
+ signed int y;
+ <unnamed type> _20;
+ signed int _21;
+ signed int _38;
+ signed int _44;
+ signed int _51;
+
+initial:
+ stack$0_45 = arg_5(D);
+ x_9 = stack$0_45;
+ stack$0_39 = x_9;
+ stack$1_32 = x_9;
+ stack$2_30 = 2;
+ y_17 = stack$2_30;
+ x_19 = stack$1_32;
+ _20 = x_19 < y_17;
+ _21 = (signed int) _20;
+ stack$1_28 = _21;
+ x_25 = stack$1_28;
+ if (x_25 != 0)
+ goto <bb 4> (instr9);
+ else
+ goto <bb 3> (instr4);
+
+instr4:
+/* DUP */:
+ x_27 = stack$0_39;
+ stack$0_22 = x_27;
+ stack$1_14 = x_27;
+ stack$2_12 = 1;
+ y_35 = stack$2_12;
+ x_37 = stack$1_14;
+ _38 = x_37 - y_35;
+ stack$1_10 = _38;
+ x_42 = stack$1_10;
+ _44 = factorial (x_42);
+ stack$1_6 = _44;
+ y_48 = stack$1_6;
+ x_50 = stack$0_22;
+ _51 = x_50 * y_48;
+ stack$0_1 = _51;
+
+ # stack$0_52 = PHI <stack$0_39(2), stack$0_1(3)>
+instr9:
+/* RETURN */:
+ x_55 = stack$0_52;
+ x_56 = x_55;
+ stack =@{v@} @{CLOBBER@};
+ return x_56;
+
+@}
+@end example
+
+@noindent
+
+Hence at this point, all those pushes and pops of the stack are now
+simply assignments to specific temporary variables.
+
+After some copy propagation, the stack manipulation has been completely
+optimized away:
+
+@example
+$ less /tmp/libgccjit-1Hywc0/fake.c.026t.copyprop1
+@end example
+
+@noindent
+
+@example
+;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
+
+factorial (signed int arg)
+@{
+ signed int stack$2;
+ signed int stack$1;
+ signed int stack$0;
+ signed int stack[8];
+ signed int stack_depth;
+ signed int x;
+ signed int y;
+ <unnamed type> _20;
+ signed int _21;
+ signed int _38;
+ signed int _44;
+ signed int _51;
+
+initial:
+ stack$0_39 = arg_5(D);
+ _20 = arg_5(D) <= 1;
+ _21 = (signed int) _20;
+ if (_21 != 0)
+ goto <bb 4> (instr9);
+ else
+ goto <bb 3> (instr4);
+
+instr4:
+/* DUP */:
+ _38 = arg_5(D) + -1;
+ _44 = factorial (_38);
+ _51 = arg_5(D) * _44;
+ stack$0_1 = _51;
+
+ # stack$0_52 = PHI <arg_5(D)(2), _51(3)>
+instr9:
+/* RETURN */:
+ stack =@{v@} @{CLOBBER@};
+ return stack$0_52;
+
+@}
+@end example
+
+@noindent
+
+Later on, another pass finally eliminated @code{stack_depth} local and the
+unused parts of the @cite{stack`} array altogether:
+
+@example
+$ less /tmp/libgccjit-1Hywc0/fake.c.036t.release_ssa
+@end example
+
+@noindent
+
+@example
+;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
+
+Released 44 names, 314.29%, removed 44 holes
+factorial (signed int arg)
+@{
+ signed int stack$0;
+ signed int mult_acc_1;
+ <unnamed type> _5;
+ signed int _6;
+ signed int _7;
+ signed int mul_tmp_10;
+ signed int mult_acc_11;
+ signed int mult_acc_13;
+
+ # arg_9 = PHI <arg_8(D)(0)>
+ # mult_acc_13 = PHI <1(0)>
+initial:
+
+ <bb 5>:
+ # arg_4 = PHI <arg_9(2), _7(3)>
+ # mult_acc_1 = PHI <mult_acc_13(2), mult_acc_11(3)>
+ _5 = arg_4 <= 1;
+ _6 = (signed int) _5;
+ if (_6 != 0)
+ goto <bb 4> (instr9);
+ else
+ goto <bb 3> (instr4);
+
+instr4:
+/* DUP */:
+ _7 = arg_4 + -1;
+ mult_acc_11 = mult_acc_1 * arg_4;
+ goto <bb 5>;
+
+ # stack$0_12 = PHI <arg_4(5)>
+instr9:
+/* RETURN */:
+ mul_tmp_10 = mult_acc_1 * stack$0_12;
+ return mul_tmp_10;
+
+@}
+@end example
+
+@noindent
+
+@node Elimination of tail recursion<2>,,Optimizing away stack manipulation<2>,Behind the curtain How does our code get optimized?<2>
+@anchor{cp/intro/tutorial04 elimination-of-tail-recursion}@anchor{f1}
+@subsubsection Elimination of tail recursion
+
+
+Another significant optimization is the detection that the call to
+@code{factorial} is tail recursion, which can be eliminated in favor of
+an iteration:
+
+@example
+$ less /tmp/libgccjit-1Hywc0/fake.c.030t.tailr1
+@end example
+
+@noindent
+
+@example
+;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0)
+
+
+Symbols to be put in SSA form
+@{ D.88 @}
+Incremental SSA update started at block: 0
+Number of blocks in CFG: 5
+Number of blocks to update: 4 ( 80%)
+
+
+factorial (signed int arg)
+@{
+ signed int stack$2;
+ signed int stack$1;
+ signed int stack$0;
+ signed int stack[8];
+ signed int stack_depth;
+ signed int x;
+ signed int y;
+ signed int mult_acc_1;
+ <unnamed type> _20;
+ signed int _21;
+ signed int _38;
+ signed int mul_tmp_44;
+ signed int mult_acc_51;
+
+ # arg_5 = PHI <arg_39(D)(0), _38(3)>
+ # mult_acc_1 = PHI <1(0), mult_acc_51(3)>
+initial:
+ _20 = arg_5 <= 1;
+ _21 = (signed int) _20;
+ if (_21 != 0)
+ goto <bb 4> (instr9);
+ else
+ goto <bb 3> (instr4);
+
+instr4:
+/* DUP */:
+ _38 = arg_5 + -1;
+ mult_acc_51 = mult_acc_1 * arg_5;
+ goto <bb 2> (initial);
+
+ # stack$0_52 = PHI <arg_5(2)>
+instr9:
+/* RETURN */:
+ stack =@{v@} @{CLOBBER@};
+ mul_tmp_44 = mult_acc_1 * stack$0_52;
+ return mul_tmp_44;
+
+@}
+@end example
+
+@noindent
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Topic Reference<2>,,Tutorial<2>,C++ bindings for libgccjit
+@anchor{cp/topics/index doc}@anchor{f2}@anchor{cp/topics/index topic-reference}@anchor{f3}
+@section Topic Reference
+
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@menu
+* Compilation contexts: Compilation contexts<2>.
+* Objects: Objects<2>.
+* Types: Types<2>.
+* Expressions: Expressions<2>.
+* Creating and using functions: Creating and using functions<2>.
+* Source Locations: Source Locations<2>.
+* Compilation results: Compilation results<2>.
+
+Compilation contexts
+
+* Lifetime-management: Lifetime-management<2>.
+* Thread-safety: Thread-safety<2>.
+* Error-handling: Error-handling<3>.
+* Debugging: Debugging<2>.
+* Options: Options<4>.
+
+Options
+
+* Boolean options: Boolean options<2>.
+* Integer options: Integer options<2>.
+
+Types
+
+* Standard types: Standard types<2>.
+* Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
+* Structures and unions: Structures and unions<2>.
+
+Expressions
+
+* Rvalues: Rvalues<2>.
+* Lvalues: Lvalues<2>.
+* Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
+
+Rvalues
+
+* Simple expressions: Simple expressions<2>.
+* Unary Operations: Unary Operations<2>.
+* Binary Operations: Binary Operations<2>.
+* Comparisons: Comparisons<2>.
+* Function calls: Function calls<2>.
+* Type-coercion: Type-coercion<2>.
+
+Lvalues
+
+* Global variables: Global variables<2>.
+
+Creating and using functions
+
+* Params: Params<2>.
+* Functions: Functions<2>.
+* Blocks: Blocks<2>.
+* Statements: Statements<2>.
+
+Source Locations
+
+* Faking it: Faking it<2>.
+
+@end menu
+
+
+@node Compilation contexts<2>,Objects<2>,,Topic Reference<2>
+@anchor{cp/topics/contexts compilation-contexts}@anchor{f4}@anchor{cp/topics/contexts doc}@anchor{f5}
+@subsection Compilation contexts
+
+
+@geindex gccjit;;context (C++ class)
+@anchor{cp/topics/contexts gccjit context}@anchor{f6}
+@deffn {C++ Class} gccjit::context
+@end deffn
+
+The top-level of the C++ API is the @pxref{f6,,gccjit;;context} type.
+
+A @pxref{f6,,gccjit;;context} instance encapsulates the state of a
+compilation.
+
+You can set up options on it, and add types, functions and code.
+Invoking @pxref{cf,,gccjit;;context;;compile()} on it gives you a
+@pxref{16,,gcc_jit_result *}.
+
+It is a thin wrapper around the C API's @pxref{8,,gcc_jit_context *}.
+
+@menu
+* Lifetime-management: Lifetime-management<2>.
+* Thread-safety: Thread-safety<2>.
+* Error-handling: Error-handling<3>.
+* Debugging: Debugging<2>.
+* Options: Options<4>.
+
+@end menu
+
+@node Lifetime-management<2>,Thread-safety<2>,,Compilation contexts<2>
+@anchor{cp/topics/contexts lifetime-management}@anchor{f7}
+@subsubsection Lifetime-management
+
+
+Contexts are the unit of lifetime-management within the API: objects
+have their lifetime bounded by the context they are created within, and
+cleanup of such objects is done for you when the context is released.
+
+@geindex gccjit;;context;;acquire (C++ function)
+@anchor{cp/topics/contexts gccjit context acquire}@anchor{c9}
+@deffn {C++ Function} gccjit::context gccjit::context::acquire ()
+
+This function acquires a new @pxref{f6,,gccjit;;context} instance,
+which is independent of any others that may be present within this
+process.
+@end deffn
+
+@geindex gccjit;;context;;release (C++ function)
+@anchor{cp/topics/contexts gccjit context release}@anchor{cb}
+@deffn {C++ Function} void gccjit::context::release ()
+
+This function releases all resources associated with the given context.
+Both the context itself and all of its @code{gccjit::object *}
+instances are cleaned up. It should be called exactly once on a given
+context.
+
+It is invalid to use the context or any of its "contextual" objects
+after calling this.
+
+@example
+ctxt.release ();
+@end example
+
+@noindent
+@end deffn
+
+@geindex gccjit;;context;;new_child_context (C++ function)
+@anchor{cp/topics/contexts gccjit context new_child_context}@anchor{f8}
+@deffn {C++ Function} gccjit::context gccjit::context::new_child_context ()
+
+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 gccjit::result of the parent context must
+outlive the gccjit::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.
+@end deffn
+
+@node Thread-safety<2>,Error-handling<3>,Lifetime-management<2>,Compilation contexts<2>
+@anchor{cp/topics/contexts thread-safety}@anchor{f9}
+@subsubsection Thread-safety
+
+
+Instances of @pxref{f6,,gccjit;;context} created via
+@pxref{c9,,gccjit;;context;;acquire()} are independent from each other:
+only one thread may use a given context at once, but multiple threads
+could each have their own contexts without needing locks.
+
+Contexts created via @pxref{f8,,gccjit;;context;;new_child_context()} are
+related to their parent context. They can be partitioned by their
+ultimate ancestor into independent "family trees". Only one thread
+within a process may use a given "family tree" of such contexts at once,
+and if you're using multiple threads you should provide your own locking
+around entire such context partitions.
+
+@node Error-handling<3>,Debugging<2>,Thread-safety<2>,Compilation contexts<2>
+@anchor{cp/topics/contexts error-handling}@anchor{fa}
+@subsubsection Error-handling
+
+
+@c FIXME: How does error-handling work for C++ API?
+
+You can only compile and get code from a context if no errors occur.
+
+In general, if an error occurs when using an API entrypoint, it returns
+NULL. You don't have to check everywhere for NULL results, since the
+API gracefully handles a NULL being passed in for any argument.
+
+Errors are printed on stderr and can be queried using
+@pxref{fb,,gccjit;;context;;get_first_error()}.
+
+@geindex gccjit;;context;;get_first_error (C++ function)
+@anchor{cp/topics/contexts gccjit context get_first_error__gccjit contextP}@anchor{fb}
+@deffn {C++ Function} const char* gccjit::context::get_first_error (gccjit::context* ctxt)
+
+Returns 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.
+@end deffn
+
+@node Debugging<2>,Options<4>,Error-handling<3>,Compilation contexts<2>
+@anchor{cp/topics/contexts debugging}@anchor{fc}
+@subsubsection Debugging
+
+
+@geindex gccjit;;context;;dump_to_file (C++ function)
+@anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{fd}
+@deffn {C++ Function} void gccjit::context::dump_to_file (const std::string& path, int update_locations)
+
+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 @pxref{fe,,gccjit;;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
+@code{GCCJIT::BOOL_OPTION_DEBUGINFO} to allow stepping through the
+code in a debugger.
+@end deffn
+
+@node Options<4>,,Debugging<2>,Compilation contexts<2>
+@anchor{cp/topics/contexts options}@anchor{ff}
+@subsubsection Options
+
+
+@c FIXME: gccjit::context::set_str_option doesn't seem to exist yet in the
+@c C++ API
+
+@menu
+* Boolean options: Boolean options<2>.
+* Integer options: Integer options<2>.
+
+@end menu
+
+@node Boolean options<2>,Integer options<2>,,Options<4>
+@anchor{cp/topics/contexts boolean-options}@anchor{100}
+@subsubsection Boolean options
+
+
+@geindex gccjit;;context;;set_bool_option (C++ function)
+@anchor{cp/topics/contexts gccjit context set_bool_option__enum i}@anchor{d1}
+@deffn {C++ Function} void gccjit::context::set_bool_option (enum gcc_jit_bool_option, int value)
+
+Set a boolean option of the context.
+
+This is a thin wrapper around the C API
+@pxref{1b,,gcc_jit_context_set_bool_option()}; the options have the same
+meaning.
+@end deffn
+
+@node Integer options<2>,,Boolean options<2>,Options<4>
+@anchor{cp/topics/contexts integer-options}@anchor{101}
+@subsubsection Integer options
+
+
+@geindex gccjit;;context;;set_int_option (C++ function)
+@anchor{cp/topics/contexts gccjit context set_int_option__enum i}@anchor{d2}
+@deffn {C++ Function} void gccjit::context::set_int_option (enum gcc_jit_int_option, int value)
+
+Set an integer option of the context.
+
+This is a thin wrapper around the C API
+@pxref{1e,,gcc_jit_context_set_int_option()}; the options have the same
+meaning.
+@end deffn
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Objects<2>,Types<2>,Compilation contexts<2>,Topic Reference<2>
+@anchor{cp/topics/objects objects}@anchor{102}@anchor{cp/topics/objects doc}@anchor{103}
+@subsection Objects
+
+
+@geindex gccjit;;object (C++ class)
+@anchor{cp/topics/objects gccjit object}@anchor{104}
+@deffn {C++ Class} gccjit::object
+@end deffn
+
+Almost every entity in the API (with the exception of
+@pxref{f6,,gccjit;;context} and @pxref{16,,gcc_jit_result *}) is a
+"contextual" object, a @pxref{104,,gccjit;;object}.
+
+A JIT object:
+
+@quotation
+
+
+@itemize *
+
+@item
+is associated with a @pxref{f6,,gccjit;;context}.
+
+@item
+is automatically cleaned up for you when its context is released so
+you don't need to manually track and cleanup all objects, just the
+contexts.
+@end itemize
+@end quotation
+
+The C++ class hierarchy within the @code{gccjit} namespace looks like this:
+
+@example
++- object
+ +- location
+ +- type
+ +- struct
+ +- field
+ +- function
+ +- block
+ +- rvalue
+ +- lvalue
+ +- param
+@end example
+
+@noindent
+
+The @pxref{104,,gccjit;;object} base class has the following operations:
+
+@geindex gccjit;;object;;get_context (C++ function)
+@anchor{cp/topics/objects gccjit object get_contextC}@anchor{105}
+@deffn {C++ Function} gccjit::context gccjit::object::get_context () const
+
+Which context is the obj within?
+@end deffn
+
+@geindex gccjit;;object;;get_debug_string (C++ function)
+@anchor{cp/topics/objects gccjit object get_debug_stringC}@anchor{cc}
+@deffn {C++ Function} std::string gccjit::object::get_debug_string () const
+
+Generate a human-readable description for the given object.
+
+For example,
+
+@example
+printf ("obj: %s\n", obj.get_debug_string ().c_str ());
+@end example
+
+@noindent
+
+might give this text on stdout:
+
+@example
+obj: 4.0 * (float)i
+@end example
+
+@noindent
+@end deffn
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Types<2>,Expressions<2>,Objects<2>,Topic Reference<2>
+@anchor{cp/topics/types doc}@anchor{106}@anchor{cp/topics/types types}@anchor{107}
+@subsection Types
+
+
+@geindex gccjit;;type (C++ class)
+@anchor{cp/topics/types gccjit type}@anchor{108}
+@deffn {C++ Class} gccjit::type
+
+gccjit::type represents a type within the library. It is a subclass
+of @pxref{104,,gccjit;;object}.
+@end deffn
+
+Types can be created in several ways:
+
+
+@itemize *
+
+@item
+fundamental types can be accessed using
+@pxref{ca,,gccjit;;context;;get_type()}:
+
+@example
+gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
+@end example
+
+@noindent
+
+or using the @code{gccjit::context::get_int_type} template:
+
+@example
+gccjit::type t = ctxt.get_int_type <unsigned short> ();
+@end example
+
+@noindent
+
+See @pxref{b,,gcc_jit_context_get_type()} for the available types.
+
+@item
+derived types can be accessed by using functions such as
+@pxref{109,,gccjit;;type;;get_pointer()} and @pxref{10a,,gccjit;;type;;get_const()}:
+
+@example
+gccjit::type const_int_star = int_type.get_const ().get_pointer ();
+gccjit::type int_const_star = int_type.get_pointer ().get_const ();
+@end example
+
+@noindent
+
+@item
+by creating structures (see below).
+@end itemize
+
+@menu
+* Standard types: Standard types<2>.
+* Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>.
+* Structures and unions: Structures and unions<2>.
+
+@end menu
+
+@node Standard types<2>,Pointers const and volatile<2>,,Types<2>
+@anchor{cp/topics/types standard-types}@anchor{10b}
+@subsubsection Standard types
+
+
+@geindex gccjit;;context;;get_type (C++ function)
+@anchor{cp/topics/types gccjit context get_type__enum}@anchor{ca}
+@deffn {C++ Function} gccjit::type gccjit::context::get_type (enum gcc_jit_types)
+
+Access a specific type. This is a thin wrapper around
+@pxref{b,,gcc_jit_context_get_type()}; the parameter has the same meaning.
+@end deffn
+
+@geindex gccjit;;context;;get_int_type (C++ function)
+@anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{10c}
+@deffn {C++ Function} gccjit::type gccjit::context::get_int_type (size_t num_bytes, int is_signed)
+
+Access the integer type of the given size.
+@end deffn
+
+@geindex gccjit;;context;;get_int_type<T> (C++ function)
+@anchor{cp/topics/types gccjit context get_int_type T}@anchor{10d}
+@deffn {C++ Function} gccjit::type gccjit::context::get_int_type<T> ()
+
+Access the given integer type. For example, you could map the
+@code{unsigned short} type into a gccjit::type via:
+
+@example
+gccjit::type t = ctxt.get_int_type <unsigned short> ();
+@end example
+
+@noindent
+@end deffn
+
+@node Pointers const and volatile<2>,Structures and unions<2>,Standard types<2>,Types<2>
+@anchor{cp/topics/types pointers-const-and-volatile}@anchor{10e}
+@subsubsection Pointers, @cite{const}, and @cite{volatile}
+
+
+@geindex gccjit;;type;;get_pointer (C++ function)
+@anchor{cp/topics/types gccjit type get_pointer}@anchor{109}
+@deffn {C++ Function} gccjit::type gccjit::type::get_pointer ()
+
+Given type "T", get type "T*".
+@end deffn
+
+@c FIXME: get_const doesn't seem to exist
+
+@geindex gccjit;;type;;get_const (C++ function)
+@anchor{cp/topics/types gccjit type get_const}@anchor{10a}
+@deffn {C++ Function} gccjit::type gccjit::type::get_const ()
+
+Given type "T", get type "const T".
+@end deffn
+
+@geindex gccjit;;type;;get_volatile (C++ function)
+@anchor{cp/topics/types gccjit type get_volatile}@anchor{10f}
+@deffn {C++ Function} gccjit::type gccjit::type::get_volatile ()
+
+Given type "T", get type "volatile T".
+@end deffn
+
+@geindex gccjit;;context;;new_array_type (C++ function)
+@anchor{cp/topics/types gccjit context new_array_type__gccjit type i gccjit location}@anchor{110}
+@deffn {C++ Function} gccjit::type gccjit::context::new_array_type (gccjit::type element_type, int num_elements, gccjit::location loc)
+
+Given type "T", get type "T[N]" (for a constant N).
+Param "loc" is optional.
+@end deffn
+
+@node Structures and unions<2>,,Pointers const and volatile<2>,Types<2>
+@anchor{cp/topics/types structures-and-unions}@anchor{111}
+@subsubsection Structures and unions
+
+
+@geindex gccjit;;struct_ (C++ class)
+@anchor{cp/topics/types gccjit struct_}@anchor{112}
+@deffn {C++ Class} gccjit::struct_
+@end deffn
+
+A compound type analagous to a C @cite{struct}.
+
+@pxref{112,,gccjit;;struct_} is a subclass of @pxref{108,,gccjit;;type} (and thus
+of @pxref{104,,gccjit;;object} in turn).
+
+@geindex gccjit;;field (C++ class)
+@anchor{cp/topics/types gccjit field}@anchor{113}
+@deffn {C++ Class} gccjit::field
+@end deffn
+
+A field within a @pxref{112,,gccjit;;struct_}.
+
+@pxref{113,,gccjit;;field} is a subclass of @pxref{104,,gccjit;;object}.
+
+You can model C @cite{struct} types by creating @pxref{112,,gccjit;;struct_} and
+@pxref{113,,gccjit;;field} instances, in either order:
+
+
+@itemize *
+
+@item
+by creating the fields, then the structure. For example, to model:
+
+@example
+struct coord @{double x; double y; @};
+@end example
+
+@noindent
+
+you could call:
+
+@example
+gccjit::field field_x = ctxt.new_field (double_type, "x");
+gccjit::field field_y = ctxt.new_field (double_type, "y");
+std::vector fields;
+fields.push_back (field_x);
+fields.push_back (field_y);
+gccjit::struct_ coord = ctxt.new_struct_type ("coord", fields);
+@end example
+
+@noindent
+
+@item
+by creating the structure, then populating it with fields, typically
+to allow modelling self-referential structs such as:
+
+@example
+struct node @{ int m_hash; struct node *m_next; @};
+@end example
+
+@noindent
+
+like this:
+
+@example
+gccjit::struct_ node = ctxt.new_opaque_struct_type ("node");
+gccjit::type node_ptr = node.get_pointer ();
+gccjit::field field_hash = ctxt.new_field (int_type, "m_hash");
+gccjit::field field_next = ctxt.new_field (node_ptr, "m_next");
+std::vector fields;
+fields.push_back (field_hash);
+fields.push_back (field_next);
+node.set_fields (fields);
+@end example
+
+@noindent
+@end itemize
+
+@c FIXME: the above API doesn't seem to exist yet
+
+@geindex gccjit;;context;;new_field (C++ function)
+@anchor{cp/topics/types gccjit context new_field__gccjit type cCP gccjit location}@anchor{114}
+@deffn {C++ Function} gccjit::field gccjit::context::new_field (gccjit::type type, const char* name, gccjit::location loc)
+
+Construct a new field, with the given type and name.
+@end deffn
+
+@geindex gccjit;;context;;new_struct_type (C++ function)
+@anchor{cp/topics/types gccjit context new_struct_type__ssCR std vector field R gccjit location}@anchor{115}
+@deffn {C++ Function} gccjit::struct_ gccjit::context::new_struct_type (const std::string& name, std::vector<field>& fields, gccjit::location loc)
+
+@quotation
+
+Construct a new struct type, with the given name and fields.
+@end quotation
+@end deffn
+
+@geindex gccjit;;context;;new_opaque_struct (C++ function)
+@anchor{cp/topics/types gccjit context new_opaque_struct__ssCR gccjit location}@anchor{116}
+@deffn {C++ Function} gccjit::struct_ gccjit::context::new_opaque_struct (const std::string& name, gccjit::location loc)
+
+Construct a new struct type, with the given name, but without
+specifying the fields. The fields can be omitted (in which case the
+size of the struct is not known), or later specified using
+@pxref{75,,gcc_jit_struct_set_fields()}.
+@end deffn
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Expressions<2>,Creating and using functions<2>,Types<2>,Topic Reference<2>
+@anchor{cp/topics/expressions expressions}@anchor{117}@anchor{cp/topics/expressions doc}@anchor{118}
+@subsection Expressions
+
+
+@menu
+* Rvalues: Rvalues<2>.
+* Lvalues: Lvalues<2>.
+* Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>.
+
+Rvalues
+
+* Simple expressions: Simple expressions<2>.
+* Unary Operations: Unary Operations<2>.
+* Binary Operations: Binary Operations<2>.
+* Comparisons: Comparisons<2>.
+* Function calls: Function calls<2>.
+* Type-coercion: Type-coercion<2>.
+
+Lvalues
+
+* Global variables: Global variables<2>.
+
+@end menu
+
+
+@node Rvalues<2>,Lvalues<2>,,Expressions<2>
+@anchor{cp/topics/expressions rvalues}@anchor{119}
+@subsubsection Rvalues
+
+
+@geindex gccjit;;rvalue (C++ class)
+@anchor{cp/topics/expressions gccjit rvalue}@anchor{11a}
+@deffn {C++ Class} gccjit::rvalue
+@end deffn
+
+A @pxref{11a,,gccjit;;rvalue} is an expression that can be computed. It is a
+subclass of @pxref{104,,gccjit;;object}, and is a thin wrapper around
+@pxref{13,,gcc_jit_rvalue *} from the C API.
+
+It can be simple, e.g.:
+
+@quotation
+
+
+@itemize *
+
+@item
+an integer value e.g. @cite{0} or @cite{42}
+
+@item
+a string literal e.g. @cite{"Hello world"}
+
+@item
+a variable e.g. @cite{i}. These are also lvalues (see below).
+@end itemize
+@end quotation
+
+or compound e.g.:
+
+@quotation
+
+
+@itemize *
+
+@item
+a unary expression e.g. @cite{!cond}
+
+@item
+a binary expression e.g. @cite{(a + b)}
+
+@item
+a function call e.g. @cite{get_distance (&player_ship@comma{} &target)}
+
+@item
+etc.
+@end itemize
+@end quotation
+
+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).
+
+@geindex gccjit;;rvalue;;get_type (C++ function)
+@anchor{cp/topics/expressions gccjit rvalue get_type}@anchor{11b}
+@deffn {C++ Function} gccjit::type gccjit::rvalue::get_type ()
+
+Get the type of this rvalue.
+@end deffn
+
+@menu
+* Simple expressions: Simple expressions<2>.
+* Unary Operations: Unary Operations<2>.
+* Binary Operations: Binary Operations<2>.
+* Comparisons: Comparisons<2>.
+* Function calls: Function calls<2>.
+* Type-coercion: Type-coercion<2>.
+
+@end menu
+
+@node Simple expressions<2>,Unary Operations<2>,,Rvalues<2>
+@anchor{cp/topics/expressions simple-expressions}@anchor{11c}
+@subsubsection Simple expressions
+
+
+@geindex gccjit;;context;;new_rvalue (C++ function)
+@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{de}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, int value) const
+
+Given a numeric type (integer or floating point), build an rvalue for
+the given constant @code{int} value.
+@end deffn
+
+@geindex gccjit;;context;;zero (C++ function)
+@anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{da}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::zero (gccjit::type numeric_type) const
+
+Given a numeric type (integer or floating point), get the rvalue for
+zero. Essentially this is just a shortcut for:
+
+@example
+ctxt.new_rvalue (numeric_type, 0)
+@end example
+
+@noindent
+@end deffn
+
+@geindex gccjit;;context;;one (C++ function)
+@anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{11d}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::one (gccjit::type numeric_type) const
+
+Given a numeric type (integer or floating point), get the rvalue for
+zero. Essentially this is just a shortcut for:
+
+@example
+ctxt.new_rvalue (numeric_type, 1)
+@end example
+
+@noindent
+@end deffn
+
+@geindex gccjit;;context;;new_rvalue (C++ function)
+@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{11e}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, double value) const
+
+Given a numeric type (integer or floating point), build an rvalue for
+the given constant value.
+@end deffn
+
+@geindex gccjit;;context;;new_rvalue (C++ function)
+@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type voidPC}@anchor{11f}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type pointer_type, void* value) const
+
+Given a pointer type, build an rvalue for the given address.
+@end deffn
+
+@geindex gccjit;;context;;new_rvalue (C++ function)
+@anchor{cp/topics/expressions gccjit context new_rvalue__ssCRC}@anchor{120}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (const std::string& value) const
+
+Generate an rvalue of type @code{GCC_JIT_TYPE_CONST_CHAR_PTR} for
+the given string. This is akin to a string literal.
+@end deffn
+
+@node Unary Operations<2>,Binary Operations<2>,Simple expressions<2>,Rvalues<2>
+@anchor{cp/topics/expressions unary-operations}@anchor{121}
+@subsubsection Unary Operations
+
+
+@geindex gccjit;;context;;new_unary_op (C++ function)
+@anchor{cp/topics/expressions gccjit context new_unary_op__enum gccjit type gccjit rvalue gccjit location}@anchor{122}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_unary_op (enum gcc_jit_unary_op, gccjit::type result_type, gccjit::rvalue rvalue, gccjit::location loc)
+
+Build a unary operation out of an input rvalue.
+
+Parameter @code{loc} is optional.
+
+This is a thin wrapper around the C API's
+@pxref{80,,gcc_jit_context_new_unary_op()} and the available unary
+operations are documented there.
+@end deffn
+
+There are shorter ways to spell the various specific kinds of unary
+operation:
+
+@geindex gccjit;;context;;new_minus (C++ function)
+@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit location}@anchor{123}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
+
+Negate an arithmetic value; for example:
+
+@example
+gccjit::rvalue negpi = ctxt.new_minus (t_double, pi);
+@end example
+
+@noindent
+
+builds the equivalent of this C expression:
+
+@example
+-pi
+@end example
+
+@noindent
+@end deffn
+
+@geindex new_bitwise_negate (C++ function)
+@anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{124}
+@deffn {C++ Function} gccjit::rvalue new_bitwise_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
+
+Bitwise negation of an integer value (one's complement); for example:
+
+@example
+gccjit::rvalue mask = ctxt.new_bitwise_negate (t_int, a);
+@end example
+
+@noindent
+
+builds the equivalent of this C expression:
+
+@example
+~a
+@end example
+
+@noindent
+@end deffn
+
+@geindex new_logical_negate (C++ function)
+@anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{125}
+@deffn {C++ Function} gccjit::rvalue new_logical_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
+
+Logical negation of an arithmetic or pointer value; for example:
+
+@example
+gccjit::rvalue guard = ctxt.new_logical_negate (t_bool, cond);
+@end example
+
+@noindent
+
+builds the equivalent of this C expression:
+
+@example
+!cond
+@end example
+
+@noindent
+@end deffn
+
+The most concise way to spell them is with overloaded operators:
+
+@geindex operator- (C++ function)
+@anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{126}
+@deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a)
+
+@example
+gccjit::rvalue negpi = -pi;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator~ (C++ function)
+@anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{127}
+@deffn {C++ Function} gccjit::rvalue operator~ (gccjit::rvalue a)
+
+@example
+gccjit::rvalue mask = ~a;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator! (C++ function)
+@anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{128}
+@deffn {C++ Function} gccjit::rvalue operator! (gccjit::rvalue a)
+
+@example
+gccjit::rvalue guard = !cond;
+@end example
+
+@noindent
+@end deffn
+
+@node Binary Operations<2>,Comparisons<2>,Unary Operations<2>,Rvalues<2>
+@anchor{cp/topics/expressions binary-operations}@anchor{129}
+@subsubsection Binary Operations
+
+
+@geindex gccjit;;context;;new_binary_op (C++ function)
+@anchor{cp/topics/expressions gccjit context new_binary_op__enum gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{ce}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_binary_op (enum gcc_jit_binary_op, gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+
+Build a binary operation out of two constituent rvalues.
+
+Parameter @code{loc} is optional.
+
+This is a thin wrapper around the C API's
+@pxref{12,,gcc_jit_context_new_binary_op()} and the available binary
+operations are documented there.
+@end deffn
+
+There are shorter ways to spell the various specific kinds of binary
+operation:
+
+@geindex gccjit;;context;;new_plus (C++ function)
+@anchor{cp/topics/expressions gccjit context new_plus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{12a}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_plus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_minus (C++ function)
+@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{12b}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_mult (C++ function)
+@anchor{cp/topics/expressions gccjit context new_mult__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{12c}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_mult (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_divide (C++ function)
+@anchor{cp/topics/expressions gccjit context new_divide__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{12d}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_divide (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_modulo (C++ function)
+@anchor{cp/topics/expressions gccjit context new_modulo__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{12e}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_modulo (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_bitwise_and (C++ function)
+@anchor{cp/topics/expressions gccjit context new_bitwise_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{12f}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_bitwise_xor (C++ function)
+@anchor{cp/topics/expressions gccjit context new_bitwise_xor__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{130}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_xor (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_bitwise_or (C++ function)
+@anchor{cp/topics/expressions gccjit context new_bitwise_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{131}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_logical_and (C++ function)
+@anchor{cp/topics/expressions gccjit context new_logical_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{132}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_logical_or (C++ function)
+@anchor{cp/topics/expressions gccjit context new_logical_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{133}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+The most concise way to spell them is with overloaded operators:
+
+@geindex operator+ (C++ function)
+@anchor{cp/topics/expressions add-operator__gccjit rvalue gccjit rvalue}@anchor{134}
+@deffn {C++ Function} gccjit::rvalue operator+ (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue sum = a + b;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator- (C++ function)
+@anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{135}
+@deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue diff = a - b;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator* (C++ function)
+@anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{136}
+@deffn {C++ Function} gccjit::rvalue operator* (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue prod = a * b;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator/ (C++ function)
+@anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{137}
+@deffn {C++ Function} gccjit::rvalue operator/ (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue result = a / b;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator% (C++ function)
+@anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{138}
+@deffn {C++ Function} gccjit::rvalue operator% (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue mod = a % b;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator& (C++ function)
+@anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{139}
+@deffn {C++ Function} gccjit::rvalue operator& (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue x = a & b;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator^ (C++ function)
+@anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{13a}
+@deffn {C++ Function} gccjit::rvalue operator^ (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue x = a ^ b;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator| (C++ function)
+@anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{13b}
+@deffn {C++ Function} gccjit::rvalue operator| (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue x = a | b;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator&& (C++ function)
+@anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{13c}
+@deffn {C++ Function} gccjit::rvalue operator&& (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue cond = a && b;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator|| (C++ function)
+@anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{13d}
+@deffn {C++ Function} gccjit::rvalue operator|| (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue cond = a || b;
+@end example
+
+@noindent
+@end deffn
+
+These can of course be combined, giving a terse way to build compound
+expressions:
+
+@quotation
+
+@example
+gccjit::rvalue discriminant = (b * b) - (four * a * c);
+@end example
+
+@noindent
+@end quotation
+
+@node Comparisons<2>,Function calls<2>,Binary Operations<2>,Rvalues<2>
+@anchor{cp/topics/expressions comparisons}@anchor{13e}
+@subsubsection Comparisons
+
+
+@geindex gccjit;;context;;new_comparison (C++ function)
+@anchor{cp/topics/expressions gccjit context new_comparison__enum gccjit rvalue gccjit rvalue gccjit location}@anchor{db}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_comparison (enum gcc_jit_comparison, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+
+Build a boolean rvalue out of the comparison of two other rvalues.
+
+Parameter @code{loc} is optional.
+
+This is a thin wrapper around the C API's
+@pxref{2c,,gcc_jit_context_new_comparison()} and the available kinds
+of comparison are documented there.
+@end deffn
+
+There are shorter ways to spell the various specific kinds of binary
+operation:
+
+@geindex gccjit;;context;;new_eq (C++ function)
+@anchor{cp/topics/expressions gccjit context new_eq__gccjit rvalue gccjit rvalue gccjit location}@anchor{13f}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_eq (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_ne (C++ function)
+@anchor{cp/topics/expressions gccjit context new_ne__gccjit rvalue gccjit rvalue gccjit location}@anchor{140}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_ne (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_lt (C++ function)
+@anchor{cp/topics/expressions gccjit context new_lt__gccjit rvalue gccjit rvalue gccjit location}@anchor{141}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_lt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_le (C++ function)
+@anchor{cp/topics/expressions gccjit context new_le__gccjit rvalue gccjit rvalue gccjit location}@anchor{142}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_le (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_gt (C++ function)
+@anchor{cp/topics/expressions gccjit context new_gt__gccjit rvalue gccjit rvalue gccjit location}@anchor{143}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_gt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+@geindex gccjit;;context;;new_ge (C++ function)
+@anchor{cp/topics/expressions gccjit context new_ge__gccjit rvalue gccjit rvalue gccjit location}@anchor{144}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_ge (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
+@end deffn
+
+The most concise way to spell them is with overloaded operators:
+
+@geindex operator== (C++ function)
+@anchor{cp/topics/expressions eq-operator__gccjit rvalue gccjit rvalue}@anchor{145}
+@deffn {C++ Function} gccjit::rvalue operator== (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue cond = (a == ctxt.zero (t_int));
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator!= (C++ function)
+@anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{146}
+@deffn {C++ Function} gccjit::rvalue operator!= (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue cond = (i != j);
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator< (C++ function)
+@anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{147}
+@deffn {C++ Function} gccjit::rvalue operator< (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue cond = i < n;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator<= (C++ function)
+@anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{148}
+@deffn {C++ Function} gccjit::rvalue operator<= (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue cond = i <= n;
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator> (C++ function)
+@anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{149}
+@deffn {C++ Function} gccjit::rvalue operator> (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue cond = (ch > limit);
+@end example
+
+@noindent
+@end deffn
+
+@geindex operator>= (C++ function)
+@anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{14a}
+@deffn {C++ Function} gccjit::rvalue operator>= (gccjit::rvalue a, gccjit::rvalue b)
+
+@example
+gccjit::rvalue cond = (score >= ctxt.new_rvalue (t_int, 100));
+@end example
+
+@noindent
+@end deffn
+
+@c TODO: beyond this point
+
+@node Function calls<2>,Type-coercion<2>,Comparisons<2>,Rvalues<2>
+@anchor{cp/topics/expressions function-calls}@anchor{14b}
+@subsubsection Function calls
+
+
+@geindex gcc_jit_context_new_call (C++ function)
+@anchor{cp/topics/expressions gcc_jit_context_new_call__gcc_jit_contextP gcc_jit_locationP gcc_jit_functionP i gcc_jit_rvaluePP}@anchor{14c}
+@deffn {C++ Function} gcc_jit_rvalue* gcc_jit_context_new_call (gcc_jit_context* ctxt, gcc_jit_location* loc, gcc_jit_function* func, int numargs, gcc_jit_rvalue** args)
+
+Given a function and the given table of argument rvalues, construct a
+call to the function, with the result as an rvalue.
+
+@cartouche
+@quotation Note
+@code{gccjit::context::new_call()} merely builds a
+@pxref{11a,,gccjit;;rvalue} i.e. an expression that can be evaluated,
+perhaps as part of a more complicated expression.
+The call @emph{won't} happen unless you add a statement to a function
+that evaluates the expression.
+
+For example, if you want to call a function and discard the result
+(or to call a function with @code{void} return type), use
+@pxref{14d,,gccjit;;block;;add_eval()}:
+
+@example
+/* Add "(void)printf (arg0, arg1);". */
+block.add_eval (ctxt.new_call (printf_func, arg0, arg1));
+@end example
+
+@noindent
+@end quotation
+@end cartouche
+@end deffn
+
+@node Type-coercion<2>,,Function calls<2>,Rvalues<2>
+@anchor{cp/topics/expressions type-coercion}@anchor{14e}
+@subsubsection Type-coercion
+
+
+@geindex gccjit;;context;;new_cast (C++ function)
+@anchor{cp/topics/expressions gccjit context new_cast__gccjit rvalue gccjit type gccjit location}@anchor{14f}
+@deffn {C++ Function} gccjit::rvalue gccjit::context::new_cast (gccjit::rvalue rvalue, gccjit::type type, gccjit::location loc)
+
+Given an rvalue of T, construct another rvalue of another type.
+
+Currently only a limited set of conversions are possible:
+
+@quotation
+
+
+@itemize *
+
+@item
+int <-> float
+
+@item
+int <-> bool
+
+@item
+P* <-> Q*, for pointer types P and Q
+@end itemize
+@end quotation
+@end deffn
+
+@node Lvalues<2>,Working with pointers structs and unions<2>,Rvalues<2>,Expressions<2>
+@anchor{cp/topics/expressions lvalues}@anchor{150}
+@subsubsection Lvalues
+
+
+@geindex gccjit;;lvalue (C++ class)
+@anchor{cp/topics/expressions gccjit lvalue}@anchor{151}
+@deffn {C++ Class} gccjit::lvalue
+@end deffn
+
+An lvalue is something that can of the @emph{left}-hand side of an assignment:
+a storage area (such as a variable). It is a subclass of
+@pxref{11a,,gccjit;;rvalue}, where the rvalue is computed by reading from the
+storage area.
+
+It iss a thin wrapper around @pxref{24,,gcc_jit_lvalue *} from the C API.
+
+@geindex gccjit;;lvalue;;get_address (C++ function)
+@anchor{cp/topics/expressions gccjit lvalue get_address__gccjit location}@anchor{152}
+@deffn {C++ Function} gccjit::rvalue gccjit::lvalue::get_address (gccjit::location loc)
+
+Take the address of an lvalue; analogous to:
+
+@example
+&(EXPR)
+@end example
+
+@noindent
+
+in C.
+
+Parameter "loc" is optional.
+@end deffn
+
+@menu
+* Global variables: Global variables<2>.
+
+@end menu
+
+@node Global variables<2>,,,Lvalues<2>
+@anchor{cp/topics/expressions global-variables}@anchor{153}
+@subsubsection Global variables
+
+
+@geindex gccjit;;context;;new_global (C++ function)
+@anchor{cp/topics/expressions gccjit context new_global__gccjit type cCP gccjit location}@anchor{154}
+@deffn {C++ Function} gccjit::lvalue gccjit::context::new_global (gccjit::type type, const char* name, gccjit::location loc)
+
+Add a new global variable of the given type and name to the context.
+@end deffn
+
+@node Working with pointers structs and unions<2>,,Lvalues<2>,Expressions<2>
+@anchor{cp/topics/expressions working-with-pointers-structs-and-unions}@anchor{155}
+@subsubsection Working with pointers, structs and unions
+
+
+@geindex gccjit;;rvalue;;dereference (C++ function)
+@anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{156}
+@deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference (gccjit::location loc)
+
+Given an rvalue of pointer type @code{T *}, dereferencing the pointer,
+getting an lvalue of type @code{T}. Analogous to:
+
+@example
+*(EXPR)
+@end example
+
+@noindent
+
+in C.
+
+Parameter "loc" is optional.
+@end deffn
+
+If you don't need to specify the location, this can also be expressed using
+an overloaded operator:
+
+
+@deffn {C++ Function} gccjit::lvalue gccjit::rvalue::operator* ();
+
+@example
+gccjit::lvalue content = *ptr;
+@end example
+
+@noindent
+@end deffn
+
+Field access is provided separately for both lvalues and rvalues:
+
+@geindex gccjit;;lvalue;;access_field (C++ function)
+@anchor{cp/topics/expressions gccjit lvalue access_field__gccjit field gccjit location}@anchor{157}
+@deffn {C++ Function} gccjit::lvalue gccjit::lvalue::access_field (gccjit::field field, gccjit::location loc)
+
+Given an lvalue of struct or union type, access the given field,
+getting an lvalue of the field's type. Analogous to:
+
+@example
+(EXPR).field = ...;
+@end example
+
+@noindent
+
+in C.
+@end deffn
+
+@geindex gccjit;;rvalue;;access_field (C++ function)
+@anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{158}
+@deffn {C++ Function} gccjit::rvalue gccjit::rvalue::access_field (gccjit::field field, gccjit::location loc)
+
+Given an rvalue of struct or union type, access the given field
+as an rvalue. Analogous to:
+
+@example
+(EXPR).field
+@end example
+
+@noindent
+
+in C.
+@end deffn
+
+@geindex gccjit;;rvalue;;dereference_field (C++ function)
+@anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{159}
+@deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference_field (gccjit::field field, gccjit::location loc)
+
+Given an rvalue of pointer type @code{T *} where T is of struct or union
+type, access the given field as an lvalue. Analogous to:
+
+@example
+(EXPR)->field
+@end example
+
+@noindent
+
+in C, itself equivalent to @code{(*EXPR).FIELD}.
+@end deffn
+
+@geindex gccjit;;context;;new_array_access (C++ function)
+@anchor{cp/topics/expressions gccjit context new_array_access__gccjit rvalue gccjit rvalue gccjit location}@anchor{15a}
+@deffn {C++ Function} gccjit::lvalue gccjit::context::new_array_access (gccjit::rvalue ptr, gccjit::rvalue index, gccjit::location loc)
+
+Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at
+the given index, using standard C array indexing rules i.e. each
+increment of @code{index} corresponds to @code{sizeof(T)} bytes.
+Analogous to:
+
+@example
+PTR[INDEX]
+@end example
+
+@noindent
+
+in C (or, indeed, to @code{PTR + INDEX}).
+
+Parameter "loc" is optional.
+@end deffn
+
+For array accesses where you don't need to specify a @pxref{fe,,gccjit;;location},
+two overloaded operators are available:
+
+@quotation
+
+gccjit::lvalue gccjit::rvalue::operator[] (gccjit::rvalue index)
+
+@example
+gccjit::lvalue element = array[idx];
+@end example
+
+@noindent
+
+gccjit::lvalue gccjit::rvalue::operator[] (int index)
+
+@example
+gccjit::lvalue element = array[0];
+@end example
+
+@noindent
+@end quotation
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Creating and using functions<2>,Source Locations<2>,Expressions<2>,Topic Reference<2>
+@anchor{cp/topics/functions doc}@anchor{15b}@anchor{cp/topics/functions creating-and-using-functions}@anchor{15c}
+@subsection Creating and using functions
+
+
+@menu
+* Params: Params<2>.
+* Functions: Functions<2>.
+* Blocks: Blocks<2>.
+* Statements: Statements<2>.
+
+@end menu
+
+@node Params<2>,Functions<2>,,Creating and using functions<2>
+@anchor{cp/topics/functions params}@anchor{15d}
+@subsubsection Params
+
+
+@geindex gccjit;;param (C++ class)
+@anchor{cp/topics/functions gccjit param}@anchor{15e}
+@deffn {C++ Class} gccjit::param
+
+A @cite{gccjit::param} represents a parameter to a function.
+@end deffn
+
+@geindex gccjit;;context;;new_param (C++ function)
+@anchor{cp/topics/functions gccjit context new_param__gccjit type cCP gccjit location}@anchor{cd}
+@deffn {C++ Function} gccjit::param gccjit::context::new_param (gccjit::type type, const char* name, gccjit::location loc)
+
+In preparation for creating a function, create a new parameter of the
+given type and name.
+@end deffn
+
+@pxref{15e,,gccjit;;param} is a subclass of @pxref{151,,gccjit;;lvalue} (and thus
+of @pxref{11a,,gccjit;;rvalue} and @pxref{104,,gccjit;;object}). It is a thin
+wrapper around the C API's @pxref{25,,gcc_jit_param *}.
+
+@node Functions<2>,Blocks<2>,Params<2>,Creating and using functions<2>
+@anchor{cp/topics/functions functions}@anchor{15f}
+@subsubsection Functions
+
+
+@geindex gccjit;;function (C++ class)
+@anchor{cp/topics/functions gccjit function}@anchor{160}
+@deffn {C++ Class} gccjit::function
+
+A @cite{gccjit::function} represents a function - either one that we're
+creating ourselves, or one that we're referencing.
+@end deffn
+
+
+@deffn {C++ Function} gccjit::function gccjit::context::new_function (enum gcc_jit_function_kind, gccjit::type return_type, const char *name, std::vector<param> ¶ms, int is_variadic, gccjit::location loc) \
+
+Create a gcc_jit_function with the given name and parameters.
+
+Parameters "is_variadic" and "loc" are optional.
+
+This is a wrapper around the C API's @pxref{11,,gcc_jit_context_new_function()}.
+@end deffn
+
+@geindex gccjit;;context;;get_builtin_function (C++ function)
+@anchor{cp/topics/functions gccjit context get_builtin_function__cCP}@anchor{161}
+@deffn {C++ Function} gccjit::function gccjit::context::get_builtin_function (const char* name)
+
+This is a wrapper around the C API's
+@pxref{b1,,gcc_jit_context_get_builtin_function()}.
+@end deffn
+
+@geindex gccjit;;function;;get_param (C++ function)
+@anchor{cp/topics/functions gccjit function get_param__iC}@anchor{162}
+@deffn {C++ Function} gccjit::param gccjit::function::get_param (int index) const
+
+Get the param of the given index (0-based).
+@end deffn
+
+@geindex gccjit;;function;;dump_to_dot (C++ function)
+@anchor{cp/topics/functions gccjit function dump_to_dot__cCP}@anchor{e0}
+@deffn {C++ Function} void gccjit::function::dump_to_dot (const char* path)
+
+Emit the function in graphviz format to the given path.
+@end deffn
+
+@geindex gccjit;;function;;new_local (C++ function)
+@anchor{cp/topics/functions gccjit function new_local__gccjit type cCP gccjit location}@anchor{d7}
+@deffn {C++ Function} gccjit::lvalue gccjit::function::new_local (gccjit::type type, const char* name, gccjit::location loc)
+
+Create a new local variable within the function, of the given type and
+name.
+@end deffn
+
+@node Blocks<2>,Statements<2>,Functions<2>,Creating and using functions<2>
+@anchor{cp/topics/functions blocks}@anchor{163}
+@subsubsection Blocks
+
+
+@geindex gccjit;;block (C++ class)
+@anchor{cp/topics/functions gccjit block}@anchor{164}
+@deffn {C++ Class} gccjit::block
+
+A @cite{gccjit::block} represents a basic block within a function i.e. a
+sequence of statements with a single entry point and a single exit
+point.
+
+@pxref{164,,gccjit;;block} is a subclass of @pxref{104,,gccjit;;object}.
+
+The first basic block that you create within a function will
+be the entrypoint.
+
+Each basic block that you create within a function must be
+terminated, either with a conditional, a jump, or a return.
+
+It's legal to have multiple basic blocks that return within
+one function.
+@end deffn
+
+@geindex gccjit;;function;;new_block (C++ function)
+@anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{165}
+@deffn {C++ Function} gccjit::block gccjit::function::new_block (const char* name)
+
+Create a basic block of the given name. The name may be NULL, but
+providing meaningful names is often helpful when debugging: it may
+show up in dumps of the internal representation, and in error
+messages.
+@end deffn
+
+@node Statements<2>,,Blocks<2>,Creating and using functions<2>
+@anchor{cp/topics/functions statements}@anchor{166}
+@subsubsection Statements
+
+
+@geindex gccjit;;block;;add_eval (C++ function)
+@anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{14d}
+@deffn {C++ Function} void gccjit::block::add_eval (gccjit::rvalue rvalue, gccjit::location loc)
+
+Add evaluation of an rvalue, discarding the result
+(e.g. a function call that "returns" void).
+
+This is equivalent to this C code:
+
+@example
+(void)expression;
+@end example
+
+@noindent
+@end deffn
+
+@geindex gccjit;;block;;add_assignment (C++ function)
+@anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{d9}
+@deffn {C++ Function} void gccjit::block::add_assignment (gccjit::lvalue lvalue, gccjit::rvalue rvalue, gccjit::location loc)
+
+Add evaluation of an rvalue, assigning the result to the given
+lvalue.
+
+This is roughly equivalent to this C code:
+
+@example
+lvalue = rvalue;
+@end example
+
+@noindent
+@end deffn
+
+@geindex gccjit;;block;;add_assignment_op (C++ function)
+@anchor{cp/topics/functions gccjit block add_assignment_op__gccjit lvalue enum gccjit rvalue gccjit location}@anchor{dd}
+@deffn {C++ Function} void gccjit::block::add_assignment_op (gccjit::lvalue lvalue, enum gcc_jit_binary_op, gccjit::rvalue rvalue, gccjit::location loc)
+
+Add evaluation of an rvalue, using the result to modify an
+lvalue.
+
+This is analogous to "+=" and friends:
+
+@example
+lvalue += rvalue;
+lvalue *= rvalue;
+lvalue /= rvalue;
+@end example
+
+@noindent
+
+etc. For example:
+
+@example
+/* "i++" */
+loop_body.add_assignment_op (
+ i,
+ GCC_JIT_BINARY_OP_PLUS,
+ ctxt.one (int_type));
+@end example
+
+@noindent
+@end deffn
+
+@geindex gccjit;;block;;add_comment (C++ function)
+@anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{e8}
+@deffn {C++ Function} void gccjit::block::add_comment (const char* text, gccjit::location loc)
+
+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 @pxref{5b,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}
+and @pxref{1c,,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.
+
+Parameter "loc" is optional.
+@end deffn
+
+@geindex gccjit;;block;;end_with_conditional (C++ function)
+@anchor{cp/topics/functions gccjit block end_with_conditional__gccjit rvalue gccjit block gccjit block gccjit location}@anchor{dc}
+@deffn {C++ Function} void gccjit::block::end_with_conditional (gccjit::rvalue boolval, gccjit::block on_true, gccjit::block on_false, gccjit::location loc)
+
+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:
+
+@example
+if (boolval)
+ goto on_true;
+else
+ goto on_false;
+@end example
+
+@noindent
+
+block, boolval, on_true, and on_false must be non-NULL.
+@end deffn
+
+@geindex gccjit;;block;;end_with_jump (C++ function)
+@anchor{cp/topics/functions gccjit block end_with_jump__gccjit block gccjit location}@anchor{167}
+@deffn {C++ Function} void gccjit::block::end_with_jump (gccjit::block target, gccjit::location loc)
+
+Terminate a block by adding a jump to the given target block.
+
+This is roughly equivalent to this C code:
+
+@example
+goto target;
+@end example
+
+@noindent
+@end deffn
+
+@geindex gccjit;;block;;end_with_return (C++ function)
+@anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{168}
+@deffn {C++ Function} void gccjit::block::end_with_return (gccjit::rvalue rvalue, gccjit::location loc)
+
+Terminate a block.
+
+Both params are optional.
+
+An rvalue must be provided for a function returning non-void, and
+must not be provided by a function "returning" @cite{void}.
+
+If an rvalue is provided, the block is terminated by evaluating the
+rvalue and returning the value.
+
+This is roughly equivalent to this C code:
+
+@example
+return expression;
+@end example
+
+@noindent
+
+If an rvalue is not provided, the block is terminated by adding a
+valueless return, for use within a function with "void" return type.
+
+This is equivalent to this C code:
+
+@example
+return;
+@end example
+
+@noindent
+@end deffn
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Source Locations<2>,Compilation results<2>,Creating and using functions<2>,Topic Reference<2>
+@anchor{cp/topics/locations source-locations}@anchor{169}@anchor{cp/topics/locations doc}@anchor{16a}
+@subsection Source Locations
+
+
+@geindex gccjit;;location (C++ class)
+@anchor{cp/topics/locations gccjit location}@anchor{fe}
+@deffn {C++ Class} gccjit::location
+
+A @cite{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.
+
+@cite{gccjit::location} instances are optional: you can always omit them
+from any C++ API entrypoint accepting one.
+
+You can construct them using @pxref{ec,,gccjit;;context;;new_location()}.
+
+You need to enable @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
+@pxref{f6,,gccjit;;context} for these locations to actually be usable by
+the debugger:
+
+@example
+ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
+@end example
+
+@noindent
+@end deffn
+
+@geindex gccjit;;context;;new_location (C++ function)
+@anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{ec}
+@deffn {C++ Function} gccjit::location gccjit::context::new_location (const char* filename, int line, int column)
+
+Create a @cite{gccjit::location} instance representing the given source
+location.
+@end deffn
+
+@menu
+* Faking it: Faking it<2>.
+
+@end menu
+
+@node Faking it<2>,,,Source Locations<2>
+@anchor{cp/topics/locations faking-it}@anchor{16b}
+@subsubsection 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 @pxref{fd,,gccjit;;context;;dump_to_file()}:
+
+@example
+ctxt.dump_to_file ("/tmp/something.c",
+ 1 /* update_locations */);
+@end example
+
+@noindent
+
+This will dump C-like code to the given path. If the @cite{update_locations}
+argument is true, this will also set up @cite{gccjit::location} information
+throughout the context, pointing at the dump file as if it were a source
+file, giving you @emph{something} you can step through in the debugger.
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Compilation results<2>,,Source Locations<2>,Topic Reference<2>
+@anchor{cp/topics/results compilation-results}@anchor{16c}@anchor{cp/topics/results doc}@anchor{16d}
+@subsection Compilation results
+
+
+@geindex gcc_jit_result (C++ type)
+@anchor{cp/topics/results gcc_jit_result}@anchor{16e}
+@deffn {C++ Type} gcc_jit_result
+
+A @cite{gcc_jit_result} encapsulates the result of compiling a context.
+@end deffn
+
+@geindex gccjit;;context;;compile (C++ function)
+@anchor{cp/topics/results gccjit context compile}@anchor{cf}
+@deffn {C++ Function} @pxref{16e,,gcc_jit_result*} gccjit::context::compile ()
+
+This calls into GCC and builds the code, returning a
+@cite{gcc_jit_result *}.
+@end deffn
+
+@geindex gcc_jit_result_get_code (C++ function)
+@anchor{cp/topics/results gcc_jit_result_get_code__gcc_jit_resultP cCP}@anchor{16f}
+@deffn {C++ Function} void* gcc_jit_result_get_code (gcc_jit_result* result, const char* funcname)
+
+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.
+@end deffn
+
+@geindex gcc_jit_result_release (C++ function)
+@anchor{cp/topics/results gcc_jit_result_release__gcc_jit_resultP}@anchor{170}
+@deffn {C++ Function} void gcc_jit_result_release (gcc_jit_result* result)
+
+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.
+@end deffn
+
+@c Copyright (C) 2014 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+@c General Public License for more details.
+@c
+@c You should have received a copy of the GNU General Public License
+@c along with this program. If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Internals,Indices and tables,C++ bindings for libgccjit,Top
+@anchor{internals/index internals}@anchor{171}@anchor{internals/index doc}@anchor{172}
+@chapter Internals
+
+
+@menu
+* Working on the JIT library::
+* Running the test suite::
+* Environment variables::
+* Overview of code structure::
+
+@end menu
+
+@node Working on the JIT library,Running the test suite,,Internals
+@anchor{internals/index working-on-the-jit-library}@anchor{173}
+@section Working on the JIT library
+
+
+Having checked out the source code (to "src"), you can configure and build
+the JIT library like this:
+
+@example
+mkdir build
+mkdir install
+PREFIX=$(pwd)/install
+cd build
+../src/configure \
+ --enable-host-shared \
+ --enable-languages=jit \
+ --disable-bootstrap \
+ --enable-checking=release \
+ --prefix=$PREFIX
+nice make -j4 # altering the "4" to however many cores you have
+@end example
+
+@noindent
+
+This should build a libgccjit.so within jit/build/gcc:
+
+@example
+[build] $ file gcc/libgccjit.so*
+gcc/libgccjit.so: symbolic link to `libgccjit.so.0'
+gcc/libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1'
+gcc/libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, not stripped
+@end example
+
+@noindent
+
+Here's what those configuration options mean:
+
+@geindex command line option; --enable-host-shared
+@anchor{internals/index cmdoption--enable-host-shared}@anchor{174}
+@deffn {Option} --enable-host-shared
+
+Configuring with this option means that the compiler is built as
+position-independent code, which incurs a slight performance hit,
+but it necessary for a shared library.
+@end deffn
+
+@geindex command line option; --enable-languages=jit
+@anchor{internals/index cmdoption--enable-languages}@anchor{175}
+@deffn {Option} --enable-languages=jit
+
+This specifies which frontends to build. The JIT library looks like
+a frontend to the rest of the code.
+@end deffn
+
+@geindex command line option; --disable-bootstrap
+@anchor{internals/index cmdoption--disable-bootstrap}@anchor{176}
+@deffn {Option} --disable-bootstrap
+
+For hacking on the "jit" subdirectory, performing a full
+bootstrap can be overkill, since it's unused by a bootstrap. However,
+when submitting patches, you should remove this option, to ensure that
+the compiler can still bootstrap itself.
+@end deffn
+
+@geindex command line option; --enable-checking=release
+@anchor{internals/index cmdoption--enable-checking}@anchor{177}
+@deffn {Option} --enable-checking=release
+
+The compile can perform extensive self-checking as it runs, useful when
+debugging, but slowing things down.
+
+For maximum speed, configure with @code{--enable-checking=release} to
+disable this self-checking.
+@end deffn
+
+@node Running the test suite,Environment variables,Working on the JIT library,Internals
+@anchor{internals/index running-the-test-suite}@anchor{178}
+@section Running the test suite
+
+
+@example
+[build] $ cd gcc
+[gcc] $ make check-jit RUNTESTFLAGS="-v -v -v"
+@end example
+
+@noindent
+
+A summary of the tests can then be seen in:
+
+@example
+jit/build/gcc/testsuite/jit/jit.sum
+@end example
+
+@noindent
+
+and detailed logs in:
+
+@example
+jit/build/gcc/testsuite/jit/jit.log
+@end example
+
+@noindent
+
+The test executables can be seen as:
+
+@example
+jit/build/gcc/testsuite/jit/*.exe
+@end example
+
+@noindent
+
+which can be run independently.
+
+You can compile and run individual tests by passing "jit.exp=TESTNAME" to RUNTESTFLAGS e.g.:
+
+@example
+[gcc] $ make check-jit RUNTESTFLAGS="-v -v -v jit.exp=test-factorial.c"
+@end example
+
+@noindent
+
+and once a test has been compiled, you can debug it directly:
+
+@example
+[gcc] $ PATH=.:$PATH \
+ LD_LIBRARY_PATH=. \
+ LIBRARY_PATH=. \
+ gdb --args \
+ testsuite/jit/test-factorial.exe
+@end example
+
+@noindent
+
+@menu
+* Running under valgrind::
+
+@end menu
+
+@node Running under valgrind,,,Running the test suite
+@anchor{internals/index running-under-valgrind}@anchor{179}
+@subsection Running under valgrind
+
+
+The jit testsuite detects if RUN_UNDER_VALGRIND is present in the
+environment (with any value). If it is present, it runs the test client
+code under valgrind@footnote{http://valgrind.org},
+specifcally, the default
+memcheck@footnote{http://valgrind.org/docs/manual/mc-manual.html}
+tool with
+--leak-check=full@footnote{http://valgrind.org/docs/manual/mc-manual.html#opt.leak-check}.
+
+It automatically parses the output from valgrind, injecting XFAIL results if
+any issues are found, or PASS results if the output is clean. The output
+is saved to @code{TESTNAME.exe.valgrind.txt}.
+
+For example, the following invocation verbosely runs the testcase
+@code{test-sum-of-squares.c} under valgrind, showing an issue:
+
+@example
+$ RUN_UNDER_VALGRIND= \
+ make check-jit \
+ RUNTESTFLAGS="-v -v -v jit.exp=test-sum-of-squares.c"
+
+(...verbose log contains detailed valgrind errors, if any...)
+
+ === jit Summary ===
+
+# of expected passes 28
+# of expected failures 2
+
+$ less testsuite/jit/jit.sum
+(...other results...)
+XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: definitely lost: 8 bytes in 1 blocks
+XFAIL: jit.dg/test-sum-of-squares.c: test-sum-of-squares.exe.valgrind.txt: unsuppressed errors: 1
+(...other results...)
+
+$ less testsuite/jit/test-sum-of-squares.exe.valgrind.txt
+(...shows full valgrind report for this test case...)
@end example
@noindent
various known false positives.
@node Environment variables,Overview of code structure,Running the test suite,Internals
-@anchor{internals/index environment-variables}@anchor{ca}
+@anchor{internals/index environment-variables}@anchor{17a}
@section Environment variables
environment variables need to be set up:
@geindex environment variable; LD_LIBRARY_PATH
-@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{cb}
+@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{17b}
@deffn {Environment Variable} LD_LIBRARY_PATH
@quotation
@end deffn
@geindex environment variable; PATH
-@anchor{internals/index envvar-PATH}@anchor{cc}
+@anchor{internals/index envvar-PATH}@anchor{17c}
@deffn {Environment Variable} PATH
The library uses a driver executable for converting from .s assembler
@end deffn
@geindex environment variable; LIBRARY_PATH
-@anchor{internals/index envvar-LIBRARY_PATH}@anchor{cd}
+@anchor{internals/index envvar-LIBRARY_PATH}@anchor{17d}
@deffn {Environment Variable} LIBRARY_PATH
The driver executable invokes the linker, and the latter needs to locate
@noindent
@node Overview of code structure,,Environment variables,Internals
-@anchor{internals/index overview-of-code-structure}@anchor{ce}
+@anchor{internals/index overview-of-code-structure}@anchor{17e}
@section Overview of code structure
run.
@end quotation
-This document describes libgccjit@footnote{http://gcc.gnu.org/wiki/JIT}, an API
-for embedding GCC inside programs and libraries.
-
-Note that libgccjit is currently of "Alpha" quality;
-the APIs are not yet set in stone, and they shouldn't be used in
-production yet.
-
@node Indices and tables,Index,Internals,Top
-@anchor{index indices-and-tables}@anchor{cf}
+@anchor{index indices-and-tables}@anchor{17f}
@unnumbered Indices and tables
projects / gcc.git / commitdiff
