[thirdparty/gcc.git] / gcc / jit / docs / topics / compatibility.rst

.. Copyright (C) 2015 Free Software Foundation, Inc.
   Originally contributed by David Malcolm <dmalcolm@redhat.com>

   This is free software: you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see
   <http://www.gnu.org/licenses/>.

.. default-domain:: c

ABI and API compatibility
=========================

The libgccjit developers strive for ABI and API backward-compatibility:
programs built against libgccjit.so stand a good chance of running
without recompilation against newer versions of libgccjit.so, and
ought to recompile without modification against newer versions of
libgccjit.h.

.. note:: The libgccjit++.h C++ API is more experimental, and less
          locked-down at this time.

API compatibility is achieved by extending the API rather than changing
it.  For ABI compatiblity, we avoid bumping the SONAME, and instead use
symbol versioning to tag each symbol, so that a binary linked against
libgccjit.so is tagged according to the symbols that it uses.

For example, :func:`gcc_jit_context_add_command_line_option` was added in
``LIBGCCJIT_ABI_1``.  If a client program uses it, this can be detected
from metadata by using ``objdump``:

.. code-block:: bash

   $ objdump -p testsuite/jit/test-extra-options.c.exe | tail -n 8

   Version References:
     required from libgccjit.so.0:
       0x00824161 0x00 04 LIBGCCJIT_ABI_1
       0x00824160 0x00 03 LIBGCCJIT_ABI_0
     required from libc.so.6:
       0x09691a75 0x00 02 GLIBC_2.2.5

You can see the symbol tags provided by libgccjit.so using ``objdump``:

.. code-block:: bash

   $ objdump -p libgccjit.so | less
   [...snip...]
   Version definitions:
   1 0x01 0x0ff81f20 libgccjit.so.0
   2 0x00 0x00824160 LIBGCCJIT_ABI_0
   3 0x00 0x00824161 LIBGCCJIT_ABI_1
           LIBGCCJIT_ABI_0
   [...snip...]

ABI symbol tags
***************

The initial release of libgccjit (in gcc 5.1) did not use symbol versioning.

Newer releases use the following tags.

.. _LIBGCCJIT_ABI_0:

``LIBGCCJIT_ABI_0``
-------------------

All entrypoints in the initial release of libgccjit are tagged with
``LIBGCCJIT_ABI_0``, to signify the transition to symbol versioning.

Binaries built against older copies of ``libgccjit.so`` should
continue to work, with this being handled transparently by the linker
(see `this post
<https://gcc.gnu.org/ml/gcc-patches/2015-06/msg02126.html>`_)

.. _LIBGCCJIT_ABI_1:

``LIBGCCJIT_ABI_1``
-------------------
``LIBGCCJIT_ABI_1`` covers the addition of
:func:`gcc_jit_context_add_command_line_option`

.. _LIBGCCJIT_ABI_2:

``LIBGCCJIT_ABI_2``
-------------------
``LIBGCCJIT_ABI_2`` covers the addition of
:func:`gcc_jit_context_set_bool_allow_unreachable_blocks`
Commit	Line	Data
fa22c20d DM	1	.. Copyright (C) 2015 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	0x09691a75 0x00 02 GLIBC_2.2.5
	51
	52	You can see the symbol tags provided by libgccjit.so using ``objdump``:
	53
	54	.. code-block:: bash
	55
	56	$ objdump -p libgccjit.so \| less
	57	[...snip...]
	58	Version definitions:
	59	1 0x01 0x0ff81f20 libgccjit.so.0
	60	2 0x00 0x00824160 LIBGCCJIT_ABI_0
	61	3 0x00 0x00824161 LIBGCCJIT_ABI_1
	62	LIBGCCJIT_ABI_0
	63	[...snip...]
	64
65	ABI symbol tags
66	***************
67
68	The initial release of libgccjit (in gcc 5.1) did not use symbol versioning.
69
70	Newer releases use the following tags.
71
72	.. _LIBGCCJIT_ABI_0:
73
74	``LIBGCCJIT_ABI_0``
75	-------------------
76
77	All entrypoints in the initial release of libgccjit are tagged with
78	``LIBGCCJIT_ABI_0``, to signify the transition to symbol versioning.
79
80	Binaries built against older copies of ``libgccjit.so`` should
81	continue to work, with this being handled transparently by the linker
82	(see `this post
83	<https://gcc.gnu.org/ml/gcc-patches/2015-06/msg02126.html>`_)
84
85	.. _LIBGCCJIT_ABI_1:
86
87	``LIBGCCJIT_ABI_1``
88	-------------------
89	``LIBGCCJIT_ABI_1`` covers the addition of
90	:func:`gcc_jit_context_add_command_line_option`
6a3603e3 DM	91
	92	.. _LIBGCCJIT_ABI_2:
	93
	94	``LIBGCCJIT_ABI_2``
	95	-------------------
	96	``LIBGCCJIT_ABI_2`` covers the addition of
	97	:func:`gcc_jit_context_set_bool_allow_unreachable_blocks`