2
0

INSTALL 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196
  1. Quick Installation Guide for musl libc
  2. ======================================
  3. There are many different ways to install musl depending on your usage
  4. case. This document covers only the build and installation of musl by
  5. itself, which is useful for upgrading an existing musl-based system or
  6. compiler toolchain, or for using the provided musl-gcc wrapper with an
  7. existing non-musl-based compiler.
  8. Building complete native or cross-compiler toolchains is outside the
  9. scope of this INSTALL file. More information can be found on the musl
  10. website and community wiki.
  11. Build Prerequisites
  12. -------------------
  13. The only build-time prerequisites for musl are GNU Make and a
  14. freestanding C99 compiler toolchain targeting the desired instruction
  15. set architecture and ABI, with support for a minimal subset of "GNU C"
  16. extensions consisting mainly of gcc-style inline assembly, weak
  17. aliases, hidden visibility, and stand-alone assembly source files.
  18. GCC, LLVM/clang, Firm/cparser, and PCC have all successfully built
  19. musl, but GCC is the most widely used/tested. Recent compiler (and
  20. binutils) versions should be used if possible since some older
  21. versions have bugs which affect musl.
  22. The system used to build musl does not need to be Linux-based, nor do
  23. the Linux kernel headers need to be available.
  24. Supported Targets
  25. -----------------
  26. musl can be built for the following CPU instruction set architecture
  27. and ABI combinations:
  28. * i386
  29. * Minimum CPU model is actually 80486 unless kernel emulation of
  30. the `cmpxchg` instruction is added
  31. * x86_64
  32. * ILP32 ABI (x32) is available as a separate arch but is still
  33. experimental
  34. * ARM
  35. * EABI, standard or hard-float VFP variant
  36. * Little-endian default; big-endian variants also supported
  37. * Compiler toolchains only support armv4t and later
  38. * AArch64
  39. * Little-endian default; big-endian variants also supported
  40. * MIPS
  41. * ABI is o32, fp32/fpxx (except on r6 which is fp64)
  42. * Big-endian default; little-endian variants also supported
  43. * Default ABI variant uses FPU registers; alternate soft-float ABI
  44. that does not use FPU registers or instructions is available
  45. * MIPS2 or later, or kernel emulation of ll/sc (standard in Linux)
  46. is required
  47. * MIPS32r6, an incompatible ISA, is supported as a variant "mipsr6"
  48. * MIPS64
  49. * ABI is n64 (LP64) or n32 (ILP32)
  50. * Big-endian default; little-endian variants also supported
  51. * Default ABI variant uses FPU registers; alternate soft-float ABI
  52. that does not use FPU registers or instructions is available
  53. * PowerPC
  54. * Compiler toolchain must provide 64-bit long double, not IBM
  55. double-double or IEEE quad
  56. * For dynamic linking, compiler toolchain must be configured for
  57. "secure PLT" variant
  58. * PowerPC64
  59. * Both little and big endian variants are supported
  60. * Compiler toolchain must provide 64-bit long double, not IBM
  61. double-double or IEEE quad
  62. * Compiler toolchain must use the new (ELFv2) ABI regardless of
  63. whether it is for little or big endian
  64. * S390X (64-bit S390)
  65. * SuperH (SH)
  66. * Standard ELF ABI or FDPIC ABI (shared-text without MMU)
  67. * Little-endian by default; big-endian variant also supported
  68. * Full FPU ABI or soft-float ABI is supported, but the
  69. single-precision-only FPU ABI is not
  70. * Microblaze
  71. * Big-endian default; little-endian variants also supported
  72. * Soft-float
  73. * Requires support for lwx/swx instructions
  74. * OpenRISC 1000 (or1k)
  75. * RISC-V
  76. * 32-bit and 64-bit
  77. * Little endian
  78. * Hard, soft, and hard-single/soft-double floating point ABIs
  79. * Standard ELF; no shared-text NOMMU support
  80. * LoongArch
  81. * 64-bit ISA
  82. * Hard, soft, and hard-single/soft-double floating point ABIs
  83. Build and Installation Procedure
  84. --------------------------------
  85. To build and install musl:
  86. 1. Run the provided configure script from the top-level source
  87. directory, passing on its command line any desired options.
  88. 2. Run "make" to compile.
  89. 3. Run "make install" with appropriate privileges to write to the
  90. target locations.
  91. The configure script attempts to determine automatically the correct
  92. target architecture based on the compiler being used. For some
  93. compilers, this may not be possible. If detection fails or selects the
  94. wrong architecture, you can provide an explicit selection on the
  95. configure command line.
  96. By default, configure installs to a prefix of "/usr/local/musl". This
  97. differs from the behavior of most configure scripts, and is chosen
  98. specifically to avoid clashing with libraries already present on the
  99. system. DO NOT set the prefix to "/usr", "/usr/local", or "/" unless
  100. you're upgrading libc on an existing musl-based system. Doing so will
  101. break your existing system when you run "make install" and it may be
  102. difficult to recover.
  103. Notes on Dynamic Linking
  104. ------------------------
  105. If dynamic linking is enabled, one file needs to be installed outside
  106. of the installation prefix: /lib/ld-musl-$ARCH.so.1. This is the
  107. dynamic linker. Its pathname is hard-coded into all dynamic-linked
  108. programs, so for the sake of being able to share binaries between
  109. systems, a consistent location should be used everywhere. Note that
  110. the same applies to glibc and its dynamic linker, which is named
  111. /lib/ld-linux.so.2 on i386 systems.
  112. If for some reason it is impossible to install the dynamic linker in
  113. its standard location (for example, if you are installing without root
  114. privileges), the --syslibdir option to configure can be used to
  115. provide a different location
  116. At runtime, the dynamic linker needs to know the paths to search for
  117. shared libraries. You should create a text file named
  118. /etc/ld-musl-$ARCH.path (where $ARCH matches the architecture name
  119. used in the dynamic linker) containing a list of directories where you
  120. want the dynamic linker to search for shared libraries, separated by
  121. colons or newlines. If the dynamic linker has been installed in a
  122. non-default location, the path file also needs to reside at that
  123. location (../etc relative to the chosen syslibdir).
  124. If you do not intend to use dynamic linking, you may disable it by
  125. passing --disable-shared to configure; this also cuts the build time
  126. in half.
  127. Checking for Successful Installation
  128. ------------------------------------
  129. After installing, you should be able to use musl via the musl-gcc
  130. wrapper. For example:
  131. cat > hello.c <<EOF
  132. #include <stdio.h>
  133. int main()
  134. {
  135. printf("hello, world!\n");
  136. return 0;
  137. }
  138. EOF
  139. /usr/local/musl/bin/musl-gcc hello.c
  140. ./a.out
  141. To configure autoconf-based program to compile and link against musl,
  142. set the CC variable to musl-gcc when running configure, as in:
  143. CC=musl-gcc ./configure ...
  144. You will probably also want to use --prefix when building libraries to
  145. ensure that they are installed under the musl prefix and not in the
  146. main host system library directories.