libc

A shard to automatically generate and distribute LibC bindings for all targets supported by Crystal (and more).

At some point we might want different projects:

• libc (or c or lib_c): the actual LibC bindings.
• libc-generator: the LibC generator.
• libc-includes: the C include generator + (with copies right in the repo).

LibC Generator

The generator is built on multiple stages:

1. Definition: the expected bindings to be found in a C header (constants, enums, unions, structs, functions); generates a CPP header to help the Resolver.

2. Parser: preprocesses and parses one or many CPP headers using libclang.

3. Resolver: searches the definitions in the preprocessed/parsed libclang AST.

4. Transformer: transforms the libclang AST, for example evaluates cursors into a value and maps C types into Crystal type.

5. Generator: generates the final Crystal bindings.

This eventually generates a single Crystal file for a C header (for example unistd.cr for unistd.h with everything as expected to be defined by C headers if they are supported by the target.

The generator can be cross compiled from a copy of a target's libc plus kernel headers, usually the copy of a target's /usr/include folder.

POSIX definitions

The generator currently focuses on POSIX definitions as per The Open Group Base Specifications Issue 7, 2018 edition IEEE Std 1003.1™-2017 (Revision of IEEE Std 1003.1-2008).

TODO: update the definitions to The Open Group Base Specifications Issue 8 IEEE Std 1003.1™-2024 Edition.

C includes

The c_includes directory is meant to contain the definitions for any target triple (e.g. x86_64-linux-gnu). The directory is empty because all current targets can be generated from make.

The Makefile should generate the folder for many targets using different means (e.g. multiarch docker or downloading src). The idea is that we should be able to gather the C includes from scratch and to update them at any moment from a simple make <target>. Some targets might be complex, for example Windows or Darwin (that also comes with a hardware issue) and it might be easier to copy-paste manually from a running system.

• aarch64-cosmo
• aarch64-darwin
• aarch64-freebsd
• aarch64-netbsd
• aarch64-linux-android21
• aarch64-linux-android24
• aarch64-linux-android28
• aarch64-linux-gnu
• aarch64-linux-musl
• aarch64-openbsd
• aarch64-windows-gnu
• aarch64-windows-msvc
• arm-freebsd
• arm-linux-gnueabihf
• arm-linux-musleabihf
• arm-netbsd
• arm-openbsd
• i386-freebsd
• i386-linux-gnueabihf
• i386-linux-musleabihf
• i386-netbsd
• i386-openbsd
• wasm32-wasi
• x86_64-cosmo
• x86_64-darwin
• x86_64-dragonflybsd
• x86_64-freebsd
• x86_64-linux-gnu
• x86_64-linux-musl
• x86_64-netbsd
• x86_64-openbsd
• x86_64-windows-gnu
• x86_64-windows-msvc

The missing targets are because they either:

1. miss an automated generation of the C include folder: The c_include/Makefile must have a target that will download sources or copy the include folder at runtime (it might be complex for Darwin on Linux);
2. miss source definitions (Windows);
3. have specific requirements (WASI, Cosmopolitan).

TODO

• DEBUG: there are bugs in the generated bindings.
• Generate a single c folder intead of one per target triple.
• Save the generated LibC bindings.
• Save the C includes for quicker setup (e.g. CI).
• Add ABI version targets, for example: freebsd13, freebsd14 and freebsd15.
• Cleanup/enhance the POSIX definitions.
• Windows definitions and targets (to be defined).

License

Distributed under the Apache-2.0 LICENSE.