X-Git-Url: http://nsz.repo.hu/git/?a=blobdiff_plain;f=INSTALL;h=2994630a403d6f41f6828d65db85b1ec2db639ec;hb=0bc03091bb674ebb9fa6fe69e4aec1da3ac484f2;hp=2470a5bf7aed5d34e5d4e46d8503ee14bf1383fc;hpb=0b44a0315b47dd8eced9f3b7f31580cf14bbfc01;p=musl diff --git a/INSTALL b/INSTALL index 2470a5bf..2994630a 100644 --- a/INSTALL +++ b/INSTALL @@ -1,43 +1,160 @@ -A quick-and-simple guide to installing musl: +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. -STEP 1: Configuration +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. -Edit config.mak to override installation prefix, compiler options, -etc. as needed. The defaults should be okay for trying out musl with -static linking only. The only arch supported at present is i386. If -you're on an x86_64 machine, you can add -m32 to the compiler options -to build a working 32bit musl. In this case you will also need to add --m32 in two locations in the generated tools/musl-gcc script if you -intend to use it. -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. +Build Prerequisites +------------------- -The default prefix is /usr/local/musl for a reason, but some people -may prefer /opt/musl or $HOME/musl. +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 requirements +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. Firm/cparser is +also believed to work but lacks support for producing shared +libraries. GCC 4.9.0 is known to have a serious bug (#61144) which +affects musl and is not supported. -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 + * Minimum CPU model is actually 80486 unless kernel emulation of + the `cmpxchg` instruction is added -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: +* x86_64 + +* ARM + * EABI, standard or hard-float VFP variant + * Little-endian default; big-endian variants also supported + * Compiler toolchains only support armv4t and later + +* 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 + +* 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 + +* Microblaze + * Big-endian default; little-endian variants also supported + * Soft-float + * Requires support for lwx/swx instructions + +The following additional targets are available for build, but may not +work correctly and may not yet have ABI stability: + +* SuperH (SH) + * 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 supported (musl always + requires IEEE single and double to be supported) + +* x32 (x86_64 ILP32 ABI) + + + +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 < @@ -47,15 +164,14 @@ int main() return 0; } EOF -musl-gcc hello.c +/usr/local/musl/bin/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 +CC=musl-gcc ./configure ... -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. +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.