1 2 Quick Installation Guide for musl libc
3 ======================================
4 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.
10 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.
14 15 16 Build Prerequisites
17 -------------------
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 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.
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 33 34 35 Supported Targets
36 -----------------
37 38 musl can be built for the following CPU instruction set architecture
39 and ABI combinations:
40 41 * i386
42 * Minimum CPU model is actually 80486 unless kernel emulation of
43 the `cmpxchg` instruction is added
44 45 * x86_64
46 * ILP32 ABI (x32) is available as a separate arch but is still
47 experimental
48 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 54 * AArch64
55 * Little-endian default; big-endian variants also supported
56 57 * MIPS
58 * ABI is o32, fp32/fpxx (except on r6 which is fp64)
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 * MIPS32r6, an incompatible ISA, is supported as a variant "mipsr6"
65 66 * MIPS64
67 * ABI is n64 (LP64) or n32 (ILP32)
68 * Big-endian default; little-endian variants also supported
69 * Default ABI variant uses FPU registers; alternate soft-float ABI
70 that does not use FPU registers or instructions is available
71 72 * PowerPC
73 * Compiler toolchain must provide 64-bit long double, not IBM
74 double-double or IEEE quad
75 * For dynamic linking, compiler toolchain must be configured for
76 "secure PLT" variant
77 78 * PowerPC64
79 * Both little and big endian variants are supported
80 * Compiler toolchain must provide 64-bit long double, not IBM
81 double-double or IEEE quad
82 * Compiler toolchain must use the new (ELFv2) ABI regardless of
83 whether it is for little or big endian
84 85 * S390X (64-bit S390)
86 87 * SuperH (SH)
88 * Standard ELF ABI or FDPIC ABI (shared-text without MMU)
89 * Little-endian by default; big-endian variant also supported
90 * Full FPU ABI or soft-float ABI is supported, but the
91 single-precision-only FPU ABI is not
92 93 * Microblaze
94 * Big-endian default; little-endian variants also supported
95 * Soft-float
96 * Requires support for lwx/swx instructions
97 98 * OpenRISC 1000 (or1k)
99 100 * RISC-V 64
101 * Little endian
102 * Hard, soft, and hard-single/soft-double floating point ABIs
103 * Standard ELF; no shared-text NOMMU support
104 105 106 107 Build and Installation Procedure
108 --------------------------------
109 110 To build and install musl:
111 112 1. Run the provided configure script from the top-level source
113 directory, passing on its command line any desired options.
114 115 2. Run "make" to compile.
116 117 3. Run "make install" with appropriate privileges to write to the
118 target locations.
119 120 The configure script attempts to determine automatically the correct
121 target architecture based on the compiler being used. For some
122 compilers, this may not be possible. If detection fails or selects the
123 wrong architecture, you can provide an explicit selection on the
124 configure command line.
125 126 By default, configure installs to a prefix of "/usr/local/musl". This
127 differs from the behavior of most configure scripts, and is chosen
128 specifically to avoid clashing with libraries already present on the
129 system. DO NOT set the prefix to "/usr", "/usr/local", or "/" unless
130 you're upgrading libc on an existing musl-based system. Doing so will
131 break your existing system when you run "make install" and it may be
132 difficult to recover.
133 134 135 136 Notes on Dynamic Linking
137 ------------------------
138 139 If dynamic linking is enabled, one file needs to be installed outside
140 of the installation prefix: /lib/ld-musl-$ARCH.so.1. This is the
141 dynamic linker. Its pathname is hard-coded into all dynamic-linked
142 programs, so for the sake of being able to share binaries between
143 systems, a consistent location should be used everywhere. Note that
144 the same applies to glibc and its dynamic linker, which is named
145 /lib/ld-linux.so.2 on i386 systems.
146 147 If for some reason it is impossible to install the dynamic linker in
148 its standard location (for example, if you are installing without root
149 privileges), the --syslibdir option to configure can be used to
150 provide a different location
151 152 At runtime, the dynamic linker needs to know the paths to search for
153 shared libraries. You should create a text file named
154 /etc/ld-musl-$ARCH.path (where $ARCH matches the architecture name
155 used in the dynamic linker) containing a list of directories where you
156 want the dynamic linker to search for shared libraries, separated by
157 colons or newlines. If the dynamic linker has been installed in a
158 non-default location, the path file also needs to reside at that
159 location (../etc relative to the chosen syslibdir).
160 161 If you do not intend to use dynamic linking, you may disable it by
162 passing --disable-shared to configure; this also cuts the build time
163 in half.
164 165 166 167 Checking for Successful Installation
168 ------------------------------------
169 170 After installing, you should be able to use musl via the musl-gcc
171 wrapper. For example:
172 173 cat > hello.c <<EOF
174 #include <stdio.h>
175 int main()
176 {
177 printf("hello, world!\n");
178 return 0;
179 }
180 EOF
181 /usr/local/musl/bin/musl-gcc hello.c
182 ./a.out
183 184 To configure autoconf-based program to compile and link against musl,
185 set the CC variable to musl-gcc when running configure, as in:
186 187 CC=musl-gcc ./configure ...
188 189 You will probably also want to use --prefix when building libraries to
190 ensure that they are installed under the musl prefix and not in the
191 main host system library directories.
192