musl FAQ

What is musl?

musl is a “libc”, an implementation of the standard library functionality described in the ISO C and POSIX standards, plus common extensions, intended for use on Linux-based systems. Whereas the kernel (Linux) governs access to hardware, memory, filesystems, and the privileges for accessing these resources, the C library is responsible for providing the actual C function interfaces userspace applications see, and for constructing higher-level buffered stdio, memory allocation management, thread creation and synchronization operations, and so on using the lower-level interfaces the kernel provides, as well as for implementing pure library routines of the C language like strstr, snprintf, strtol, exp, sqrt, etc.

Originally in the 1990s, Linux-based systems used a fork of the GNU C library (glibc) version 1, which existed in various versions (libc4, libc5). Later, distributions adopted the more mature version 2 of glibc, and denoted it libc6. Since then, other specialized C library implementations such as uClibc and dietlibc have emerged as well.

musl is a new general-purpose implementation of the C library. It is lightweight, fast, simple, free, and aims to be correct in the sense of standards-conformance and safety.

How do you say musl?

It’s pronounced the same as the English words “mussel” or “muscle”.

musl is small like one but powerful like the other.

What are musl’s dependencies?

When building musl, you will also need a C99 compiler with support for gcc-style __asm__ statements and assembly source files, and weak symbol support in the linker. gcc 3.3 or later (with the GNU assembler and linker) and clang 3.2 or later are known to work. Users have also had success building musl with PCC and Firm/cparser.

For compiling and linking programs against musl, almost any standards-conforming C compiler (even pre-C99) should work.

How do I build musl?

In short, simply run ./configure and make. By default make install installs to /usr/local/musl. You may override this by passing --prefix to configure, but DO NOT use a prefix that overlaps with existing libraries on your system unless your system is already using musl as its primary libc and you are just upgrading.

For further details, see the INSTALL file provided with the source distribution.

How do I use the musl-gcc wrapper?

The musl-gcc wrapper lets you use an existing compiler toolchain with its include and library paths swapped out and replaced by the paths for the newly-installed musl. By default, it runs gcc regardless of the $CC used for compiling musl. This can be changed by exporting the REALGCC environment variable before running musl-gcc or by editing the musl-gcc script itself.

For building software that use autoconf or compatible configure scripts using musl-gcc, it should suffice to set the $CC variable when running configure:

CC=musl-gcc ./configure

If the package is a library, you will want to override its installation prefix to install in the same location you installed musl, using --prefix=/usr/local/musl or similar.

Be aware that, "out of the box", the wrapper only supports C applications, not C++. This is because the C++ libraries and headers are missing from the musl include/library path. The existing libstdc++ is actually compatible with musl in most cases and could be used by copying it into the musl library path, but the C++ header files are usually not compatible. One option may be rebuilding just libstdc++ against musl; however, if C++ support is needed, it's recommended just to build a native toolchain targetting musl.

For software that is not autoconf-based, it may be suffice to add CC=musl-gcc to the end of the make command line, or it may be necessary to modify the makefiles accordingly.

Is musl compatible with glibc?

Yes and no. At both the source and binary level, musl aims for a degree of feature-compatibility, but not bug-compatibility, with glibc. When applications that work with glibc fail to compile against musl, the cause will usually be one of the following:

Binary compatibility is much more limited, but it will steadily increase with new versions of musl. At present, some glibc-linked shared libraries can be loaded with musl, but all but the simplest glibc-linked applications will fail if musl is dropped-in in place of /lib/

What applications are compatible with musl?

Most, but many require very minor patches to fix incorrect assumptions about glibc's headers or other portability issues.

The compatibility page on the musl community wiki has links to patch sets used in several musl-based distributions, and success/failure reports for all packages in pkgsrc. Note that failure in the pkgsrc report does not mean a package cannot be used with musl; in many cases, it just means that minor portability fixes still need to be made either in the package itself or in one of its dependencies. Also note that the pkgsrc results page is huge and takes considerable browser resources to load.

Where can I find patches for applications that don’t build out of the box with musl?

Also on the wiki. The compatibility section, as well as the various distributions using musl, are good sources for patches and information on getting troublesome packages to build.

What is the recommended way to build a musl-native GCC?

See the musl-cross project. In addition to cross-compiler build scripts, the included patches can be used for building a native GCC with $ARCH-linux-musl as its target. It includes changes for building libstdc++ against musl and setting the default dynamic linker to /lib/ld-musl-$

Why is libm.a empty?

On musl, the entire standard library is included in a single library file — libc.a for static linking, and for dynamic linking. This significantly improves the efficiency of dynamic linking, and avoids all sorts of symbol interposition bugs that arise when you split the libraries up — bugs which have plagued glibc for more than a decade.

Why not just omit libm.a, libpthread.a, etc. entirely? POSIX says -lm, -lpthread, etc. are valid options to the compiler and conforming applications must use these options when they need the corresponding functionality, and the easiest way to comply with that requirement (and avoid breaking applications) is with empty .a files by those names.

How can I send bug reports, patches, or support requests?

At this time there is no bug tracker. Complete bug reports or patches should be sent to the mailing list. See the support page for details on how to subscribe or send to the list. Questions or discussion of potential bugs are also welcome on the list, but may receive better attention on our IRC channel, Freenode #musl.

When will it be finished?

When there's nothing left to remove.