compilation.rst revision 1.1.1.2
1.. Copyright (C) 2014-2016 Free Software Foundation, Inc. 2 Originally contributed by David Malcolm <dmalcolm@redhat.com> 3 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. 8 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. 13 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/>. 17 18.. default-domain:: c 19 20Compiling a context 21=================== 22 23Once populated, a :c:type:`gcc_jit_context *` can be compiled to 24machine code, either in-memory via :c:func:`gcc_jit_context_compile` or 25to disk via :c:func:`gcc_jit_context_compile_to_file`. 26 27You can compile a context multiple times (using either form of 28compilation), although any errors that occur on the context will 29prevent any future compilation of that context. 30 31In-memory compilation 32********************* 33 34.. function:: gcc_jit_result *\ 35 gcc_jit_context_compile (gcc_jit_context *ctxt) 36 37 This calls into GCC and builds the code, returning a 38 `gcc_jit_result *`. 39 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 42 with it. 43 44.. type:: gcc_jit_result 45 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. 49 50.. function:: void *\ 51 gcc_jit_result_get_code (gcc_jit_result *result,\ 52 const char *funcname) 53 54 Locate a given function within the built machine code. 55 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`: 61 62 .. code-block:: c 63 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, 69 any_return_type, 70 /* Must string-compare equal: */ 71 funcname, 72 /* etc */); 73 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. 77 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. 80 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. 85 86.. function:: void *\ 87 gcc_jit_result_get_global (gcc_jit_result *result,\ 88 const char *name) 89 90 Locate a given global within the built machine code. 91 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`. 97 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. 100 101 This is a *pointer* to the global, so e.g. for an :c:type:`int` this is 102 an :c:type:`int *`. 103 104 For example, given an ``int foo;`` created this way: 105 106 .. code-block:: c 107 108 gcc_jit_lvalue *exported_global = 109 gcc_jit_context_new_global (ctxt, 110 any_location, /* or NULL */ 111 GCC_JIT_GLOBAL_EXPORTED, 112 int_type, 113 "foo"); 114 115 we can access it like this: 116 117 .. code-block:: c 118 119 int *ptr_to_foo = 120 (int *)gcc_jit_result_get_global (result, "foo"); 121 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. 125 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. 130 131.. function:: void\ 132 gcc_jit_result_release (gcc_jit_result *result) 133 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. 139 140 141Ahead-of-time compilation 142************************* 143 144Although libgccjit is primarily aimed at just-in-time compilation, it 145can also be used for implementing more traditional ahead-of-time 146compilers, via the :c:func:`gcc_jit_context_compile_to_file` 147API entrypoint. 148 149.. function:: void \ 150 gcc_jit_context_compile_to_file (gcc_jit_context *ctxt, \ 151 enum gcc_jit_output_kind output_kind,\ 152 const char *output_path) 153 154 Compile the :c:type:`gcc_jit_context *` to a file of the given 155 kind. 156 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. 160 161.. note:: 162 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. 165 166.. type:: enum gcc_jit_output_kind 167 168The available kinds of output are: 169 170============================================== ============== 171Output 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============================================== ============== 178 179.. c:macro:: GCC_JIT_OUTPUT_KIND_ASSEMBLER 180 181 Compile the context to an assembler file. 182 183.. c:macro:: GCC_JIT_OUTPUT_KIND_OBJECT_FILE 184 185 Compile the context to an object file. 186 187.. c:macro:: GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY 188 189 Compile the context to a dynamic library. 190 191 There is currently no support for specifying other libraries to link 192 against. 193 194.. c:macro:: GCC_JIT_OUTPUT_KIND_EXECUTABLE 195 196 Compile the context to an executable. 197 198 There is currently no support for specifying libraries to link 199 against. 200