new installation guide with alternate and primary libc setups

INSTALL

@@ -1,45 +1,58 @@
 
-A quick-and-simple guide to installing musl:
+==== Installing musl ====
+
+musl may be installed either as an alternate C library alongside the
+existing libraries on a system, or as the primary C library for a new
+or existing musl-based system.
+
+First, some prerequisites:
+
+- A C99 compiler with gcc-style inline assembly support, support for
+  weak aliases, and support for building stand-alone assembly files.
+  gcc 3.x and 4.x are known to work. pcc and LLVM/clang may work but
+  are untested, and pcc is known to have some bugs.
+
+- GNU make
+
+- Linux, preferably 2.6.22 or later. Older versions are known to have
+  serious bugs that will make some interfaces non-conformant, but if
+  you don't need threads or POSIX 2008 features, even 2.4 is probably
+  okay.
+
+- A supported CPU architecture (currently i386, x86_64, or arm).
+
+- If you want to use dynamic linking, it's recommended that you have
+  permissions to write to /lib and /etc. Otherwise your binaries will
+  have to use a nonstandard dynamic linker path.
 
 
-STEP 1: Configuration
 
-Edit config.mak to override installation prefix, compiler options,
-target architecture, etc. as needed. Currently supported archs are
-i386 and x86_64. Otherwise, the defaults should be okay for trying out
-musl with static linking only.
+== Option 1: Installing musl as an alternate C library ==
 
-DO NOT set the prefix to /, /usr, or even /usr/local unless you really
-know what you're doing! You'll probably break your system such that
-you'll no longer be able to compile and link programs against glibc!
-This kind of setup should only be used if you're building a system
-where musl is the default/primary/only libc.
+In this setup, musl and any third-party libraries linked to musl will
+reside under an alternate prefix such as /usr/local/musl or /opt/musl.
+A wrapper script for gcc, called musl-gcc, can be used in place of gcc
+to compile and link programs and libraries against musl.
 
-The default prefix is /usr/local/musl for a reason, but some people
-may prefer /opt/musl or $HOME/musl.
+To install musl as an alternate libc, follow these steps:
 
-For shared library support, the dynamic linker pathname needs to be
-hard-coded into every program you link to musl. Ideally, you should
-leave the path ($syslibdir) set to /lib unless you are unable to
-install files to /lib, in which case you can change it.
+1. Edit config.mak to select your system's CPU architecture (i386,
+   x86_64, or arm), installation prefix, location for the dynamic
+   linker, and other build preferences.
 
+2. Run "make". Parallel build is fully supported, so you can instead
+   use "make -j3" or so on SMP systems if you like.
 
-STEP 2: Compiling
+3. Run "make install" as a user sufficient privileges to write to the
+   destination.
 
-Run "make". (GNU make is required.)
+4. Ensure that /etc/ld-musl-$ARCH.path (where $ARCH is replaced by
+   i386, x86_64, etc. as appropriate) contains the correct search path
+   for where you intend to install musl-linked shared library files.
+   This step can be skipped if you disabled dynamic linking.
 
-
-STEP 3: Installation
-
-With appropriate privileges, run "make install".
-
-
-STEP 4: Using the gcc wrapper.
-
-musl comes with a script "musl-gcc" (installed in /usr/local/bin by
-default) that can be used to compile and link C programs against musl.
-It requires a version of gcc with the -wrapper option (gcc 4.x should
-work). For example:
+After installing, you can use musl via the musl-gcc wrapper. For
+example:
 
 cat > hello.c <<EOF
 #include <stdio.h>
@@ -52,17 +65,74 @@ EOF
 musl-gcc hello.c
 ./a.out
 
-For compiling programs that use autoconf, you'll need to configure
-them with a command like this:
+To configure autoconf-based program to compile and link against musl,
+you may wish to use:
 
-CC=musl-gcc ./configure
+CC="musl-gcc -D_GNU_SOURCE" ./configure ...
 
-Be aware that (at present) libraries linked against glibc are unlikely
-to be usable, and the musl-gcc wrapper inhibits search of the system
-library paths in any case. You'll need to compile any prerequisite
-libraries (like ncurses, glib, etc.) yourself.
+Correctly-written build systems should not need -D_GNU_SOURCE as part
+of $CC, but many programs do not use feature-test macros correctly and
+simply assume the compiler will automatically give them the kitchen
+sink, so the above command is an easy workaround.
+
+You will probably also want to use --prefix when building libraries to
+ensure that they are installed under the musl prefix and not in the
+main host system library directories.
+
+Finally, it's worth noting that musl's include and lib directories in
+the build tree are setup to be usable without installation, if
+necessary. Just modify the musl-gcc wrapper's libc_prefix variable to
+point to the source/build tree.
+
+
+
+== Option 2: Installing musl as the primary C library ==
+
+In this setup, you will need an existing compiler/toolchain. It
+shouldnt matter whether it was configured for glibc, uClibc, musl, or
+something else entirely, but sometimes gcc can be uncooperative,
+especially if the system distributor has built gcc with strange
+options. It probably makes the most sense to perform the following
+steps inside a chroot setup or on a virtualized machine with the
+filesystem containing just a minimal toolchain.
+
+WARNING: DO NOT DO THIS ON AN EXISTING SYSTEM UNLESS YOU REALLY WANT
+TO CONVERT IT TO BE A MUSL-BASED SYSTEM!!
+
+1. If you are just upgrading an existing version of musl, you can skip
+   step 1 entirely. Otherwise, move the existing include and lib
+   directories on your system out of the way. Unless all the binaries
+   you will need are static-linked, you should edit /etc/ld.so.conf
+   (or equivalent) and put the new locations of your old libraries in
+   the search path before you move them, or your system will break
+   badly and you will not be able to continue.
+
+2. Edit musl's config.mak and set the installation prefix to the
+   prefix your compiler toolchain is configured to search, probably
+   /usr. Set ARCH to match your CPU architecture, and change any other
+   options as you see fit.
+
+3. Run "make" to compile musl.
+
+4. Run "make install" with appropriate privileges.
+
+5. If you are using gcc and wish to use dynamic linking, find the gcc
+   directory containing libgcc.a (it should be something like
+   /usr/lib/gcc/i486-linux-gnu/4.3.5, with the arch and version
+   possibly different) and look for a specs file there. If none
+   exists, use "gcc -dumpspecs > specs" to generate a specs file. Find
+   the dynamic linker (/lib/ld-linux.so.2 or similar) and change it to
+   "/lib/ld-musl-$ARCH.so.1" (with $ARCH replaced by your CPU arch).
+
+At this point, musl should be the default libc. Compile a small test
+program with gcc and verify (using readelf -a or objdump -x) that the
+dynamic linker (program interpreter) is /lib/ld-musl-$ARCH.so.1. If
+you're using static linking only, you might instead check the symbols
+and look for anything suspicious that would indicate your old glibc or
+uClibc was used.
+
+When building programs against musl, you may still want to ensure the
+appropriate feature test macros get defined, as in:
+
+CC="gcc -D_GNU_SOURCE" ./configure ...
 
-Note: If you want the system headers to behave something like glibc's
-and expose the kitchen sink by default, you might want to try
-CC="musl-gcc -D_GNU_SOURCE" instead of just CC=musl-gcc. This is
-needed for compiling many programs with portability issues.