1 2Quick Installation Guide for musl libc 3====================================== 4 5There are many different ways to install musl depending on your usage 6case. This document covers only the build and installation of musl by 7itself, which is useful for upgrading an existing musl-based system or 8compiler toolchain, or for using the provided musl-gcc wrapper with an 9existing non-musl-based compiler. 10 11Building complete native or cross-compiler toolchains is outside the 12scope of this INSTALL file. More information can be found on the musl 13website and community wiki. 14 15 16Build Prerequisites 17------------------- 18 19The only build-time prerequisites for musl are GNU Make and a 20freestanding C99 compiler toolchain targeting the desired instruction 21set architecture and ABI, with support for a minimal subset of "GNU C" 22extensions consisting mainly of gcc-style inline assembly, weak 23aliases, hidden visibility, and stand-alone assembly source files. 24 25GCC, LLVM/clang, Firm/cparser, and PCC have all successfully built 26musl, but GCC is the most widely used/tested. Recent compiler (and 27binutils) versions should be used if possible since some older 28versions have bugs which affect musl. 29 30The system used to build musl does not need to be Linux-based, nor do 31the Linux kernel headers need to be available. 32 33 34 35Supported Targets 36----------------- 37 38musl can be built for the following CPU instruction set architecture 39and 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 101 * 32-bit and 64-bit 102 * Little endian 103 * Hard, soft, and hard-single/soft-double floating point ABIs 104 * Standard ELF; no shared-text NOMMU support 105 106* LoongArch 107 * 64-bit ISA 108 * Hard, soft, and hard-single/soft-double floating point ABIs 109 110 111 112Build and Installation Procedure 113-------------------------------- 114 115To build and install musl: 116 1171. Run the provided configure script from the top-level source 118 directory, passing on its command line any desired options. 119 1202. Run "make" to compile. 121 1223. Run "make install" with appropriate privileges to write to the 123 target locations. 124 125The configure script attempts to determine automatically the correct 126target architecture based on the compiler being used. For some 127compilers, this may not be possible. If detection fails or selects the 128wrong architecture, you can provide an explicit selection on the 129configure command line. 130 131By default, configure installs to a prefix of "/usr/local/musl". This 132differs from the behavior of most configure scripts, and is chosen 133specifically to avoid clashing with libraries already present on the 134system. DO NOT set the prefix to "/usr", "/usr/local", or "/" unless 135you're upgrading libc on an existing musl-based system. Doing so will 136break your existing system when you run "make install" and it may be 137difficult to recover. 138 139 140 141Notes on Dynamic Linking 142------------------------ 143 144If dynamic linking is enabled, one file needs to be installed outside 145of the installation prefix: /lib/ld-musl-$ARCH.so.1. This is the 146dynamic linker. Its pathname is hard-coded into all dynamic-linked 147programs, so for the sake of being able to share binaries between 148systems, a consistent location should be used everywhere. Note that 149the same applies to glibc and its dynamic linker, which is named 150/lib/ld-linux.so.2 on i386 systems. 151 152If for some reason it is impossible to install the dynamic linker in 153its standard location (for example, if you are installing without root 154privileges), the --syslibdir option to configure can be used to 155provide a different location 156 157At runtime, the dynamic linker needs to know the paths to search for 158shared libraries. You should create a text file named 159/etc/ld-musl-$ARCH.path (where $ARCH matches the architecture name 160used in the dynamic linker) containing a list of directories where you 161want the dynamic linker to search for shared libraries, separated by 162colons or newlines. If the dynamic linker has been installed in a 163non-default location, the path file also needs to reside at that 164location (../etc relative to the chosen syslibdir). 165 166If you do not intend to use dynamic linking, you may disable it by 167passing --disable-shared to configure; this also cuts the build time 168in half. 169 170 171 172Checking for Successful Installation 173------------------------------------ 174 175After installing, you should be able to use musl via the musl-gcc 176wrapper. For example: 177 178cat > hello.c <<EOF 179#include <stdio.h> 180int main() 181{ 182 printf("hello, world!\n"); 183 return 0; 184} 185EOF 186/usr/local/musl/bin/musl-gcc hello.c 187./a.out 188 189To configure autoconf-based program to compile and link against musl, 190set the CC variable to musl-gcc when running configure, as in: 191 192CC=musl-gcc ./configure ... 193 194You will probably also want to use --prefix when building libraries to 195ensure that they are installed under the musl prefix and not in the 196main host system library directories. 197