INSTALL

   1
   2 ==== Installing musl ====
   3
   4 musl may be installed either as an alternate C library alongside the
   5 existing libraries on a system, or as the primary C library for a new
   6 or existing musl-based system.
   7
   8 This document covers the prerequisites and procedures for compiling
   9 and installation.
  10
  11
  12
  13 ==== Build Prerequisites ====
  14
  15 The only build-time prerequisites for musl are GNU Make and a
  16 freestanding C99 compiler toolchain targeting the desired instruction
  17 set architecture and ABI, with support for gcc-style inline assembly,
  18 weak aliases, and stand-alone assembly source files.
  19
  20 The system used to build musl does not need to be Linux-based, nor do
  21 the Linux kernel headers need to be available.
  22
  23 If support for dynamic linking is desired, some further requirements
  24 are placed on the compiler and linker. In particular, the linker must
  25 support the -Bsymbolic-functions option.
  26
  27 At present, GCC 4.6 or later is the recommended compiler for building
  28 musl. Any earlier version of GCC with full C99 support should also
  29 work, but may be subject to minor floating point conformance issues on
  30 i386 targets. Sufficiently recent versions of PCC and LLVM/clang are
  31 also believed to work, but have not been tested as heavily; prior to
  32 Fall 2012, both had known bugs that affected musl.
  33
  34
  35
  36 === Supported Targets ====
  37
  38 musl can be built for the following CPU instruction set architecture
  39 and ABI combinations:
  40
  41 - i386 (requires 387 math and 486 cmpxchg instructions)
  42 - x86_64
  43 - arm (EABI)
  44 - mips (o32 ABI, requires fpu or float emulation in kernel)
  45 - microblaze (requires a cpu with lwx/swx instructions)
  46 - powerpc (32-bit, must use "secure plt" mode for dynamic linking)
  47
  48 For architectures with both little- and big-endian options, both are
  49 supported unless otherwise noted.
  50
  51 In general, musl assumes the availability of all Linux syscall
  52 interfaces available in Linux 2.6.0. Some programs that do not use
  53 threads or other modern functionality may be able to run on 2.4.x
  54 kernels. Other kernels (such as BSD) that provide a Linux-compatible
  55 syscall ABI should also work but have not been extensively tested.
  56
  57
  58
  59 ==== Option 1: Installing musl as an alternate C library ====
  60
  61 In this setup, musl and any third-party libraries linked to musl will
  62 reside under an alternate prefix such as /usr/local/musl or /opt/musl.
  63 A wrapper script for gcc, called musl-gcc, can be used in place of gcc
  64 to compile and link programs and libraries against musl.
  65
  66 (Note: There are not yet corresponding wrapper scripts for other
  67 compilers, so if you wish to compile and link against musl using
  68 another compiler, you are responsible for providing the correct
  69 options to override the default include and library search paths.)
  70
  71 To install musl as an alternate libc, follow these steps:
  72
  73 1. Configure musl's build with a command similar to:
  74    ./configure --prefix=/usr/local/musl --exec-prefix=/usr/local
  75    Refer to ./configure --help for details on other options. You may
  76    change the install prefix if you like, but DO NOT set it to a
  77    location that contains your existing libraries based on another
  78    libc such as glibc or uClibc. If you do not intend to use dynamic
  79    linking, you may disable it at this point via --disable-shared and
  80    cut the build time in half. If you wish to use dynamic linking but
  81    do not have permissions to write to /lib, you will need to set an
  82    alternate dynamic linker location via --syslibdir.
  83
  84 2. Run "make". Parallel build is fully supported, so you can instead
  85    use "make -j3" or so on SMP systems if you like.
  86
  87 3. Run "make install" as a user sufficient privileges to write to the
  88    destination.
  89
  90 4. Create a file named /etc/ld-musl-$ARCH.path (where $ARCH is
  91    replaced by i386, x86_64, etc. as appropriate) containing the
  92    correct colon-delimited search path for where you intend to install
  93    musl-linked shared library files. If this file is missing, musl
  94    will search the standard path, and you will encounter problems when
  95    it attempts to load libraries linked against your host libc. Note
  96    that this step can be skipped if you disabled dynamic linking.
  97
  98 After installing, you can use musl via the musl-gcc wrapper. For
  99 example:
 100
 101 cat > hello.c <<EOF
 102 #include <stdio.h>
 103 int main()
 104 {
 105         printf("hello, world!\n");
 106         return 0;
 107 }
 108 EOF
 109 musl-gcc hello.c
 110 ./a.out
 111
 112 To configure autoconf-based program to compile and link against musl,
 113 set the CC variable to musl-gcc when running configure, as in:
 114
 115 CC=musl-gcc ./configure ...
 116
 117 You will probably also want to use --prefix when building libraries to
 118 ensure that they are installed under the musl prefix and not in the
 119 main host system library directories.
 120
 121 Finally, it's worth noting that musl's include and lib directories in
 122 the build tree are setup to be usable without installation, if
 123 necessary. Just modify the paths in the spec file used by musl-gcc
 124 (it's located at $prefix/lib/musl-gcc.specs) to point to the
 125 source/build tree.
 126
 127
 128
 129 ==== Option 2: Installing musl as the primary C library ====
 130
 131 In this setup, you will need an existing compiler/toolchain. It
 132 shouldn't matter whether it was configured for glibc, uClibc, musl, or
 133 something else entirely, but sometimes gcc can be uncooperative,
 134 especially if the system distributor has built gcc with strange
 135 options. It probably makes the most sense to perform the following
 136 steps inside a chroot setup or on a virtualized machine with the
 137 filesystem containing just a minimal toolchain.
 138
 139 WARNING: DO NOT DO THIS ON AN EXISTING SYSTEM UNLESS YOU REALLY WANT
 140 TO CONVERT IT TO BE A MUSL-BASED SYSTEM!!
 141
 142 1. If you are just upgrading an existing version of musl, you can skip
 143    step 1 entirely. Otherwise, move the existing include and lib
 144    directories on your system out of the way. Unless all the binaries
 145    you will need are static-linked, you should edit /etc/ld.so.conf
 146    (or equivalent) and put the new locations of your old libraries in
 147    the search path before you move them, or your system will break
 148    badly and you will not be able to continue.
 149
 150 2. Configure musl's build with a command similar to:
 151    ./configure --prefix=/usr --disable-gcc-wrapper
 152    Refer to ./configure --help for details on other options.
 153
 154 3. Run "make" to compile musl.
 155
 156 4. Run "make install" with appropriate privileges.
 157
 158 5. If you are using gcc and wish to use dynamic linking, find the gcc
 159    directory containing libgcc.a (it should be something like
 160    /usr/lib/gcc/i486-linux-gnu/4.3.5, with the arch and version
 161    possibly different) and look for a specs file there. If none
 162    exists, use "gcc -dumpspecs > specs" to generate a specs file. Find
 163    the dynamic linker (/lib/ld-linux.so.2 or similar) and change it to
 164    "/lib/ld-musl-$ARCH.so.1" (with $ARCH replaced by your CPU arch).
 165
 166 At this point, musl should be the default libc. Compile a small test
 167 program with gcc and verify (using readelf -a or objdump -x) that the
 168 dynamic linker (program interpreter) is /lib/ld-musl-$ARCH.so.1. If
 169 you're using static linking only, you might instead check the symbols
 170 and look for anything suspicious that would indicate your old glibc or
 171 uClibc was used.