To start using musl, you have three choices.
Using the musl-gcc wrapper
This allows you to test and use musl on a glibc/uclibc system with no great effort. You cannot, however, use C++ with it.
When building musl, there are 3 important flags to pass to configure:
--prefix=<path>Where to install musl. A good choice is something like
--exec-prefix=<path>This is where the musl-gcc wrapper gets installed to. It should point to somewhere in your
PATH. A good choice is something like
--syslibdir=<path>This is where the dynamic linker gets installed into. The default is
/lib; this path will be baked into binaries built by musl-gcc, so you should not alter it if you want your dynamic binaries to be portable. Installing to
/libon most systems requires root privileges, so a typical choice for non-root users would be
You can omit shared library support (static linking only) and cut musl’s build
time in half using
This configure run will generate a config.mak file, which contains your settings.
make && make install.
Now you can use
musl-gcc instead of
gcc to compile things against musl. Use
-static to build static binaries. For example, to compile a software package
that uses autoconf statically against musl:
CC="musl-gcc -static" ./configure --prefix=$HOME/musl && make
Building a cross compiler targeting musl libc
Unofficial prebuilt cross compilers are available at musl.cc, or you can build them yourself (in about 10-15 minutes on a reasonably recent system) using musl-cross-make. This gives you a full, relocatable musl-targeting toolchain, with C++ support and its own library paths you can install third-party libraries into.
Whether building your own or downloading binaries, you need to select
the appropriate GCC-style tuple for the architecture/ABI you want to
target. It takes the form
example, ARM is
arm-linux-musleabi for standard soft-float EABI and
arm-linux-musleabihf for the hard-float variant. x86_64 is
x86_64-linux-musl. A fairly complete list of interesting tuple
patterns can be found in musl-cross-make’s
If building your own toolchain with musl-cross-make,
make TARGET=x86_64-linux-musl install
will produce an x86_64-targeting toolchain in
./output/x86_64-linux-musl which you can then move to wherever you’d
like to keep it. Note that parallel make (
-jN) is fully supported
and recommended as long as you have multiple cores and plenty ram.
Notes on ARM Float Mode
Note: This information may be outdated or imprecise. It was converted over from instructions for the older musl-cross build script project, which is still maintained but lacks support for newer gcc versions and may have other limitations.
There are three float modes available on modern ARM SoC’s:
soft- floating point is completely emulated, very slow
softfp- uses hardware floating point, but is ABI compatible with soft
hard- complete hardware floating point, incompatible ABI with soft and softfp
On modern armv6 and armv7 chips, hardware floating point is usually implemented on chip. To use the hard-float ABI variant, it suffices to include “hf” at the end the target tuple’s “ABI part” when building your toolchain; musl-cross-make will automatically pick that up and pass the right options to GCC’s build process. For hard-float with the standard baseline EABI (“softfp”), you need to pass custom configuration options for gcc’s build process, e.g.
make TARGET=arm-linux-musleabi GCC_CONFIG="--with-float=softfp --with-arch=armv6k --with-fpu=vfpv2" install
You can also specify custom gcc configure options just to set the
default ISA level so that you don’t have to pass
make TARGET=arm-linux-musleabihf GCC_CONFIG="--with-arch=armv7-a --with-fpu=vfpv3-d16" install
This should produce a cross-toolchain that is compatible at least with: Marvell Dove, Freescale i.MX5x, TI OMAP3+4, Qualcomm Snapdragon, nVidia Tegra2+3 and probably all other modern Cortex-A8, Cortex-A9 and Cortex-A15 SoC’s on the market.
If you plan to compile for older armv6 SoC’s, like the one found on the RasperryPi, use something like:
make TARGET=arm-linux-musleabihf GCC_CONFIG="--with-arch=armv6k --with-fpu=vfpv2" install
VFPv3 contains the VFPv2 subset, so you can also use the armv6 binaries on a more modern armv7 system, but losing some performance. On contrary, for Cortex-A15 SoC’s like the new Samsung Exynos 5, you can activate the even more powerful VFPv4.
Using a distro targeting musl
If your distro uses musl natively, then naturally, anything compiled on that distro will use musl. Multiple distros using musl are listed on the Projects using musl page of this wiki. Some of the most well-known and widely-used are: