gcc/jit/docs/topics/compilation.rst

   1 .. Copyright (C) 2014-2024 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    <https://www.gnu.org/licenses/>.
  17
  18 .. default-domain:: c
  19
  20 Compiling a context
  21 ===================
  22
  23 Once populated, a :c:expr:`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`.
  26
  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.
  30
  31 In-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    :expr:`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 :expr:`int` this is
 102    an :expr:`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    :expr:`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
 141 Ahead-of-time compilation
 142 *************************
 143
 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`
 147 API entrypoint.
 148
 149 For linking in object files, use :c:func:`gcc_jit_context_add_driver_option`.
 150
 151 .. function:: void \
 152               gcc_jit_context_compile_to_file (gcc_jit_context *ctxt, \
 153                                                enum gcc_jit_output_kind output_kind,\
 154                                                const char *output_path)
 155
 156    Compile the :c:expr:`gcc_jit_context *` to a file of the given
 157    kind.
 158
 159 :c:func:`gcc_jit_context_compile_to_file` ignores the suffix of
 160 ``output_path``, and insteads uses the given
 161 :c:enum:`gcc_jit_output_kind` to decide what to do.
 162
 163 .. note::
 164
 165    This is different from the ``gcc`` program, which does make use of the
 166    suffix of the output file when determining what to do.
 167
 168 .. enum:: gcc_jit_output_kind
 169
 170 The available kinds of output are:
 171
 172 .. list-table::
 173    :header-rows: 1
 174
 175    * - Output kind
 176      - Typical suffix
 177
 178    * - :c:macro:`GCC_JIT_OUTPUT_KIND_ASSEMBLER`
 179      - .s
 180    * - :c:macro:`GCC_JIT_OUTPUT_KIND_OBJECT_FILE`
 181      - .o
 182    * - :c:macro:`GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY`
 183      - .so or .dll
 184    * - :c:macro:`GCC_JIT_OUTPUT_KIND_EXECUTABLE`
 185      - None, or .exe
 186
 187 .. c:macro:: GCC_JIT_OUTPUT_KIND_ASSEMBLER
 188
 189    Compile the context to an assembler file.
 190
 191 .. c:macro:: GCC_JIT_OUTPUT_KIND_OBJECT_FILE
 192
 193    Compile the context to an object file.
 194
 195 .. c:macro:: GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY
 196
 197    Compile the context to a dynamic library.
 198
 199 .. c:macro:: GCC_JIT_OUTPUT_KIND_EXECUTABLE
 200
 201    Compile the context to an executable.