From 3ffb556c58ba69b4f52ae50fa92424300bd58bd1 Mon Sep 17 00:00:00 2001 From: Rich Felker Date: Fri, 26 Oct 2012 20:14:19 -0400 Subject: update documentation --- INSTALL | 65 +++++++++++++++++++++++++++++++++++++++++++++++++---------------- README | 35 ++++++++++++++++++----------------- 2 files changed, 67 insertions(+), 33 deletions(-) diff --git a/INSTALL b/INSTALL index 5c923ee5..017900df 100644 --- a/INSTALL +++ b/INSTALL @@ -5,35 +5,68 @@ 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, arm, or mips). +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) + +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. Configure musl's build with a command similar to: @@ -92,7 +125,7 @@ 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 diff --git a/README b/README index 9df22055..65a7d3e7 100644 --- a/README +++ b/README @@ -8,7 +8,7 @@ musl is an alternative to glibc, eglibc, uClibc, dietlibc, and klibc. For reasons why one might prefer musl, please see the FAQ and libc comparison chart on the project website, - http://www.etalabs.net/musl/ + http://www.musl-libc.org/ For installation instructions, see the INSTALL file. @@ -19,22 +19,23 @@ license status of code included in musl (standard MIT license). Greetings! -With the 0.9.0 release, musl has reached a milestone in completeness -and compatibility. All interfaces in ISO C99 and POSIX 2008 base exist -in musl, along with a number of non-standardized interfaces based on -GNU and BSD libraries and syscall interfaces for Linux-kernel-specific -functions. Some interfaces lack obscure or rarely-used functionality -needed for strict conformance, but the vast majority of interfaces go -above and beyond the requirements for conformance, often promising -success where other implementations can fail under resource exhaustion -or other corner-case conditions. - -At this point, hundreds of packages have been successfully built -against musl - either out-of-the-box or with minor patches to address -portability errors - ranging from low-level system utilities and -network daemons to major gui applications. Testing has been conducted -using three separate test frameworks and numerous additional -standalone test cases to verify the correctness of the implementation. +The 0.9.x release series for musl features interface coverage for all +interfaces defined in ISO C99 and POSIX 2008 base, along with a number +of non-standardized interfaces for compatibility with Linux, BSD, and +glibc functionality. As the release series progresses, we are +gradually adding support for incomplete functionality in existing +interfaces, additional functions that are deemed to be important due +to their use in real-world software, and support for new library and +language features in C11 such as thread-local storage, which is now +supported on all targets. In addition, support for additional target +cpu architectures is being added. + +The number of packages build successfully against musl - either +out-of-the-box or with minor patches to address portability errors - +has exceeded 5000 and is steadily growing. In addition to application +compatibility testing, unit testing has been conducted using three +separate test frameworks and numerous additional standalone test cases +to verify the correctness of the implementation. Included with this package is a gcc wrapper script (musl-gcc) which allows you to build musl-linked programs using an existing gcc 3.x or -- cgit v1.2.1