Getting Started with Craft

April 11, 2026 · View on GitHub

Craft is a lightweight build tool for C and C++ projects. You describe your project in a simple craft.toml file and Craft handles the rest by generating CMake, managing dependencies, and building your project.

Installation

macOS & Linux

curl -fsSL https://raw.githubusercontent.com/randerson112/craft/main/install.sh | bash

Windows

irm https://raw.githubusercontent.com/randerson112/craft/main/install.ps1 | iex

Requirements: git and cmake must be installed and available in your PATH.

Verify Installation

craft --version
craft help

Your First Project

Create a new project

craft project my_app
cd my_app

This creates a new directory with the following structure:

MyApp/
├── craft.toml
├── CMakeLists.txt        # generated by Craft, do not edit
├── .gitignore
├── include/
├── src/
│   └── main.cpp
└── .craft/
    └── deps/

Build and run it

craft build
craft run

That's it. You now have a working C++ project.

Understanding craft.toml

craft.toml is the single source of truth for your project. Open it and you'll see:

[project]
name = "my_app"
version = "0.1.0"
language = "cpp"
cpp_standard = 17

[build]
type = "executable"
include_dirs = ["include"]
source_dirs = ["src"]

Craft reads this file and generates CMakeLists.txt automatically whenever you run craft build. You should never need to write or edit CMake directly.

See the full craft.toml reference for all available fields.

Creating a C Project

craft project my_app --lang c

Or set C as your global default so you don't have to specify it every time:

craft config set defaults.language c

Adding Dependencies

From the registry

craft add sfml

Craft fetches the package from the registry and wires everything up automatically.

From GitHub

craft add --git https://github.com/raysan5/raylib.git --links raylib

From a local Craft project

craft add --path ../my_library

After adding a dependency run craft build to fetch and compile it.

Removing a dependency

craft remove raylib

Adopting an Existing Project

Already have a C/C++ project? Run craft init in the project directory:

cd my_existing_project
craft init

Craft will scan your project structure, detect the language, source directories, and include directories, then generate craft.toml and CMakeLists.txt automatically. Your existing source files are never modified.

If a CMakeLists.txt already exists it will be backed up to CMakeLists.backup.cmake.

Project Templates

Craft ships with built-in templates for common project types:

TemplateDescription
executableStandard executable (default)
static-libraryStatic library
shared-libraryShared library
header-onlyHeader-only library
craft project my_lib --template static-library
craft project my_lib --template static-library --lang c

Custom Templates

Save any project as a reusable template:

craft template save my_game_template
craft project new_game --template my_game_template

Global Configuration

Set global defaults that apply to all new projects:

craft config set defaults.language cpp
craft config set defaults.cpp_standard 17
craft config set defaults.template static-library

View your current configuration:

craft config list

Common Workflows

Starting a game with raylib

craft project my_game
cd my_game
craft add raylib
craft build
craft run

Creating a library with a demo executable

# Create the library
craft project my_lib --template static-library
cd my_lib
craft build

# Create the demo
cd ..
craft project my_demo
cd my_demo
craft add --path ../my_lib
craft build
craft run

Generating boilerplate files

craft gen utils.hpp    # generates include/utils.hpp
craft gen utils.cpp    # generates src/utils.cpp
craft gen math.h       # generates include/math.h
craft gen math.c       # generates src/math.c
  • Files are automatically placed in the source and include directories respectively
  • Source files include respective headers automatically

Keeping Craft Up to Date

craft upgrade

Next Steps