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.

Locales

Musl does not support locales (at least not in the traditional way glibc would). However, it is still possible to install sys-apps/musl-locales to at least have a locale binary on the system for compatibility:

root #emerge --ask sys-apps/musl-locales

Because of the limitations within musl, the locale-gen command is unavailable. Furthermore the LANG and LC_* environment variables are also not available on musl, making it impossible to directly set the locale.

Note
This is not an issue, as because of the musl-locales package and the fact that musl sets C.UTF-8 as the default locale, everything should work just fine, provided your desired locale is included in the package.

Timezones

By default, the /usr/share/zoneinfo directory is not populated with binary timezone files as it would be on a glibc system. This is because sys-libs/timezone-data is not packaged with any of the musl stage3 builds, due to it going against how a timezone should be set on musl.

Changing the timezone must be done via setting the TZ variable according to the POSIX timezone specification in /etc/env.d/00musl file. There are 2 methods of setting a timezone on musl.

Method 1: Setting TZ to a posix timezone code

A quick and easy way to get the proper TZ variable for the timezone, is to temporarily emerge sys-libs/timezone-data:

root #emerge --ask sys-libs/timezone-data

Then grab the string at the end of the binary file for timezone of choice. This is the POSIX specification. In this example a value of America/New_York will be used:

root #cat /usr/share/zoneinfo/America/New_York | tail -n 1

EST5EDT,M3.2.0,M11.1.0

Finally, edit the /etc/env.d/00musl file, and specify the TZ value like so:

FILE /etc/env.d/00muslSetting TZ to the posix timezone specification for New York

TZ="EST5EDT,M3.2.0,M11.1.0"

Remove sys-libs/timezone-data package:

root #emerge --ask --unmerge sys-libs/timezone-data

Method 2: Setting TZ to binary timezone file path

This is the recommended option, as it is simple and reliable since it uses a binary timezone file instead of a posix timezone specification.

To set this up, simply install sys-libs/timezone-data like so:

root #emerge --ask sys-libs/timezone-data

Then edit /etc/env.d/00musl and set TZ to the path to your timezone of choice inside /usr/share/zoneinfo like so:

FILE /etc/env.d/00muslSetting TZ to the path of the binary timezone file of New York

TZ="/usr/share/zoneinfo/America/New_York"

Note
For this method, the path does not have to be absolute. If an exact path is not given, musl will search for the timezone in /usr/share/zoneinfo, /share/zoneinfo, and /etc/zoneinfo. Any path with a dot in it will be rejected and ignored by 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.

Musl repository

Warning
The official musl overlay is no longer required due to all fixes already being incorporated in the main gentoo repository and is no longer maintained, continue at your own risk.

The musl overlay included things like musl specific temporary patches that are not yet ready for the master Gentoo repository. Nowadays this is handled in the main Gentoo repository with an example being the standalone header packages, see packages.gentoo.org.

For historic purposes this is how to enable the old repository.

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

Then enabling, and syncing the repository with:

root #eselect repository enable musl

root #emerge --sync musl

Troubleshooting

Rust

Warning
On LLVM built systems running musl, some packages may break if dev-lang/rust-bin is the actively used rust installation due to complications with its binary nature and musl (see bug #912154) . You can see the actively selected rust install by running eselect rust list . A workaround of this is to instead manually compile rust, set that as the rust target via eselect rust and compile the broken package like that.