Running CST

How to compile and run CST

Compiling

To use CST, you must compile your project and test sources together. Let’s suppose you have a project with the following structure:

• src/: All project source files.

• test/: All test files for your project.

This is the recommended layout for most projects. In this guide, we’ll use src/*.c for the main sources and test/*.c for the tests.

In all examples, the output binary will be named test_run (Set using the -o test_run flag).

Note: CST defines its own main() function. Do not include any source file that defines a main() function when compiling your test runner, as it will cause a redefinition error.

If you really need to include a file with a main() function (For example, main.c also contains helper functions you want to test), you can use this workaround to avoid conflicts.

With a system-wide installation

If you have installed CST system-wide, you can simply link it using:

gcc src/*.c test/*.c -lcst -o test_run

Without installation

If you cloned CST’s repository locally (for example via git submodule), you can compile it manually.

This assumes CST is in a directory named cst/ at your project root:

gcc src/*.c test/*.c cst/src/*.c -Icst/src -o test_run

We include cst/src in the include path (-Icst/src) to make cst.h visible to our test files.

About Valgrind

CST is 100% compatible with Valgrind. To use it, just run the compiled executable with something like valgrind ./test_run. Due to how CST works, each test is executed on a new process, so you will get isolated valgrind results per test, this way you know exactly which tests are failing or where the memory leaks are located.

Valgrind may show you functions named __cst_fn_N, where N is the test number. This is because tests need an actual function in order to be executed, so the TEST macro creates one with this format under the hood. Specific details about how this works are provided here.

Main redefinition workaround

If you REALLY want to include a file that defines a main() function for whatever reason, most likely that you have other functions to test in said file besides the main function. Then you can use this trick:

Compile the test runner with a flag like -DTESTING to avoid defining main if TESTING is defined.

main.c

// Other functions you want to test
int add(int a, int b) {
    return a + b;
}

#ifndef TESTING
int main(void) {
    // Your awesome code
}
#endif