existing libraries on a system, or as the primary C library for a new
or existing musl-based system.
-First, some prerequisites:
+This document covers the prerequisites and procedures for compiling
+and installation.
-- 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.
+==== Build Prerequisites ====
-- A supported CPU architecture (currently i386, x86_64, or arm).
+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.
-- 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.
+The system used to build musl does not need to be Linux-based, nor do
+the Linux kernel headers need to be available.
+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.
-== Option 1: Installing musl as an alternate C library ==
+
+
+=== Supported Targets ====
+
+musl can be built for the following CPU instruction set architecture
+and ABI combinations:
+
+- 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. 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.
+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. 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.
+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:
./a.out
To configure autoconf-based program to compile and link against musl,
-you may wish to use:
-
-CC="musl-gcc -D_GNU_SOURCE" ./configure ...
+set the CC variable to musl-gcc when running configure, as in:
-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.
+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
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.
+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 ==
+==== 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
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.
+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.
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 ...
-
projects / musl / blobdiff