INSTALL 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148
  1. ==== Installing musl ====
  2. musl may be installed either as an alternate C library alongside the
  3. existing libraries on a system, or as the primary C library for a new
  4. or existing musl-based system.
  5. First, some prerequisites:
  6. - A C99 compiler with gcc-style inline assembly support, support for
  7. weak aliases, and support for building stand-alone assembly files.
  8. gcc 3.x and 4.x are known to work. pcc and LLVM/clang may work but
  9. are untested, and pcc is known to have some bugs.
  10. - GNU make
  11. - Linux, preferably 2.6.22 or later. Older versions are known to have
  12. serious bugs that will make some interfaces non-conformant, but if
  13. you don't need threads or POSIX 2008 features, even 2.4 is probably
  14. okay.
  15. - A supported CPU architecture (currently i386, x86_64, arm, or mips).
  16. - If you want to use dynamic linking, it's recommended that you have
  17. permissions to write to /lib and /etc. Otherwise your binaries will
  18. have to use a nonstandard dynamic linker path.
  19. == Option 1: Installing musl as an alternate C library ==
  20. In this setup, musl and any third-party libraries linked to musl will
  21. reside under an alternate prefix such as /usr/local/musl or /opt/musl.
  22. A wrapper script for gcc, called musl-gcc, can be used in place of gcc
  23. to compile and link programs and libraries against musl.
  24. To install musl as an alternate libc, follow these steps:
  25. 1. Configure musl's build with a command similar to:
  26. ./configure --prefix=/usr/local/musl --exec-prefix=/usr/local
  27. Refer to ./configure --help for details on other options. You may
  28. change the install prefix if you like, but DO NOT set it to a
  29. location that contains your existing libraries based on another
  30. libc such as glibc or uClibc. If you do not intend to use dynamic
  31. linking, you may disable it at this point via --disable-shared and
  32. cut the build time in half. If you wish to use dynamic linking but
  33. do not have permissions to write to /lib, you will need to set an
  34. alternate dynamic linker location via --syslibdir.
  35. 2. Run "make". Parallel build is fully supported, so you can instead
  36. use "make -j3" or so on SMP systems if you like.
  37. 3. Run "make install" as a user sufficient privileges to write to the
  38. destination.
  39. 4. Create a file named /etc/ld-musl-$ARCH.path (where $ARCH is
  40. replaced by i386, x86_64, etc. as appropriate) containing the
  41. correct colon-delimited search path for where you intend to install
  42. musl-linked shared library files. If this file is missing, musl
  43. will search the standard path, and you will encounter problems when
  44. it attempts to load libraries linked against your host libc. Note
  45. that this step can be skipped if you disabled dynamic linking.
  46. After installing, you can use musl via the musl-gcc wrapper. For
  47. example:
  48. cat > hello.c <<EOF
  49. #include <stdio.h>
  50. int main()
  51. {
  52. printf("hello, world!\n");
  53. return 0;
  54. }
  55. EOF
  56. musl-gcc hello.c
  57. ./a.out
  58. To configure autoconf-based program to compile and link against musl,
  59. you may wish to use:
  60. CC="musl-gcc -D_GNU_SOURCE" ./configure ...
  61. Correctly-written build systems should not need -D_GNU_SOURCE as part
  62. of $CC, but many programs do not use feature-test macros correctly and
  63. simply assume the compiler will automatically give them the kitchen
  64. sink, so the above command is an easy workaround.
  65. You will probably also want to use --prefix when building libraries to
  66. ensure that they are installed under the musl prefix and not in the
  67. main host system library directories.
  68. Finally, it's worth noting that musl's include and lib directories in
  69. the build tree are setup to be usable without installation, if
  70. necessary. Just modify the the paths in the spec file used by musl-gcc
  71. (it's located at $prefix/lib/musl-gcc.specs) to point to the
  72. source/build tree.
  73. == Option 2: Installing musl as the primary C library ==
  74. In this setup, you will need an existing compiler/toolchain. It
  75. shouldnt matter whether it was configured for glibc, uClibc, musl, or
  76. something else entirely, but sometimes gcc can be uncooperative,
  77. especially if the system distributor has built gcc with strange
  78. options. It probably makes the most sense to perform the following
  79. steps inside a chroot setup or on a virtualized machine with the
  80. filesystem containing just a minimal toolchain.
  81. WARNING: DO NOT DO THIS ON AN EXISTING SYSTEM UNLESS YOU REALLY WANT
  82. TO CONVERT IT TO BE A MUSL-BASED SYSTEM!!
  83. 1. If you are just upgrading an existing version of musl, you can skip
  84. step 1 entirely. Otherwise, move the existing include and lib
  85. directories on your system out of the way. Unless all the binaries
  86. you will need are static-linked, you should edit /etc/ld.so.conf
  87. (or equivalent) and put the new locations of your old libraries in
  88. the search path before you move them, or your system will break
  89. badly and you will not be able to continue.
  90. 2. Configure musl's build with a command similar to:
  91. ./configure --prefix=/usr --disable-gcc-wrapper
  92. Refer to ./configure --help for details on other options.
  93. 3. Run "make" to compile musl.
  94. 4. Run "make install" with appropriate privileges.
  95. 5. If you are using gcc and wish to use dynamic linking, find the gcc
  96. directory containing libgcc.a (it should be something like
  97. /usr/lib/gcc/i486-linux-gnu/4.3.5, with the arch and version
  98. possibly different) and look for a specs file there. If none
  99. exists, use "gcc -dumpspecs > specs" to generate a specs file. Find
  100. the dynamic linker (/lib/ld-linux.so.2 or similar) and change it to
  101. "/lib/ld-musl-$ARCH.so.1" (with $ARCH replaced by your CPU arch).
  102. At this point, musl should be the default libc. Compile a small test
  103. program with gcc and verify (using readelf -a or objdump -x) that the
  104. dynamic linker (program interpreter) is /lib/ld-musl-$ARCH.so.1. If
  105. you're using static linking only, you might instead check the symbols
  106. and look for anything suspicious that would indicate your old glibc or
  107. uClibc was used.
  108. When building programs against musl, you may still want to ensure the
  109. appropriate feature test macros get defined, as in:
  110. CC="gcc -D_GNU_SOURCE" ./configure ...