Maki

Maki is a small CLI tool for bootstrapping modern C++ projects on macOS and Linux.

It was created to make starting a terminal-first C++ project feel closer to tools such as Angular's ng new: choose a project name, generate a sensible starting structure, and then continue using the standard C++ toolchain directly.

Maki does not replace CMake, Ninja, Clang, or Git. It creates the project structure and configuration needed to get started quickly and then gets out of the way.

Features

Maki supports:

• Creating new C++ projects with maki new <name>
• Project name validation
• Dry-run previews without writing files
• Optional Git repository initialization
• CMake project generation
• CMake presets configured for Clang and Ninja
• C++23 by default
• Debug build preset
• compile_commands.json generation for tools such as clangd
• macOS and Linux

Generated Project

Running:

maki new MyProject

creates:

MyProject/
├── .gitignore
├── CMakeLists.txt
├── CMakePresets.json
├── include/
└── src/
    └── main.cpp

The generated project uses:

• Clang / Clang++
• CMake
• Ninja
• C++23

The generated CMakePresets.json includes a debug preset and enables CMAKE_EXPORT_COMPILE_COMMANDS.

Installation

Homebrew

Homebrew is the recommended installation method on macOS.

Install Maki directly from the PixelBrewer tap:

brew install PixelBrewer/tap/maki

Verify the installation:

maki --help

Homebrew can then be used to upgrade Maki when a new version is published:

brew update
brew upgrade maki

Arch Linux / AUR

Coming soon: Maki will be available through the Arch User Repository (AUR).

Once the AUR package is published, installation instructions will be added here.

Manual Installation

Prebuilt self-contained binaries are also available from the GitHub Releases page.

Release builds are available for:

• Linux x64
• macOS Apple Silicon
• macOS Intel

Because Maki is published as a self-contained .NET application, the .NET runtime or SDK is not required to use a release build.

Linux x64

Download the linux-x64 archive from the latest GitHub release.

For example, for v0.1.0:

tar -xzf maki-v0.1.0-linux-x64.tar.gz

Move the executable somewhere on your PATH:

sudo mv maki /usr/local/bin/maki

Verify the installation:

maki --help

macOS — Apple Silicon

Download the osx-arm64 archive from the latest GitHub release.

For example, for v0.1.0:

tar -xzf maki-v0.1.0-osx-arm64.tar.gz

Move the executable somewhere on your PATH:

sudo mv maki /usr/local/bin/maki

Verify the installation:

maki --help

macOS — Intel

Download the osx-x64 archive from the latest GitHub release.

For example, for v0.1.0:

tar -xzf maki-v0.1.0-osx-x64.tar.gz

Move the executable somewhere on your PATH:

sudo mv maki /usr/local/bin/maki

Verify the installation:

maki --help

macOS Gatekeeper

Maki is not currently notarized with Apple. macOS may therefore prevent a manually downloaded release from opening.

If macOS reports that it cannot verify Maki, remove the quarantine attribute from the extracted executable:

xattr -d com.apple.quarantine maki

Then move it onto your PATH:

sudo mv maki /usr/local/bin/maki

and verify:

maki --help

Prerequisites

Maki itself does not require the .NET SDK when installed through Homebrew or from a GitHub Release.

The C++ projects generated by Maki expect the following tools to be available on your PATH:

• Clang
• CMake
• Ninja

Git is optional and is only required when using the --git option.

Arch Linux

Install the C++ toolchain with:

sudo pacman -S clang cmake ninja git

Git can be omitted if you do not intend to use --git.

macOS

Using Homebrew:

brew install llvm cmake ninja

Git is available through the Xcode Command Line Tools and can also be installed through Homebrew.

Make sure clang, clang++, cmake, and ninja are available on your PATH before configuring a generated project.

Usage

Create a new project:

maki new MyProject

Maki will generate the project and display the commands needed to configure and build it.

Dry Run

Preview the project without writing anything to disk:

maki new MyProject --dry-run

For example:

Project: MyProject

Directories
 /home/user/projects/MyProject
 /home/user/projects/MyProject/src
 /home/user/projects/MyProject/include

Files
 /home/user/projects/MyProject/CMakeLists.txt
 /home/user/projects/MyProject/CMakePresets.json
 /home/user/projects/MyProject/.gitignore
 /home/user/projects/MyProject/src/main.cpp

No files were written.

Initialize Git

Maki can initialize a Git repository after generating the project:

maki new MyProject --git

Git initialization is optional. Without --git, Maki will not create a Git repository.

Help

Display the available commands:

maki --help

Display help for maki new:

maki new --help

Building a Generated Project

Once Maki creates a project:

cd MyProject

Configure it using the generated debug preset:

cmake --preset debug

Build it:

cmake --build --preset debug

Run the resulting executable:

./build/debug/MyProject

A newly generated application prints:

Hello, World!

Maki's responsibility ends after project generation. Building and managing the project remains the responsibility of standard C++ tooling such as CMake and Ninja.

clangd

The generated debug preset enables:

CMAKE_EXPORT_COMPILE_COMMANDS

After configuring the project:

cmake --preset debug

CMake generates:

build/debug/compile_commands.json

This provides compilation information that can be consumed by tools such as clangd and editors that integrate with it.

Running From Source

Building Maki itself from source requires the .NET 10 SDK.

Clone the repository:

git clone https://github.com/PixelBrewer/Maki.git
cd Maki

Restore dependencies:

dotnet restore Maki.slnx

Build:

dotnet build Maki.slnx

Run the tests:

dotnet test Maki.slnx

Run Maki directly:

dotnet run --project src/Maki.Cli -- new MyProject --dry-run

Maki Project Structure

Maki itself is organized into a CLI, a Core library, and a test project:

Maki/
├── src/
│   ├── Maki.Cli/
│   └── Maki.Core/
└── tests/
    └── Maki.Tests/

Maki.Cli

Contains the command-line interface, Spectre.Console integration, command definitions, and terminal rendering.

Maki.Core

Contains the core project-generation functionality, including project planning, validation, templates, filesystem writing, and Git initialization.

Maki.Tests

Contains the NUnit test suite for Maki's core behavior.

Philosophy

Maki deliberately has a narrow scope.

Starting a small C++ project from a terminal-based development environment can involve a surprising amount of repetitive setup: creating the directory structure, writing the initial CMake configuration, configuring a generator and compiler, enabling compile commands, and creating the initial source files.

Maki handles that initial setup and then gets out of the way.

maki new MyProject
        │
        ▼
 C++ project scaffold
        │
        ▼
Clang + CMake + Ninja

Maki is not intended to replace:

• CMake
• Ninja
• a C++ package manager
• a compiler
• an IDE or editor
• Git

Instead, it provides an opinionated starting point for those tools.

Current Scope

Maki v0.1.0 intentionally focuses on a small set of defaults:

• C++23
• Clang
• CMake
• Ninja
• Executable projects
• Debug CMake preset
• macOS
• Linux

Additional templates and configuration options may be considered in future releases, but Maki's goal is to remain focused on quickly creating useful C++ project scaffolds.

Distribution

Maki is currently distributed through:

• GitHub Releases
• Homebrew via PixelBrewer/tap

Arch Linux distribution through the AUR is in progress.

Technology

Maki is built with:

• C#
• .NET 10
• Spectre.Console
• Spectre.Console.Cli
• NUnit
• AwesomeAssertions
• GitHub Actions

Contributing

Maki is a small project, but contributions, bug reports, and suggestions are welcome.

If you encounter a problem or have an idea for improving the project, open an issue on GitHub.

For code contributions, fork the repository, create a branch, make your changes, and open a pull request.

Please make sure the test suite passes before submitting changes:

dotnet test Maki.slnx

License

Maki is licensed under the MIT License. See LICENSE for details.