Carbon

You can’t unit test C, right?

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

Carbon is a testing library and 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).

Warning

Carbon is currently in an alpha quality stage, and is not production-ready yet.

Table of Contents

• Usage
  • Get the code
  • Example
• Code coverage
• Licensing
• References

Usage

Carbon can operate in both header-only and externally-linked (static or dynamic) modes, it’s just a matter of defining the CARBON_IMPLEMENTATION macro ONCE in our codebase.

Get the code

We can get Carbon in our preferred way of managing dependencies or external libraries in our projects. It’s important to do so via the OFFICIAL Git repository hosted on GitHub, and not through any other website or server. Appart from that, any ref can be checked out, being master (the trunk of all dev progress), a tagged commit (e.g. v1.0), an actively maintained version branch (e.g. v1.0.y/stable) or a LTS version branch (e.g. v1.0.y/lts) the preferred ones.

Here are the main options of obtaining it:

Git Submodule:

git submodule add https://github.com/sparky-game/carbon vendor/carbon

CMake FetchContent:

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

Pre-compiled Package:

You might want to take a look to the latest release available and download the appropriate pre-compiled package for your CPU’s architecture and OS.

Build from source:

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.

This custom build system can rebuild itself properly (using our preferred compilation flags), which means that you’ll only need to bootstrap it once:

cc src/make.c -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.
If compiled with `CARBON_MAKE_USE_SANITIZERS`, tests will run with sanitizers enabled.

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

Example

// example.c

#define CARBON_IMPLEMENTATION
#include <carbon.h>

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

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

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

cc -I vendor/carbon example.c -o example

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

$ ./example -h
usage: ./example [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 software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License Version 3 (GNU AGPL-3.0) as published by the Free Software Foundation (FSF) on November 19th 2007.
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 Affero General Public License Version 3 for more details.
For more information, see https://www.gnu.org/licenses/agpl-3.0.

As mentioned above, Carbon is licensed under the GNU’s AGPL-3.0-only, which means that any software created or that uses it is also subject to the same license. This implies that if you develop an application using Carbon, it must also be released as free software under the GNU’s AGPL-3.0-only. This ensures that the freedoms to use, study, modify and share the software are preserved for everyone.

If you prefer to release your game or application under a different, more commercially friendly license, there is an option available. You can purchase a copy of the Carbon Runtime Library Exception (Carbon RLE), which is in essence a GPL Exception, for you to use this library without releasing your software under GNU’s AGPL-3.0-only. Some key aspects of the Carbon RLE are the following:

• One-Time Purchase (OTP): Once obtaining a copy of the RLE, it lasts forever without expiration date.
• Project-specific: Each RLE is tied to a single project of yours.
• Version compatibility: Each RLE applies to a specific branch or major version of Carbon (e.g. v1.y), enabling you to update the library to a more up-to-date version with the same RLE.
• Professional support: You also gain access to more advanced support regarding the library, as well as a private channel to make high-priority requests such as bug fixes or security vulnerabilities.

For more details and to acquire a copy of the Carbon RLE, please visit https://carbonlib.org.

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
• Charm. (2024, November 8). charmbracelet/vhs: Your CLI home video recorder 📼 [Code]. GitHub. https://github.com/charmbracelet/vhs
• Alshahwan, N., Chheda, J., Finegenova, A., Gokkaya, B., Harman, M., Harper, I., Marginean, A., Sengupta, S., Wang, E. (2024, February 14). Automated Unit Test Improvement using Large Language Models at Meta [Paper]. arXiv, Cornell University. https://doi.org/10.48550/arXiv.2402.09171
• Matsumoto, M., Nishimura, T. (1998, January 1). Mersenne twister: a 623-dimensionally equidistributed uniform pseudo-random number generator [Paper]. Transactions on Modeling and Computer Simulation (TOMACS), Association for Computing Machinery (ACM). https://doi.org/10.1145/272991.272995
• Nishimura, T. (2000, October 1). Tables of 64-bit Mersenne twisters [Paper]. Transactions on Modeling and Computer Simulation (TOMACS), Association for Computing Machinery (ACM). https://doi.org/10.1145/369534.369540
• Matsumoto, M., Nishimura, T. (2004, September 29). A C-program for MT19937-64 (2004/9/29 version) [Code]. Department of Mathematics, Hiroshima University. http://www.math.sci.hiroshima-u.ac.jp/m-mat/MT/VERSIONS/C-LANG/mt19937-64.c