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. To set a locale, first set MUSL_LOCPATH like:

FILE /etc/env.d/00localSet MUSL_LOCPATH to the path of musl locales

MUSL_LOCPATH="/usr/share/i18n/locales/musl"

Then, to view available locales simply do:

root #eselect locale list

Available targets for the LANG variable:
  [1]   C
  [2]   C.UTF-8
  [3]   sr_RS.UTF-8
  [4]   cs_CZ.UTF-8
  [5]   nb_NO.UTF-8
  [6]   de_DE.UTF-8
  [7]   sv_SE.UTF-8
  [8]   nl_NL.UTF-8
  [9]   fr_FR.UTF-8
  [10]  fi_FI.UTF-8
  [11]  en_GB.UTF-8
  [12]  it_IT.UTF-8
  [13]  pt_PT.UTF-8
  [14]  en_US.UTF-8
  [15]  de_CH.UTF-8
  [16]  es_ES.UTF-8 *
  [17]  pt_BR.UTF-8
  [18]  ru_RU.UTF-8
  [ ]   (free form)

And set the one you want likewise.

Note
Keep in mind your desired locale may not be complete or even available.

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/00local file.

See also
Defining variables globally

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/00local file, and specify the TZ value like so:

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

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

And update the environment:

root #env-update && source /etc/profile

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/00local and set TZ to the path to your timezone of choice inside /usr/share/zoneinfo like so:

FILE /etc/env.d/00localSetting 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.

And update the environment:

root #env-update && source /etc/profile

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 provide 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 is 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

On LLVM-based systems using musl, packages may break if dev-lang/rust-bin is the active Rust installation due to compatibility issues arising from its binary nature and musl (bug #912154).

Check which Rust installation is active:

user $eselect rust list

If rust-bin is active, the workaround is to emerge dev-lang/rust manually:

root #emerge --ask --verbose dev-lang/rust

Then, use eselect rust to set it active, and finally, attempt to re-emerge the affected package.

External resources

voidnsrun - Tool to run glibc programs on musl using mount namespaces and bind mounts