INSTALL

   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) or n32 (ILP32)
  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 * RISC-V 64
 100     * Little endian
 101     * Hard, soft, and hard-single/soft-double floating point ABIs
 102     * Standard ELF; no shared-text NOMMU support
 103
 104
 105
 106 Build and Installation Procedure
 107 --------------------------------
 108
 109 To build and install musl:
 110
 111 1. Run the provided configure script from the top-level source
 112    directory, passing on its command line any desired options.
 113
 114 2. Run "make" to compile.
 115
 116 3. Run "make install" with appropriate privileges to write to the
 117    target locations.
 118
 119 The configure script attempts to determine automatically the correct
 120 target architecture based on the compiler being used. For some
 121 compilers, this may not be possible. If detection fails or selects the
 122 wrong architecture, you can provide an explicit selection on the
 123 configure command line.
 124
 125 By default, configure installs to a prefix of "/usr/local/musl". This
 126 differs from the behavior of most configure scripts, and is chosen
 127 specifically to avoid clashing with libraries already present on the
 128 system. DO NOT set the prefix to "/usr", "/usr/local", or "/" unless
 129 you're upgrading libc on an existing musl-based system. Doing so will
 130 break your existing system when you run "make install" and it may be
 131 difficult to recover.
 132
 133
 134
 135 Notes on Dynamic Linking
 136 ------------------------
 137
 138 If dynamic linking is enabled, one file needs to be installed outside
 139 of the installation prefix: /lib/ld-musl-$ARCH.so.1. This is the
 140 dynamic linker. Its pathname is hard-coded into all dynamic-linked
 141 programs, so for the sake of being able to share binaries between
 142 systems, a consistent location should be used everywhere. Note that
 143 the same applies to glibc and its dynamic linker, which is named
 144 /lib/ld-linux.so.2 on i386 systems.
 145
 146 If for some reason it is impossible to install the dynamic linker in
 147 its standard location (for example, if you are installing without root
 148 privileges), the --syslibdir option to configure can be used to
 149 provide a different location
 150
 151 At runtime, the dynamic linker needs to know the paths to search for
 152 shared libraries. You should create a text file named
 153 /etc/ld-musl-$ARCH.path (where $ARCH matches the architecture name
 154 used in the dynamic linker) containing a list of directories where you
 155 want the dynamic linker to search for shared libraries, separated by
 156 colons or newlines. If the dynamic linker has been installed in a
 157 non-default location, the path file also needs to reside at that
 158 location (../etc relative to the chosen syslibdir).
 159
 160 If you do not intend to use dynamic linking, you may disable it by
 161 passing --disable-shared to configure; this also cuts the build time
 162 in half.
 163
 164
 165
 166 Checking for Successful Installation
 167 ------------------------------------
 168
 169 After installing, you should be able to use musl via the musl-gcc
 170 wrapper. For example:
 171
 172 cat > hello.c <<EOF
 173 #include <stdio.h>
 174 int main()
 175 {
 176         printf("hello, world!\n");
 177         return 0;
 178 }
 179 EOF
 180 /usr/local/musl/bin/musl-gcc hello.c
 181 ./a.out
 182
 183 To configure autoconf-based program to compile and link against musl,
 184 set the CC variable to musl-gcc when running configure, as in:
 185
 186 CC=musl-gcc ./configure ...
 187
 188 You will probably also want to use --prefix when building libraries to
 189 ensure that they are installed under the musl prefix and not in the
 190 main host system library directories.