Awesome
mlibc is a C standard library
Official Discord server: https://discord.gg/7WB6Ur3
AUR package (provides mlibc-gcc
): https://aur.archlinux.org/packages/mlibc
Design of the library
Directory | Purpose |
---|---|
options/ | (More or less) OS-independent headers and code.<br>options/ is divided into subdirectories that can be enabled or disabled by ports. |
sysdeps/ | OS-specific headers and code.<br>sysdeps/ is divided into per-port subdirectories. Exactly one of those subdirectories is enabled in each build. |
abis/ | OS-specific interface headers ("ABI headers"). Those contain the constants and structs of the OS interface. For example, the numerical values of SEEK_SET or O_CREAT live here, as well as structs like struct stat . ABI headers are only allowed to contain constants, structs and unions but no function declarations or logic.<br>abis/ is divided into per-OS subdirectories but this division is for organizational purposes only. Ports can still mix headers from different abis/ subdirectories. |
Porting mlibc to a new OS
Ports to new OSes are welcome. To port mlibc to another OS, the following changes need to be made:
- Add new
sysdeps/
subdirectorysysdeps/some-new-os/
and ameson.build
to compile it. Integratesysdeps/some-new-os/meson.build
into the toplevelmeson.build
. - Create ABI headers in
abis/some-new-os/
. Add symlinks insysdeps/some-new-os/include/abi-bits
to your ABI headers. Look at existing ports to figure out the ABI headers required for the options enabled bysysdeps/some-new-os/meson.build
. - In
sysdeps/some-new-os/
, add code to implement (a subset of) the functions fromoptions/internal/include/mlibc/internal-sysdeps.hpp
. Which subset you need depends on the options thatsysdeps/some-new-os/meson.build
enables.
We recommend that new ports do not build from master
as we occasionally make internal changes that cause out-of-tree sysdeps to break. Instead we recommend you pin a specific release (or commit), or to upstream your changes to this repository so that we can build them on our CI and thus any breakages will be fixed by us in-tree.
Build Configuration
The following custom meson options are accepted, in addition to the built-in options. The options below are booleans which default to false (see meson_options.txt
).
headers_only
: Only install headers; don't buildlibc.so
orld.so
.mlibc_no_headers
: Don't install headers; only buildlibc.so
andld.so
.build_tests
: Build the test suite (see below).disable_x_option
: Disablex
component of mlibc functionality. Seemeson_options.txt
for a full list of possible values forx
. This may be used to e.g disable POSIX and glibc extensions.linux_kernel_headers
: Allows for directing mlibc to installed linux headers. These can be obtained easily, placed in a directory and this option set to the corresponding path. This is required if the linux option is enabled, i.e. when the linux option is not disabled.use_freestnd_hdrs
: Use freestnd-c{,xx}-hdrs instead of looking for compiler headers. Useful if not using a compiler with the correct target triple.
The type of library to be built (static, shared, or both) is controlled by meson's default_library
option. Passing -Ddefault_library=static
effectively disables the dynamic linker.
We also support building with -Db_sanitize=undefined
to use UBSan inside mlibc. Note that this does not enable UBSan for external applications which link against libc.so
, but it can be useful during development to detect internal bugs (e.g when adding new sysdeps).
Running Tests
The mlibc
test suite can be run under a Linux host. To do this, first install a set of kernel headers (as described here), then run from the project root:
meson setup -Dbuild_tests=true -Dlinux_kernel_headers=/path/to/kernel/headers/include build
This will create a build
directory. Then, cd build
and run the tests (showing output) with:
meson test -v