Getting started

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 $HOME/musl.
• --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 $HOME/bin.
• --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 /lib on most systems requires root privileges, so a typical choice for non-root users would be $HOME/musl/lib.

You can omit shared library support (static linking only) and cut musl's build time in half using --disable-shared.

This configure run will generate a config.mak file, which contains your settings.

Now run 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 [arch]-linux-musl[abi_modifiers]. For 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 README.md.

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 -march=..., e.g.

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][Projects using musl]. Some of the most well-known and widely-used are:

• Sabotage, the original build-from-source distro based on musl
• Adélie Linux, Alpine Linux, and Void Linux, binary-package based distros with lots of packaged software