]>
Commit | Line | Data |
---|---|---|
8d9254fc | 1 | .. Copyright (C) 2015-2020 Free Software Foundation, Inc. |
fa22c20d DM |
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: | |
fa22c20d DM |
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` | |
6a3603e3 DM |
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` | |
ec5d0088 DM |
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` | |
afed3459 DM |
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` | |
9376dd63 DM |
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` | |
15c671a7 DM |
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` | |
0ebd1f00 DM |
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` | |
47ee1b7c DM |
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` | |
15a65e63 DM |
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` | |
6069fe72 DM |
166 | |
167 | .. _LIBGCCJIT_ABI_10: | |
168 | ||
169 | ``LIBGCCJIT_ABI_10`` | |
170 | -------------------- | |
6069fe72 DM |
171 | ``LIBGCCJIT_ABI_10`` covers the addition of |
172 | :func:`gcc_jit_context_new_rvalue_from_vector` | |
216090cc AC |
173 | |
174 | .. _LIBGCCJIT_ABI_11: | |
175 | ||
176 | ``LIBGCCJIT_ABI_11`` | |
177 | -------------------- | |
178 | ``LIBGCCJIT_ABI_11`` covers the addition of | |
179 | :func:`gcc_jit_context_add_driver_option` | |
ee118c14 AC |
180 | |
181 | ``LIBGCCJIT_ABI_12`` | |
182 | -------------------- | |
183 | ``LIBGCCJIT_ABI_12`` covers the addition of | |
184 | :func:`gcc_jit_context_new_bitfield` |