diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 139 |
1 files changed, 139 insertions, 0 deletions
@@ -0,0 +1,139 @@ +Build Instructions +------------------ + +* Requirements + ------------ + + - A POSIX-compliant C development environment + - GNU make version 3.81 or later + - If cross-compiling: the sysdeps for your target architecture + (see the "Cross-compilation" section below) + + This software will install on any operating system that implements +POSIX.1-2008, available at: + http://pubs.opengroup.org/onlinepubs/9699919799/ + + +* Standard usage + -------------- + + ./configure && make && sudo make install + + will work for most users. + It will install the static libraries in /usr/lib/skalibs, the shared +libraries in /lib, and the sysdeps in /usr/lib/skalibs/sysdeps. + + You can strip the libraries of their extra symbols via "make strip" +before the "make install" phase. It will shave a few bytes off them. + + +* Customization + ------------- + + You can customize paths via flags given to configure. + See ./configure --help for a list of all available configure options. + + + +* Environment variables + --------------------- + + Controlling a build process via environment variables is a big and +dangerous hammer. You should try and pass flags to configure instead; +nevertheless, the standard environment variables are recognized. + + The value of the CROSS_COMPILE environment variable will prefix the +building tools' names. The --enable-cross option is preferred, see +"Cross-compilation" below. + + If the CC environment variable is set, its value will override compiler +detection by configure. + + The values of CFLAGS, CPPFLAGS and LDFLAGS will be appended to flags +auto-detected by configure. To entirely override the flags set by +configure, use make -e. + + The Makefile supports the DESTDIR convention for staging. + + +* Shared libraries + ---------------- + + Software from skarnet.org is small enough that shared libraries are +generally not worth using. Static linking is simpler and incurs less +runtime overhead and less points of failure: but since skalibs only +provides libraries, both versions are built by default. + Nevertheless, you can: + * avoid building shared libraries: --disable-shared + * avoid building static libraries: --disable-static + + If you are using a GNU/Linux system, be aware that the GNU libc +behaves badly with static linking and produces huge executables, +so if you plan on making static executables, you should consider +using another libc, which you also need to use when compiling +skalibs. musl is recommended: http://musl-libc.org/ + + +* Cross-compilation + ----------------- + + skarnet.org centralizes all the difficulty of cross-compilation +in skalibs. + The native skalibs build process runs some tests to gather "sysdeps", +i.e. system-dependent properties of the target, and stores those +into a sysdeps directory; software depending on skalibs is provided +the name of the sysdeps directory at build time, and can depend on +its contents - that's how skarnet.org packages are easily made +portable. + However, when the host differs from the target - the cross-compilation +case - those build-time tests are invalid. So you must provide +configure with a precomputed sysdeps directory, containing valid +sysdeps values for your target. + + Use the --with-sysdeps=DIR option to specify DIR as a sysdeps +directory for your target. Also use the --enable-cross=PREFIX option +to specify a cross-compiling PREFIX for your toolchain's binaries, +or simply --enable-cross if your default toolchain is a cross-compiler. + + If you know the peculiarities of your target system, you can build +a sysdeps directory by hand. However, a much easier, and recommended, +method of obtaining sysdeps, is to natively determine them (via +./configure) in a virtual machine, for instance provided by qemu. If you +are using Linux, simple root filesystems bootable with qemu for testing +purposes are available at Aboriginal Linux: http://landley.net/aboriginal/ + Precomputed sysdeps for various targets may also be available on +skarnet.org or on third-party sites. + + +* The slashpackage convention + --------------------------- + + The slashpackage convention (http://cr.yp.to/slashpackage.html) +is a package installation scheme that provides a few guarantees +over other conventions such as the FHS, for instance fixed +absolute pathnames. skarnet.org packages support it: use the +--enable-slashpackage option to configure, or +--enable-slashpackage=DIR for a prefixed DIR/package tree. +This option will activate slashpackage support during the build +and set slashpackage-compatible installation directories. +Other options setting individual installation directories will be +ignored. + + When using slashpackage, two additional Makefile targets are +available after "make install": + - "make -L update" changes the default version of the software to the +freshly installed one. (This is useful when you have several installed +versions of the same software, which slashpackage supports.) + - "make -L global-links" adds links from /command and /library.so to the +default version of the binaries and shared libraries. + The "-L" option to make is necessary because targets are symbolic links, +and the default make behaviour is to check the pointed file's timestamp +and not the symlink's timestamp. + + +* Out-of-tree builds + ------------------ + + skarnet.org packages do not support out-of-tree builds. They +are small, so it does not cost much to duplicate the entire +source tree if parallel builds are needed. |