Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 1 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 2 | Quick Installation Guide for musl libc |
| 3 | ====================================== |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 4 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 5 | There are many different ways to install musl depending on your usage |
| 6 | case. This document covers only the build and installation of musl by |
| 7 | itself, which is useful for upgrading an existing musl-based system or |
| 8 | compiler toolchain, or for using the provided musl-gcc wrapper with an |
| 9 | existing non-musl-based compiler. |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 10 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 11 | Building complete native or cross-compiler toolchains is outside the |
| 12 | scope of this INSTALL file. More information can be found on the musl |
| 13 | website and community wiki. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 14 | |
| 15 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 16 | Build Prerequisites |
| 17 | ------------------- |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 18 | |
| 19 | The only build-time prerequisites for musl are GNU Make and a |
| 20 | freestanding C99 compiler toolchain targeting the desired instruction |
| 21 | set architecture and ABI, with support for gcc-style inline assembly, |
| 22 | weak aliases, and stand-alone assembly source files. |
| 23 | |
| 24 | The system used to build musl does not need to be Linux-based, nor do |
| 25 | the Linux kernel headers need to be available. |
| 26 | |
Rich Felker | 9f50537 | 2013-12-01 23:16:38 -0500 | [diff] [blame] | 27 | If support for dynamic linking is desired, some further requirements |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 28 | are placed on the compiler and linker. In particular, the linker must |
| 29 | support the -Bsymbolic-functions option. |
| 30 | |
| 31 | At present, GCC 4.6 or later is the recommended compiler for building |
| 32 | musl. Any earlier version of GCC with full C99 support should also |
| 33 | work, but may be subject to minor floating point conformance issues on |
| 34 | i386 targets. Sufficiently recent versions of PCC and LLVM/clang are |
| 35 | also believed to work, but have not been tested as heavily; prior to |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 36 | Fall 2012, both had known bugs that affected musl. Firm/cparser is |
| 37 | also believed to work but lacks support for producing shared |
Rich Felker | 60276b9 | 2014-07-31 19:02:54 -0400 | [diff] [blame] | 38 | libraries. GCC 4.9.0 and 4.9.1 are known to have a serious bug |
| 39 | (#61144) which affects musl. Beginning with version 1.1.4 musl |
| 40 | attempts to work around the bug, but these compiler versions are still |
| 41 | considered unstable and unsupported. |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 42 | |
| 43 | |
| 44 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 45 | Supported Targets |
| 46 | ----------------- |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 47 | |
| 48 | musl can be built for the following CPU instruction set architecture |
| 49 | and ABI combinations: |
| 50 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 51 | * i386 |
| 52 | * Minimum CPU model is actually 80486 unless kernel emulation of |
| 53 | the `cmpxchg` instruction is added |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 54 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 55 | * x86_64 |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 56 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 57 | * ARM |
| 58 | * EABI, standard or hard-float VFP variant |
| 59 | * Little-endian default; big-endian variants also supported |
| 60 | * Compiler toolchains only support armv4t and later |
| 61 | |
| 62 | * MIPS |
| 63 | * ABI is o32 |
| 64 | * Big-endian default; little-endian variants also supported |
| 65 | * Default ABI variant uses FPU registers; alternate soft-float ABI |
| 66 | that does not use FPU registers or instructions is available |
| 67 | * MIPS2 or later, or kernel emulation of ll/sc (standard in Linux) |
| 68 | is required |
| 69 | |
| 70 | * PowerPC |
| 71 | * Only 32-bit is supported |
| 72 | * Compiler toolchain must provide 64-bit long double, not IBM |
| 73 | double-double or IEEE quad |
| 74 | * For dynamic linking, compiler toolchain must be configured for |
| 75 | "secure PLT" variant |
| 76 | |
| 77 | * Microblaze |
| 78 | * Big-endian default; little-endian variants also supported |
| 79 | * Soft-float |
| 80 | * Requires support for lwx/swx instructions |
| 81 | |
| 82 | The following additional targets are available for build, but may not |
| 83 | work correctly and may not yet have ABI stability: |
| 84 | |
| 85 | * SuperH (SH) |
| 86 | * Little-endian by default; big-engian variant also supported |
| 87 | * Full FPU ABI or soft-float ABI is supported, but the |
| 88 | single-precision-only FPU ABI is not supported (musl always |
| 89 | requires IEEE single and double to be supported) |
| 90 | |
| 91 | * x32 (x86_64 ILP32 ABI) |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 92 | |
| 93 | |
| 94 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 95 | Build and Installation Procedure |
| 96 | -------------------------------- |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 97 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 98 | To build and install musl: |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 99 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 100 | 1. Run the provided configure script from the top-level source |
| 101 | directory, passing on its command line any desired options. |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 102 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 103 | 2. Run "make" to compile. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 104 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 105 | 3. Run "make install" with appropriate privileges to write to the |
| 106 | target locations. |
Rich Felker | f9c9d8c | 2011-06-27 22:34:47 -0400 | [diff] [blame] | 107 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 108 | The configure script attempts to determine automatically the correct |
| 109 | target architecture based on the compiler being used. For some |
| 110 | compilers, this may not be possible. If detection fails or selects the |
| 111 | wrong architecture, you can provide an explicit selection on the |
| 112 | configure command line. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 113 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 114 | By default, configure installs to a prefix of "/usr/local/musl". This |
| 115 | differs from the behavior of most configure scripts, and is chosen |
| 116 | specifically to avoid clashing with libraries already present on the |
| 117 | system. DO NOT set the prefix to "/usr", "/usr/local", or "/" unless |
| 118 | you're upgrading libc on an existing musl-based system. Doing so will |
| 119 | break your existing system when you run "make install" and it may be |
| 120 | difficult to recover. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 121 | |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 122 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 123 | |
| 124 | Notes on Dynamic Linking |
| 125 | ------------------------ |
| 126 | |
| 127 | If dynamic linking is enabled, one file needs to be installed outside |
| 128 | of the installation prefix: /lib/ld-musl-$ARCH.so.1. This is the |
| 129 | dynamic linker. Its pathname is hard-coded into all dynamic-linked |
| 130 | programs, so for the sake of being able to share binaries between |
| 131 | systems, a consistent location should be used everywhere. Note that |
| 132 | the same applies to glibc and its dynamic linker, which is named |
| 133 | /lib/ld-linux.so.2 on i386 systems. |
| 134 | |
| 135 | If for some reason it is impossible to install the dynamic linker in |
| 136 | its standard location (for example, if you are installing without root |
| 137 | privileges), the --syslibdir option to configure can be used to |
| 138 | provide a different location |
| 139 | |
| 140 | At runtime, the dynamic linker needs to know the paths to search for |
| 141 | shared libraries. You should create a text file named |
| 142 | /etc/ld-musl-$ARCH.path (where $ARCH matches the architecture name |
| 143 | used in the dynamic linker) containing a list of directories where you |
| 144 | want the dynamic linker to search for shared libraries, separated by |
| 145 | colons or newlines. If the dynamic linker has been installed in a |
| 146 | non-default location, the path file also needs to reside at that |
| 147 | location (../etc relative to the chosen syslibdir). |
| 148 | |
| 149 | If you do not intend to use dynamic linking, you may disable it by |
| 150 | passing --disable-shared to configure; this also cuts the build time |
| 151 | in half. |
| 152 | |
| 153 | |
| 154 | |
| 155 | Checking for Successful Installation |
| 156 | ------------------------------------ |
| 157 | |
| 158 | After installing, you should be able to use musl via the musl-gcc |
| 159 | wrapper. For example: |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 160 | |
| 161 | cat > hello.c <<EOF |
| 162 | #include <stdio.h> |
| 163 | int main() |
| 164 | { |
| 165 | printf("hello, world!\n"); |
| 166 | return 0; |
| 167 | } |
| 168 | EOF |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 169 | /usr/local/musl/bin/musl-gcc hello.c |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 170 | ./a.out |
| 171 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 172 | To configure autoconf-based program to compile and link against musl, |
Rich Felker | c1a9658 | 2012-09-07 23:13:55 -0400 | [diff] [blame] | 173 | set the CC variable to musl-gcc when running configure, as in: |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 174 | |
Rich Felker | c1a9658 | 2012-09-07 23:13:55 -0400 | [diff] [blame] | 175 | CC=musl-gcc ./configure ... |
Rich Felker | f9c9d8c | 2011-06-27 22:34:47 -0400 | [diff] [blame] | 176 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 177 | You will probably also want to use --prefix when building libraries to |
| 178 | ensure that they are installed under the musl prefix and not in the |
| 179 | main host system library directories. |