 |
libmemalloc 0.0.0-alpha
The Magic of Memory Transmutation
|
|
libmemalloc 0.0.0-alpha
The Magic of Memory Transmutation
|
Install host tools using the instructions for your operating system, then continue with cloning and first use. The playbook bootstrap supports Linux x86_64 and native macOS on Apple Silicon or Intel, with Python 3.12. Ubuntu 24.04 is validated locally; macOS execution must also pass the native CI job. The other installation paths below have not been executed in this workspace.
| Host | Setup path |
|---|---|
| Ubuntu 24.04 | Native packages; Python 3.12 is the distribution default |
| Arch Linux | Native build tools, then user-managed Python 3.12 and Ansible |
| Fedora | Native build tools, then user-managed Python 3.12 and Ansible |
| Windows | Ubuntu 24.04 under WSL 2 on an x86_64 machine |
| macOS | Native Homebrew prerequisites; the same Ansible playbook on Apple Silicon and Intel |
Install the prerequisites once:
sudo apt update sudo apt install ansible-core git lua5.4 python3.12-venv build-essential cmake \ curl tar unzip coreutils util-linux cargo jq
Continue with cloning and first use.
Install the host build tools and uv from the official repositories:
sudo pacman -Syu --needed base-devel git lua54 cmake curl tar unzip \ coreutils util-linux rust jq uv
The rust package supplies Cargo. Complete the Python and Ansible setup below before running the playbook. Arch's current system Python is not the project's Python 3.12 baseline. See the official Lua package and uv package catalogs.
Install the host build tools and uv:
sudo dnf install git lua gcc gcc-c++ make cmake curl tar unzip \ coreutils util-linux cargo jq uv
Complete the Python and Ansible setup below; a separately installed python3.12 does not by itself change the python3 selected by the bootstrap. Fedora provides uv and Lua through its package repositories.
Install Python 3.12 and an Ansible controller within the project's supported range:
uv python install 3.12 --default uv tool install --python 3.12 'ansible-core>=2.16,<2.22' uv python update-shell uv tool update-shell
The --default option creates user-level python and python3 commands; it leaves the distribution's /usr/bin/python3 intact. uv currently marks this option experimental. The shell updates persist the executable paths. Open a new terminal once, then check:
python3 -c 'import ensurepip, sys; assert sys.version_info[:2] == (3, 12); print(sys.executable)' ansible-playbook --version uname -sm
The architecture check must report Linux x86_64. If the Python check fails, put the directory printed by uv python dir --bin before /usr/bin in your shell's persistent PATH, then open a new terminal. Continue with cloning and first use; no environment activation is needed on later runs. The bootstrap's missing-package message currently uses Ubuntu package names; use the package list above on Arch or Fedora. See uv's Python selection and tool installation documentation.
Use an x86_64 Windows machine with WSL 2. In PowerShell as Administrator, install Ubuntu 24.04:
wsl --install -d Ubuntu-24.04
Restart if requested, launch Ubuntu and create its Linux user. To enter it again from PowerShell:
wsl -d Ubuntu-24.04
Inside Ubuntu, run the Ubuntu prerequisites, then clone and run the playbook from your Linux home directory. These commands build Linux artifacts inside WSL; they do not qualify a native Windows build. Windows on ARM does not meet the current x86_64 bootstrap requirement. See Microsoft's WSL installation guide and Ubuntu's WSL setup. Ansible's controller requires a Unix-like environment; see its control-node requirements.
Install Apple's Command Line Tools and finish the installer:
xcode-select --install
Install Homebrew and apply its printed shell configuration once. Then install the native prerequisites:
brew install git lua python@3.12 uv cmake coreutils curl rust jq gnupg graphviz \ bison flex openssl@3 pkgconf uv tool install --python python3.12 'ansible-core>=2.16,<2.22' uv tool update-shell
Open a new terminal once so ansible-playbook is on PATH, then continue with cloning and first use. No VM, container or Rosetta is needed. The playbook discovers Homebrew's prefix and selects its Python 3.12 and GNU utilities automatically; no project environment activation or AP variable is needed.
The runtime builds Lua and luv locally. Task preparation selects native Intel or Apple Silicon archives with separate hashes, installs Python tools from the lock, and compiles Rust validators when needed. On Intel Macs, Ansible installation may compile cryptography using Rust and Homebrew OpenSSL. Doxygen is built from verified source on macOS; bison and flex are needed by the full quality profile. Cleanup uses a native kernel lock through Python; installing a Linux flock command is unnecessary. Linux-specific analysis, cross-compilation and release campaigns still require their declared hosts. See Homebrew's Python 3.12 package and GNU utilities.
Clone the repository, enter its root, and list the available tasks:
git clone https://github.com/RafaelVVolkmer/libmemalloc.git cd libmemalloc ansible-playbook playbook.yml
The first run checks prerequisites and prepares Lua and luv under .cache/tools/. Development tasks also activate the repository's Git configuration. Each task prepares its declared tools and reuses verified installations. System packages are installed by you; missing prerequisites produce an installation command. The machine's Ansible stays on PATH, so subsequent terminals can use the same commands without activating an environment or setting AP. The optional Ansible configuration lives in infra/ansible/ansible.cfg.
Start with the specification and source checks:
ansible-playbook playbook.yml -e lma_task=sdd-check ansible-playbook playbook.yml -e lma_task=check-eof ansible-playbook playbook.yml -e lma_task=lua-check
See workspace setup for host requirements and preparation profiles, Git hooks for contributor configuration, and the Nix environment for the development tool catalog.
Run these commands from the repository root:
| Task | Command |
|---|---|
| List all registered tasks | ansible-playbook playbook.yml |
| Diagnose the workspace | ansible-playbook playbook.yml -e lma_task=doctor |
| Build, test and compare fixture installations in Release | ansible-playbook playbook.yml -e lma_task=build |
| Run the automation regression suites | ansible-playbook playbook.yml -e lma_task=tests |
| Check Lua formatting, analysis and complexity | ansible-playbook playbook.yml -e lma_task=lua-check |
| Validate SDD IDs, scope and verification plans | ansible-playbook playbook.yml -e lma_task=sdd-check |
| Test the SDD validator | ansible-playbook playbook.yml -e lma_task=sdd-test |
| Check EOF markers and the final blank line | ansible-playbook playbook.yml -e lma_task=check-eof |
| Check documentation policy | ansible-playbook playbook.yml -e lma_task=docs-check |
| Build the documentation site | ansible-playbook playbook.yml -e lma_task=docs-build |
| Test the Ansible adapter | ansible-playbook playbook.yml -e lma_task=ansible-test |
| Run the full local verification driver | ansible-playbook playbook.yml -e lma_task=checks |
Pass task options through lma_arguments. For example, build the fixture in Debug with four parallel jobs:
ansible-playbook playbook.yml -e lma_task=build \
-e '{"lma_arguments":["--profile=debug","--jobs=4"]}'
Build and full-check runs retain fresh evidence and refuse to overwrite an existing output directory. Use a new --output path or the cleanup scopes below before repeating them. Task logs and results are retained under .cache/logs/tasks/. The engineering playbook documents all task families and their scope; the workflow catalog maps them to CI jobs.
Remove only download and package-manager caches:
ansible-playbook playbook.yml -e lma_task=clean \
-e '{"lma_arguments":["--scope=cache"]}'
Remove builds, metadata, caches and temporary files:
ansible-playbook playbook.yml -e lma_task=clean
Installed tools, sources and Git data are preserved. Use --scope=build or --scope=temporary to narrow the cleanup. To list the selected paths without deleting them:
ansible-playbook playbook.yml -e lma_task=clean \
-e '{"lma_arguments":["--dry-run"]}'
See cleanup scopes for the exact directories and lock behavior.
Build and test the current fixture with CMake:
cmake -S . -B .cache/build/example -D LMA_BUILD_MOCK=ON -D LMA_BUILD_TESTS=ON cmake --build .cache/build/example ctest --test-dir .cache/build/example --output-on-failure --no-tests=error
See CMake build profiles for options and installed consumers. The documentation index covers development, qualification and release procedures.
libmemalloc is a portable, inspectable, and research-oriented memory management library for C projects, designed to support both low-level systems software and application-layer workloads.
It is built on decades of allocator and garbage-collection research, combining modern security-oriented allocation techniques with the strong foundations of classic memory-management literature. The library aims to provide configurable heap strategies, strong portability across systems and architectures, advanced logging and debugging systems, compliance-aware metadata, intuitive documentation, and efficient allocation behavior suitable for comparison with modern allocators.
Optional garbage collector support is part of the broader runtime architecture, allowing projects to choose between manual allocation strategies and automatic memory-management models when appropriate.
The project is being shaped around a set of design goals aligned with its research-oriented memory-management architecture:
| Area | Goal |
|---|---|
| Research Foundation | Build allocator and GC decisions on decades of memory-management literature, combining modern techniques with strong classic foundations. |
| Portability | Isolate compiler, platform, ABI, operating-system, and architecture details behind explicit environment and compatibility layers. |
| Security | Support modern allocation-hardening techniques, defensive APIs, deterministic diagnostics, and auditable metadata. |
| Efficiency | Prioritize fast, cache-conscious, low-overhead algorithms for allocation, deallocation, heap management, diagnostics, and runtime services, while keeping the allocator suitable for benchmarking and optimization against modern general-purpose allocators. |
| Configurability | Support selectable heap strategies, benchmarking-oriented development, and optional garbage collector integration. |
| Diagnostics & Documentation | Provide structured logging, debugging support, generated API documentation, implementation notes, and project metadata that make the library easier to inspect, test, audit, and maintain. |
| Metric | Badge | Meaning |
|---|---|---|
| Repository Size |  | Shows the total repository size reported by GitHub. |
| Code Size |  | Shows the total source-code size reported by GitHub Linguist. |
| Top Language |  | Shows the dominant language detected in the repository. |
| Directory | Responsibility |
|---|---|
| core/ | Distribution fixture |
| cmake/ | Build, installation and consumer contracts |
| scripts/ | Lua automation and verification |
| tests/ | Executable engineering tests and fixtures |
| docs/specs/ | Planned product contracts |
| tools/ | Tool identities and verification policies |