Get started

Below is a quick guide for installing C Traceback into your project.

Building Examples

Before putting C Traceback into your project, you can first try the examples. Simply follow the steps below.

Note: CMake is required for building examples.

Install CMake if needed

On Linux:


sudo apt update
sudo apt install cmake

Clone C Traceback


git clone https://github.com/c-modules/c_traceback

Build the examples


cd c_traceback
cmake -B build -S . -DBUILD_EXAMPLES=ON
cmake --build build

Run the examples

We have provided many examples. Simply pick one and run. For example,


cd build/
./example/example

Output

The actual output depends on your environment. You should see something similar to this:


────────────────────────────────────────────────────────────────────────────────
Traceback (most recent call last):
(#00) File "/home/alvinng/Desktop/c_traceback/examples/example.c", line 20 in main:
    do_calculation(vec)
(#01) File "/home/alvinng/Desktop/c_traceback/examples/example.c", line 39 in do_calculation:
    division_vec(vec, 0)
(#02) File "/home/alvinng/Desktop/c_traceback/examples/example.c", line 56 in division_vec:
    <Error thrown here>
ValueError: Denominator must be nonzero! Received: 0.000000
────────────────────────────────────────────────────────────────────────────────

Setting up a simple project

Adding C Traceback to your project is simple. However, the actual setup depends on your directory structure. For demonstration, let’s setup a simple project together:

- project.c
- CMakeLists.txt

project.c has the following contents:


#include <stdio.h>
#include "c_traceback.h"
 
int main(void)
{
    ctb_print_compilation_info();
    return 0;
}

To compile the project, you can use either CMake or just a C compiler. For compiler, we will use gcc as an example.

gcc

Simply run the following commands


gcc -Ic_traceback/include project.c c_traceback/src/*.c -o project
./project

Output

Either way, you should see the following output:


───────────────────────── C Traceback Compilation Info ─────────────────────────
      %%%%%%%%%%%%        C Traceback Version: Unknown
    %%%%%%%%%%%%%%%%      Operating System: Linux
   %%%%%%%%%%%%%%%%%%     Build Date: Jan  4 2026 18:14:12
  %%%%%%%%%%*  %%%%%%%    Compiler: GCC (version: 13)
  %%%%%%%*     %%%%%%%    
  %%%%%*       %%%%%%%    Config
  %%%%%%%*     %%%%%%%    ──────
  %%%%%%%%%%*  %%%%%%%    Max Call Stack Depth: 32
   %%%%%%%%%%%%%%%%%%     Max Error Message Length: 256
    %%%%%%%%%%%%%%%%      Max Number of Errors: 16
      %%%%%%%%%%%%        Default Terminal Width: 80
                          Default File Width: 120
                          Horizontal Rule Max Width: 120
                          Horizontal Rule Min Width: 50
 
Logging (example)
─────────────────
Error: File "c_traceback/src/traceback.c", line 602 in ctb_print_compilation_info:
   Sample error for compilation info
UserWarning: File "c_traceback/src/traceback.c", line 603 in ctb_print_compilation_info:
   Sample warning for compilation info
Message: File "c_traceback/src/traceback.c", line 604 in ctb_print_compilation_info:
   Sample info for compilation info
 
Traceback (example)
───────────────────
Traceback (most recent call last):
  (#00) File "example/example.c", line 10 in main:
    hello_world();
  (#01) File "example/hello_world.c", line 25 in check_terminal:
    data = compute(data)
  (#02) File "example/libs/utils.c", line 50 in compute:
    recursion()
 
      [... Skipped 123 frames ...]
 
  (#127) File "example/libs/utils.c", line 75 in recursion:
    <error thrown here>
Error: Something went wrong!
───────────────────────────────────── END ──────────────────────────────────────

Wrap up

Congrats!🥳 You have successfully built a project with C Traceback. For detailed usage of C Traceback, please try our tutorial!