Subject: doc: Improve documentation of -export-symbols
From: Bruno Haible <[email-masked]>
To: [email-masked]
Date: Mon, 02 Sep 2024 11:42:17 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi,

In GNU libffcall, I make use of libtool's '-export-symbols-regex' option.
Since the doc says "This option has no effect on some platforms." I wanted
to know more, in order to judge whether it's worth doing additional measures
for library namespacing.

Here's what I found:
  * It has no effect on static libraries.
  * It has the desired effect on shared libraries on
      - most ELF systems (Linux, FreeBSD, NetBSD, OpenBSD, Solaris 10 and 11,
        Android),
      - macOS,
      - Cygwin,
      - native Windows (mingw, MSVC).
  * It has no effect on AIX and Haiku.

Find attached a doc patch.

Bruno

From 0e2536c60b2699644fd1accebc93bdea2659dadc Mon Sep 17 00:00:00 2001
From: Bruno Haible <[email-masked]>
Date: Mon, 2 Sep 2024 11:33:27 +0200
Subject: [PATCH] Document situations where -export-symbols does not work.

* doc/libtool.texi (Link mode): Document that -export-symbols does not work on
static libraries. Document the most important platforms where it does not work
on shared libraries.
---
 doc/libtool.texi | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/doc/libtool.texi b/doc/libtool.texi
index 04ab34f1..503c0fb1 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -1491,7 +1491,13 @@ Allow symbols from @var{output-file} to be resolved with @code{dlsym}
 @item -export-symbols @var{symfile}
 Tells the linker to export only the symbols listed in @var{symfile}.
 The symbol file should end in @file{.sym} and must contain the name of one
-symbol per line.  This option has no effect on some platforms.
+symbol per line.  This option has no effect:
+@itemize @bullet
+@item
+on static libraries, and
+@item
+on shared libraries on some platforms, such as AIX and Haiku.
+@end itemize
 By default all symbols are exported.
 
 @item -export-symbols-regex @var{regex}
-- 
2.34.1