README.md

   1 About musl-cross
   2 ================
   3
   4 This is a small suite of scripts and patches to build a musl libc
   5 cross-compiler. Prebuilt cross and native compilers are available at
   6 http://musl.codu.org/
   7
   8 For the impatient, ./build.sh should build a cross compiler to
   9 /opt/cross/<arch>-linux-musl, no muss, no fuss. Otherwise, you can edit
  10 config.sh to make cross-compilers to other architectures, and even copy
  11 config.sh to another directory then run build.sh from there to avoid polluting
  12 the source dir.
  13
  14 Project Scope
  15 =============
  16 Supported are GCC 4.0.3 until 5.3.0.
  17 for newer GCCs check out the [musl-cross-make project][0].
  18
  19 Notes on building normal cross compilers
  20 ========================================
  21
  22 * For ARM, you must set the triple to arm-linux-musleabi (eabi is the important
  23   bit here)
  24
  25 * You can set versions of binutils, GCC or musl in config.sh with:
  26
  27         BINUTILS_VERSION=<version>
  28         GCC_VERSION=<version>
  29         MUSL_VERSION=<version>
  30
  31 * You can set configure flags for each step:
  32
  33         BINUTILS_CONFFLAGS=...
  34         GCC_BOOTSTRAP_CONFFLAGS=...
  35         MUSL_CONFFLAGS=...
  36         GCC_CONFFLAGS=...
  37
  38 * You can use a git checkout of musl with:
  39
  40         MUSL_VERSION=<git tag or commit>
  41         MUSL_GIT=yes
  42
  43 * If you do not have the GMP, MPFR and/or MPC development libraries on your
  44   host, you can build them along with GCC with a config.sh line:
  45
  46         GCC_BUILTIN_PREREQS=yes
  47
  48
  49 Recommendations
  50 ===============
  51
  52 * If you would like to target a specific CPU revision, usually this is done by
  53   GCC configuration options like so:
  54
  55         GCC_BOOTSTRAP_CONFFLAGS="--with-cpu=armv4t"
  56         GCC_CONFFLAGS="--with-cpu=armv4t"
  57
  58   For ix86 however, it is more common to do this by the target name, e.g.
  59   i486-linux-musl instead of i686-linux-musl.
  60
  61
  62 Upgrading cross compilers
  63 =========================
  64
  65 It is possible to upgrade the musl version in a musl-cross cross compiler
  66 without rebuilding the entire cross compiler prefix from scratch. Simply
  67 download and extract the new version of musl, then configure it like so:
  68
  69     ./configure --prefix="<prefix>/<triple>" CC="<triple>-gcc"
  70
  71 Where "<prefix>" is the prefix the cross compiler root was installed/extracted
  72 to, and <triple> is the GNU-style target triple (e.g. i486-linux-musl).
  73
  74
  75 Other scripts and helpers
  76 =========================
  77
  78 * config.sh is an example configuration file. In many cases, it will do exactly
  79   what you want it to do with no modification, which is why it's simply named
  80   "config.sh" instead of, e.g., "config-sample.sh"
  81
  82 * extra/build-gcc-deps.sh will build the dependencies for GCC into the build
  83   prefix specified by config.sh, which are just
  84   often a nice thing to have. It is of course not necessary.
  85
  86 * extra/build-tarballs.sh builds convenient musl cross-compiler tarballs in a
  87   rather inconvenient way. It first builds a musl cross-compiler to the host
  88   platform (e.g. i686), then it uses that to build static cross-compilers to
  89   various platforms. As a result, building e.g. three cross-compiler tarballs
  90   involves eight compiler build phases (read: this is slow). However, the
  91   resultant tarballs are cross-compilers statically linked against musl, making
  92   them stable and portable.
  93
  94 * config-static.sh is an example configuration file for building a static
  95   cross-compiler. You can use this if, e.g., you already have a build of musl
  96   (and so have musl-gcc) but would like to make a complete, static
  97   cross-compiler based on that, or if you already have a musl cross-compiler
  98   (and so have <arch>-linux-musl-gcc) but would like to make a static
  99   cross-compiler itself compiled against musl.
 100
 101
 102 Requirements
 103 ============
 104
 105 musl-cross depends on:
 106
 107 * shell and core utils (busybox is fine)
 108 * mercurial or git (for checkout only)
 109 * wget (busybox is fine)
 110 * patch
 111 * gcc
 112 * make
 113 * gawk
 114
 115 The following are GCC dependencies, which can be installed on the host system,
 116 or installed automatically using `GCC_BUILTIN_PREREQS=yes`:
 117
 118 * gmp
 119 * mpfr
 120 * mpc
 121
 122 Building GMP additionally requires m4.
 123
 124
 125 Other sources
 126 =============
 127
 128 The patches for GCC are maintained in a separate repository,
 129 http://bitbucket.org/GregorR/musl-gcc-patches/ (mirrored to git at
 130 http://github.com/GregorR/musl-gcc-patches ).
 131
 132 Compiler/Arch Compatibility Matrix
 133 ==================================
 134 |       | i?86 | x86_64 | x32 | mips | powerpc | armv7 | microblaze | sh4 | or1k|
 135 |:------|:-----|:-------|:----|:-----|:--------|:------|:-----------|:----|:---:|
 136 | 4.7.4 | yes  | yes    |     | yes  | yes     | yes   |            |     |     |
 137 | 4.8.5 | yes  | yes    | yes | yes  | yes     | yes   | yes        | yes |     |
 138 | 4.9.3 | yes  | yes    | yes | yes  | yes     | yes   | yes        | yes |     |
 139 | 5.3.0 | yes  | yes    | yes | yes  | yes     | yes   | yes        | yes | *   |
 140
 141 * or1k requires integration of a patch (issue #61)
 142
 143 [0]:https://github.com/richfelker/musl-cross-make