doc/ld-version-script.texi

   1 @node LD Version Scripts
   2 @section LD Version Scripts
   3
   4 The @code{lib-symbol-versions} module can be used to add shared
   5 library versioning support.  Currently, only GNU LD and the Solaris
   6 linker supports this.
   7
   8 Version scripts provides information that can be used by GNU/Linux
   9 distribution packaging tools.  For example, Debian has a tool
  10 @code{dpkg-shlibdeps} that can determine the minimal required version
  11 of each dependency (by looking at the symbol list) and stuff the
  12 information into the Debian specific packaging files.
  13
  14 For more information and other uses of version scripts, see Ulrich
  15 Drepper's paper @url{https://www.akkadia.org/drepper/dsohowto.pdf}
  16
  17 You use the module by importing it to your library, and then add the
  18 following lines to the @code{Makefile.am} that builds the library:
  19
  20 @smallexample
  21 if HAVE_LD_VERSION_SCRIPT
  22 libfoo_la_LDFLAGS += -Wl,--version-script=$(srcdir)/libfoo.map
  23 endif
  24 @end smallexample
  25
  26 The version script file format is documented in the GNU LD manual, but
  27 a small example would be:
  28
  29 @smallexample
  30 LIBFOO_1.0 @{
  31   global:
  32     libfoo_init; libfoo_doit; libfoo_done;
  33
  34   local:
  35     *;
  36 @};
  37 @end smallexample
  38
  39 If you target platforms that do not support linker scripts (i.e., all
  40 platforms that doesn't use GNU LD) you may want to consider a more
  41 portable but less powerful alternative: libtool
  42 @code{-export-symbols}.  It will hide internal symbols from your
  43 library, but will not add ELF versioning symbols.  Your usage would
  44 then be something like:
  45
  46 @smallexample
  47 if HAVE_LD_VERSION_SCRIPT
  48 libfoo_la_LDFLAGS += -Wl,--version-script=$(srcdir)/libfoo.map
  49 else
  50 libfoo_la_LDFLAGS += -export-symbols $(srcdir)/libfoo.sym
  51 endif
  52 @end smallexample
  53
  54 See the Libtool manual for the file syntax, but a small example would
  55 be:
  56
  57 @smallexample
  58 libfoo_init
  59 libfoo_doit
  60 libfoo_done
  61 @end smallexample
  62
  63 To avoid the need for a @code{*.sym} file if your symbols are easily
  64 expressed using a regular expression, you may use
  65 @code{-export-symbols-regex}:
  66
  67 @smallexample
  68 if HAVE_LD_VERSION_SCRIPT
  69 libfoo_la_LDFLAGS += -Wl,--version-script=$(srcdir)/libfoo.map
  70 else
  71 libfoo_la_LDFLAGS += -export-symbols-regex '^libfoo_.*'
  72 endif
  73 @end smallexample
  74
  75 For more discussions about symbol visibility, rather than shared
  76 library versioning, see the @code{visibility} module
  77 (@pxref{Exported Symbols of Shared Libraries}).