Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 1 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 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. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 27 | |
| 28 | |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 29 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 30 | == Option 1: Installing musl as an alternate C library == |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 31 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 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. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 36 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 37 | To install musl as an alternate libc, follow these steps: |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 38 | |
Rich Felker | a235630 | 2012-05-04 23:53:50 -0400 | [diff] [blame] | 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. |
Rich Felker | f9c9d8c | 2011-06-27 22:34:47 -0400 | [diff] [blame] | 49 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 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. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 52 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 53 | 3. Run "make install" as a user sufficient privileges to write to the |
| 54 | destination. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 55 | |
Rich Felker | a235630 | 2012-05-04 23:53:50 -0400 | [diff] [blame] | 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. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 63 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 64 | After installing, you can use musl via the musl-gcc wrapper. For |
| 65 | example: |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 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 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 78 | To configure autoconf-based program to compile and link against musl, |
| 79 | you may wish to use: |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 80 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 81 | CC="musl-gcc -D_GNU_SOURCE" ./configure ... |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 82 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 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. |
Rich Felker | f9c9d8c | 2011-06-27 22:34:47 -0400 | [diff] [blame] | 87 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 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 |
Rich Felker | a235630 | 2012-05-04 23:53:50 -0400 | [diff] [blame] | 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. |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 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 | |
Rich Felker | a235630 | 2012-05-04 23:53:50 -0400 | [diff] [blame] | 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. |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 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 | |