# caxe (cx) 🪓
[](https://github.com/dhimasardinata/caxe/actions/workflows/ci.yml)
[](https://github.com/dhimasardinata/caxe/releases)
[](https://github.com/dhimasardinata/caxe/releases)
[](https://crates.io/crates/caxe)
**caxe** _(pronounced "c-axe")_ is a modern project manager for C and C++ designed to **cut through the complexity** of legacy build systems.
It provides a unified workflow for scaffolding, building, testing, formatting, and managing dependencies—giving C/C++ developers the modern experience they deserve.
> **Zero Configuration. Lightning Fast. Batteries Included.**
## ✨ Features
- **⚡ Zero Config Start**: Create a Hello World C/C++ project in seconds.
- **🔧 Automatic Toolchain Discovery**: Detects MSVC, Clang-CL, Clang++, and GCC without relying on PATH. Uses `vswhere` on Windows.
- **📦 Smart Dependency Management**:
- **Git Libraries**: Auto-download from GitHub. Supports **Pinning** (Tag/Branch/Commit) for stability.
- **System Packages**: Native support for `pkg-config` (e.g., GTK, OpenSSL).
- **Header-Only Support**: Automatically detects libraries that don't need linking (e.g., nlohmann/json).
- **🎨 Code Formatting**: Built-in `cx fmt` command (via `clang-format`).
- **🚀 Parallel & Incremental Builds**: Lock-free parallel compilation engine for maximum speed.
- **💾 Global Caching**: Libraries are downloaded once and shared across all projects. Use `cx update` to refresh them.
- **👁️ Watch Mode**: Automatically recompiles and runs your project when you save a file.
- **🛠️ Flexible Configuration**: Custom binary names, compiler selection, and build scripts.
## 📦 Installation
### Automatic Script (Recommended)
**Windows (PowerShell)**:
```powershell
**Unix (Linux/macOS)**:
```bash
### Option 2: Install via Cargo
```bash
cargo install caxe
```
### Option 3: Manual Download
Download the latest binary from [Releases](https://github.com/dhimasardinata/caxe/releases/latest) and add it to your PATH.
## 🚀 Quick Start
### Interactive Mode
Simply run `cx new` without arguments to start the wizard.
```bash
cx new
# ? What is your project name? › my-app
# ? Select a template: › console
# ? Select language: › cpp
```
### CLI Arguments Mode
```bash
# Default (Hello World)
cx new my-game --lang cpp
# Web Server (cpp-httplib)
cx new my-server --template web
# Raylib Game Config
cx new my-game --template raylib
```
---
## 📖 CLI Reference
### `cx new <name>`
Creates a new project.
- `--lang <c|cpp>` : Set language.
- `--template <console|web|raylib>` : Choose template.
### `cx run`
Compiles and runs the project.
- `--release` : Enable optimizations (`-O3`).
- `-v, --verbose` : Show detailed build commands and decisions.
- `--dry-run` : Preview commands without executing (shows compile/link commands).
- `-- <args>` : Pass arguments to your executable.
### `cx build`
Compiles the project without running it.
- `--release` : Enable optimizations.
- `-v, --verbose` : Show detailed build commands and decisions.
- `--dry-run` : Preview commands without executing.
### `cx add <lib>`
Adds a Git dependency to `cx.toml`. Supports version pinning.
- **Alias (New!)**: `cx add raylib` (No URL needed!)
- **Standard**: `cx add nlohmann/json`
- **Tag**: `cx add nlohmann/json --tag v3.11.2`
- **Branch**: `cx add raysan5/raylib --branch master`
- **Commit**: `cx add fmtlib/fmt --rev a3b1c2d`
### `cx remove <lib>`
Removes a dependency from `cx.toml`.
### `cx update`
Updates all dependencies in your cache to the latest version (unless pinned).
### `cx fmt`
Formats all source code in `src/`. Requires `clang-format`.
### `cx clean`
Removes the `build/` directory and metadata files.
### `cx watch`
Watches for file changes and auto-runs.
### `cx test`
Compiles and runs files in `tests/` directory.
### `cx search <query>`
**_New!_** Search for libraries in the official registry.
```bash
cx search raylib
# Output: raylib - https://github.com/raysan5/raylib.git
```
### `cx lock` & Reproducibility
**_New!_** caxe automatically generates a `cx.lock` file to pin dependencies to exact commits.
- Run `cx update` to ignore the lockfile and fetch the latest versions.
### `cx init`
**_New!_** Initialize a caxe project in an existing directory.
### `cx cache <clean|ls|path>`
**_New!_** Manage the global library cache.
- `clean`: Wipe all cached libraries.
- `ls`: List cached libraries.
- `path`: Show cache directory path.
### `cx upgrade`
**_New!_** Self-update caxe to the latest version.
### `cx toolchain`
**_New!_** Manage compiler toolchains.
- Run `cx toolchain` to interactively select a compiler
- `cx toolchain clear` to reset cached selection
### `cx info`
Displays diagnostic information including:
- All available toolchains (MSVC, Clang-CL, Clang++, GCC)
- Currently active compiler (marked with `← in use`)
- Target ABI (x86_64/x86)
- Build tools status (CMake, Make, Ninja)
### `cx doctor`
**_New!_** Diagnose system and project issues.
- Checks: Toolchain, Build Tools (CMake/Make/Ninja/Git), Project config
- Shows issues and suggestions for fixing them
- Great for troubleshooting build problems
---
## ⚙️ Configuration (`cx.toml`)
Comprehensive configuration example:
```toml
[package]
name = "my-awesome-app"
version = "0.1.0"
edition = "c++20"
[build]
bin = "app" # Output: app.exe
compiler = "clang" # Options: msvc, clang, clang-cl, g++
cflags = ["-O2", "-Wall", "-Wextra"]
libs = ["pthread", "m"]
[dependencies]
# 1. Simple Git (HEAD)
fmt = "https://github.com/fmtlib/fmt.git"
# 2. Pinned Version (Recommended for production)
json = { git = "https://github.com/nlohmann/json.git", tag = "v3.11.2" }
# Pin to specific commit hash
utils = { git = "...", rev = "a1b2c3d4" }
# 3. System Dependency (pkg-config)
gtk4 = { pkg = "gtk4" }
# 4. Complex Build (Library with source code)
# 'output' field tells caxe to link this file.
# If 'output' is missing, caxe treats it as Header-Only.
raylib = { git = "...", build = "make", output = "src/libraylib.a" }
[scripts]
pre_build = "echo Compiling..."
post_build = "echo Done!"
```
## 🛠️ Advanced
### Header-Only Libraries
`caxe` is smart. If you add a library like `nlohmann/json` or `fmt` and do not specify an `output` file in `cx.toml`, `caxe` assumes it is a **Header-Only** library. It will add the include paths (`-I`) but will not attempt to link any static library.
### Environment Variables
Override the compiler without changing config:
```bash
# Windows (PowerShell)
$env:CXX="g++"; cx run
```
### Unit Testing
Create a `tests/` directory and add `.cpp` files.
```bash
cx test
```
## 📝 License
MIT