nsz Git - musl/blob - 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 First, some prerequisites:
   9
  10 - A C99 compiler with gcc-style inline assembly support, support for
  11   weak aliases, and support for building stand-alone assembly files.
  12   gcc 3.x and 4.x are known to work. pcc and LLVM/clang may work but
  13   are untested, and pcc is known to have some bugs.
  14
  15 - GNU make
  16
  17 - Linux, preferably 2.6.22 or later. Older versions are known to have
  18   serious bugs that will make some interfaces non-conformant, but if
  19   you don't need threads or POSIX 2008 features, even 2.4 is probably
  20   okay.
  21
  22 - A supported CPU architecture (currently i386, x86_64, or arm).
  23
  24 - If you want to use dynamic linking, it's recommended that you have
  25   permissions to write to /lib and /etc. Otherwise your binaries will
  26   have to use a nonstandard dynamic linker path.
  27
  28
  29
  30 == Option 1: Installing musl as an alternate C library ==
  31
  32 In this setup, musl and any third-party libraries linked to musl will
  33 reside under an alternate prefix such as /usr/local/musl or /opt/musl.
  34 A wrapper script for gcc, called musl-gcc, can be used in place of gcc
  35 to compile and link programs and libraries against musl.
  36
  37 To install musl as an alternate libc, follow these steps:
  38
  39 1. Configure musl's build with a command similar to:
  40    ./configure --prefix=/usr/local/musl --exec-prefix=/usr/local
  41    Refer to ./configure --help for details on other options. You may
  42    change the install prefix if you like, but DO NOT set it to a
  43    location that contains your existing libraries based on another
  44    libc such as glibc or uClibc. If you do not intend to use dynamic
  45    linking, you may disable it at this point via --disable-shared and
  46    cut the build time in half. If you wish to use dynamic linking but
  47    do not have permissions to write to /lib, you will need to set an
  48    alternate dynamic linker location via --syslibdir.
  49
  50 2. Run "make". Parallel build is fully supported, so you can instead
  51    use "make -j3" or so on SMP systems if you like.
  52
  53 3. Run "make install" as a user sufficient privileges to write to the
  54    destination.
  55
  56 4. Create a file named /etc/ld-musl-$ARCH.path (where $ARCH is
  57    replaced by i386, x86_64, etc. as appropriate) containing the
  58    correct colon-delimited search path for where you intend to install
  59    musl-linked shared library files. If this file is missing, musl
  60    will search the standard path, and you will encounter problems when
  61    it attempts to load libraries linked against your host libc. Note
  62    that this step can be skipped if you disabled dynamic linking.
  63
  64 After installing, you can use musl via the musl-gcc wrapper. For
  65 example:
  66
  67 cat > hello.c <<EOF
  68 #include <stdio.h>
  69 int main()
  70 {
  71         printf("hello, world!\n");
  72         return 0;
  73 }
  74 EOF
  75 musl-gcc hello.c
  76 ./a.out
  77
  78 To configure autoconf-based program to compile and link against musl,
  79 you may wish to use:
  80
  81 CC="musl-gcc -D_GNU_SOURCE" ./configure ...
  82
  83 Correctly-written build systems should not need -D_GNU_SOURCE as part
  84 of $CC, but many programs do not use feature-test macros correctly and
  85 simply assume the compiler will automatically give them the kitchen
  86 sink, so the above command is an easy workaround.
  87
  88 You will probably also want to use --prefix when building libraries to
  89 ensure that they are installed under the musl prefix and not in the
  90 main host system library directories.
  91
  92 Finally, it's worth noting that musl's include and lib directories in
  93 the build tree are setup to be usable without installation, if
  94 necessary. Just modify the the paths in the spec file used by musl-gcc
  95 (it's located at $prefix/lib/musl-gcc.specs) to point to the
  96 source/build tree.
  97
  98
  99
 100 == Option 2: Installing musl as the primary C library ==
 101
 102 In this setup, you will need an existing compiler/toolchain. It
 103 shouldnt matter whether it was configured for glibc, uClibc, musl, or
 104 something else entirely, but sometimes gcc can be uncooperative,
 105 especially if the system distributor has built gcc with strange
 106 options. It probably makes the most sense to perform the following
 107 steps inside a chroot setup or on a virtualized machine with the
 108 filesystem containing just a minimal toolchain.
 109
 110 WARNING: DO NOT DO THIS ON AN EXISTING SYSTEM UNLESS YOU REALLY WANT
 111 TO CONVERT IT TO BE A MUSL-BASED SYSTEM!!
 112
 113 1. If you are just upgrading an existing version of musl, you can skip
 114    step 1 entirely. Otherwise, move the existing include and lib
 115    directories on your system out of the way. Unless all the binaries
 116    you will need are static-linked, you should edit /etc/ld.so.conf
 117    (or equivalent) and put the new locations of your old libraries in
 118    the search path before you move them, or your system will break
 119    badly and you will not be able to continue.
 120
 121 2. Configure musl's build with a command similar to:
 122    ./configure --prefix=/usr --disable-gcc-wrapper
 123    Refer to ./configure --help for details on other options.
 124
 125 3. Run "make" to compile musl.
 126
 127 4. Run "make install" with appropriate privileges.
 128
 129 5. If you are using gcc and wish to use dynamic linking, find the gcc
 130    directory containing libgcc.a (it should be something like
 131    /usr/lib/gcc/i486-linux-gnu/4.3.5, with the arch and version
 132    possibly different) and look for a specs file there. If none
 133    exists, use "gcc -dumpspecs > specs" to generate a specs file. Find
 134    the dynamic linker (/lib/ld-linux.so.2 or similar) and change it to
 135    "/lib/ld-musl-$ARCH.so.1" (with $ARCH replaced by your CPU arch).
 136
 137 At this point, musl should be the default libc. Compile a small test
 138 program with gcc and verify (using readelf -a or objdump -x) that the
 139 dynamic linker (program interpreter) is /lib/ld-musl-$ARCH.so.1. If
 140 you're using static linking only, you might instead check the symbols
 141 and look for anything suspicious that would indicate your old glibc or
 142 uClibc was used.
 143
 144 When building programs against musl, you may still want to ensure the
 145 appropriate feature test macros get defined, as in:
 146
 147 CC="gcc -D_GNU_SOURCE" ./configure ...
 148