OLD | NEW |
(Empty) | |
| 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. |
OLD | NEW |