https://github.com/alternative-intelligence-cp/nitpick-libc
Standard C library wrappers for the Aria programming language — libc without the boilerplate. 10 modules, 571 tests, static + dynamic linking.
https://github.com/alternative-intelligence-cp/nitpick-libc
aria ffi libc musl networking posix programming-language regex static-linking systems-programming
Last synced: about 6 hours ago
JSON representation
Standard C library wrappers for the Aria programming language — libc without the boilerplate. 10 modules, 571 tests, static + dynamic linking.
- Host: GitHub
- URL: https://github.com/alternative-intelligence-cp/nitpick-libc
- Owner: alternative-intelligence-cp
- License: apache-2.0
- Created: 2026-03-27T01:55:55.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-23T06:13:46.000Z (4 days ago)
- Last Synced: 2026-06-23T08:12:40.049Z (4 days ago)
- Topics: aria, ffi, libc, musl, networking, posix, programming-language, regex, static-linking, systems-programming
- Language: C
- Homepage:
- Size: 2.8 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nitpick-libc
> 🚧 **Rebrand in progress:** Nitpick is becoming **Nitpick**. This libc repo still
> uses Nitpick names while the migration is underway. Existing source, tests, and
> compatibility paths are being preserved; package and module renames will happen
> in later coordinated slices.
Pure Nitpick standard library for systems programming — libc functionality without any C dependencies.
[](LICENSE)
## What is nitpick-libc?
nitpick-libc provides Nitpick-native modules for I/O, memory, strings, math, time, process management, networking, POSIX, and filesystem operations. All modules are written in **100% pure Nitpick** using `sys()` syscall wrappers and compiler runtime externs — no C shim layer required. It also enables fully static builds via [musl libc](https://musl.libc.org/) for maximum portability.
## Why?
1. **Zero C dependencies** — Every module is pure Nitpick code. No C shims, no extern C libraries to build or link
2. **Static builds** — Use `nitpickc --static` or the musl pipeline for zero-dependency, fully portable binaries
3. **One canonical source** — Tested, documented standard library the whole ecosystem can depend on
## Status
**v0.3.0** — Standalone Release. 538 tests passing across 18 test suites, all as fully static musl-linked binaries.
**Zero C shim dependencies.** All modules are pure Nitpick code using `sys()` syscalls and compiler runtime (`libnitpick_runtime.a`) externs.
## Architecture
```
nitpick-libc/
├── musl-1.2.6/ # musl source (for static builds)
├── build/musl/ # musl install (libc.a, crt*.o, headers)
├── compat/ # glibc→musl compatibility shim (for libstdc++)
│ └── glibc_compat.c
├── src/ # Pure Nitpick source modules
│ ├── _*.npk # Internal implementation modules
│ └── *.npk # Public API modules (use-importable)
├── tests/ # Test files
├── scripts/ # Build & test automation
│ ├── build_static.sh # Static build pipeline
│ └── run_tests_static.sh # Static test suite runner
└── nitpick-package.toml # Package config
```
### Modules
| Module | Description | Tests |
|--------|-------------|-------|
| **errno** | POSIX error codes and errno handling | 23 |
| **identity** | System identity (uid, gid, pid, hostname) | 10 |
| **io_core** | File I/O via sys() — open, read, write, close, seek | 27 |
| **stat** | File stat via sys() — size, permissions, timestamps | 29 |
| **fs_core** | Filesystem ops — mkdir, rmdir, rename, unlink, access | 14 |
| **fs_link** | Symlinks, hardlinks, readlink, realpath | 15 |
| **fs_dir** | Directory creation and management | 11 |
| **fs_readdir** | Directory listing via getdents64 syscall | 22 |
| **mmap** | Memory mapping via sys() — mmap, munmap, mprotect, msync | 16 |
| **alloc** | Memory allocation — alloc, calloc, realloc, release, byte/int64/string R/W | 29 |
| **buf** | Buffer management — ring buffers, byte buffers | 25 |
| **time** | Time and clock via sys() — time_now, clock, nanosleep, formatting | 54 |
| **net** | Networking via sys() — socket, bind, listen, accept, connect, send, recv, poll, ip parse | 65 |
| **proc** | Process management via sys() — fork, exec, waitpid, pipes, signals, spawn | 38 |
| **posix_extra** | POSIX extras — random, advanced signal handling, errno table | 61 |
| **str** | String operations — search, parse, buffer, formatting | 79 |
| **math** | Math functions — trig, sqrt, pow, log, floor/ceil/round, fmod, constants | 20 |
### Static Binary Size
All nitpick-libc programs compile to ~2.2 MB fully static musl-linked binaries with zero runtime dependencies.
## Quick Start
### Building
```bash
# Build musl (one-time, for hermetic static builds)
cd musl-1.2.6
./configure --prefix=$(pwd)/../build/musl --disable-shared
make -j$(nproc) && make install
cd ..
# Build glibc compat shim (one-time)
cd compat && cc -O2 -Wall -c glibc_compat.c -o glibc_compat.o && ar rcs libglibc_compat.a glibc_compat.o && cd ..
```
### Dynamic Build (default)
No special link flags needed — nitpick-libc modules are `use`-imported directly:
```bash
npkc myfile.npk -o myfile
./myfile
```
### Static Build (simple)
As of npkc v0.2.16+, use the `--static` flag for system static linking:
```bash
npkc --static myfile.npk -o myfile_static
file myfile_static # → "statically linked"
./myfile_static # Just works
```
### Static Build (musl — hermetic)
For zero-dependency, hermetic binaries that work on any Linux (no glibc needed):
```bash
# Using the build script:
./scripts/build_static.sh myfile.npk -o myfile_static
# The binary has zero dependencies:
file myfile_static # → "statically linked"
ldd myfile_static # → "not a dynamic executable"
./myfile_static # Works on any x86-64 Linux
```
### Manual Static Build
The `build_static.sh` script automates this 3-step pipeline:
```bash
# 1. Compile Nitpick → assembly
npkc myfile.npk --emit-asm -o myfile.s
# 2. Assemble
clang -c myfile.s -o myfile.o
# 3. Link against musl + nitpick runtime
MUSL=build/musl/lib
clang++ -static -nostdlib -nostartfiles \
$MUSL/crt1.o $MUSL/crti.o \
myfile.o \
/path/to/libnitpick_runtime.a \
-Lcompat -lglibc_compat \
-L/usr/lib/gcc/x86_64-linux-gnu/13 -lstdc++ -lgcc -lgcc_eh -latomic \
$MUSL/libc.a $MUSL/crtn.o \
-o myfile_static
```
## Testing
```bash
# Run all tests (static, musl-linked)
./scripts/run_tests_static.sh
```
## Usage
### With `use` Imports (recommended)
```nitpick
use "../src/io_core.npk".*;
use "../src/fs_core.npk".*;
func:failsafe = int32(tbb32:err) {
drop(println("Failsafe triggered"));
exit(1);
};
func:main = int32() {
int64:fd = raw(io_open_write("/tmp/test.txt"));
drop(raw(io_write_string(fd, "Hello from Nitpick!\n")));
drop(raw(io_close(fd)));
drop(println("Done"));
exit(0);
};
```
See `src/` for the full set of available modules and their public functions.
## How Static Linking Works
The static build pipeline replaces glibc with musl libc:
1. **nitpickc** compiles `.npk` → x86-64 assembly (via LLVM)
2. **clang** assembles → `.o` object file
3. **clang++** links statically:
- musl's CRT (crt1.o, crti.o, crtn.o) — program entry point
- musl's libc.a — all C standard library functions
- libnitpick_runtime.a — Nitpick's runtime (GC, strings, threads, math, memory primitives)
- libglibc_compat.a — bridges glibc-specific symbols that libstdc++ needs
- GCC static libs — libstdc++.a, libgcc.a, libgcc_eh.a, libatomic.a
The glibc compatibility shim (`compat/glibc_compat.c`) provides ~15 glibc-specific
symbols (fortified functions, LFS aliases, etc.) that libstdc++.a references when
compiled on glibc systems. This lets us use the system's libstdc++ with musl's libc.
## Architecture
As of v0.3.0, nitpick-libc is a **standalone** pure Nitpick library:
- **System calls** are made directly via Nitpick's `sys()` built-in — no C wrapper functions needed
- **Memory primitives** (byte/word read/write, memcpy, memset, memcmp) are provided by the compiler runtime (`libnitpick_runtime.a`)
- **Math functions** (sin, cos, sqrt, etc.) are provided by the compiler runtime
- **String conversions** (to_float, from_float, from_int) are provided by the compiler runtime
- **Everything else** (networking, process management, filesystem, string parsing, buffers, time formatting) is implemented in pure Nitpick
The only C code remaining is `compat/glibc_compat.c`, which is infrastructure for musl static linking (not an nitpick-libc dependency).
## Installation
### From source (recommended)
```bash
git clone https://github.com/alternative-intelligence-cp/nitpick-libc
cd nitpick-libc
# Build musl (one-time, for hermetic static builds)
cd musl-1.2.6
./configure --prefix=$(pwd)/../build/musl --disable-shared
make -j$(nproc) && make install
cd ..
# Build glibc compat shim
cd compat && cc -O2 -Wall -c glibc_compat.c -o glibc_compat.o && ar rcs libglibc_compat.a glibc_compat.o && cd ..
```
### From nitpick package registry
```bash
npkpkg install nitpick-libc
```
## License
Apache License 2.0 — see [LICENSE](LICENSE)
## Part of the Nitpick Ecosystem
| Project | Description |
|---------|-------------|
| [Nitpick Compiler](https://github.com/alternative-intelligence-cp/nitpick) | The Nitpick programming language compiler (npkc, was nitpickc) |
| [nitpick-libc](https://github.com/alternative-intelligence-cp/nitpick-libc) | C standard library wrappers (this repo) |
| [Nitpick Packages](https://github.com/alternative-intelligence-cp/nitpick-packages) | Package registry — 103+ packages |
| [Nitpick Documentation](https://github.com/alternative-intelligence-cp/nitpick-docs) | Language documentation and tutorials |
| [nitpick-build](https://github.com/alternative-intelligence-cp/nitpick-build) | Build system for Nitpick projects (npkbld) |
| [nitpick-tools](https://github.com/alternative-intelligence-cp/nitpick-tools) | Safety auditor, MCP server, developer tools |
| [Nitpicker](https://github.com/alternative-intelligence-cp/nitpicker) | Nitpicker Linux distribution with Nitpick integration |