Documentation

#Introduction

Mux is a command-line tool written in Rust that brings a modern developer experience to C and C++ projects. It handles dependency management, project scaffolding, and build system integration — all from a single binary with no runtime dependencies.

#Installation

The recommended way to install Mux is via the install script. It detects your platform automatically, downloads the correct pre-built binary, and verifies its checksum.

Linux / macOS

curl -fsSL https://themux.dev/install.sh | sh

Installs to ~/.local/bin by default. Pass --system to install to /usr/local/bin (requires sudo).

Windows

irm https://themux.dev/install.ps1 | iex

Installs to %USERPROFILE%\.mux\bin and adds it to your user PATH automatically. Pass -System to install to %ProgramFiles%\mux\bin (requires admin).

From Source

cargo install mux

Requires a recent stable Rust toolchain. Run rustup update stable if needed.

Verify Installation

mux --version
# mux v0.1.2

#Quick Start

Create a new project and build in two commands.

mux init my-app
cd my-app
mux build && mux run

This scaffolds a CMake preset-based project and compiles it. To add a dependency, see mux add.

#mux init

Scaffold a new C or C++ project. Creates a directory with the given name, a starter src/main.c or src/main.cpp, and a CMakeLists.txt.

mux init <project-name> [flags]

# C project (default)
mux init my-lib

# C++ project via --lang
mux init my-app --lang cpp

# C++ project shorthand
mux init my-app --cpp

#mux add

Add a dependency to the project. Registers it in mux.lock and patches CMakeLists.txt to link it automatically. The lib argument accepts a local path, a git URL, or a GitHub shorthand.

mux add <lib> [flags]

# GitHub shorthand (owner/repo)
mux add fmtlib/fmt

# GitHub shorthand — repo name only
mux add fmt

# Full git URL
mux add https://github.com/gabime/spdlog

# Local path
mux add ./vendor/mylib

# Link to a specific CMake target
mux add fmtlib/fmt --target my_server

#mux remove

Remove a library from the project. Updates mux.lock and removes the corresponding entries from CMakeLists.txt.

mux remove <lib-name>

mux remove fmt

#mux build

Compile the project using CMake. Runs configure and build in one step.

mux build [flags]

# Debug build (default)
mux build

# Optimized release build
mux build --release

# Build both presets
mux build --all

#mux run

Build and immediately run the project binary.

mux run [flags]

mux run
mux run --release

#mux test

Build and run the project's test suite via CMake's CTest integration.

mux test [flags]

mux test
mux test --release
mux test --all

#mux clean

Remove build artifacts from the output directory.

mux clean [flags]

mux clean
mux clean --release
mux clean --all

mux.lock

Mux records every installed dependency in a mux.lock file at the project root. This file is managed automatically — do not edit it by hand.

The lockfile is a tab-separated text file with a version header. Each row records the library name, its source, the CMake target it was linked to, and the include path.

# mux lock v1
name	source	target	include
fmt	registry	my-app	fmt/core.h
spdlog	registry	my-app	spdlog/spdlog.h

Commit mux.lock to version control to ensure reproducible builds across machines.

CMakeLists.txt

Mux generates and maintains a CMakeLists.txt at the project root. When you run mux add or mux remove, Mux patches the managed section automatically.

You can freely edit the parts of CMakeLists.txt outside the managed block — Mux will not overwrite your customizations.

cmake_minimum_required(VERSION 3.20)
project(my-app CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(my-app src/main.cpp)

# Managed by mux — do not edit below this line
find_package(fmt REQUIRED)
find_package(spdlog REQUIRED)
target_link_libraries(my-app PRIVATE fmt::fmt spdlog::spdlog)

#Examples

A simple C project

mux init hello
cd hello
mux build && mux run

// src/main.c
#include <stdio.h>

int main(void) {
    printf("Hello from mux!\n");
    return 0;
}

Adding a dependency

mux init greeter
cd greeter
mux add antirez/linenoise
mux build && mux run

// src/main.c
#include <linenoise.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    char *name = linenoise("Enter your name: ");
    if (name) {
        printf("Hello, %s!\n", name);
        free(name);
    }
    return 0;
}