X-Git-Url: http://nsz.repo.hu/git/?p=musl;a=blobdiff_plain;f=INSTALL;h=35f02a32b8d2397afb549c3903a1d49b89492495;hp=9e2c0061d922e3437b016ce310f001af84fdd320;hb=ef5507867b59d19f21437970e87b5d0415c07b2e;hpb=f9c9d8c333494c0a81301d326f28528d96594efd diff --git a/INSTALL b/INSTALL index 9e2c0061..35f02a32 100644 --- a/INSTALL +++ b/INSTALL @@ -1,45 +1,102 @@ -A quick-and-simple guide to installing musl: +==== Installing musl ==== +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. -STEP 1: Configuration +This document covers the prerequisites and procedures for compiling +and installation. -Edit config.mak to override installation prefix, compiler options, -target architecture, etc. as needed. Currently supported archs are -i386 and x86_64. Otherwise, the defaults should be okay for trying out -musl with static linking only. -DO NOT set the prefix to /, /usr, or even /usr/local unless you really -know what you're doing! You'll probably break your system such that -you'll no longer be able to compile and link programs against glibc! -This kind of setup should only be used if you're building a system -where musl is the default/primary/only libc. -The default prefix is /usr/local/musl for a reason, but some people -may prefer /opt/musl or $HOME/musl. +==== Build Prerequisites ==== -For shared library support, the dynamic linker pathname needs to be -hard-coded into every program you link to musl. Ideally, you should -leave the path ($syslibdir) set to /lib unless you are unable to -install files to /lib, in which case you can change it. +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. +The system used to build musl does not need to be Linux-based, nor do +the Linux kernel headers need to be available. -STEP 2: Compiling +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. -Run "make". (GNU make is required.) +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. -STEP 3: Installation -With appropriate privileges, run "make install". +=== Supported Targets ==== +musl can be built for the following CPU instruction set architecture +and ABI combinations: -STEP 4: Using the gcc wrapper. +- 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) -musl comes with a script "musl-gcc" (installed in /usr/local/bin by -default) that can be used to compile and link C programs against musl. -It requires a version of gcc with the -wrapper option (gcc 4.x should -work). For example: +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: + ./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. + +3. Run "make install" as a user sufficient privileges to write to the + destination. + +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: cat > hello.c < @@ -52,17 +109,63 @@ EOF musl-gcc hello.c ./a.out -For compiling programs that use autoconf, you'll need to configure -them with a command like this: +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. + +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 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 ==== + +In this setup, you will need an existing compiler/toolchain. It +shouldnt matter whether it was configured for glibc, uClibc, musl, or +something else entirely, but sometimes gcc can be uncooperative, +especially if the system distributor has built gcc with strange +options. It probably makes the most sense to perform the following +steps inside a chroot setup or on a virtualized machine with the +filesystem containing just a minimal toolchain. + +WARNING: DO NOT DO THIS ON AN EXISTING SYSTEM UNLESS YOU REALLY WANT +TO CONVERT IT TO BE A MUSL-BASED SYSTEM!! + +1. If you are just upgrading an existing version of musl, you can skip + step 1 entirely. Otherwise, move the existing include and lib + directories on your system out of the way. Unless all the binaries + you will need are static-linked, you should edit /etc/ld.so.conf + (or equivalent) and put the new locations of your old libraries in + the search path before you move them, or your system will break + badly and you will not be able to continue. + +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. -CC=musl-gcc ./configure +4. Run "make install" with appropriate privileges. -Be aware that (at present) libraries linked against glibc are unlikely -to be usable, and the musl-gcc wrapper inhibits search of the system -library paths in any case. You'll need to compile any prerequisite -libraries (like ncurses, glib, etc.) yourself. +5. If you are using gcc and wish to use dynamic linking, find the gcc + directory containing libgcc.a (it should be something like + /usr/lib/gcc/i486-linux-gnu/4.3.5, with the arch and version + possibly different) and look for a specs file there. If none + exists, use "gcc -dumpspecs > specs" to generate a specs file. Find + the dynamic linker (/lib/ld-linux.so.2 or similar) and change it to + "/lib/ld-musl-$ARCH.so.1" (with $ARCH replaced by your CPU arch). -Note: If you want the system headers to behave something like glibc's -and expose the kitchen sink by default, you might want to try -CC="musl-gcc -D_GNU_SOURCE" instead of just CC=musl-gcc. This is -needed for compiling many programs with portability issues. +At this point, musl should be the default libc. Compile a small test +program with gcc and verify (using readelf -a or objdump -x) that the +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.