Musl usage guide

musl is a standard C library implementation striving to be lightweight and correct in the sense of standards, and it is supported by Gentoo for most common CPU architectures. It is a replacement for the widely used GNU C library (glibc). This guide is about using musl libc, for a development guide, see Musl porting notes.

Getting started

Choosing musl over glibc has to be done at install time, because replacing the standard C library on an already installed system is not possible. This is done by unpacking the -musl stage3 tarball instead of the default glibc one. The install handbook for the target architecture can be used as normal, except that generating locales is not necessary on musl libc.

After installation it is a good idea to enable the musl overlay. The musl overlay includes things like musl specific temporary patches that are not yet ready for the master Gentoo repository. This can be done by first installing app-eselect/eselect-repository.

root #emerge --ask app-eselect/eselect-repository

then enabling, and syncing the repository with:

root #eselect repository enable musl

root #emerge --sync musl

Build failures

musl has a focus on being standards compliant and correct, which means that some packages can fail to build if they use non-standard functionality often referred to as extensions. Normally these are GNU extensions provided by glibc, which is the most widely used standard C library on Linux systems such as Gentoo.

The best way of dealing with these build failures is to fix them and report upstream. It is also a good idea to file a bug on the Gentoo Bugzilla. More information regarding porting software to musl can be found here: musl porting notes. For user convenience there are also standalone packages that provides functionality not included in musl, see Musl_porting_notes#Standalone_packages.

Running glibc software

Some pieces of software are not yet compatible with musl libc. This is usually caused because:

The software in closed source, so compiling for musl is not possible unless contacting the proprietor. Example: www-client/google-chrome
Upstream is not willing to support musl. Maintaining musl patches downstream involves a lot of hassle, and is usually not done. Example: www-client/chromium

Flatpak

The easiest method of working around this is by using Flatpak. Flatpak works by sandboxing applications and running them with provided runtimes. The runtimes include needed libraries such as glibc, and therefore applications will run as normal.

Chroot

Using chroots is another method for running glibc programs. Chroot is used to change the apparent root directory, which means programs running inside the chroot will see another directory structure. In this case a normal Gentoo glibc installation can be installed on top of a Gentoo musl system. Using chroots for this purpose often requires setting up sound and graphics, instructions for this can be found at Chroot#Sound and graphics.