Skip to content
BranchesTags

Repository files navigation

scrap 🔧

Build codecov License: MIT C++23

A Modern C++ Package Manager and Build System

Quick Start • Features • Installation • Documentation • Contributing

🎯 What is scrap?

scrap is a modern development tool for C++ that brings the simplicity and power of Rust's Cargo to the C++ ecosystem. It provides a unified interface for project management, dependency handling, and build orchestration - all without the traditional complexity of C++ development.

Why scrap?

C++ development has traditionally suffered from:

  • 🔧 Complex build systems - CMake, Make, Bazel, Meson... each with its own learning curve
  • 📦 No standard package manager - Unlike Rust, Go, or Node.js, C++ lacks a unified ecosystem
  • 🖥️ System-dependent toolchains - "It works on my machine" is too common
  • 📚 High barrier to entry - Setting up a C++ project shouldn't require a PhD

scrap solves these problems by providing:

  • 🚀 Zero-configuration project setup - Get started in seconds, not hours
  • 📁 Standardized project structure - Convention over configuration
  • 🔄 Reproducible builds - Same toolchain, same results, everywhere
  • 📦 Modern package management - GitHub-based ecosystem for sharing libraries
  • 🛠️ Integrated toolchain management - No more system dependency hell

🚀 Quick Start

# Create a new C++ application
scrap new my-app

# Create a new C++ library
scrap new my-lib --type=lib

# Build your project
cd my-app
scrap build

# Run your application
scrap run

# Clean build artifacts
scrap clean

That's it! No CMakeLists.txt, no Makefiles, no complex setup. scrap handles everything.

✨ Features

📝 Simple Configuration

Projects are configured with a simple scrap.toml file:

[package]
name = "my-app"
version = "0.1.0"
type = "app"
std = "23"

[[bin]]
name = "my-app"
src = "src/main.cpp"

[dependencies]
fmt = "10.2.1"
boost = { version = "1.84.0", features = ["filesystem", "asio"] }

🎨 Project Templates

Get started quickly with built-in templates:

# Use the default app template
scrap new my-project

# Use a specific template
scrap new my-game --template=game-engine

# Use a GitHub template
scrap new my-tool --template=github:user/template-repo

🔧 Integrated Toolchain Management (Coming Soon)

# Install a specific toolchain
scrap toolchain install llvm@18.0.0

# List available toolchains
scrap toolchain list

# Select a toolchain for your project
scrap toolchain select gcc@13.2.0

📦 Modern Package Management (Planned)

# Add a dependency
scrap add fmt

# Search for packages
scrap search boost

# Update dependencies
scrap update

📋 Project Status

scrap is in early alpha development (v0.0.1). Currently implemented:

✅ Core Features

  • CLI command framework (help, version, command discovery)
  • External command metadata fetching - scrap-* executables are probed via --scrap-metadata (falling back to --help) for a plain first-line description shown in scrap --help; structured JSON/options metadata is not yet part of the protocol

🚧 In Progress

  • Project creation (scrap new) - currently a placeholder command
  • Template system with variable substitution
  • Basic command structure (build, run, clean) - currently placeholder commands
  • Configuration file parsing (scrap.toml)
  • Git-based template repository integration
  • Build system implementation
  • Toolchain management

📅 Planned

  • Package registry and dependency management
  • Cross-compilation support
  • IDE integrations
  • CI/CD templates

🛠️ Installation

Prerequisites

  • C++23 compatible compiler (GCC 13+, Clang 16+, MSVC 2022+)
  • CMake 3.20 or higher
  • Git

Building from Source

# Clone the repository
git clone https://github.com/skipbit/scrap.git
cd scrap

# Configure and build
cmake -S . -B build/release -DCMAKE_BUILD_TYPE=Release
cmake --build build/release --parallel

# The executable will be at build/release/bin/scrap

Install (Unix-like systems)

sudo cp build/release/bin/scrap /usr/local/bin/

📖 Documentation

Detailed documentation is being developed. For now:

🌐 Ecosystem

scrap is building a comprehensive C++ ecosystem:

Related Repositories

Vision

Our goal is to create a Homebrew-like ecosystem for C++ development, where:

  • Libraries are easily discoverable and installable
  • Toolchains are managed independently from the system
  • Projects are reproducible across different environments
  • The community can easily contribute and share packages

🤝 Contributing

We welcome contributions! scrap is built with:

  • Clean Architecture - Domain-driven design with clear separation of concerns
  • Modern C++23 - Leveraging the latest language features
  • SOLID Principles - Extensible and maintainable codebase

How to Contribute

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Follow our coding style guide
  4. Commit your changes
  5. Push to your branch
  6. Open a Pull Request

Development Setup

# Clone with submodules
git clone --recursive https://github.com/skipbit/scrap.git

# Build in debug mode
cmake -S . -B build/debug -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
cmake --build build/debug --parallel

# Run tests
cmake --build build/debug --target test

# Or run tests directly with ctest
ctest --test-dir build/debug --output-on-failure

Testing

The project uses GoogleTest for unit and end-to-end testing, run through ctest. Tests are automatically built when BUILD_TESTS=ON.

# Build and run all tests
cmake --build build/debug --target test

# Run tests with verbose output
ctest --test-dir build/debug --output-on-failure --verbose

# Run a specific test executable directly
./build/debug/test/scrap_gtest
./build/debug/test/scrap_gtest_cli11
./build/debug/test/scrap_e2e

# Release build testing
cmake -S . -B build/release -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
cmake --build build/release --target test

Test Structure:

  • test/unit/command/ - Unit tests for the command layer
  • test/e2e/ - End-to-end tests that spawn the built scrap binary as a subprocess

📊 Roadmap

Phase 1: Foundation (Current)

  • ✅ Command structure (CLI framework)
  • 🚧 Template system
  • 🚧 Configuration management
  • 🚧 Basic build system

Phase 2: Toolchain & Build

  • ⏳ Toolchain management
  • ⏳ Full build system implementation
  • ⏳ Dependency resolution

Phase 3: Package Ecosystem

  • ⏳ Package registry
  • ⏳ Binary package distribution
  • ⏳ Package publishing tools

Phase 4: Advanced Features

  • ⏳ Cross-compilation
  • ⏳ IDE integrations
  • ⏳ CI/CD templates
  • ⏳ SBOM generation

🎯 Design Philosophy

scrap follows these core principles:

  1. Convention over Configuration - Sensible defaults that just work
  2. Reproducible Builds - Same input, same output, everywhere
  3. Modern C++ First - Built for C++17/20/23, not C++98
  4. Community Driven - Open source, open development
  5. Developer Experience - Making C++ development enjoyable

📜 License

scrap is MIT licensed. See LICENSE for details.

🙏 Acknowledgments

scrap is inspired by:

  • Cargo - Rust's excellent package manager
  • Homebrew - The missing package manager for macOS
  • Poetry - Python's modern dependency management

Special thanks to all contributors and the C++ community for feedback and support.

📬 Contact

Made with ❤️ for the C++ Community

⬆ Back to top

About

A Modern C++ Package Manager and Build System

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages