Build and Tooling

# GCC and Clang share almost all of their command-line interface.
$ gcc   -std=c23 -Wall -Wextra -o app main.c util.c
$ clang -std=c23 -Wall -Wextra -o app main.c util.c

# Separate compilation, which is what a real build does:
$ clang -std=c23 -Wall -Wextra -c main.c -o main.o
$ clang -std=c23 -Wall -Wextra -c util.c -o util.o
$ clang main.o util.o -o app -lm

# Useful stage-by-stage flags:
$ clang -E main.c            # preprocess only
$ clang -S main.c            # emit assembly
$ clang -c main.c            # compile to an object file
$ clang -MMD -MP -c main.c   # also write main.d, header dependencies for make

# Include paths, defines, libraries:
$ clang -std=c23 -Iinclude -DVERSION='"1.2.3"' -DNDEBUG \
        -Llib -lmylib -lm -o app main.c

# MSVC (Developer Command Prompt):
> cl /std:clatest /W4 /permissive- main.c util.c /Fe:app.exe

# Development / CI
CFLAGS = -std=c23 -Wall -Wextra -Werror -Wpedantic -Wshadow -Wconversion \
         -Wstrict-prototypes -Wmissing-prototypes -Wwrite-strings -Wvla \
         -Wcast-qual -Wformat=2 -Og -g -fsanitize=address,undefined

# Release
CFLAGS = -std=c23 -Wall -Wextra -O2 -DNDEBUG -D_FORTIFY_SOURCE=3 \
         -fstack-protector-strong -flto

CC      := clang
CFLAGS  := -std=c23 -Wall -Wextra -Werror -Og -g -MMD -MP -Iinclude
LDFLAGS :=
LDLIBS  := -lm

SRC := $(wildcard src/*.c)
OBJ := $(SRC:src/%.c=build/%.o)
DEP := $(OBJ:.o=.d)
BIN := build/app

.PHONY: all clean test asan
all: $(BIN)

$(BIN): $(OBJ)
	@mkdir -p $(dir $@)
	$(CC) $(LDFLAGS) $^ -o $@ $(LDLIBS)

build/%.o: src/%.c
	@mkdir -p $(dir $@)
	$(CC) $(CFLAGS) -c $< -o $@

asan: CFLAGS += -fsanitize=address,undefined
asan: LDFLAGS += -fsanitize=address,undefined
asan: clean all

test: $(BIN)
	./$(BIN) --self-test

clean:
	rm -rf build

-include $(DEP)

cmake_minimum_required(VERSION 3.21)   # CMAKE_C_STANDARD 23 needs 3.21
project(myapp VERSION 1.0.0 LANGUAGES C)

set(CMAKE_C_STANDARD 23)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_C_EXTENSIONS OFF)          # -std=c23, not -std=gnu23
set(CMAKE_EXPORT_COMPILE_COMMANDS ON) # writes compile_commands.json for clangd/clang-tidy

# A library, with its public headers declared for consumers.
add_library(mylib src/util.c src/parse.c)
target_include_directories(mylib PUBLIC include)
target_compile_options(mylib PRIVATE
    $<$<C_COMPILER_ID:GNU,Clang>:-Wall;-Wextra;-Wpedantic;-Wshadow;-Wconversion>
    $<$<C_COMPILER_ID:MSVC>:/W4>
)

# The executable.
add_executable(myapp src/main.c)
target_link_libraries(myapp PRIVATE mylib m)

# Sanitizers behind an option.
option(ENABLE_SANITIZERS "Build with ASan and UBSan" OFF)
if(ENABLE_SANITIZERS)
    target_compile_options(myapp PRIVATE -fsanitize=address,undefined -fno-omit-frame-pointer)
    target_link_options(myapp PRIVATE -fsanitize=address,undefined)
endif()

# Tests through CTest.
include(CTest)
add_executable(test_parse tests/test_parse.c)
target_link_libraries(test_parse PRIVATE mylib)
add_test(NAME parse COMMAND test_parse)

$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZERS=ON
$ cmake --build build -j
$ ctest --test-dir build --output-on-failure

# AddressSanitizer + UndefinedBehaviorSanitizer: the default pairing.
$ clang -std=c23 -g -O1 -fsanitize=address,undefined -fno-omit-frame-pointer -o app *.c
$ ASAN_OPTIONS=detect_leaks=1 UBSAN_OPTIONS=print_stacktrace=1 ./app

# ThreadSanitizer -- races and lock-order inversions. Mutually exclusive with ASan.
$ clang -std=c23 -g -fsanitize=thread -o app *.c && ./app

# MemorySanitizer -- uninitialized reads (Clang only; needs instrumented deps).
$ clang -std=c23 -g -fsanitize=memory -fPIE -pie -o app *.c

# Fail the build in CI instead of just printing:
$ clang -std=c23 -g -fsanitize=undefined -fno-sanitize-recover=all -o app *.c

# Valgrind: no rebuild, much slower, catches leaks and invalid accesses.
$ valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes ./app
$ valgrind --tool=helgrind ./app        # races
$ valgrind --tool=cachegrind ./app      # cache behavior

# GCC's built-in analyzer -- no extra tooling required.
$ gcc -std=c23 -fanalyzer -Wanalyzer-too-complex -c src/*.c

# Clang's analyzer.
$ clang --analyze -Xanalyzer -analyzer-output=text src/*.c
$ scan-build make                       # wraps a whole build, produces an HTML report

# clang-tidy: analysis plus modernization and naming checks.
$ clang-tidy -p build src/*.c \
    -checks='clang-analyzer-*,bugprone-*,cert-*,performance-*,readability-*'

# cppcheck: independent implementation, different findings. Worth running as well.
$ cppcheck --enable=all --std=c23 --inline-suppr --error-exitcode=1 -Iinclude src/

# Include-what-you-use: reports headers you include but do not need, and vice versa.
$ include-what-you-use -Iinclude src/main.c

$ clang-format --style=LLVM -i src/*.c include/*.h
$ clang-format --dump-config --style=GNU > .clang-format     # start from a named style
$ git diff -U0 --no-color | clang-format-diff -p1 -i         # format only what changed
$ clang-format --dry-run --Werror src/*.c                    # CI check

BasedOnStyle: LLVM
Language: Cpp
IndentWidth: 4
ColumnLimit: 100
PointerAlignment: Right
AlignAfterOpenBracket: Align
AllowShortIfStatementsOnASingleLine: false
BreakBeforeBraces: Linux
SortIncludes: CaseSensitive

# Build with debug info and no (or light) optimization.
$ clang -std=c23 -g3 -Og -o app *.c

# GDB
$ gdb ./app
(gdb) break main                # or  break util.c:42  /  break parse if depth > 3
(gdb) run --input data.txt
(gdb) next / step / finish / continue
(gdb) print *node               # print a struct through a pointer
(gdb) print array[0]@10         # print 10 elements
(gdb) ptype struct Node         # show a type's layout
(gdb) backtrace full            # frames with locals
(gdb) watch counter             # break when a value changes
(gdb) info locals / info registers
(gdb) x/16xb buffer             # examine 16 bytes in hex

# Post-mortem: enable cores, then load one.
$ ulimit -c unlimited && ./app          # crashes, writes a core
$ gdb ./app core

# LLDB (the same session, different syntax)
$ lldb ./app
(lldb) breakpoint set --name main
(lldb) run
(lldb) frame variable
(lldb) memory read --size 1 --format x --count 16 buffer

# rr: record once, then replay and step BACKWARDS. Invaluable for rare bugs.
$ rr record ./app && rr replay

/**
 * @file util.h
 * @brief Small utilities shared across the project.
 */

#ifndef PROJECT_UTIL_H
#define PROJECT_UTIL_H

#include <stddef.h>

/**
 * @brief Copies at most @p size bytes of @p source into @p destination.
 *
 * The result is always NUL-terminated, unlike strncpy.
 *
 * @param destination Buffer to write to; must not be null.
 * @param size        Size of @p destination in bytes, including the terminator.
 * @param source      NUL-terminated string to copy; must not be null.
 * @return The length of @p source, so a value >= @p size means the copy was
 *         truncated.
 * @warning Passing overlapping buffers is undefined behavior.
 * @see util_append
 */
size_t util_copy(char *destination, size_t size, const char *source);

#endif /* PROJECT_UTIL_H */

$ doxygen -g Doxyfile           # generate a default configuration
$ doxygen Doxyfile              # build the documentation into html/

$ clang-format --dry-run --Werror src/*.c include/*.h        # formatting
$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZERS=ON
$ cmake --build build -j                                     # -Werror build
$ ctest --test-dir build --output-on-failure                 # tests under sanitizers
$ for f in src/*.c; do                                       # static analysis
>   gcc -std=c23 -fanalyzer -Iinclude -c "$f" -o /dev/null || exit 1
> done
$ cppcheck --enable=all --std=c23 --error-exitcode=1 -Iinclude src/
$ clang-tidy -p build src/*.c