projects / thirdparty / gcc.git / blame
| Commit | Line | Data |
|---|---|---|
| c63539ff ML |
1 | .. |
| 2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
| 3 | This is part of the GCC manual. | |
| 4 | For copying conditions, see the copyright.rst file. | |
| 5 | ||
| 6 | .. _symbol-versioning: | |
| 7 | ||
| 8 | Symbol Versioning | |
| 9 | ***************** | |
| 10 | ||
| 11 | In general, this capability exists only on a few platforms, thus there | |
| 12 | is a need for configure magic so that it is used only on those targets | |
| 13 | where it is supported. | |
| 14 | ||
| 15 | The central concept in symbol versioning is the so-called map file, | |
| 16 | which specifies the version node(s) exported symbols are labeled with. | |
| 17 | Also, the map file is used to hide local symbols. | |
| 18 | ||
| 19 | Some relevant references: | |
| 20 | ||
| 21 | * `GNU ld manual <https://sourceware.org/binutils/docs/ld/VERSION.html>`_ | |
| 22 | ||
| 23 | * `ELF Symbol | |
| 24 | Versioning - Ulrich Depper <https://www.akkadia.org/drepper/symbol-versioning>`_ | |
| 25 | ||
| 26 | * `How to Write Shared | |
| 27 | Libraries - Ulrich Drepper (see Chapter 3) <https://www.akkadia.org/drepper/dsohowto.pdf>`_ | |
| 28 | ||
| 29 | If one adds a new symbol to a library that should be exported, the new | |
| 30 | symbol should be mentioned in the map file and a new version node | |
| 31 | defined, e.g., if one adds a new symbols ``foo`` and ``bar`` to | |
| 32 | libgfortran for the next GCC release, the following should be added to | |
| 33 | the map file: | |
| 34 | ||
| 35 | :: | |
| 36 | ||
| 37 | GFORTRAN_1.1 { | |
| 38 | global: | |
| 39 | foo; | |
| 40 | bar; | |
| 41 | } GFORTRAN_1.0; | |
| 42 | ||
| 43 | where ``GFORTRAN_1.0`` is the version node of the current release, | |
| 44 | and ``GFORTRAN_1.1`` is the version node of the next release where | |
| 45 | foo and bar are made available. | |
| 46 | ||
| 47 | If one wants to change an existing interface, it is possible by using | |
| 48 | some asm trickery (from the :command:`ld` manual referenced above): | |
| 49 | ||
| 50 | .. code-block:: c++ | |
| 51 | ||
| 52 | __asm__(".symver original_foo,foo@"); | |
| 53 | __asm__(".symver old_foo,foo@VERS_1.1"); | |
| 54 | __asm__(".symver old_foo1,foo@VERS_1.2"); | |
| 55 | __asm__(".symver new_foo,foo@VERS_2.0"); | |
| 56 | ||
| 57 | In this example, ``foo@`` represents the symbol ``foo`` bound to | |
| 58 | the unspecified base version of the symbol. The source file that | |
| 59 | contains this example would define 4 C functions: ``original_foo``, | |
| 60 | ``old_foo``, ``old_foo1``, and ``new_foo``. | |
| 61 | ||
| 62 | In this case the map file must contain ``foo`` in ``VERS_1.1`` | |
| 3ed1b4ce | 63 | and ``VERS_1.2`` as well as in ``VERS_2.0``. |