1 .. Copyright (C) 2014-2020 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <dmalcolm@redhat.com>
4 This is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see
16 <http://www.gnu.org/licenses/>.
23 Once populated, a :c:type:`gcc_jit_context *` can be compiled to
24 machine code, either in-memory via :c:func:`gcc_jit_context_compile` or
25 to disk via :c:func:`gcc_jit_context_compile_to_file`.
27 You can compile a context multiple times (using either form of
28 compilation), although any errors that occur on the context will
29 prevent any future compilation of that context.
34 .. function:: gcc_jit_result *\
35 gcc_jit_context_compile (gcc_jit_context *ctxt)
37 This calls into GCC and builds the code, returning a
40 If the result is non-NULL, the caller becomes responsible for
41 calling :func:`gcc_jit_result_release` on it once they're done
44 .. type:: gcc_jit_result
46 A `gcc_jit_result` encapsulates the result of compiling a context
47 in-memory, and the lifetimes of any machine code functions or globals
48 that are within the result.
51 gcc_jit_result_get_code (gcc_jit_result *result,\
54 Locate a given function within the built machine code.
56 Functions are looked up by name. For this to succeed, a function
57 with a name matching `funcname` must have been created on
58 `result`'s context (or a parent context) via a call to
59 :func:`gcc_jit_context_new_function` with `kind`
60 :macro:`GCC_JIT_FUNCTION_EXPORTED`:
64 gcc_jit_context_new_function (ctxt,
65 any_location, /* or NULL */
66 /* Required for func to be visible to
67 gcc_jit_result_get_code: */
68 GCC_JIT_FUNCTION_EXPORTED,
70 /* Must string-compare equal: */
74 If such a function is not found (or `result` or `funcname` are
75 ``NULL``), an error message will be emitted on stderr and
76 ``NULL`` will be returned.
78 If the function is found, the result will need to be cast to a
79 function pointer of the correct type before it can be called.
81 Note that the resulting machine code becomes invalid after
82 :func:`gcc_jit_result_release` is called on the
83 :type:`gcc_jit_result *`; attempting to call it after that may lead
84 to a segmentation fault.
87 gcc_jit_result_get_global (gcc_jit_result *result,\
90 Locate a given global within the built machine code.
92 Globals are looked up by name. For this to succeed, a global
93 with a name matching `name` must have been created on
94 `result`'s context (or a parent context) via a call to
95 :func:`gcc_jit_context_new_global` with `kind`
96 :macro:`GCC_JIT_GLOBAL_EXPORTED`.
98 If the global is found, the result will need to be cast to a
99 pointer of the correct type before it can be called.
101 This is a *pointer* to the global, so e.g. for an :c:type:`int` this is
104 For example, given an ``int foo;`` created this way:
108 gcc_jit_lvalue *exported_global =
109 gcc_jit_context_new_global (ctxt,
110 any_location, /* or NULL */
111 GCC_JIT_GLOBAL_EXPORTED,
115 we can access it like this:
120 (int *)gcc_jit_result_get_global (result, "foo");
122 If such a global is not found (or `result` or `name` are
123 ``NULL``), an error message will be emitted on stderr and
124 ``NULL`` will be returned.
126 Note that the resulting address becomes invalid after
127 :func:`gcc_jit_result_release` is called on the
128 :type:`gcc_jit_result *`; attempting to use it after that may lead
129 to a segmentation fault.
132 gcc_jit_result_release (gcc_jit_result *result)
134 Once we're done with the code, this unloads the built .so file.
135 This cleans up the result; after calling this, it's no longer
136 valid to use the result, or any code or globals that were obtained
137 by calling :func:`gcc_jit_result_get_code` or
138 :func:`gcc_jit_result_get_global` on it.
141 Ahead-of-time compilation
142 *************************
144 Although libgccjit is primarily aimed at just-in-time compilation, it
145 can also be used for implementing more traditional ahead-of-time
146 compilers, via the :c:func:`gcc_jit_context_compile_to_file`
150 gcc_jit_context_compile_to_file (gcc_jit_context *ctxt, \
151 enum gcc_jit_output_kind output_kind,\
152 const char *output_path)
154 Compile the :c:type:`gcc_jit_context *` to a file of the given
157 :c:func:`gcc_jit_context_compile_to_file` ignores the suffix of
158 ``output_path``, and insteads uses the given
159 :c:type:`enum gcc_jit_output_kind` to decide what to do.
163 This is different from the ``gcc`` program, which does make use of the
164 suffix of the output file when determining what to do.
166 .. type:: enum gcc_jit_output_kind
168 The available kinds of output are:
170 ============================================== ==============
171 Output kind Typical suffix
172 ============================================== ==============
173 :c:macro:`GCC_JIT_OUTPUT_KIND_ASSEMBLER` .s
174 :c:macro:`GCC_JIT_OUTPUT_KIND_OBJECT_FILE` .o
175 :c:macro:`GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY` .so or .dll
176 :c:macro:`GCC_JIT_OUTPUT_KIND_EXECUTABLE` None, or .exe
177 ============================================== ==============
179 .. c:macro:: GCC_JIT_OUTPUT_KIND_ASSEMBLER
181 Compile the context to an assembler file.
183 .. c:macro:: GCC_JIT_OUTPUT_KIND_OBJECT_FILE
185 Compile the context to an object file.
187 .. c:macro:: GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY
189 Compile the context to a dynamic library.
191 There is currently no support for specifying other libraries to link
194 .. c:macro:: GCC_JIT_OUTPUT_KIND_EXECUTABLE
196 Compile the context to an executable.
198 There is currently no support for specifying libraries to link