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 gcc-style inline assembly,
  22 weak aliases, and stand-alone assembly source files.
  23
  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.
  26
  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.
  30
  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 and 4.9.1 are known to have a serious bug
  39 (#61144) which affects musl. Beginning with version 1.1.4 musl
  40 attempts to work around the bug, but these compiler versions are still
  41 considered unstable and unsupported.
  42
  43
  44
  45 Supported Targets
  46 -----------------
  47
  48 musl can be built for the following CPU instruction set architecture
  49 and ABI combinations:
  50
  51 * i386
  52     * Minimum CPU model is actually 80486 unless kernel emulation of
  53       the `cmpxchg` instruction is added
  54
  55 * x86_64
  56
  57 * ARM
  58     * EABI, standard or hard-float VFP variant
  59     * Little-endian default; big-endian variants also supported
  60     * Compiler toolchains only support armv4t and later
  61
  62 * MIPS
  63     * ABI is o32
  64     * Big-endian default; little-endian variants also supported
  65     * Default ABI variant uses FPU registers; alternate soft-float ABI
  66       that does not use FPU registers or instructions is available
  67     * MIPS2 or later, or kernel emulation of ll/sc (standard in Linux)
  68       is required
  69
  70 * PowerPC
  71     * Only 32-bit is supported
  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 * Microblaze
  78     * Big-endian default; little-endian variants also supported
  79     * Soft-float
  80     * Requires support for lwx/swx instructions
  81
  82 The following additional targets are available for build, but may not
  83 work correctly and may not yet have ABI stability:
  84
  85 * SuperH (SH)
  86     * Little-endian by default; big-engian variant also supported
  87     * Full FPU ABI or soft-float ABI is supported, but the
  88       single-precision-only FPU ABI is not supported (musl always
  89       requires IEEE single and double to be supported)
  90
  91 * x32 (x86_64 ILP32 ABI)
  92
  93
  94
  95 Build and Installation Procedure
  96 --------------------------------
  97
  98 To build and install musl:
  99
 100 1. Run the provided configure script from the top-level source
 101    directory, passing on its command line any desired options.
 102
 103 2. Run "make" to compile.
 104
 105 3. Run "make install" with appropriate privileges to write to the
 106    target locations.
 107
 108 The configure script attempts to determine automatically the correct
 109 target architecture based on the compiler being used. For some
 110 compilers, this may not be possible. If detection fails or selects the
 111 wrong architecture, you can provide an explicit selection on the
 112 configure command line.
 113
 114 By default, configure installs to a prefix of "/usr/local/musl". This
 115 differs from the behavior of most configure scripts, and is chosen
 116 specifically to avoid clashing with libraries already present on the
 117 system. DO NOT set the prefix to "/usr", "/usr/local", or "/" unless
 118 you're upgrading libc on an existing musl-based system. Doing so will
 119 break your existing system when you run "make install" and it may be
 120 difficult to recover.
 121
 122
 123
 124 Notes on Dynamic Linking
 125 ------------------------
 126
 127 If dynamic linking is enabled, one file needs to be installed outside
 128 of the installation prefix: /lib/ld-musl-$ARCH.so.1. This is the
 129 dynamic linker. Its pathname is hard-coded into all dynamic-linked
 130 programs, so for the sake of being able to share binaries between
 131 systems, a consistent location should be used everywhere. Note that
 132 the same applies to glibc and its dynamic linker, which is named
 133 /lib/ld-linux.so.2 on i386 systems.
 134
 135 If for some reason it is impossible to install the dynamic linker in
 136 its standard location (for example, if you are installing without root
 137 privileges), the --syslibdir option to configure can be used to
 138 provide a different location
 139
 140 At runtime, the dynamic linker needs to know the paths to search for
 141 shared libraries. You should create a text file named
 142 /etc/ld-musl-$ARCH.path (where $ARCH matches the architecture name
 143 used in the dynamic linker) containing a list of directories where you
 144 want the dynamic linker to search for shared libraries, separated by
 145 colons or newlines. If the dynamic linker has been installed in a
 146 non-default location, the path file also needs to reside at that
 147 location (../etc relative to the chosen syslibdir).
 148
 149 If you do not intend to use dynamic linking, you may disable it by
 150 passing --disable-shared to configure; this also cuts the build time
 151 in half.
 152
 153
 154
 155 Checking for Successful Installation
 156 ------------------------------------
 157
 158 After installing, you should be able to use musl via the musl-gcc
 159 wrapper. For example:
 160
 161 cat > hello.c <<EOF
 162 #include <stdio.h>
 163 int main()
 164 {
 165         printf("hello, world!\n");
 166         return 0;
 167 }
 168 EOF
 169 /usr/local/musl/bin/musl-gcc hello.c
 170 ./a.out
 171
 172 To configure autoconf-based program to compile and link against musl,
 173 set the CC variable to musl-gcc when running configure, as in:
 174
 175 CC=musl-gcc ./configure ...
 176
 177 You will probably also want to use --prefix when building libraries to
 178 ensure that they are installed under the musl prefix and not in the
 179 main host system library directories.