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. Edit config.mak to select your system's CPU architecture (i386,
  40    x86_64, or arm), installation prefix, location for the dynamic
  41    linker, and other build preferences.
  42
  43 2. Run "make". Parallel build is fully supported, so you can instead
  44    use "make -j3" or so on SMP systems if you like.
  45
  46 3. Run "make install" as a user sufficient privileges to write to the
  47    destination.
  48
  49 4. Ensure that /etc/ld-musl-$ARCH.path (where $ARCH is replaced by
  50    i386, x86_64, etc. as appropriate) contains the correct search path
  51    for where you intend to install musl-linked shared library files.
  52    This step can be skipped if you disabled dynamic linking.
  53
  54 After installing, you can use musl via the musl-gcc wrapper. For
  55 example:
  56
  57 cat > hello.c <<EOF
  58 #include <stdio.h>
  59 int main()
  60 {
  61         printf("hello, world!\n");
  62         return 0;
  63 }
  64 EOF
  65 musl-gcc hello.c
  66 ./a.out
  67
  68 To configure autoconf-based program to compile and link against musl,
  69 you may wish to use:
  70
  71 CC="musl-gcc -D_GNU_SOURCE" ./configure ...
  72
  73 Correctly-written build systems should not need -D_GNU_SOURCE as part
  74 of $CC, but many programs do not use feature-test macros correctly and
  75 simply assume the compiler will automatically give them the kitchen
  76 sink, so the above command is an easy workaround.
  77
  78 You will probably also want to use --prefix when building libraries to
  79 ensure that they are installed under the musl prefix and not in the
  80 main host system library directories.
  81
  82 Finally, it's worth noting that musl's include and lib directories in
  83 the build tree are setup to be usable without installation, if
  84 necessary. Just modify the musl-gcc wrapper's libc_prefix variable to
  85 point to the source/build tree.
  86
  87
  88
  89 == Option 2: Installing musl as the primary C library ==
  90
  91 In this setup, you will need an existing compiler/toolchain. It
  92 shouldnt matter whether it was configured for glibc, uClibc, musl, or
  93 something else entirely, but sometimes gcc can be uncooperative,
  94 especially if the system distributor has built gcc with strange
  95 options. It probably makes the most sense to perform the following
  96 steps inside a chroot setup or on a virtualized machine with the
  97 filesystem containing just a minimal toolchain.
  98
  99 WARNING: DO NOT DO THIS ON AN EXISTING SYSTEM UNLESS YOU REALLY WANT
 100 TO CONVERT IT TO BE A MUSL-BASED SYSTEM!!
 101
 102 1. If you are just upgrading an existing version of musl, you can skip
 103    step 1 entirely. Otherwise, move the existing include and lib
 104    directories on your system out of the way. Unless all the binaries
 105    you will need are static-linked, you should edit /etc/ld.so.conf
 106    (or equivalent) and put the new locations of your old libraries in
 107    the search path before you move them, or your system will break
 108    badly and you will not be able to continue.
 109
 110 2. Edit musl's config.mak and set the installation prefix to the
 111    prefix your compiler toolchain is configured to search, probably
 112    /usr. Set ARCH to match your CPU architecture, and change any other
 113    options as you see fit.
 114
 115 3. Run "make" to compile musl.
 116
 117 4. Run "make install" with appropriate privileges.
 118
 119 5. If you are using gcc and wish to use dynamic linking, find the gcc
 120    directory containing libgcc.a (it should be something like
 121    /usr/lib/gcc/i486-linux-gnu/4.3.5, with the arch and version
 122    possibly different) and look for a specs file there. If none
 123    exists, use "gcc -dumpspecs > specs" to generate a specs file. Find
 124    the dynamic linker (/lib/ld-linux.so.2 or similar) and change it to
 125    "/lib/ld-musl-$ARCH.so.1" (with $ARCH replaced by your CPU arch).
 126
 127 At this point, musl should be the default libc. Compile a small test
 128 program with gcc and verify (using readelf -a or objdump -x) that the
 129 dynamic linker (program interpreter) is /lib/ld-musl-$ARCH.so.1. If
 130 you're using static linking only, you might instead check the symbols
 131 and look for anything suspicious that would indicate your old glibc or
 132 uClibc was used.
 133
 134 When building programs against musl, you may still want to ensure the
 135 appropriate feature test macros get defined, as in:
 136
 137 CC="gcc -D_GNU_SOURCE" ./configure ...
 138