grimx - GCC Runtime & Installation Manager, Cross-platform

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:

[dependencies]

fmt = { manager = "vcpkg", version = "11.0.2" }
spdlog = { manager = "vcpkg", version = "1.15.3" }

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:

project/
vcpkg.json ← generated from grimx.lock
vcpkg_installed/ ← local to the project, not global

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.