| |
| Quick Installation Guide for musl libc |
| ====================================== |
| |
| There are many different ways to install musl depending on your usage |
| case. This document covers only the build and installation of musl by |
| itself, which is useful for upgrading an existing musl-based system or |
| compiler toolchain, or for using the provided musl-gcc wrapper with an |
| existing non-musl-based compiler. |
| |
| Building complete native or cross-compiler toolchains is outside the |
| scope of this INSTALL file. More information can be found on the musl |
| website and community wiki. |
| |
| |
| Build Prerequisites |
| ------------------- |
| |
| The only build-time prerequisites for musl are GNU Make and a |
| freestanding C99 compiler toolchain targeting the desired instruction |
| set architecture and ABI, with support for a minimal subset of "GNU C" |
| extensions consisting mainly of gcc-style inline assembly, weak |
| aliases, hidden visibility, and stand-alone assembly source files. |
| |
| GCC, LLVM/clang, Firm/cparser, and PCC have all successfully built |
| musl, but GCC is the most widely used/tested. Recent compiler (and |
| binutils) versions should be used if possible since some older |
| versions have bugs which affect musl. |
| |
| The system used to build musl does not need to be Linux-based, nor do |
| the Linux kernel headers need to be available. |
| |
| |
| |
| Supported Targets |
| ----------------- |
| |
| musl can be built for the following CPU instruction set architecture |
| and ABI combinations: |
| |
| * i386 |
| * Minimum CPU model is actually 80486 unless kernel emulation of |
| the `cmpxchg` instruction is added |
| |
| * x86_64 |
| * ILP32 ABI (x32) is available as a separate arch but is still |
| experimental |
| |
| * ARM |
| * EABI, standard or hard-float VFP variant |
| * Little-endian default; big-endian variants also supported |
| * Compiler toolchains only support armv4t and later |
| |
| * AArch64 |
| * Little-endian default; big-endian variants also supported |
| |
| * MIPS |
| * ABI is o32 |
| * Big-endian default; little-endian variants also supported |
| * Default ABI variant uses FPU registers; alternate soft-float ABI |
| that does not use FPU registers or instructions is available |
| * MIPS2 or later, or kernel emulation of ll/sc (standard in Linux) |
| is required |
| |
| * MIPS64 |
| * ABI is n64 (LP64) |
| * Big-endian default; little-endian variants also supported |
| * Default ABI variant uses FPU registers; alternate soft-float ABI |
| that does not use FPU registers or instructions is available |
| |
| * PowerPC |
| * Only 32-bit is supported |
| * Compiler toolchain must provide 64-bit long double, not IBM |
| double-double or IEEE quad |
| * For dynamic linking, compiler toolchain must be configured for |
| "secure PLT" variant |
| |
| * SuperH (SH) |
| * Standard ELF ABI or FDPIC ABI (shared-text without MMU) |
| * Little-endian by default; big-engian variant also supported |
| * Full FPU ABI or soft-float ABI is supported, but the |
| single-precision-only FPU ABI is not |
| |
| * Microblaze |
| * Big-endian default; little-endian variants also supported |
| * Soft-float |
| * Requires support for lwx/swx instructions |
| |
| * OpenRISC 1000 (or1k) |
| |
| |
| |
| Build and Installation Procedure |
| -------------------------------- |
| |
| To build and install musl: |
| |
| 1. Run the provided configure script from the top-level source |
| directory, passing on its command line any desired options. |
| |
| 2. Run "make" to compile. |
| |
| 3. Run "make install" with appropriate privileges to write to the |
| target locations. |
| |
| The configure script attempts to determine automatically the correct |
| target architecture based on the compiler being used. For some |
| compilers, this may not be possible. If detection fails or selects the |
| wrong architecture, you can provide an explicit selection on the |
| configure command line. |
| |
| By default, configure installs to a prefix of "/usr/local/musl". This |
| differs from the behavior of most configure scripts, and is chosen |
| specifically to avoid clashing with libraries already present on the |
| system. DO NOT set the prefix to "/usr", "/usr/local", or "/" unless |
| you're upgrading libc on an existing musl-based system. Doing so will |
| break your existing system when you run "make install" and it may be |
| difficult to recover. |
| |
| |
| |
| Notes on Dynamic Linking |
| ------------------------ |
| |
| If dynamic linking is enabled, one file needs to be installed outside |
| of the installation prefix: /lib/ld-musl-$ARCH.so.1. This is the |
| dynamic linker. Its pathname is hard-coded into all dynamic-linked |
| programs, so for the sake of being able to share binaries between |
| systems, a consistent location should be used everywhere. Note that |
| the same applies to glibc and its dynamic linker, which is named |
| /lib/ld-linux.so.2 on i386 systems. |
| |
| If for some reason it is impossible to install the dynamic linker in |
| its standard location (for example, if you are installing without root |
| privileges), the --syslibdir option to configure can be used to |
| provide a different location |
| |
| At runtime, the dynamic linker needs to know the paths to search for |
| shared libraries. You should create a text file named |
| /etc/ld-musl-$ARCH.path (where $ARCH matches the architecture name |
| used in the dynamic linker) containing a list of directories where you |
| want the dynamic linker to search for shared libraries, separated by |
| colons or newlines. If the dynamic linker has been installed in a |
| non-default location, the path file also needs to reside at that |
| location (../etc relative to the chosen syslibdir). |
| |
| If you do not intend to use dynamic linking, you may disable it by |
| passing --disable-shared to configure; this also cuts the build time |
| in half. |
| |
| |
| |
| Checking for Successful Installation |
| ------------------------------------ |
| |
| After installing, you should be able to use musl via the musl-gcc |
| wrapper. For example: |
| |
| cat > hello.c <<EOF |
| #include <stdio.h> |
| int main() |
| { |
| printf("hello, world!\n"); |
| return 0; |
| } |
| EOF |
| /usr/local/musl/bin/musl-gcc hello.c |
| ./a.out |
| |
| To configure autoconf-based program to compile and link against musl, |
| set the CC variable to musl-gcc when running configure, as in: |
| |
| CC=musl-gcc ./configure ... |
| |
| You will probably also want to use --prefix when building libraries to |
| ensure that they are installed under the musl prefix and not in the |
| main host system library directories. |