INSTALL - platform/external/musl - Gitiles


 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.

 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.


 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 requirements
 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. Firm/cparser is
 also believed to work but lacks support for producing shared
 libraries. GCC 4.9.0 and 4.9.1 are known to have a serious bug
 (#61144) which affects musl. Beginning with version 1.1.4 musl
 attempts to work around the bug, but these compiler versions are still
 considered unstable and unsupported.


 Supported Targets
 -----------------

 musl can be built for the following CPU instruction set architecture
 and ABI combinations:

 * i386
     * Minimum CPU model is actually 80486 unless kernel emulation of
       the `cmpxchg` instruction is added

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

	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.

	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.


	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 requirements
	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. Firm/cparser is
	also believed to work but lacks support for producing shared
	libraries. GCC 4.9.0 and 4.9.1 are known to have a serious bug
	(#61144) which affects musl. Beginning with version 1.1.4 musl
	attempts to work around the bug, but these compiler versions are still
	considered unstable and unsupported.



	Supported Targets
	-----------------

	musl can be built for the following CPU instruction set architecture
	and ABI combinations:

	* i386
	* Minimum CPU model is actually 80486 unless kernel emulation of
	the `cmpxchg` instruction is added

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