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 |
Rich Felker | 40891ae | 2016-02-02 17:35:06 -0500 | [diff] [blame] | 21 | set architecture and ABI, with support for a minimal subset of "GNU C" |
| 22 | extensions consisting mainly of gcc-style inline assembly, weak |
| 23 | aliases, hidden visibility, and stand-alone assembly source files. |
| 24 | |
| 25 | GCC, LLVM/clang, Firm/cparser, and PCC have all successfully built |
| 26 | musl, but GCC is the most widely used/tested. Recent compiler (and |
| 27 | binutils) versions should be used if possible since some older |
| 28 | versions have bugs which affect musl. |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 29 | |
| 30 | The system used to build musl does not need to be Linux-based, nor do |
| 31 | the Linux kernel headers need to be available. |
| 32 | |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 33 | |
| 34 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 35 | Supported Targets |
| 36 | ----------------- |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 37 | |
| 38 | musl can be built for the following CPU instruction set architecture |
| 39 | and ABI combinations: |
| 40 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 41 | * i386 |
| 42 | * Minimum CPU model is actually 80486 unless kernel emulation of |
| 43 | the `cmpxchg` instruction is added |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 44 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 45 | * x86_64 |
Rich Felker | 40891ae | 2016-02-02 17:35:06 -0500 | [diff] [blame] | 46 | * ILP32 ABI (x32) is available as a separate arch but is still |
| 47 | experimental |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 48 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 49 | * ARM |
| 50 | * EABI, standard or hard-float VFP variant |
| 51 | * Little-endian default; big-endian variants also supported |
| 52 | * Compiler toolchains only support armv4t and later |
| 53 | |
Rich Felker | 40891ae | 2016-02-02 17:35:06 -0500 | [diff] [blame] | 54 | * AArch64 |
| 55 | * Little-endian default; big-endian variants also supported |
| 56 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 57 | * MIPS |
| 58 | * ABI is o32 |
| 59 | * Big-endian default; little-endian variants also supported |
| 60 | * Default ABI variant uses FPU registers; alternate soft-float ABI |
| 61 | that does not use FPU registers or instructions is available |
| 62 | * MIPS2 or later, or kernel emulation of ll/sc (standard in Linux) |
| 63 | is required |
| 64 | |
Rich Felker | 589aefa | 2016-03-06 17:48:58 +0000 | [diff] [blame] | 65 | * MIPS64 |
| 66 | * ABI is n64 (LP64) |
| 67 | * Big-endian default; little-endian variants also supported |
| 68 | * Default ABI variant uses FPU registers; alternate soft-float ABI |
| 69 | that does not use FPU registers or instructions is available |
| 70 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 71 | * PowerPC |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 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 | |
Rich Felker | 5f3b652 | 2017-08-29 20:48:02 -0400 | [diff] [blame] | 77 | * PowerPC64 |
| 78 | * Both little and big endian variants are supported |
| 79 | * Compiler toolchain must provide 64-bit long double, not IBM |
| 80 | double-double or IEEE quad |
| 81 | * Compiler toolchain must use the new (ELFv2) ABI regardless of |
| 82 | whether it is for little or big endian |
| 83 | |
| 84 | * S390X (64-bit S390) |
| 85 | |
Rich Felker | 40891ae | 2016-02-02 17:35:06 -0500 | [diff] [blame] | 86 | * SuperH (SH) |
| 87 | * Standard ELF ABI or FDPIC ABI (shared-text without MMU) |
| 88 | * Little-endian by default; big-engian variant also supported |
| 89 | * Full FPU ABI or soft-float ABI is supported, but the |
| 90 | single-precision-only FPU ABI is not |
| 91 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 92 | * Microblaze |
| 93 | * Big-endian default; little-endian variants also supported |
| 94 | * Soft-float |
| 95 | * Requires support for lwx/swx instructions |
| 96 | |
Rich Felker | 40891ae | 2016-02-02 17:35:06 -0500 | [diff] [blame] | 97 | * OpenRISC 1000 (or1k) |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 98 | |
| 99 | |
| 100 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 101 | Build and Installation Procedure |
| 102 | -------------------------------- |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 103 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 104 | To build and install musl: |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 105 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 106 | 1. Run the provided configure script from the top-level source |
| 107 | directory, passing on its command line any desired options. |
Rich Felker | 3ffb556 | 2012-10-26 20:14:19 -0400 | [diff] [blame] | 108 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 109 | 2. Run "make" to compile. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 110 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 111 | 3. Run "make install" with appropriate privileges to write to the |
| 112 | target locations. |
Rich Felker | f9c9d8c | 2011-06-27 22:34:47 -0400 | [diff] [blame] | 113 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 114 | The configure script attempts to determine automatically the correct |
| 115 | target architecture based on the compiler being used. For some |
| 116 | compilers, this may not be possible. If detection fails or selects the |
| 117 | wrong architecture, you can provide an explicit selection on the |
| 118 | configure command line. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 119 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 120 | By default, configure installs to a prefix of "/usr/local/musl". This |
| 121 | differs from the behavior of most configure scripts, and is chosen |
| 122 | specifically to avoid clashing with libraries already present on the |
| 123 | system. DO NOT set the prefix to "/usr", "/usr/local", or "/" unless |
| 124 | you're upgrading libc on an existing musl-based system. Doing so will |
| 125 | break your existing system when you run "make install" and it may be |
| 126 | difficult to recover. |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 127 | |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 128 | |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 129 | |
| 130 | Notes on Dynamic Linking |
| 131 | ------------------------ |
| 132 | |
| 133 | If dynamic linking is enabled, one file needs to be installed outside |
| 134 | of the installation prefix: /lib/ld-musl-$ARCH.so.1. This is the |
| 135 | dynamic linker. Its pathname is hard-coded into all dynamic-linked |
| 136 | programs, so for the sake of being able to share binaries between |
| 137 | systems, a consistent location should be used everywhere. Note that |
| 138 | the same applies to glibc and its dynamic linker, which is named |
| 139 | /lib/ld-linux.so.2 on i386 systems. |
| 140 | |
| 141 | If for some reason it is impossible to install the dynamic linker in |
| 142 | its standard location (for example, if you are installing without root |
| 143 | privileges), the --syslibdir option to configure can be used to |
| 144 | provide a different location |
| 145 | |
| 146 | At runtime, the dynamic linker needs to know the paths to search for |
| 147 | shared libraries. You should create a text file named |
| 148 | /etc/ld-musl-$ARCH.path (where $ARCH matches the architecture name |
| 149 | used in the dynamic linker) containing a list of directories where you |
| 150 | want the dynamic linker to search for shared libraries, separated by |
| 151 | colons or newlines. If the dynamic linker has been installed in a |
| 152 | non-default location, the path file also needs to reside at that |
| 153 | location (../etc relative to the chosen syslibdir). |
| 154 | |
| 155 | If you do not intend to use dynamic linking, you may disable it by |
| 156 | passing --disable-shared to configure; this also cuts the build time |
| 157 | in half. |
| 158 | |
| 159 | |
| 160 | |
| 161 | Checking for Successful Installation |
| 162 | ------------------------------------ |
| 163 | |
| 164 | After installing, you should be able to use musl via the musl-gcc |
| 165 | wrapper. For example: |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 166 | |
| 167 | cat > hello.c <<EOF |
| 168 | #include <stdio.h> |
| 169 | int main() |
| 170 | { |
| 171 | printf("hello, world!\n"); |
| 172 | return 0; |
| 173 | } |
| 174 | EOF |
Rich Felker | cec05e0 | 2014-03-20 00:55:28 -0400 | [diff] [blame] | 175 | /usr/local/musl/bin/musl-gcc hello.c |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 176 | ./a.out |
| 177 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 178 | To configure autoconf-based program to compile and link against musl, |
Rich Felker | c1a9658 | 2012-09-07 23:13:55 -0400 | [diff] [blame] | 179 | set the CC variable to musl-gcc when running configure, as in: |
Rich Felker | 0b44a03 | 2011-02-12 00:22:29 -0500 | [diff] [blame] | 180 | |
Rich Felker | c1a9658 | 2012-09-07 23:13:55 -0400 | [diff] [blame] | 181 | CC=musl-gcc ./configure ... |
Rich Felker | f9c9d8c | 2011-06-27 22:34:47 -0400 | [diff] [blame] | 182 | |
Rich Felker | 7dd86ec | 2011-09-21 19:39:40 -0400 | [diff] [blame] | 183 | You will probably also want to use --prefix when building libraries to |
| 184 | ensure that they are installed under the musl prefix and not in the |
| 185 | main host system library directories. |