X-Git-Url: http://nsz.repo.hu/git/?p=musl;a=blobdiff_plain;f=INSTALL;h=35f02a32b8d2397afb549c3903a1d49b89492495;hp=5b58693eb749ca598875ed61b964ada9174a493c;hb=3df0b66ee95c837496ae434ba7a2282d97ca71ef;hpb=7dd86ec16852cf189e88fb2829caee4e114087e7 diff --git a/INSTALL b/INSTALL index 5b58693e..35f02a32 100644 --- a/INSTALL +++ b/INSTALL @@ -5,40 +5,81 @@ musl may be installed either as an alternate C library alongside the existing libraries on a system, or as the primary C library for a new or existing musl-based system. -First, some prerequisites: +This document covers the prerequisites and procedures for compiling +and installation. -- A C99 compiler with gcc-style inline assembly support, support for - weak aliases, and support for building stand-alone assembly files. - gcc 3.x and 4.x are known to work. pcc and LLVM/clang may work but - are untested, and pcc is known to have some bugs. -- GNU make -- Linux, preferably 2.6.22 or later. Older versions are known to have - serious bugs that will make some interfaces non-conformant, but if - you don't need threads or POSIX 2008 features, even 2.4 is probably - okay. +==== Build Prerequisites ==== -- A supported CPU architecture (currently i386, x86_64, or arm). +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 gcc-style inline assembly, +weak aliases, and stand-alone assembly source files. -- If you want to use dynamic linking, it's recommended that you have - permissions to write to /lib and /etc. Otherwise your binaries will - have to use a nonstandard dynamic linker path. +The system used to build musl does not need to be Linux-based, nor do +the Linux kernel headers need to be available. +If support for dynamic linking is desired, some further requriements +are placed on the compiler and linker. In particular, the linker must +support the -Bsymbolic-functions option. +At present, GCC 4.6 or later is the recommended compiler for building +musl. Any earlier version of GCC with full C99 support should also +work, but may be subject to minor floating point conformance issues on +i386 targets. Sufficiently recent versions of PCC and LLVM/clang are +also believed to work, but have not been tested as heavily; prior to +Fall 2012, both had known bugs that affected musl. -== Option 1: Installing musl as an alternate C library == + + +=== Supported Targets ==== + +musl can be built for the following CPU instruction set architecture +and ABI combinations: + +- i386 (requires 387 math and 486 cmpxchg instructions) +- x86_64 +- arm (EABI) +- mips (o32 ABI, requires fpu or float emulation in kernel) +- microblaze (requires a cpu with lwx/swx instructions) +- powerpc (32-bit, must use "secure plt" mode for dynamic linking) + +For architectures with both little- and big-endian options, both are +supported unless otherwise noted. + +In general, musl assumes the availability of all Linux syscall +interfaces available in Linux 2.6.0. Some programs that do not use +threads or other modern functionality may be able to run on 2.4.x +kernels. Other kernels (such as BSD) that provide a Linux-compatible +syscall ABI should also work but have not been extensively tested. + + + +==== Option 1: Installing musl as an alternate C library ==== In this setup, musl and any third-party libraries linked to musl will reside under an alternate prefix such as /usr/local/musl or /opt/musl. A wrapper script for gcc, called musl-gcc, can be used in place of gcc to compile and link programs and libraries against musl. +(Note: There are not yet corresponding wrapper scripts for other +compilers, so if you wish to compile and link against musl using +another compiler, you are responsible for providing the correct +options to override the default include and library search paths.) + To install musl as an alternate libc, follow these steps: -1. Edit config.mak to select your system's CPU architecture (i386, - x86_64, or arm), installation prefix, location for the dynamic - linker, and other build preferences. +1. Configure musl's build with a command similar to: + ./configure --prefix=/usr/local/musl --exec-prefix=/usr/local + Refer to ./configure --help for details on other options. You may + change the install prefix if you like, but DO NOT set it to a + location that contains your existing libraries based on another + libc such as glibc or uClibc. If you do not intend to use dynamic + linking, you may disable it at this point via --disable-shared and + cut the build time in half. If you wish to use dynamic linking but + do not have permissions to write to /lib, you will need to set an + alternate dynamic linker location via --syslibdir. 2. Run "make". Parallel build is fully supported, so you can instead use "make -j3" or so on SMP systems if you like. @@ -46,10 +87,13 @@ To install musl as an alternate libc, follow these steps: 3. Run "make install" as a user sufficient privileges to write to the destination. -4. Ensure that /etc/ld-musl-$ARCH.path (where $ARCH is replaced by - i386, x86_64, etc. as appropriate) contains the correct search path - for where you intend to install musl-linked shared library files. - This step can be skipped if you disabled dynamic linking. +4. Create a file named /etc/ld-musl-$ARCH.path (where $ARCH is + replaced by i386, x86_64, etc. as appropriate) containing the + correct colon-delimited search path for where you intend to install + musl-linked shared library files. If this file is missing, musl + will search the standard path, and you will encounter problems when + it attempts to load libraries linked against your host libc. Note + that this step can be skipped if you disabled dynamic linking. After installing, you can use musl via the musl-gcc wrapper. For example: @@ -66,14 +110,9 @@ musl-gcc hello.c ./a.out To configure autoconf-based program to compile and link against musl, -you may wish to use: - -CC="musl-gcc -D_GNU_SOURCE" ./configure ... +set the CC variable to musl-gcc when running configure, as in: -Correctly-written build systems should not need -D_GNU_SOURCE as part -of $CC, but many programs do not use feature-test macros correctly and -simply assume the compiler will automatically give them the kitchen -sink, so the above command is an easy workaround. +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 @@ -81,12 +120,13 @@ main host system library directories. Finally, it's worth noting that musl's include and lib directories in the build tree are setup to be usable without installation, if -necessary. Just modify the musl-gcc wrapper's libc_prefix variable to -point to the source/build tree. +necessary. Just modify the the paths in the spec file used by musl-gcc +(it's located at $prefix/lib/musl-gcc.specs) to point to the +source/build tree. -== Option 2: Installing musl as the primary C library == +==== Option 2: Installing musl as the primary C library ==== In this setup, you will need an existing compiler/toolchain. It shouldnt matter whether it was configured for glibc, uClibc, musl, or @@ -107,10 +147,9 @@ TO CONVERT IT TO BE A MUSL-BASED SYSTEM!! the search path before you move them, or your system will break badly and you will not be able to continue. -2. Edit musl's config.mak and set the installation prefix to the - prefix your compiler toolchain is configured to search, probably - /usr. Set ARCH to match your CPU architecture, and change any other - options as you see fit. +2. Configure musl's build with a command similar to: + ./configure --prefix=/usr --disable-gcc-wrapper + Refer to ./configure --help for details on other options. 3. Run "make" to compile musl. @@ -130,9 +169,3 @@ dynamic linker (program interpreter) is /lib/ld-musl-$ARCH.so.1. If you're using static linking only, you might instead check the symbols and look for anything suspicious that would indicate your old glibc or uClibc was used. - -When building programs against musl, you may still want to ensure the -appropriate feature test macros get defined, as in: - -CC="gcc -D_GNU_SOURCE" ./configure ... -