grimx - GCC Runtime & Installation Manager, Cross-platform
A Python CLI tool that scaffolds, builds, and manages dependencies for C and C++ projects. Wraps vcpkg (manifest mode), CMake, and a manager-agnostic lock file into a minimal, reproducible developer workflow.
Project Description
grimx is a command-line tool that orchestrates C and C++ project workflows. It handles scaffolding, dependency management, build configuration, and environment diagnostics through a small set of composable commands.
The goal is straightforward: compress the infrastructure overhead of native development into a repeatable, low-friction interface.
The problem
Starting a C or C++ project from scratch involves a sequence of decisions that have nothing to do with the actual software being built:
- Which build system? CMake, Meson, Bazel?
- Which package manager? vcpkg, Conan, system packages?
- How should the directory structure be organized?
- How do you wire the package manager into CMake without it breaking on another developer's machine?
These are solved problems. They should not require manual assembly on every new project. grimx treats them as defaults.
Architecture
The lock file as source of truth
grimx introduces grimx.lock as the canonical record of a project's dependencies. It is intentionally manager-agnostic:
From this file, grimx generates vcpkg.json (vcpkg's native manifest format) before any install or build operation. The lock file is what developers commit and share; the generated artifacts are derived outputs.
vcpkg in manifest mode
grimx drives vcpkg exclusively in manifest mode with a local install root:
Dependencies are installed per-project using --x-install-root, which guarantees isolation. No global vcpkg state leaks between projects. VCPKG_ROOT is intentionally left unset — grimx locates vcpkg independently and passes VCPKG_MANIFEST_INSTALL=OFF during CMake builds to prevent redundant install passes.
CMake auto-patching
When a dependency is installed, grimx parses vcpkg's usage output to determine the correct find_package call and target_link_libraries entry, then patches CMakeLists.txt automatically. If vcpkg's usage file is absent or ambiguous, grimx falls back to a CMake probe — a minimal CMake configuration to discover available targets.
This means grimx install fmt does not just install the library. It makes the library usable immediately, without manually editing build files.
Toolchain integration
At configure time, grimx injects the vcpkg toolchain file into the CMake invocation:
cmake -DCMAKE_TOOLCHAIN_FILE=<vcpkg>/scripts/buildsystems/vcpkg.cmake
The developer does not write or manage this line. It is derived automatically from the resolved vcpkg path.
Command Set
grimx ships with a complete workflow surface:
| Command | Description |
|---|---|
| grimx new | Scaffold a new C or C++ project |
| grimx install | Install a dependency and patch CMakeLists.txt |
| grimx remove | Remove a dependency and revert CMake patches |
| grimx upgrade | Upgrade a dependency to a newer version |
| grimx sync | Reconcile the environment against grimx.lock |
| grimx build | Configure and build via CMake |
| grimx test | Run the project's test suite |
| grimx run | Execute the compiled binary |
| grimx clean | Remove build artifacts |
| grimx list | List installed dependencies |
| grimx doctor | Diagnose the development environment |
Reproducibiliy
Any developer with grimx installed can reproduce the full environment from the lock file alone:
No manual vcpkg setup. No CMake variable hunting. No version drift.
Project Structure
A project generated by grimx new follows a consistent layout:
The generated CMakeLists.txt is a working configuration from the start, with the vcpkg toolchain path resolved at build time.
Implementation
grimx is implemented in Python using the click framework for the CLI layer and tomlkit for round-trip TOML parsing (preserving comments and formatting in grimx.lock). It is distributed on PyPI and installable as a standard package:
The tool is also usable in editable mode during development:
CI/CD uses GitHub Actions with OIDC trusted publishing to PyPI — no stored API tokens.
Design Constrains
A few explicit constraints shaped the implementation:
grimx does not replace existing tools. CMake, vcpkg, and the compiler remain in place and visible. grimx coordinates them; it does not abstract them away. Developrs can inspect generated files, run CMake manually, and use vcpkg directly at any time.
Per-project isolation over global state. Dependencies live inside the project tree. This avoids the class of bugs where two projects share a vcpkg installation and interfere with each other.
The lock file is commit-worthy; generated files are not. grimx.lock belongs in version control. vcpkg.json and vcpkg_installed/ are derived and should be in .gitignore.
Status
grimx is actively developed and published on PyPI under the [grimlabs.org] GitHub organization.
The core workflow — scaffold, install, build, test — is stable. Active development continues on dependency lifecycle commands and environment diagnostics.
MIT licensed. Contributions welcome