INSTALL - platform/external/musl - Gitiles


 ==== 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.

 This document covers the prerequisites and procedures for compiling
 and installation.


 ==== 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 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.

 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.


 === 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. 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 <<EOF
 #include <stdio.h>
 int main()
 {
 	printf("hello, world!\n");
 	return 0;
 }
 EOF
 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.

 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.

 4. Run "make install" with appropriate privileges.

 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).

 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.

	==== 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.

	This document covers the prerequisites and procedures for compiling
	and installation.



	==== 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 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.

	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.



	=== 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. 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 <<EOF
	#include <stdio.h>
	int main()
	{
	printf("hello, world!\n");
	return 0;
	}
	EOF
	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.

	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.

	4. Run "make install" with appropriate privileges.

	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).

	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.