[352] | 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.
|
---|