Re: shared library symbol exports and versioning

[Simon Josefsson]

Thinking even more, "ld-version-script" seems like a better module name,
to avoid confusion with any other non-LD "version" scripts.

The patch below also makes the visibility.texi be part of the gnulib
manual.  I assume this was just a mistake and not intentional?

I have pushed the patch below, but I still would appreciate more review
and discussion of it.

/Simon

>From 5d412172ab1a1775153957a47dc397ce26caf90c Mon Sep 17 00:00:00 2001
From: Simon Josefsson <address@hidden>
Date: Tue, 3 Mar 2009 12:00:59 +0100
Subject: [PATCH] Add new module ld-version-script.  Fix doc for visibility.

---
 ChangeLog                  |    9 +++++
 doc/gnulib.texi            |    6 +++
 doc/ld-version-script.texi |   77 ++++++++++++++++++++++++++++++++++++++++++++
 doc/visibility.texi        |    3 ++
 m4/ld-version-script.m4    |   39 ++++++++++++++++++++++
 modules/ld-version-script  |   14 ++++++++
 6 files changed, 148 insertions(+), 0 deletions(-)
 create mode 100644 doc/ld-version-script.texi
 create mode 100644 m4/ld-version-script.m4
 create mode 100644 modules/ld-version-script

diff --git a/ChangeLog b/ChangeLog
index b3e2b3b..796cd5e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2009-03-03  Simon Josefsson  <address@hidden>
+
+       * doc/gnulib.texi: Link to sections for ld version script and
+       visibility.
+       * doc/visibility.texi: Add @node and @section.
+       * modules/ld-version-script: New module.
+       * m4/ld-version-script.m4: New file.
+       * doc/ld-version-script.texi: New file.
+
 2009-03-02  David Lutterkort  <address@hidden>
 
        * lib/safe-alloc.h (__GNUC_PREREQ): New macro.
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index d2a3a13..ceb0335 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -5825,6 +5825,8 @@ This list of functions is sorted according to the header 
that declares them.
 * func::
 * warnings::
 * manywarnings::
+* visibility::
+* LD Version Scripts::
 @end menu
 
 @node alloca
@@ -5917,6 +5919,10 @@ generated automatically.
 
 @include manywarnings.texi
 
address@hidden visibility.texi
+
address@hidden ld-version-script.texi
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 
diff --git a/doc/ld-version-script.texi b/doc/ld-version-script.texi
new file mode 100644
index 0000000..8582edf
--- /dev/null
+++ b/doc/ld-version-script.texi
@@ -0,0 +1,77 @@
address@hidden LD Version Scripts
address@hidden LD Version Scripts
+
+The @code{ld-version-script} module can be used to add shared library
+versioning support.  Currently, only GNU LD and the Solaris linker
+supports this.
+
+Version scripts provides information that can be used by GNU/Linux
+distribution packaging tools.  For example, Debian has a tool
address@hidden that can determine the minimal required version
+of each dependency (by looking at the symbol list) and stuff the
+information into the Debian specific packaging files.
+
+For more information and other uses of version scripts, see Ulrich
+Drepper's paper @url{http://people.redhat.com/drepper/dsohowto.pdf}
+
+You use the module by importing it to your library, and then add the
+following lines to the @code{Makefile.am} that builds the library:
+
address@hidden
+if HAVE_LD_VERSION_SCRIPT
+libfoo_la_LDFLAGS += -Wl,--version-script=$(srcdir)/libfoo.map
+endif
address@hidden smallexample
+
+The version script file format is documented in the GNU LD manual, but
+a small example would be:
+
address@hidden
+LIBFOO_1.0 @{
+  global:
+    libfoo_init; libfoo_doit; libfoo_done;
+
+  local:
+    *;
address@hidden;
address@hidden smallexample
+
+If you target platforms that do not support linker scripts (i.e., all
+platforms that doesn't use GNU LD) you may want to consider a more
+portable but less powerful alternative: libtool
address@hidden  It will hide internal symbols from your
+library, but will not add ELF versioning symbols.  Your usage would
+then be something like:
+
address@hidden
+if HAVE_LD_VERSION_SCRIPT
+libfoo_la_LDFLAGS += -Wl,--version-script=$(srcdir)/libfoo.map
+else
+libfoo_la_LDFLAGS += -export-symbols $(srcdir)/libfoo.sym
+endif
address@hidden smallexample
+
+See the Libtool manual for the file syntax, but a small example would
+be:
+
address@hidden
+libfoo_init
+libfoo_doit
+libfoo_done
address@hidden smallexample
+
+To avoid the need for a @code{*.sym} file if your symbols are easily
+expressed using a regular expression, you may use
address@hidden:
+
address@hidden
+if HAVE_LD_VERSION_SCRIPT
+libfoo_la_LDFLAGS += -Wl,--version-script=$(srcdir)/libfoo.map
+else
+libfoo_la_LDFLAGS += -export-symbols-regex '^libfoo_.*'
+endif
address@hidden smallexample
+
+For more discussions about symbol visibility, rather than shared
+library versioning, see the @code{visibility} module
+(@pxref{visibility}).
diff --git a/doc/visibility.texi b/doc/visibility.texi
index c6dcbb8..2fbcbf5 100644
--- a/doc/visibility.texi
+++ b/doc/visibility.texi
@@ -1,3 +1,6 @@
address@hidden visibility
address@hidden visibility
+
 @c Documentation of gnulib module 'visibility'.
 
 @c Copyright (C) 2005-2006, 2009 Free Software Foundation, Inc.
diff --git a/m4/ld-version-script.m4 b/m4/ld-version-script.m4
new file mode 100644
index 0000000..e321347
--- /dev/null
+++ b/m4/ld-version-script.m4
@@ -0,0 +1,39 @@
+# ld-version-script.m4 serial 1
+dnl Copyright (C) 2008, 2009 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
+
+dnl From Simon Josefsson
+
+# gl_LD_VERSION_SCRIPT
+# --------------------
+# Check if LD supports linker scripts, and define automake conditional
+# HAVE_LD_VERSION_SCRIPT if so.
+AC_DEFUN([gl_LD_VERSION_SCRIPT],
+[
+  AC_ARG_ENABLE([ld-version-script],
+    AS_HELP_STRING([--enable-ld-version-script],
+      [enable linker version script (default is enabled when possible)]),
+      [have_ld_version_script=$enableval], [])
+  if test -z "$have_ld_version_script"; then
+    AC_MSG_CHECKING([if LD -Wl,--version-script works])
+    save_LDFLAGS="$LDFLAGS"
+    LDFLAGS="$LDFLAGS -Wl,--version-script=conftest.map"
+    cat > conftest.map <<EOF
+VERS_1 {
+       global: sym;
+};
+
+VERS_2 {
+        global: sym;
+} VERS_1;
+EOF
+    AC_LINK_IFELSE(AC_LANG_PROGRAM([], []),
+                   [have_ld_version_script=yes], [have_ld_version_script=no])
+    rm -f conftest.map
+    LDFLAGS="$save_LDFLAGS"
+    AC_MSG_RESULT($have_ld_version_script)
+  fi
+  AM_CONDITIONAL(HAVE_LD_VERSION_SCRIPT, test "$have_ld_version_script" = 
"yes")
+])
diff --git a/modules/ld-version-script b/modules/ld-version-script
new file mode 100644
index 0000000..6b0d990
--- /dev/null
+++ b/modules/ld-version-script
@@ -0,0 +1,14 @@
+Description:
+Macros to test whether LD support --linker-script.
+
+Files:
+m4/ld-version-script.m4
+
+configure.ac:
+gl_LD_VERSION_SCRIPT
+
+License:
+unlimited
+
+Maintainer:
+Simon Josefsson
-- 
1.5.6.5