|
111
|
1 .. Copyright (C) 2015-2017 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
|
|
|
20 ABI and API compatibility
|
|
|
21 =========================
|
|
|
22
|
|
|
23 The libgccjit developers strive for ABI and API backward-compatibility:
|
|
|
24 programs built against libgccjit.so stand a good chance of running
|
|
|
25 without recompilation against newer versions of libgccjit.so, and
|
|
|
26 ought to recompile without modification against newer versions of
|
|
|
27 libgccjit.h.
|
|
|
28
|
|
|
29 .. note:: The libgccjit++.h C++ API is more experimental, and less
|
|
|
30 locked-down at this time.
|
|
|
31
|
|
|
32 API compatibility is achieved by extending the API rather than changing
|
|
|
33 it. For ABI compatiblity, we avoid bumping the SONAME, and instead use
|
|
|
34 symbol versioning to tag each symbol, so that a binary linked against
|
|
|
35 libgccjit.so is tagged according to the symbols that it uses.
|
|
|
36
|
|
|
37 For example, :func:`gcc_jit_context_add_command_line_option` was added in
|
|
|
38 ``LIBGCCJIT_ABI_1``. If a client program uses it, this can be detected
|
|
|
39 from metadata by using ``objdump``:
|
|
|
40
|
|
|
41 .. code-block:: bash
|
|
|
42
|
|
|
43 $ objdump -p testsuite/jit/test-extra-options.c.exe | tail -n 8
|
|
|
44
|
|
|
45 Version References:
|
|
|
46 required from libgccjit.so.0:
|
|
|
47 0x00824161 0x00 04 LIBGCCJIT_ABI_1
|
|
|
48 0x00824160 0x00 03 LIBGCCJIT_ABI_0
|
|
|
49 required from libc.so.6:
|
|
|
50
|
|
|
51 You can see the symbol tags provided by libgccjit.so using ``objdump``:
|
|
|
52
|
|
|
53 .. code-block:: bash
|
|
|
54
|
|
|
55 $ objdump -p libgccjit.so | less
|
|
|
56 [...snip...]
|
|
|
57 Version definitions:
|
|
|
58 1 0x01 0x0ff81f20 libgccjit.so.0
|
|
|
59 2 0x00 0x00824160 LIBGCCJIT_ABI_0
|
|
|
60 3 0x00 0x00824161 LIBGCCJIT_ABI_1
|
|
|
61 LIBGCCJIT_ABI_0
|
|
|
62 [...snip...]
|
|
|
63
|
|
|
64 ABI symbol tags
|
|
|
65 ***************
|
|
|
66
|
|
|
67 The initial release of libgccjit (in gcc 5.1) did not use symbol versioning.
|
|
|
68
|
|
|
69 Newer releases use the following tags.
|
|
|
70
|
|
|
71 .. _LIBGCCJIT_ABI_0:
|
|
|
72
|
|
|
73 ``LIBGCCJIT_ABI_0``
|
|
|
74 -------------------
|
|
|
75
|
|
|
76 All entrypoints in the initial release of libgccjit are tagged with
|
|
|
77 ``LIBGCCJIT_ABI_0``, to signify the transition to symbol versioning.
|
|
|
78
|
|
|
79 Binaries built against older copies of ``libgccjit.so`` should
|
|
|
80 continue to work, with this being handled transparently by the linker
|
|
|
81 (see `this post
|
|
|
82 <https://gcc.gnu.org/ml/gcc-patches/2015-06/msg02126.html>`_)
|
|
|
83
|
|
|
84 .. _LIBGCCJIT_ABI_1:
|
|
|
85
|
|
|
86 ``LIBGCCJIT_ABI_1``
|
|
|
87 -------------------
|
|
|
88 ``LIBGCCJIT_ABI_1`` covers the addition of
|
|
|
89 :func:`gcc_jit_context_add_command_line_option`
|
|
|
90
|
|
|
91 .. _LIBGCCJIT_ABI_2:
|
|
|
92
|
|
|
93 ``LIBGCCJIT_ABI_2``
|
|
|
94 -------------------
|
|
|
95 ``LIBGCCJIT_ABI_2`` covers the addition of
|
|
|
96 :func:`gcc_jit_context_set_bool_allow_unreachable_blocks`
|
|
|
97
|
|
|
98 .. _LIBGCCJIT_ABI_3:
|
|
|
99
|
|
|
100 ``LIBGCCJIT_ABI_3``
|
|
|
101 -------------------
|
|
|
102 ``LIBGCCJIT_ABI_3`` covers the addition of switch statements via API
|
|
|
103 entrypoints:
|
|
|
104
|
|
|
105 * :func:`gcc_jit_block_end_with_switch`
|
|
|
106
|
|
|
107 * :func:`gcc_jit_case_as_object`
|
|
|
108
|
|
|
109 * :func:`gcc_jit_context_new_case`
|
|
|
110
|
|
|
111 .. _LIBGCCJIT_ABI_4:
|
|
|
112
|
|
|
113 ``LIBGCCJIT_ABI_4``
|
|
|
114 -------------------
|
|
|
115 ``LIBGCCJIT_ABI_4`` covers the addition of timers via API
|
|
|
116 entrypoints:
|
|
|
117
|
|
|
118 * :func:`gcc_jit_context_get_timer`
|
|
|
119
|
|
|
120 * :func:`gcc_jit_context_set_timer`
|
|
|
121
|
|
|
122 * :func:`gcc_jit_timer_new`
|
|
|
123
|
|
|
124 * :func:`gcc_jit_timer_release`
|
|
|
125
|
|
|
126 * :func:`gcc_jit_timer_push`
|
|
|
127
|
|
|
128 * :func:`gcc_jit_timer_pop`
|
|
|
129
|
|
|
130 * :func:`gcc_jit_timer_print`
|
|
|
131
|
|
|
132 .. _LIBGCCJIT_ABI_5:
|
|
|
133
|
|
|
134 ``LIBGCCJIT_ABI_5``
|
|
|
135 -------------------
|
|
|
136 ``LIBGCCJIT_ABI_5`` covers the addition of
|
|
|
137 :func:`gcc_jit_context_set_bool_use_external_driver`
|
|
|
138
|
|
|
139 .. _LIBGCCJIT_ABI_6:
|
|
|
140
|
|
|
141 ``LIBGCCJIT_ABI_6``
|
|
|
142 -------------------
|
|
|
143 ``LIBGCCJIT_ABI_6`` covers the addition of
|
|
|
144 :func:`gcc_jit_rvalue_set_bool_require_tail_call`
|
|
|
145
|
|
|
146 .. _LIBGCCJIT_ABI_7:
|
|
|
147
|
|
|
148 ``LIBGCCJIT_ABI_7``
|
|
|
149 -------------------
|
|
|
150 ``LIBGCCJIT_ABI_7`` covers the addition of
|
|
|
151 :func:`gcc_jit_type_get_aligned`
|
|
|
152
|
|
|
153 .. _LIBGCCJIT_ABI_8:
|
|
|
154
|
|
|
155 ``LIBGCCJIT_ABI_8``
|
|
|
156 -------------------
|
|
|
157 ``LIBGCCJIT_ABI_8`` covers the addition of
|
|
|
158 :func:`gcc_jit_type_get_vector`
|
|
|
159
|
|
|
160 .. _LIBGCCJIT_ABI_9:
|
|
|
161
|
|
|
162 ``LIBGCCJIT_ABI_9``
|
|
|
163 -------------------
|
|
|
164 ``LIBGCCJIT_ABI_9`` covers the addition of
|
|
|
165 :func:`gcc_jit_function_get_address`
|
|
|
166
|
|
|
167 .. _LIBGCCJIT_ABI_10:
|
|
|
168
|
|
|
169 ``LIBGCCJIT_ABI_10``
|
|
|
170 --------------------
|
|
|
171
|
|
|
172 ``LIBGCCJIT_ABI_10`` covers the addition of
|
|
|
173 :func:`gcc_jit_context_new_rvalue_from_vector`
|
