crame

A build tool for c projects, with a small testing framework.

• Rationale
• Installation
• How to use

Features

• Create a c project with a simple directory structure, main file, and test runner.
• Automatically initializes a git repository.
• Dependency free test runner.
• Build, run, test, watch, and add code modules with Just.

Planned features

• Move builder, runner, tester, and watcher out of justfile and into the application.
• Configurable build options.
• Add code modules with tests already setup.

Rationale

This CLI tool is intended to give a Cargo-like experience for simple c projects. It's primary goals are to reduce the tedium of writing a makefile, adding and running tests, and adding additional source files with proper include guards.

The framework currently relies on Just for most of its functionality. The basis of this application is the justfile.

Why write it in Rust?

As the project is inspired by Cargo and other modern development tools, it seems natural to use Rust and its plethora of CLI libraries.

Installation

Prerequisites

crame projects currently use Just as their main build tool and test runner. The justfile is also dependent on fd and requires watchexec for file watching.

A c compiler linked to the cc executable is also required.

Cargo

If you're a Rust programmer, crame can be installed with cargo.

cargo install crame

Building

crame is written in Rust, so you'll need to grab a Rust installation in order to compile it.

To build crame:

git clone https://github.com/sonro/crame
cd crame
cargo build --release
./target/release/crame

How to use

Create a project

Using crame new creates a project in the specified directory. Automatically intializes a git repository, unless the directory is already within one, or the --vcs option is set to none.

crame new my-project

Resulting directory structure:

my-project
├── Crame.toml
├── justfile
├── lib
├── src
│   └── main.c
└── tests
    ├── run.c
    ├── test_all.c
    └── unit
        └── it_works.c

Building and running

Build the program as an executable in the target/ directory.

just build

Build the program and then run it.

just run

The justfile will add all the .c files in src/ and lib/ as arguments for the c compiler. It doesn't need to be kept up to date as with a makefile.

Adding modules

Use just add-module to create .c and .h files in the src directory.

just add-module my_module

Resulting files:

// src/my_module.h
#ifndef MY_PROJECT_MY_MODULE_H
#define MY_PROJECT_MY_MODULE_H

#endif

// src/my_module.c
#include "my_module.h"

Testing

Test files must have the follwing layout:

#if defined HEADERS
// include all headers in this section
#elif defined TESTS
// create tests in this section
#endif

Add a unit test in tests/unit/. Use the TEST macro to specify a test name and function and the ASSERT macro to test a Boolean value.

// tests/unit/my_test.c
#if defined HEADERS
#include "../../src/my_module.h"
#elif defined TESTS

TEST("test name") {
    ASSERT(1 + 1 == 2);
}

#endif

Include your test files in tests/test_all.c.

// tests/test_all.c
#include "unit/my_test.c"
...

Build and run all tests with

just test

This builds all .c files in the src/, lib/ and tests/ directories.

License

crame is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.