-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.
-STEP 1: Configuration
+This document covers the prerequisites and procedures for compiling
+and installation.
-Edit config.mak to override installation prefix, compiler options,
-etc. as needed. The defaults should be okay for trying out musl with
-static linking only. The only arch supported at present is i386. If
-you're on an x86_64 machine, you can add -m32 to the compiler options
-to build a working 32bit musl. In this case you will also need to add
--m32 in two locations in the generated tools/musl-gcc script if you
-intend to use it.
-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.
-The default prefix is /usr/local/musl for a reason, but some people
-may prefer /opt/musl or $HOME/musl.
+==== Build Prerequisites ====
+The only build-time prerequisites for musl are GNU Make and a
+freestanding C99 compiler toolchain targeting the desired instruction
+set architecture and ABI, with support for gcc-style inline assembly,
+weak aliases, and stand-alone assembly source files.
-STEP 2: Compiling
+The system used to build musl does not need to be Linux-based, nor do
+the Linux kernel headers need to be available.
-Run "make". (GNU make is required.)
+If support for dynamic linking is desired, some further requriements
+are placed on the compiler and linker. In particular, the linker must
+support the -Bsymbolic-functions option.
+At present, GCC 4.6 or later is the recommended compiler for building
+musl. Any earlier version of GCC with full C99 support should also
+work, but may be subject to minor floating point conformance issues on
+i386 targets. Sufficiently recent versions of PCC and LLVM/clang are
+also believed to work, but have not been tested as heavily; prior to
+Fall 2012, both had known bugs that affected musl.
-STEP 3: Installation
-With appropriate privileges, run "make install".
+=== Supported Targets ====
-STEP 4: Using the gcc wrapper.
+musl can be built for the following CPU instruction set architecture
+and ABI combinations:
-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:
+- i386 (requires 387 math and 486 cmpxchg instructions)
+- x86_64
+- arm (EABI)
+- mips (o32 ABI, requires fpu or float emulation in kernel)
+- microblaze (requires a cpu with lwx/swx instructions)
+- powerpc (32-bit, must use "secure plt" mode for dynamic linking)
+
+For architectures with both little- and big-endian options, both are
+supported unless otherwise noted.
+
+In general, musl assumes the availability of all Linux syscall
+interfaces available in Linux 2.6.0. Some programs that do not use
+threads or other modern functionality may be able to run on 2.4.x
+kernels. Other kernels (such as BSD) that provide a Linux-compatible
+syscall ABI should also work but have not been extensively tested.
+
+
+
+==== Option 1: Installing musl as an alternate C library ====
+
+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.
+
+(Note: There are not yet corresponding wrapper scripts for other
+compilers, so if you wish to compile and link against musl using
+another compiler, you are responsible for providing the correct
+options to override the default include and library search paths.)
+
+To install musl as an alternate libc, follow these steps:
+
+1. Configure musl's build with a command similar to:
+ ./configure --prefix=/usr/local/musl --exec-prefix=/usr/local
+ Refer to ./configure --help for details on other options. You may
+ change the install prefix if you like, but DO NOT set it to a
+ location that contains your existing libraries based on another
+ libc such as glibc or uClibc. If you do not intend to use dynamic
+ linking, you may disable it at this point via --disable-shared and
+ cut the build time in half. If you wish to use dynamic linking but
+ do not have permissions to write to /lib, you will need to set an
+ alternate dynamic linker location via --syslibdir.
+
+2. Run "make". Parallel build is fully supported, so you can instead
+ use "make -j3" or so on SMP systems if you like.
+
+3. Run "make install" as a user sufficient privileges to write to the
+ destination.
+
+4. Create a file named /etc/ld-musl-$ARCH.path (where $ARCH is
+ replaced by i386, x86_64, etc. as appropriate) containing the
+ correct colon-delimited search path for where you intend to install
+ musl-linked shared library files. If this file is missing, musl
+ will search the standard path, and you will encounter problems when
+ it attempts to load libraries linked against your host libc. Note
+ that this step can be skipped if you disabled dynamic linking.
+
+After installing, you can use musl via the musl-gcc wrapper. For
+example:
cat > hello.c <<EOF
#include <stdio.h>
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,
+set the CC variable to musl-gcc when running configure, as in:
+
+CC=musl-gcc ./configure ...
+
+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 the paths in the spec file used by musl-gcc
+(it's located at $prefix/lib/musl-gcc.specs) 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. Configure musl's build with a command similar to:
+ ./configure --prefix=/usr --disable-gcc-wrapper
+ Refer to ./configure --help for details on other options.
+
+3. Run "make" to compile musl.
+
+4. Run "make install" with appropriate privileges.
-CC=musl-gcc ./configure
+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).
-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.
+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.
projects / musl / blobdiff