Rivets (riv)

C++ for beginners.

---

Rivets handles the first 30 minutes of setting up a C++ project so you can focus on writing code, not fighting build scripts. It wraps standard tools like CMake and Clang/GCC in a friendly, modern CLI.

The Problem

Learning C++ is hard enough. Setting up a project shouldn't be. Beginners often face a wall of frustration before writing a single line of code:

• "Where do I put my files?"
• "How do I link a library?"
• "Why is CMakeLists.txt syntax so confusing?"
• "It works on my machine but not my friend's."

The Solution

Rivets is not a build system. It is a manager for your build system.

• Standard by default: We enforce a clean folder structure that scales.
• No magic: We generate standard, readable CMake files. You can stop using Rivets at any time and keep your project.
• Zero config: riv init sets up everything. riv run just works.

Features

• riv doctor: Automatically checks your system for compilers (Clang/GCC) and tools (CMake, Ninja).
• riv init: Creates a modern C++ project structure with separated source, include, and test directories.
• riv build: Scans your project and generates the necessary CMake configuration on the fly, then compiles it.
• riv run: Builds (if necessary) and executes your binary with argument forwarding.
• Dependency Management: (Coming Soon) Simple text-based dependency handling.

Installation

Option 1: Go Install (Recommended)

If you have Go installed:

go install github.com/rivets-cli/rivets/cmd/riv@latest

Option 2: Build from Source

git clone https://github.com/rivets-cli/rivets.git
cd rivets
go build -o riv ./cmd/riv
# Move 'riv' to a folder in your PATH

(Note: Pre-compiled binaries for Linux, macOS, and Windows are coming soon!)

Quick Start

1. Check your environment:

   riv doctor

2. Create a new project:

   riv init hello-world
   cd hello-world

3. Run it:

   riv run
   # Output:
   # Hello from riv!
   # 2 + 3 = 5

Commands Reference

Command	Description	Example
riv doctor	Validates toolchain requirements	riv doctor
riv init <name>	Creates a new project folder	riv init game_engine
riv build	Generates CMake and compiles	riv build -j 4
riv run	Builds and runs the executable	riv run -- --flag

Project Structure

Rivets enforces a "Convention over Configuration" structure. When you run riv init, you get:

myproject/
├── riv.toml           # Simple configuration (Name, Version, Standard)
├── src/
│   └── main.cpp       # Your entry point
├── lib/               # Local libraries (automatically linked)
│   └── graphics/
│       ├── include/
│       │   └── graphics/
│       └── src/
└── include/           # Header-only libraries
    └── utils/

Why?

• src/: Keeps your application logic clean.
• lib/: Encourages modular code. Any folder in lib/ is automatically compiled and linked to your main app.
• riv.toml: A readable alternative to complex build scripts.

How It Works

When you run riv build:

1. Scan: Rivets looks at your folders (src, lib, include).
2. Validate: It ensures you haven't done anything dangerous (like putting .cpp files in include/).
3. Generate: It creates a standard .riv/CMakeLists.txt file tailored to your files.
4. Execute: It invokes cmake to configure and build your project inside the hidden .riv/ folder.

Philosophy

1. No Build Scripts in Packages: Security first. Downloading a library shouldn't run arbitrary code on your machine.
2. No Lock-in: The artifacts we generate are standard CMake. If you outgrow Rivets, you can take the generated CMake file and move on.
3. Fail Loudly: If your project structure is invalid, we tell you exactly why and how to fix it.

Roadmap

• Basic Project Structure
• CMake Generator
• Build & Run
• Dependency Management (The big one!)
• Windows Support (Native)
• macOS Support
• Test Runner Integration

FAQ

Q: Why not just teach beginners CMake? A: CMake is powerful but has a steep learning curve. Rivets acts as "training wheels," letting users write C++ immediately. They can learn CMake by inspecting the files Rivets generates.

Q: Is this production ready? A: No. Rivets is currently for learning, prototyping, and small hobby projects. For enterprise systems, stick to CMake/Bazel/Conan.

Q: Can I use this with VS Code / CLion? A: Yes! Since we generate a standard compile_commands.json (via CMake), your IDE's C++ extension will provide full intellisense.

Q: Where is my executable? A: It's located in .riv/build/<project_name>. We keep the root directory clean.

Contributing

We love contributions, especially from beginners!

1. Check CONTRIBUTING.md for setup instructions.
2. Open an issue to discuss your idea.

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgments

• The Go team for an amazing standard library.
• The CMake team for the build system that powers the world.