Carbon

You can’t unit test C, right?

Carbon helps you write better C/C++ tests. 🙂

Carbon is a testing framework that focuses on being lightweight and straightforward, giving the best possible development experience. Whether you work on GNU/Linux, BSDs, Windows or macOS, if you write C/C++ code, Carbon can help you.

The above example was generated with VHS (source code).

Table of Contents

• Usage
  • Get the code
  • Target code
  • Test case
  • Entrypoint
• Code coverage
• Licensing
• References

Usage

Get the code

We can get Carbon in our preferred way of managing dependencies or external libraries in our projects. Here are the main options of obtaining the library:

Git Submodules:

git submodule add https://github.com/sparky-game/carbon vendor/carbon
cd vendor/carbon && git switch -d v0.8-alpha

CMake FetchContent:

include(FetchContent)
FetchContent_Declare(
  carbon
  GIT_REPOSITORY "https://github.com/sparky-game/carbon"
  GIT_TAG        v0.8-alpha
  GIT_PROGRESS   TRUE
)
FetchContent_MakeAvailable(carbon)

Pre-compiled Package:

wget https://github.com/sparky-game/carbon/releases/download/v0.8-alpha/carbon-0.8-linux-amd64.tgz
tar -xvf carbon-0.8-linux-amd64.tgz

If wanted to build Carbon from source independently (i.e. without defining CARBON_IMPLEMENTATION in your code), it can be done without any problems. We use a custom make utility (which uses Carbon under the hood) as our build system to manage testing, compiling and packaging the library.

cc -std=c99 -Wall -Wextra -pipe -Os src/make.c -static -s -o make

Once built, we can take a look at the available subcommands:

$ ./make help
usage: ./make [SUBCMD]
Subcommands:
  help        display this help
  clean       remove previously created build artifacts
  mrproper    same as `clean` plus remove this binary
  check       only run tests

If not provided any subcommand, it runs the full build pipeline.

Report bugs to: <https://github.com/sparky-game/carbon/issues>
SPARKY Carbon homepage: <https://github.com/sparky-game/carbon>

Target code

// x.h

#pragma once

void inc_int(int *x) {
  ++(*x);
}

Test case

// x_test.c

#include <carbon.h>
#include "x.h"

CARBON_TEST(x, inc_int) {
  int a = 1, b = 0;
  carbon_should_not_be(a, b);
  inc_int(&b);
  carbon_should_be(a, b);
  return CARBON_OK;
}

Entrypoint

// carbon.c

#define CARBON_IMPLEMENTATION
#include <carbon.h>

int main(void) {
  return CARBON_RUN_ALL();
}

If we define the macro CARBON_IMPLEMENTATION, it makes the library operate in a header-only structure: all the internal source code of Carbon is included in that translation unit, i.e. no need to compile and link it separately. Alternatively, one can link with the library’s internal source code either compiling it ourselves, or using a pre-compiled package of the latest release available.

cc -I vendor/carbon -std=c99 -Wall -Wextra -pipe -Os *.c -o carbon

Once built, we can take a look at the available options:

$ ./carbon -h
usage: ./carbon [OPTION]
Options:
  -n, --no-output  disable JUnit XML test results output
  -o, --output     output JUnit XML test results to specific file (default: `carbon_results.xml`)
  -h, --help       display this help and exit
  -v, --version    output version information and exit

Report bugs to: <https://github.com/sparky-game/carbon/issues>
SPARKY Carbon homepage: <https://github.com/sparky-game/carbon>

Code coverage

Code or test coverage is a metric which measures the amount of source code getting executed when a test suite is run. It’s important to mention that this measurement doesn’t relate by any means to the quality of the codebase, it just reflects how complete and thorough a specific test suite is, nothing more.

Nevertheless, it’s a nice metric to have, and it’s important that Carbon supports it. As we’re working with C/C++, the most used tool for the job is gcov. When using the --coverage flag, it passes to the compiler/linker specific flags to produce certain code instrumentation.

• The *.gcno notes files are generated when the source files are compiled with the -ftest-coverage option (contained inside the --coverage flag). It contains information to reconstruct the basic block graphs and assign soure line numbers to blocks.
• The *.gcda count data files are generated when a program linked with -lgcov option (contained inside the --coverage flag) containing object files built with the -fprofile-arcs option (contained inside the --coverage flag) is executed. It contains arc transition counts, value profile counts and some summary information.

They shouldn’t be accessed manually, but with gcov itself, using one of its formatting options, e.g. --json-format.

Licensing

Copyright (C) Wasym A. Alonso. All Rights Reserved.

Carbon is free and open-source sofware (FOSS) and available under 2 licenses, when using it choose whichever you prefer.

BSD 3-Clause “New” or “Revised” License ( COPYING.BSD ):

Carbon is free software: you can redistribute it and/or modify it under the terms of the BSD 3-Clause “New” or “Revised” License (BSD-3-Clause) as published by The Regents of the University of California.
Carbon is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the BSD 3-Clause “New” or “Revised” License (BSD-3-Clause) for more details.
You should have received a copy of the BSD 3-Clause “New” or “Revised” License (BSD-3-Clause) along with Carbon. If not, see https://opensource.org/license/BSD-3-Clause.

GNU General Public License v3.0 only ( COPYING.GPL ):

Carbon is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 only (GPL-3.0-only) as published by the Free Software Foundation (FSF).
Carbon is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License v3.0 only (GPL-3.0-only) for more details.
You should have received a copy of the GNU General Public License v3.0 only (GPL-3.0-only) along with Carbon. If not, see https://www.gnu.org/licenses/gpl-3.0.

References

• Benno Rice. (2018, January 23). You Can’t Unit Test C, Right? [Video]. YouTube. https://www.youtube.com/watch?v=z-uWt5wVVkU
• Alexey Kutepov. (2023, June 30). tsoding/nn.h: Simple stb-style header-only library for Neural Networks [Code]. GitHub. https://github.com/tsoding/nn.h
• Alexey Kutepov. (2024, November 5). tsoding/nob.h: Next generation of the NoBuild idea [Code]. GitHub. https://github.com/tsoding/nob.h
• Daniel Holden. (2021, April 16). orangeduck/Cello: Higher level programming in C [Code]. GitHub. https://github.com/orangeduck/Cello
• Sean Barrett. (2015, June 7). Advice for Writing Small Programs in C [Video]. YouTube. https://www.youtube.com/watch?v=eAhWIO1Ra6M