mirror/libtool
2
0
Fork 0
mirror of git://git.savannah.gnu.org/libtool.git synced 2025-02-17 15:10:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

Do not use @sc nor @acronym in the manual.

Browse Source 
* doc/libtool.texi: Remove all usage of @sc.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
This commit is contained in:
Ralf Wildenhues 2010-03-28 18:02:22 +02:00
parent 57c342937d
commit c334a37bc6
2 changed files with 77 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
ChangeLog
View File

@ -1,3 +1,8 @@
2010-03-28 Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
Do not use @sc nor @acronym in the manual.
* doc/libtool.texi: Remove all usage of @sc.
2010-03-19 Chris Demetriou <cgd@google.com>
Sort output of 'find' to enable deterministic builds.

144
doc/libtool.texi
View File

@ -56,11 +56,11 @@ identical to this one except for the removal of this paragraph
Copyright @copyright{} 2009 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the @sc{gnu} Free Documentation License, Version 1.3
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts. A copy of the license is included in
the section entitled "@sc{gnu} Free Documentation License".
the section entitled "GNU Free Documentation License".
@end titlepage
@ -75,12 +75,12 @@ the section entitled "@sc{gnu} Free Documentation License".
@comment node-name, next, previous, up
@top Shared library support for GNU
This file documents @sc{gnu} Libtool, a script that allows package developers
This file documents GNU Libtool, a script that allows package developers
to provide generic shared library support. This edition documents
version @value{VERSION}.
@xref{Reporting bugs}, for information on how to report problems with
@sc{gnu} Libtool.
GNU Libtool.
@menu
* Introduction:: What the heck is libtool?
@ -231,13 +231,13 @@ for each platform on which his package ran. He also had to design a
configuration interface so that the package installer could choose what
sort of libraries were built.
@sc{gnu} Libtool simplifies the developer's job by encapsulating both the
GNU Libtool simplifies the developer's job by encapsulating both the
platform-specific dependencies, and the user interface, in a single
script. @sc{gnu} Libtool is designed so that the complete functionality of
script. GNU Libtool is designed so that the complete functionality of
each host type is available via a generic interface, but nasty quirks
are hidden from the programmer.
@sc{gnu} Libtool's consistent interface is reassuring@dots{} users don't need
GNU Libtool's consistent interface is reassuring@dots{} users don't need
to read obscure documentation in order to have their favorite source
package build shared libraries. They just run your package
@code{configure} script (or equivalent), and libtool does all the dirty
@ -267,18 +267,18 @@ or want to write code to extend libtool in a consistent way.
@cindex motivation for writing libtool
@cindex design philosophy
Since early 1995, several different @sc{gnu} developers have recognized the
Since early 1995, several different GNU developers have recognized the
importance of having shared library support for their packages. The
primary motivation for such a change is to encourage modularity and
reuse of code (both conceptually and physically) in @sc{gnu} programs.
reuse of code (both conceptually and physically) in GNU programs.
Such a demand means that the way libraries are built in @sc{gnu} packages
Such a demand means that the way libraries are built in GNU packages
needs to be general, to allow for any library type the package installer
might want. The problem is compounded by the absence of a standard
procedure for creating shared libraries on different platforms.
The following sections outline the major issues facing shared library
support in @sc{gnu}, and how shared library support could be standardized
support in GNU, and how shared library support could be standardized
with libtool.
@cindex specifications for libtool
@ -291,13 +291,13 @@ system:
The system must be as elegant as possible.
@item
The system must be fully integrated with the @sc{gnu} Autoconf and Automake
utilities, so that it will be easy for @sc{gnu} maintainers to use. However,
The system must be fully integrated with the GNU Autoconf and Automake
utilities, so that it will be easy for GNU maintainers to use. However,
the system must not require these tools, so that it can be used by
non-@sc{gnu} packages.
non-GNU packages.
@item
Portability to other (non-@sc{gnu}) architectures and tools is desirable.
Portability to other (non-GNU) architectures and tools is desirable.
@end enumerate
@node Issues
@ -388,7 +388,7 @@ It isolates the problems and inconsistencies in library building that
plague @file{Makefile} writers by wrapping the compiler suite on
different platforms with a consistent, powerful interface.
With luck, libtool will be useful to and used by the @sc{gnu} community, and
With luck, libtool will be useful to and used by the GNU community, and
that the lessons that were learned in writing it will be taken up by
designers of future library systems.
@ -1113,9 +1113,9 @@ listing all the object files every time.
If you just want to link this convenience library into programs, then
you could just ignore libtool entirely, and use the old @command{ar} and
@command{ranlib} commands (or the corresponding @sc{gnu} Automake
@command{ranlib} commands (or the corresponding GNU Automake
@samp{_LIBRARIES} rules). You can even install a convenience library
using @sc{gnu} Libtool, though you probably don't want to and hence @sc{gnu}
using GNU Libtool, though you probably don't want to and hence GNU
Automake doesn't allow you to do so.
@example
@ -1147,13 +1147,13 @@ libraries. But be careful not to link a single convenience library,
directly or indirectly, into a single program or library, otherwise you
may get errors about symbol redefinitions.
The key is remembering that a convenience library contains @sc{pic}
objects, and can be linked where a list of @sc{pic} objects makes sense;
The key is remembering that a convenience library contains PIC
objects, and can be linked where a list of PIC objects makes sense;
i.e.@: into a shared library. A static convenience library contains
non-@sc{pic} objects, so can be linked into an old static library, or
non-PIC objects, so can be linked into an old static library, or
a program.
When @sc{gnu} Automake is used, you should use @code{noinst_LTLIBRARIES}
When GNU Automake is used, you should use @code{noinst_LTLIBRARIES}
instead of @code{lib_LTLIBRARIES} for convenience libraries, so that
the @option{-rpath} option is not passed when they are linked.
@ -1820,12 +1820,12 @@ path to particular system commands:
@defmac LT_PATH_LD
Add a @option{--with-gnu-ld} option to @file{configure}. Try to find
the path to the linker used by @samp{$CC}, and whether it is the
@sc{gnu} linker. The result is stored in the shell variable
GNU linker. The result is stored in the shell variable
@samp{$LD}, which is @code{AC_SUBST}ed.
@end defmac
@defmac LT_PATH_NM
Try to find a @sc{bsd} compatible @command{nm} or a @sc{ms} compatible
Try to find a BSD compatible @command{nm} or a MS compatible
@command{dumpbin} command on this machine. The result is stored in the
shell variable @samp{$NM}, which is @code{AC_SUBST}ed.
@end defmac
@ -1843,7 +1843,7 @@ are stored in the shell variables @samp{$enable_dlopen_self} and
@defmac LT_SYS_DLOPEN_DEPLIBS
Define the preprocessor symbol @samp{LTDL_DLOPEN_DEPLIBS} if the
@sc{os} needs help to load dependent libraries for @samp{dlopen} (or
OS needs help to load dependent libraries for @samp{dlopen} (or
equivalent).
@end defmac
@ -1887,7 +1887,7 @@ package you need to do one of the following:
@enumerate 1
@item
Download the latest Automake distribution from your nearest @sc{gnu}
Download the latest Automake distribution from your nearest GNU
mirror, install it, and start using it.
@item
@ -1912,7 +1912,7 @@ libtool distribution's @file{demo} subdirectory.
First, to link a program against a libtool library, just use the
@samp{program_LDADD}@footnote{@c
@c
Since @sc{gnu} Automake 1.5, the flags @option{-dlopen}
Since GNU Automake 1.5, the flags @option{-dlopen}
or @option{-dlpreopen} (@pxref{Link mode}) can be employed with the
@var{program_LDADD} variable. Unfortunately, older releases didn't
accept these flags, so if you are stuck with an ancient Automake, we
@ -1975,7 +1975,7 @@ However, when you distribute libtool with your own packages
operating system that are used to compile your package.
For this reason, libtool must be @dfn{configured} before it can be
used. This idea should be familiar to anybody who has used a @sc{gnu}
used. This idea should be familiar to anybody who has used a GNU
@code{configure} script. @code{configure} runs a number of tests for
system features, then generates the @file{Makefile}s (and possibly a
@file{config.h} header file), after which you can run @code{make} and
@ -1992,7 +1992,7 @@ generate a libtool script for the installer's host machine.
@node LT_INIT
@subsection The @code{LT_INIT} macro
If you are using @sc{gnu} Autoconf (or Automake), you should add a call to
If you are using GNU Autoconf (or Automake), you should add a call to
@code{LT_INIT} to your @file{configure.ac} file. This macro
adds many new tests to the @code{configure} script so that the generated
libtool script will understand the characteristics of the host. It's the
@ -2073,7 +2073,7 @@ libtool: $(LIBTOOL_DEPS)
$(SHELL) ./config.status libtool
@end example
If you are using @sc{gnu} Automake, you can omit the assignment, as Automake
If you are using GNU Automake, you can omit the assignment, as Automake
will take care of it. You'll obviously have to create some dependency
on @file{libtool}.
@ -2135,12 +2135,12 @@ specifying @option{--enable-static} to @command{configure}.
@item pic-only
Change the default behaviour for @command{libtool} to try to use only
@sc{pic} objects. The user may still override this default by specifying
PIC objects. The user may still override this default by specifying
@option{--without-pic} to @command{configure}.
@item no-pic
Change the default behaviour of @command{libtool} to try to use only
non-@sc{pic} objects. The user may still override this default by
non-PIC objects. The user may still override this default by
specifying @option{--with-pic} to @command{configure}.
@end table
@ -2493,7 +2493,7 @@ include libltdl/Makefile.inc
@item --quiet
@itemx -q
Work silently. @samp{libtoolize --quiet} is used by @sc{gnu} Automake
Work silently. @samp{libtoolize --quiet} is used by GNU Automake
to add libtool files to your package if necessary.
@item --recursive
@ -2653,12 +2653,12 @@ you can see how libtool behaves on static-only platforms.
You may want to put a small note in your package @file{README} to let
other developers know that @option{--disable-shared} can save them time.
The following example note is taken from the GIMP@footnote{@sc{gnu} Image
The following example note is taken from the GIMP@footnote{GNU Image
Manipulation Program, for those who haven't taken the plunge. See
@url{http://www.gimp.org/}.} distribution @file{README}:
@example
The GIMP uses @sc{gnu} Libtool in order to build shared libraries on a
The GIMP uses GNU Libtool in order to build shared libraries on a
variety of systems. While this is very nice for making usable
binaries, it can be a pain when trying to debug a program. For that
reason, compilation of shared libraries can be turned off by
@ -2966,7 +2966,7 @@ may also be replaced by other libraries using it.
Often, people want to encode the name of the package release into the
shared library so that it is obvious to the user which package their
programs are linked against. This convention is used especially on
@sc{gnu}/Linux:
GNU/Linux:
@example
trick$ @kbd{ls /usr/lib/libbfd*}
@ -2988,7 +2988,7 @@ So, in order to accommodate both views, you can use the @option{-release}
flag in order to set release information for libraries for which you do not
want to use @option{-version-info}. For the @file{libbfd} example, the
next release that uses libtool should be built with @samp{-release
2.9.0}, which will produce the following files on @sc{gnu}/Linux:
2.9.0}, which will produce the following files on GNU/Linux:
@example
trick$ @kbd{ls /usr/lib/libbfd*}
@ -3506,7 +3506,7 @@ provide only static linkage can't even load the intrinsic interpreter
methods. Not so! We can statically link those methods by
@strong{dlpreopening} them.
Unfortunately, since platforms such as @sc{aix} and cygwin require
Unfortunately, since platforms such as AIX and cygwin require
that all library symbols must be resolved at compile time, the
interpreter maintainers will need to provide a library to both its own
dlpreopened modules, and third-party modules loaded by dlopen. In
@ -3672,7 +3672,7 @@ hiding the various difficulties of dlopening libraries from programmers.
It consists of a few headers and small C source files that can be
distributed with applications that need dlopening functionality. On
some platforms, whose dynamic linkers are too limited for a simple
implementation of @file{libltdl} services, it requires @sc{gnu} DLD, or it
implementation of @file{libltdl} services, it requires GNU DLD, or it
will only emulate dynamic linking with libtool's dlpreopening mechanism.
@noindent
@ -3690,19 +3690,19 @@ libltdl supports currently the following dynamic linking mechanisms:
@item
@code{NSAddImage} or @code{NSLinkModule} (Darwin and Mac OS X)
@item
@sc{gnu} DLD (emulates dynamic linking for static libraries)
GNU DLD (emulates dynamic linking for static libraries)
@item
libtool's dlpreopen (see @pxref{Dlpreopening})
@end itemize
@noindent
libltdl is licensed under the terms of the @sc{gnu} Library General
libltdl is licensed under the terms of the GNU Library General
Public License, with the following exception:
@quotation
As a special exception to the @sc{gnu} Lesser General Public License,
As a special exception to the GNU Lesser General Public License,
if you distribute this file as part of a program or library that
is built using @sc{gnu} Libtool, you may include it under the same
is built using GNU Libtool, you may include it under the same
distribution terms that you use for the rest of that program.
@end quotation
@ -3731,7 +3731,7 @@ To use libltdl in your program you have to include the header file @file{ltdl.h}
@noindent
The early releases of libltdl used some symbols that violated the
@sc{posix} namespace conventions. These symbols are now deprecated,
POSIX namespace conventions. These symbols are now deprecated,
and have been replaced by those described here. If you have code that
relies on the old deprecated symbol names, defining
@samp{LT_NON_POSIX_NAMESPACE} before you include @file{ltdl.h} provides
@ -3743,7 +3743,7 @@ your application in order to use this version of libltdl.
Note that libltdl is not well tested in a multithreaded environment,
though the intention is that it should work (@pxref{Thread Safety
in libltdl, , Using libltdl in a multi threaded environment}). It was
reported that @sc{gnu}/Linux's glibc 2.0's @code{dlopen} with
reported that GNU/Linux's glibc 2.0's @code{dlopen} with
@samp{RTLD_LAZY} (which libltdl uses by default) is not thread-safe,
but this problem is supposed to be fixed in glibc 2.1. On the other
hand, @samp{RTLD_NOW} was reported to introduce problems in
@ -3876,7 +3876,7 @@ module loader. The @var{advise} parameter is opaque and can only be
accessed with the functions documented below.
Note that this function does not change the content of @var{advise}, so
unlike the other calls in this @sc{api} takes a direct @code{lt_dladvise}
unlike the other calls in this API takes a direct @code{lt_dladvise}
type, and not a pointer to the same.
@end deftypefun
@ -3936,7 +3936,7 @@ unresolved symbols in subsequently loaded modules.
If neither the @code{symglobal} nor the @code{symlocal} hints are set,
or if a module is loaded without using the @code{lt_dlopenadvise} call
in any case, then the visibility of the module's symbols will be as per
the default for the underlying module loader and @sc{os}. Even if a
the default for the underlying module loader and OS. Even if a
suitable hint is passed, not all loaders are able to act upon it in
which case @code{lt_dlgetinfo} will reveal whether the hint was actually
followed.
@ -3954,7 +3954,7 @@ visible to subsequently loaded modules.
If neither the @code{symglobal} nor the @code{symlocal} hints are set,
or if a module is loaded without using the @code{lt_dlopenadvise} call
in any case, then the visibility of the module's symbols will be as per
the default for the underlying module loader and @sc{os}. Even if a
the default for the underlying module loader and OS. Even if a
suitable hint is passed, not all loaders are able to act upon it in
which case @code{lt_dlgetinfo} will reveal whether the hint was actually
followed.
@ -4139,13 +4139,13 @@ If you wish to use libltdl in a multithreaded environment, then you
must mutex lock around libltdl calls, since they may in turn be calling
non-thread-safe system calls on some target hosts.
Some old releases of libtool provided a mutex locking @sc{api} that
Some old releases of libtool provided a mutex locking API that
was unusable with POSIX threads, so callers were forced to lock around
all libltdl @sc{api} calls anyway. That mutex locking @sc{api} was
all libltdl API calls anyway. That mutex locking API was
next to useless, and is not present in current releases.
Some future release of libtool may provide a new POSIX thread
compliant mutex locking @sc{api}.
compliant mutex locking API.
@node User defined module data
@section Data associated with loaded modules
@ -4269,7 +4269,7 @@ if no such named module has been loaded by @var{iface}.
However, you might still need to maintain your own list of loaded
module handles (in parallel with the list maintained inside libltdl)
if there were any other data that your application wanted to associate
with each open module. Instead, you can use the following @sc{api}
with each open module. Instead, you can use the following API
calls to do that for you. You must first obtain a unique interface id
from libltdl as described above, and subsequently always use it to
retrieve the data you stored earlier. This allows different libraries
@ -4309,12 +4309,12 @@ Return the address of the data associated with @var{key} and
@var{handle}, or else @code{NULL} if there is none.
@end deftypefun
Old versions of libltdl also provided a simpler, but similar, @sc{api}
Old versions of libltdl also provided a simpler, but similar, API
based around @code{lt_dlcaller_id}. Unfortunately, it had no
provision for detecting whether a module belonged to a particular
interface as libltdl didn't support multiple loaders in the same
address space at that time. Those @sc{api}s are no longer supported
as there would be no way to stop clients of the old @sc{api}s from
address space at that time. Those APIs are no longer supported
as there would be no way to stop clients of the old APIs from
seeing (and accidentally altering) modules loaded by other libraries.
@ -4344,7 +4344,7 @@ already in use by libltdl's builtin loaders:
@item "dlopen"
The system dynamic library loader, if one exists.
@item "dld"
The @sc{gnu} dld loader, if @file{libdld} was installed when libltdl was
The GNU dld loader, if @file{libdld} was installed when libltdl was
built.
@item "dlpreload"
The loader for @code{lt_dlopen}ing of preloaded static modules.
@ -4372,7 +4372,7 @@ level types.
@deftypefn {Type} {struct} lt_user_dlloader @{@w{const char *@var{sym_prefix};} @w{lt_module_open *@var{module_open};} @w{lt_module_close *@var{module_close};} @w{lt_find_sym *@var{find_sym};} @w{lt_dlloader_exit *@var{dlloader_exit};} @}
If you want to define a new way to open dynamic modules, and have the
@code{lt_dlopen} @sc{api} use it, you need to instantiate one of these
@code{lt_dlopen} API use it, you need to instantiate one of these
structures and pass it to @code{lt_dlloader_add}. You can pass whatever
you like in the @var{dlloader_data} field, and it will be passed back as
the value of the first parameter to each of the functions specified in
@ -4501,7 +4501,7 @@ Return the first loader with a matching @var{loader_name} identifier, or else
The identifiers that may be used by libltdl itself, if the host
architecture supports them are @dfn{dlopen}@footnote{This is used for
the host dependent module loading @sc{api} -- @code{shl_load} and
the host dependent module loading API -- @code{shl_load} and
@code{LoadLibrary} for example}, @dfn{dld} and @dfn{dlpreload}.
@example
@ -5048,8 +5048,8 @@ shared libraries (@option{--disable-static}).
@file{demo-nofast.test} configures @file{demo/libtool} to
disable the fast-install mode (@option{--enable-fast-install=no}).
@file{demo-pic.test} configures @file{demo/libtool} to
prefer building @sc{pic} code (@option{--with-pic}), @file{demo-nopic.test}
to prefer non-@sc{pic} code (@option{--without-pic}).
prefer building PIC code (@option{--with-pic}), @file{demo-nopic.test}
to prefer non-PIC code (@option{--without-pic}).
@item demo-deplibs.test
@pindex demo-deplibs.test
@ -5449,7 +5449,7 @@ can make changes to the libtool configuration process without affecting
other systems.
@item man pages for @command{ld} and @command{cc}
These generally describe what flags are used to generate @sc{pic}, to create
These generally describe what flags are used to generate PIC, to create
shared libraries, and to link against only static libraries. You may
need to follow some cross references to find the information that is
required.
@ -5571,7 +5571,7 @@ platforms where it claims to support shared libraries:
Note: The vendor-distributed HP-UX @command{sed}(1) programs are horribly
broken, and cannot handle libtool's requirements, so users may report
unusual problems. There is no workaround except to install a working
@command{sed} (such as @sc{gnu} @command{sed}) on these systems.
@command{sed} (such as GNU @command{sed}) on these systems.
Note: The vendor-distributed NCR MP-RAS @command{cc} programs emits
copyright on standard error that confuse tests on size of
@ -5633,8 +5633,8 @@ IBM has online documentation at
@subsection Compilers
The only compiler characteristics that affect libtool are the flags
needed (if any) to generate @sc{pic} objects. In general, if a C compiler
supports certain @sc{pic} flags, then any derivative compilers support the
needed (if any) to generate PIC objects. In general, if a C compiler
supports certain PIC flags, then any derivative compilers support the
same flags. Until there are some noteworthy exceptions to this rule,
this section will document only C compilers.
@ -5644,8 +5644,8 @@ of the platform:
@table @code
@item gcc
This is the @sc{gnu} C compiler, which is also the system compiler for many
free operating systems (FreeBSD, @sc{gnu}/Hurd, @sc{gnu}/Linux, Lites, NetBSD, and
This is the GNU C compiler, which is also the system compiler for many
free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, NetBSD, and
OpenBSD, to name a few).
The @option{-fpic} or @option{-fPIC} flags can be used to generate
@ -5663,26 +5663,26 @@ they are bundled with:
@table @code
@item aix3*
@itemx aix4*
Most AIX compilers have no @sc{pic} flags, since AIX (with the exception of
Most AIX compilers have no PIC flags, since AIX (with the exception of
AIX for IA-64) runs on PowerPC and RS/6000 chips. @footnote{All code compiled
for the PowerPC and RS/6000 chips (@code{powerpc-*-*}, @code{powerpcle-*-*},
and @code{rs6000-*-*}) is position-independent, regardless of the operating
system or compiler suite. So, ``regular objects'' can be used to build
shared libraries on these systems and no special @sc{pic} compiler flags are
shared libraries on these systems and no special PIC compiler flags are
required.}
@item hpux10*
Use @samp{+Z} to generate @sc{pic}.
Use @samp{+Z} to generate PIC.
@item osf3*
Digital/UNIX 3.x does not have @sc{pic} flags, at least not on the PowerPC
Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC
platform.
@item solaris2*
Use @option{-KPIC} to generate @sc{pic}.
Use @option{-KPIC} to generate PIC.
@item sunos4*
Use @option{-PIC} to generate @sc{pic}.
Use @option{-PIC} to generate PIC.
@end table
@node Reloadable objects