Blame README

Kylie McClain 51bef4
# slibtool
Kylie McClain 51bef4
46bdb3
`slibtool` is an independent reimplementation of the widely used libtool,
Kylie McClain 51bef4
written in C. `slibtool` is designed to be a clean, fast, easy-to-use
Kylie McClain 51bef4
libtool drop-in replacement, and is accordingly aimed at package authors,
Kylie McClain 51bef4
distro developers, and system integrators. `slibtool` maintains compatibility
Kylie McClain 51bef4
with libtool in nearly every aspect of the tool's functionality as well as
46bdb3
semantics, leaving out (or turning into a no-op) only a small number of
Kylie McClain 51bef4
features that are no longer needed on modern systems.
Kylie McClain 51bef4
Kylie McClain 51bef4
Being a compiled binary, and although not primarily written for the sake of
Kylie McClain 51bef4
performance, building a package with `slibtool` is often faster than with its
Kylie McClain 51bef4
script-based counterpart. The resulting performance gain would normally vary
Kylie McClain 51bef4
between packages, and is most noticeable in builds that invoke libtool a large
46bdb3
number of times, and which are characterized by the short compilation duration
46bdb3
of individual translation units.
Kylie McClain 51bef4
f19e85
## why reimplement libtool?
f19e85
46bdb3
Midipix targets use the PE binary format, and so require import library
f19e85
integration on the one hand, yet follow ELF naming conventions
f19e85
(i.e. libfoo.so.x.y.z) on the other. In consequence, midipix shared
f19e85
libraries are not fully supported by existing libtool implementations.
f19e85
As an interim solution used for the porting of gcc, a libtool script
f19e85
generated by ltmain.sh was hand-edited so that it would correctly produce
f19e85
the host's shared libraries as part of the toolchain build process.
f19e85
f19e85
Bypassing the libtool script generated by a package's ltmain.sh requires
f19e85
overriding the `LIBTOOL` variable as part of invoking `make(1)`. In that
f19e85
sense, and unless midipix support is added to every single ltmain.sh in
f19e85
every single package that uses autotools, it does not truly matter whether
f19e85
the surrogate libtool that one chooses be a script, a program written in C,
f19e85
or something else.
f19e85
f19e85
At the time of this writing, an average libtool script consists of about
f19e85
`10K lines of code` with `several hundred case-esac statements` and a similar
f19e85
number of `if-then blocks`. In view of the length of the generated script,
f19e85
and in light of its challenging logic and overall complexity, a rewrite of
f19e85
the tool in C seemed to be the right choice not only with respect to quality,
f19e85
readability, and anticipated performance, but also in terms of development
f19e85
effort, ease of customization, and long-term maintenance.
f19e85
Kylie McClain 51bef4
## Requirements for building slibtool
Kylie McClain 51bef4
46bdb3
- a C toolchain, consisting of
46bdb3
    - a C compiler such as gcc, clang, or [cparser];
46bdb3
    - the compiler should support -std=c99;
46bdb3
    - the system's libc should support -D_XOPEN_SOURCE=700.
Kylie McClain 51bef4
Kylie McClain 51bef4
## Usage
Kylie McClain 51bef4
Kylie McClain 51bef4
With most packages, simply adding `LIBTOOL=slibtool` to the `make` invocation
Kylie McClain 51bef4
should suffice. To have `slibtool` operate in debug mode (outputting a colorized
Kylie McClain 51bef4
raw argument vector), use `LIBTOOL=dlibtool` instead, or alternatively add
Kylie McClain 51bef4
`--debug` to the libtool flags inside of your Makefile.
Kylie McClain 51bef4
Kylie McClain 51bef4
### Corner cases
Kylie McClain 51bef4
Kylie McClain 51bef4
Some programs which make heavy use of recursive `make` are known to drop the
Kylie McClain 51bef4
`LIBTOOL` value at some point in the process, and as such you may additionally
Kylie McClain 51bef4
need to export the environment variable; `export MAKE="make LIBTOOL=slibtool"`.
Kylie McClain 51bef4
Kylie McClain 51bef4
`slibtool` additionally installs two symlinks that are the equivalent of
Kylie McClain 51bef4
`-disable-shared` and `-disable-static`, named `slibtool-static` and
Kylie McClain 51bef4
`slibtool-shared`, respectively. These symlinks should be used when building
Kylie McClain 51bef4
packages that have the above switches hard-coded into the generated libtool
46bdb3
script; two examples of such packages are `binutils` and `gdb`, which both
46bdb3
have shared library builds disabled by default. A quick way to determine
46bdb3
whether this invocation form is appropriate with a specific package is to
46bdb3
run `./libtool --features` from the build directory, then check whether the
46bdb3
output has either shared or static library builds disabled.
Kylie McClain 51bef4
Kylie McClain 51bef4
## Differences from GNU libtool
Kylie McClain 51bef4
46bdb3
While `slibtool` aims to be compatible with all common usages of libtool at the
46bdb3
build system level, there exist several differences at the implementation level
46bdb3
that should be noted.
Kylie McClain 51bef4
ddc3e6
- `.la wrappers` are always generated, but by default are never installed;
ddc3e6
  `.la wrappers` contain key information that is provided to libtool when
ddc3e6
  generating a shared library or static archive, and which is needed when
ddc3e6
  passing the archive or library as an input argument in .la form to the
ddc3e6
  compiler driver in subsequent link steps. Since `slibtool` is entirely
ddc3e6
  independent of the above wrappers with respect to its own functionality,
ddc3e6
  and given its announced goal to remain compatible with the script-based
ddc3e6
  libtool as much as possible, `slibtool`'s behavior is to always produce
ddc3e6
  `.la wrappers` on the one hand, yet fully ignore their content on the
ddc3e6
  other.
ddc3e6
ddc3e6
  Despite their internal nature, installed .la wrappers are often [ab]used
ddc3e6
  in strange and mysterious ways by distro-related tools other than libtool
ddc3e6
  itself. For the sake of distributions that depend on the aforementioned
ddc3e6
  wrappers, slibtool comes with three special symlinks named `clibtool`,
ddc3e6
  `clibtool-shared`, and `clibtool-static`, respectively. The `'c'` in
ddc3e6
  `clibtool` stands for `compatible`, and accordingly indicates an end-user's
ddc3e6
  preference towards perfect emulation of legacy behavior.
ddc3e6
Kylie McClain 51bef4
- `-rpath` argument values are passed to the compiler and linker as needed only;
Kylie McClain 51bef4
  `-rpath` is often [mis]used by libtool to add redundant paths to a program's
Kylie McClain 51bef4
  linker search path. When using slibtool, `-rpath` argument values are only
Kylie McClain 51bef4
  forwarded to the compiler and linker when pointing to non-default linker
46bdb3
  directories, and are accordingly filtered out when pointing to default
46bdb3
  library locations (i.e. `/usr/lib`, `/lib`, and so on).
Kylie McClain 51bef4
Kylie McClain 51bef4
- no-ops
Kylie McClain 51bef4
    - `-R`, which adds a path to the generated program's run-time search path;
Kylie McClain 51bef4
      this switch is currently not needed, and is accordingly ignored.
Kylie McClain 51bef4
    - `-export-symbols`, which exports symbols listed in a given file, and
Kylie McClain 51bef4
      `-export-symbols-regex`, which exports symbols matching a regex;
Kylie McClain 51bef4
      both are unimplemented because similar functionality has long been
Kylie McClain 51bef4
      provided by the compiler or toolchain; `gcc` has supported setting ELF
Kylie McClain 51bef4
      visibility since v4.0, for instance, and PE import library support is
Kylie McClain 51bef4
      provided by slibtool via the --output-def linker switch and a subsequent
Kylie McClain 51bef4
      invocation of dlltool.
Kylie McClain 51bef4
    - `-no-install`, which considers the executable wrapper to be optional;
Kylie McClain 51bef4
      this switch is not needed on modern systems, and is accordingly ignored.
Kylie McClain 51bef4
Kylie McClain 51bef4
- No `libltdl`.
Kylie McClain 51bef4
  libltdl is nowadays no longer needed; it serves to provide a `dlopen()`
Kylie McClain 51bef4
  functionality on systems which do not offer it, i.e. HP-UX and BeOS,
Kylie McClain 51bef4
  however since neither HP-UX nor BeOS is currently supported by slibtool,
Kylie McClain 51bef4
  there exists no urgent need to provide equivalent functionality.
Kylie McClain 51bef4
Kylie McClain 51bef4
## Development
Kylie McClain 51bef4
Kylie McClain 51bef4
Major changes to slibtool should be discussed on [#midipix] prior to pursuing
Kylie McClain 51bef4
a considerable effort, and patches should be sent, gpg-signed, to the project
Kylie McClain 51bef4
maintainer; before hacking on slibtool, please take a moment of your time and
Kylie McClain 51bef4
read the [CONTRIB] document.
Kylie McClain 51bef4
46bdb3
As you finalize your changes to the code, please consider building at least
46bdb3
once with `cparser` as the compiler. cparser is excellent at catching logical
46bdb3
errors and semantic flaws, and as of the time of this writing is capable of
46bdb3
spotting bugs that go unnoticed by other major compilers. For a few examples
46bdb3
of such hidden bugs, see commits [94d109f], [1142bf2], and [55c95a8].
Kylie McClain 51bef4
Kylie McClain 51bef4
## License
Kylie McClain 51bef4
Kylie McClain 51bef4
`slibtool` is distributed under a permissive [MIT license].
Kylie McClain 51bef4
Kylie McClain 51bef4
[MIT license]:  http://git.midipix.org/cgit.cgi/slibtool/tree/COPYING.SLIBTOOL
Kylie McClain 51bef4
[libltdl]:      https://www.gnu.org/software/libtool/manual/html_node/Using-libltdl.html#Using-libltdl
Kylie McClain 51bef4
[dlopen()]:     http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlopen.html
Kylie McClain 51bef4
[CONTRIB]:      http://git.midipix.org/cgit.cgi/slibtool/tree/CONTRIB
Kylie McClain 51bef4
[libtool]:      https://www.gnu.org/software/libtool/
Kylie McClain 51bef4
[#midipix]:     irc://irc.freenode.net/#midipix
Kylie McClain 51bef4
[cparser]:      http://pp.ipd.kit.edu/git/cparser/
Kylie McClain 51bef4
[94d109f]:      http://git.midipix.org/cgit.cgi/slibtool/commit/?id=94d109fa418c024c214a50d645624e2e2935e6d1
Kylie McClain 51bef4
[1142bf2]:      http://git.midipix.org/cgit.cgi/slibtool/commit/?id=1142bf2e13f411cf967c1ed8b4060d7829eb13bb
Kylie McClain 51bef4
[55c95a8]:      http://git.midipix.org/cgit.cgi/slibtool/commit/?id=55c95a829928ae9f053678a58a2145276cad9c08