Rivets riv

C++ for beginners. Without the build-system headache.
Rivets handles the first 30 minutes of C++ setup so you can focus on writing code, not fighting CMakeLists.txt.

Quick Start · Documentation · CLI Reference · Structure · Contributing

---

Rivets wraps standard tools like CMake and Clang/GCC in a friendly, modern CLI. It generates readable, standard CMake — you can eject anytime and keep your project.

riv doctor        # check your toolchain
riv init hello    # scaffold a project
riv run           # build & run — that's it

Why Rivets?

Learning C++ is hard enough. Setting up a project shouldn't be.

The Problem	The Rivets Way
“Where do I put my files?”	Opinionated src/, lib/, include/ layout that scales
“How do I link a library?”	Drop it in lib/ — auto-discovered and linked
“Why is CMakeLists.txt so confusing?”	We generate it. Read it, learn it, own it
“Works on my machine…”	Reproducible generation in .riv/

Rivets is not a build system. It is a manager for your build system. No magic. No lock-in. Just standard CMake you can take with you.

Features

• 🩺 riv doctor — Detects clang++/g++/MSVC, cmake, ninja with --json and fix hints.
• 📦 riv init / riv new — Scaffolds riv.toml, src/main.cpp, lib/, include/ with --template full|minimal|lib and .clang-format.
• 🔨 riv build — Validates, generates .riv/CMakeLists.txt, invokes CMake with --release/--debug/-j/-v; symlinks compile_commands.json to root.
• ▶️ riv run — Builds if needed and runs with arg forwarding; --watch for auto-rebuild.
• ✨ riv fmt / riv check / riv test — Format, lint (clang-tidy), and test (ctest) integration.
• 📦 riv add/remove/list/search + riv info — Curated local registry (no network build scripts) + project inspector.
• 🧹 riv clean — Removes .riv/build cleanly.
• 🔒 No build scripts in packages — Downloading a lib never runs arbitrary code.
• 📤 Eject anytime — Keep the generated CMake and walk away.
• 🌓 Dark/Light themed docs — System-aware theme toggle on the site (site/components/theme-*.tsx).

Dependency Management is on the roadmap but intentionally deferred — see Roadmap.

Installation

Go Install (recommended)

go install github.com/Akash97p/rivets/cmd/riv@latest

Make sure $(go env GOPATH)/bin is in your PATH.

Build from Source

git clone https://github.com/Akash97p/rivets.git
cd rivets
go build -o riv ./cmd/riv
# move `riv` to a folder in your PATH, e.g. /usr/local/bin

Pre-compiled binaries for Linux, macOS, and Windows are on the way.

Verify installation

riv --help
riv doctor

You should see compiler and CMake versions detected. Follow the hints if anything is missing.

Quick Start

# 1. Check your toolchain
riv doctor

# 2. Create a new project
riv init hello-world
cd hello-world

# 3. Run it
riv run
# Hello from riv!
# 2 + 3 = 5

Edit src/main.cpp and run riv run again — incremental builds just work.

Commands Reference

Command	What it does	Example
riv doctor [--json]	Validates toolchain (clang++/g++/MSVC, cmake, ninja) with hints	riv doctor --json
riv init <name> [--template full|minimal|lib] [--minimal] [--no-git]	Scaffolds a project (also riv new)	riv init myapp --template minimal
riv build [--release|--debug] [--clean] [-j N] [-v]	Generates CMake and compiles	riv build --release -j 8 -v
riv run [--release] [--watch] [--no-build] [-- <args>]	Builds (if needed) and runs, with watch mode	riv run --watch -- --flag
riv clean	Removes .riv/build (keeps config)	riv clean
riv fmt [--check]	Formats with clang-format	riv fmt --check
riv check	Validates layout + runs clang-tidy if available	riv check
riv info [--json]	Shows project info from riv.toml	riv info --json
riv add <lib>	Adds a curated lib from registry.toml / local registry	riv add stb_image
riv remove <lib>	Removes a lib from lib/ / include/	riv remove stb_image
riv list	Lists installed local libs	riv list
riv search <query>	Searches the curated registry	riv search image
riv test	Runs ctest via CMake (riv test -- --verbose)	riv test
completion [bash|zsh|fish]	Generates shell completion	riv completion bash

Run riv <command> --help for flags. Version: riv --version (v0.1.0-dev).

Project Structure

riv init creates a convention-over-configuration layout:

myproject/
├── riv.toml           # name, version, cxx standard
├── src/
│   └── main.cpp       # entry point
├── lib/               # local libs — auto compiled & linked
│   └── graphics/
│       ├── include/graphics/
│       └── src/
├── include/           # header-only libs
│   └── utils/
└── .riv/              # generated CMake + build (gitignored)
    ├── CMakeLists.txt
    └── build/

Why this layout?

• src/ — your app logic, clean and separate.
• lib/ — modular code; each subfolder becomes a static lib and is linked automatically.
• include/ — header-only utilities.
• riv.toml — tiny, readable manifest instead of CMake boilerplate.
• .riv/ — keeps your root clean; all generation stays hidden.

How It Works

flowchart LR
  A[riv build] --> B[Scan src/lib/include]
  B --> C[Validate layout]
  C --> D[Generate .riv/CMakeLists.txt]
  D --> E[cmake -S .riv -B .riv/build]
  E --> F[cmake --build]

Loading

1. Scan — discover .cpp/.h under src/, lib/, include/.
2. Validate — reject invalid layouts (e.g., .cpp in include/) with friendly errors.
3. Generate — render internal/generator/templates/CMakeLists.txt.tmpl with your file list.
4. Execute — invoke cmake in .riv/; your binary lands at .riv/build/<name>.

Your IDE gets compile_commands.json for free — VS Code / CLion IntelliSense just works.

Philosophy

1. Security first — No build scripts in packages. Dependencies are data, not code execution.
2. No lock-in — Generated CMake is standard and human-readable. Outgrow Rivets? Take it with you.
3. Fail loudly — Invalid structure → precise error + how to fix it.

Roadmap

• Project scaffolding (riv init / riv new with --template)
• CMake generator (with .clang-format, compile_commands.json symlink)
• Build & Run (--release/--debug/--clean/-j/-v, --watch)
• Toolchain doctor (--json, MSVC/clang/g++ gates)
• Code quality (riv fmt, riv check, riv test)
• Local lib registry (add/remove/list/search, riv info)
• Docs wiki at /docs (Next.js + shadcn/ui + GitHub Pages)
• Native Windows & macOS support
• Dependency management — deferred by design (curated stb_image only, see registry.toml)

See PROJECT_PLAN.md and docs/specs/ for the full spec.

Documentation

Full docs live at https://akash97p.github.io/rivets/ — built with Next.js 15 + shadcn/ui and deployed via GitHub Pages.

• Site: https://akash97p.github.io/rivets/ — landing + features
• Wiki: https://akash97p.github.io/rivets/docs/ — beginner-friendly wiki (Getting Started, Core Concepts, all Commands, Guides, Troubleshooting)
• Wrong URL → 404: https://akash97p.github.io/docs is missing the /rivets prefix — use the links above.

Pages is deployed via .github/workflows/pages.yml (output: 'export' + basePath: '/rivets'). If you see “There isn’t a GitHub Pages site here”, ensure Settings → Pages → Source: GitHub Actions is selected — the latest run at actions/runs should be green.

Local preview:

cd site
npm install
npm run dev        # http://localhost:3000 (dev uses no basePath; prod is /rivets)
npm run build      # static export to out/ (also creates .nojekyll)

FAQ

Q: Why not just teach beginners CMake?

CMake is powerful but steep. Rivets is training wheels — you write C++ immediately and learn CMake by reading what we generate.

Q: Is this production ready?

Not yet. Great for learning, prototyping, hobby projects. For enterprise, stick to CMake/Bazel/Conan.

Q: Does it work with VS Code / CLion?

Yes. We generate compile_commands.json via CMake, so C++ extensions get full IntelliSense.

Q: Where is my executable?

.riv/build/<project_name> — root stays clean.

Q: Can I add existing CMake libs?

Yes — put compiled sources in lib/<name>/src + headers in lib/<name>/include/<name>/, or header-only in include/.

Contributing

We love contributions — especially from beginners!

1. Read CONTRIBUTING.md
2. go test ./... and go build -o riv ./cmd/riv
3. go fmt ./... before committing
4. Open a PR against main

See Good First Issues.

License

MIT © AKASH P — see LICENSE.

Acknowledgments

• Go team for a stellar standard library
• CMake, Clang, and GCC — the tools that power C++
• Logo & favicons in assets/ — the rivet-shaped R is Rivets' mark

---

_{Built with care for the next C++ beginner. If Rivets saved you 30 minutes, leave a ⭐.}