2 Quick Installation Guide for musl libc
3 ======================================
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.
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.
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.
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.
27 If support for dynamic linking is desired, some further requirements
28 are placed on the compiler and linker. In particular, the linker must
29 support the -Bsymbolic-functions option.
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
36 Fall 2012, both had known bugs that affected musl. Firm/cparser is
37 also believed to work but lacks support for producing shared
38 libraries. GCC 4.9.0 is known to have a serious bug (#61144) which
39 affects musl and is not supported.
46 musl can be built for the following CPU instruction set architecture
50 * Minimum CPU model is actually 80486 unless kernel emulation of
51 the `cmpxchg` instruction is added
56 * EABI, standard or hard-float VFP variant
57 * Little-endian default; big-endian variants also supported
58 * Compiler toolchains only support armv4t and later
62 * Big-endian default; little-endian variants also supported
63 * Default ABI variant uses FPU registers; alternate soft-float ABI
64 that does not use FPU registers or instructions is available
65 * MIPS2 or later, or kernel emulation of ll/sc (standard in Linux)
69 * Only 32-bit is supported
70 * Compiler toolchain must provide 64-bit long double, not IBM
71 double-double or IEEE quad
72 * For dynamic linking, compiler toolchain must be configured for
76 * Big-endian default; little-endian variants also supported
78 * Requires support for lwx/swx instructions
80 The following additional targets are available for build, but may not
81 work correctly and may not yet have ABI stability:
84 * Little-endian by default; big-engian variant also supported
85 * Full FPU ABI or soft-float ABI is supported, but the
86 single-precision-only FPU ABI is not supported (musl always
87 requires IEEE single and double to be supported)
89 * x32 (x86_64 ILP32 ABI)
93 Build and Installation Procedure
94 --------------------------------
96 To build and install musl:
98 1. Run the provided configure script from the top-level source
99 directory, passing on its command line any desired options.
101 2. Run "make" to compile.
103 3. Run "make install" with appropriate privileges to write to the
106 The configure script attempts to determine automatically the correct
107 target architecture based on the compiler being used. For some
108 compilers, this may not be possible. If detection fails or selects the
109 wrong architecture, you can provide an explicit selection on the
110 configure command line.
112 By default, configure installs to a prefix of "/usr/local/musl". This
113 differs from the behavior of most configure scripts, and is chosen
114 specifically to avoid clashing with libraries already present on the
115 system. DO NOT set the prefix to "/usr", "/usr/local", or "/" unless
116 you're upgrading libc on an existing musl-based system. Doing so will
117 break your existing system when you run "make install" and it may be
118 difficult to recover.
122 Notes on Dynamic Linking
123 ------------------------
125 If dynamic linking is enabled, one file needs to be installed outside
126 of the installation prefix: /lib/ld-musl-$ARCH.so.1. This is the
127 dynamic linker. Its pathname is hard-coded into all dynamic-linked
128 programs, so for the sake of being able to share binaries between
129 systems, a consistent location should be used everywhere. Note that
130 the same applies to glibc and its dynamic linker, which is named
131 /lib/ld-linux.so.2 on i386 systems.
133 If for some reason it is impossible to install the dynamic linker in
134 its standard location (for example, if you are installing without root
135 privileges), the --syslibdir option to configure can be used to
136 provide a different location
138 At runtime, the dynamic linker needs to know the paths to search for
139 shared libraries. You should create a text file named
140 /etc/ld-musl-$ARCH.path (where $ARCH matches the architecture name
141 used in the dynamic linker) containing a list of directories where you
142 want the dynamic linker to search for shared libraries, separated by
143 colons or newlines. If the dynamic linker has been installed in a
144 non-default location, the path file also needs to reside at that
145 location (../etc relative to the chosen syslibdir).
147 If you do not intend to use dynamic linking, you may disable it by
148 passing --disable-shared to configure; this also cuts the build time
153 Checking for Successful Installation
154 ------------------------------------
156 After installing, you should be able to use musl via the musl-gcc
157 wrapper. For example:
163 printf("hello, world!\n");
167 /usr/local/musl/bin/musl-gcc hello.c
170 To configure autoconf-based program to compile and link against musl,
171 set the CC variable to musl-gcc when running configure, as in:
173 CC=musl-gcc ./configure ...
175 You will probably also want to use --prefix when building libraries to
176 ensure that they are installed under the musl prefix and not in the
177 main host system library directories.