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
|
---|
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 |
|
---|
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 |
|
---|
71 | * PowerPC
|
---|
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 | * 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 |
|
---|
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 |
|
---|
92 | * Microblaze
|
---|
93 | * Big-endian default; little-endian variants also supported
|
---|
94 | * Soft-float
|
---|
95 | * Requires support for lwx/swx instructions
|
---|
96 |
|
---|
97 | * OpenRISC 1000 (or1k)
|
---|
98 |
|
---|
99 |
|
---|
100 |
|
---|
101 | Build and Installation Procedure
|
---|
102 | --------------------------------
|
---|
103 |
|
---|
104 | To build and install musl:
|
---|
105 |
|
---|
106 | 1. Run the provided configure script from the top-level source
|
---|
107 | directory, passing on its command line any desired options.
|
---|
108 |
|
---|
109 | 2. Run "make" to compile.
|
---|
110 |
|
---|
111 | 3. Run "make install" with appropriate privileges to write to the
|
---|
112 | target locations.
|
---|
113 |
|
---|
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.
|
---|
119 |
|
---|
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.
|
---|
127 |
|
---|
128 |
|
---|
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:
|
---|
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
|
---|
175 | /usr/local/musl/bin/musl-gcc hello.c
|
---|
176 | ./a.out
|
---|
177 |
|
---|
178 | To configure autoconf-based program to compile and link against musl,
|
---|
179 | set the CC variable to musl-gcc when running configure, as in:
|
---|
180 |
|
---|
181 | CC=musl-gcc ./configure ...
|
---|
182 |
|
---|
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.
|
---|