initial commit with rc for skalibs-2.0.0.0

1 files changed, 139 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..efa5596
--- /dev/null
+++ b/INSTALL
@@ -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.