A minimal C library providing a foundation object system with atoms, pairs, garbage collection, and a light type system. It is the object, type and heap layer under x-engine-c, the C engine of x-lang, which carries it as the submodule ext/x-expr and reaches the C library only through this library's x_sys_* and x_lib_* functions.
- Minimal, self-contained object system (atoms and pairs)
- Light type system with runtime type checking
- Optional garbage collection (
-DX_HEAP) - No stdlib dependency (provides its own system abstractions)
- ANSI C compliant, portable across architectures
- Suitable as a foundation for Lisp-like interpreters
#include "x-base.h"
/* Create a base environment */
struct x_base_t conf = { STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO };
x_obj_t *base = x_base_make(NULL, conf);
/* Make atoms and pairs */
x_obj_t *a = x_mksatom(base, X_OBJ_FLAG_NONE, (x_obj_t *)42);
x_obj_t *p = x_mkspair(base, X_OBJ_FLAG_NONE, a, NULL);
/* Access data */
printf("%ld\n", x_atomint(a)); /* 42 */
printf("%ld\n", x_atomint(x_firstobj(p))); /* 42 */See examples/hello.c for a complete working program.
make # Build static library (libx-expr.a)
make test # Run unit tests
make doc # Generate HTML + man page documentation
make install # Install to /usr/local (override with PREFIX=...)Run make help for the full list of targets.
Supported -- tested in CI:
| Flag | Default | Description |
|---|---|---|
X_HEAP |
on | Enable heap management and mark-sweep garbage collection |
X_USE_STDLIB |
off | Delegate x-lib functions to standard library equivalents |
DEBUG |
off | Enable debug output macros (x_debug, x_obj_dump) |
Experimental -- functional but not CI-tested:
| Flag | Default | Description |
|---|---|---|
X_PROFILE |
off | Enable allocation profiling counters |
X_SYS_CLOCK |
off | Enable CPU clock measurement (x_sys_clock) |
X_USE_STDLIB_NONSTD |
off | Use non-standard library extensions (requires X_USE_STDLIB) |
Internal -- for x-expr development:
| Flag | Default | Description |
|---|---|---|
X_OPT_MEMZERO |
off | Zero allocated memory in x_lib_memdup |
X_SYS_FUNC |
identity | Macro to redirect system calls at compile time |
Pass flags to the compiler: make CFLAGS+="-DX_HEAP -DDEBUG"
| Header | Purpose |
|---|---|
| x.h | Core types (x_int_t, x_char_t), architecture detection, error handling |
| x-sys.h | System-level wrappers (malloc, free, read, write, exit) |
| x-lib.h | Portable string, memory, and math utilities |
| x-stdlib.h | Stand-ins for standard C library functions, or wrappers over the real ones under X_USE_STDLIB |
| x-obj.h | Object system: atoms, pairs, flags, type checking, allocation |
| x-base.h | Base environment: I/O, hooks, heap config, field accessors |
| x-heap.h | Mark-sweep garbage collection (requires X_HEAP) |
| x-lisp.h | Lisp-style aliases: cons, car, cdr, setcar, setcdr |
The base environment is a nested pair tree whose field positions are accessed via macros in x-base.h. The library is before 1.0 and the layout is not frozen: it changed between 0.1.0 and 0.2.0. Read a field through its macro, not by position.
x-expr assumes single-threaded execution. The heap chain, garbage collector, and field stack operations are not synchronized. If you need to use x-expr from multiple threads, you must provide your own external synchronization around all object allocation, GC, and base environment mutation.
Add x-expr to your project:
git submodule add https://github.com/jonruttan/x-expr.git ext/x-exprIn your Makefile, add the include path and sources:
X_EXPR_DIR=ext/x-expr
CFLAGS+=-I$(X_EXPR_DIR)/include -DX_HEAP
X_EXPR_SOURCES=$(wildcard $(X_EXPR_DIR)/src/*.c)include/ C headers
src/ C source files
tests/ Unit tests using test-runner submodule
examples/ Example programs
docs/ Documentation and contributor guide
Generate the API reference with make doc. Output is written to docs/ref/html/ (HTML) and docs/ref/man/ (man pages).
See docs/contributing.md for development setup, code style, and pull request guidelines.
MIT No Attribution (MIT-0). See LICENSE.