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.
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.
musl does not support locales (at least not in the traditional way glibc would). However, it is still possible to install locale binary on the system for compatibility:to at least have a
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.
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.
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 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:
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:
cat /usr/share/zoneinfo/America/New_York | tail -n 1
Finally, edit the /etc/env.d/00musl file, and specify the TZ value like so:
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 installlike so:
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:
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.
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:
- Upstream is not willing to support musl. Maintaining musl patches downstream involves a lot of hassle, and is usually not done. Example:
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.
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.
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.
emerge --ask app-eselect/eselect-repository
Then enabling, and syncing the repository with:
eselect repository enable musl
emerge --sync musl
On LLVM built systems running musl, some packages may break if is the actively used rust installation due to complications with its binary nature and musl (see ) . 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.
- Libc — a software component that allows userspace applications to interact with operating system services.
- Project:Musl - Gentoo's musl project
- Musl porting notes — pointers on getting software to compile with musl
- voidnsrun - Tool to run glibc programs on musl using mount namespaces and bind mounts