The second revision (#8)

Author: habedi

.editorconfig

@@ -21,12 +21,13 @@ max_line_length = 100
 max_line_length = 120
 trim_trailing_whitespace = false # Don't remove trailing whitespace in Markdown files
 
-# Bash scripts
-[*.sh]
-indent_size = 2
-
 # YAML files
 [*.{yml,yaml}]
 indent_size = 2
 
+# Bash files
+[*.{sh,bash}]
+indent_size = 2
+indent_style = tab
+max_line_length = 100
 

.gitignore

@@ -137,6 +137,11 @@ temp/
 poetry.lock
 
 # Additional files and directories to ignore (put below)
-doc/html
+doc
 target
 *.log\.*
+profile_report.txt
+perf.data
+*.old
+*.folded
+*.perf

Doxyfile

@@ -15,6 +15,7 @@ INPUT              = .
 FILE_PATTERNS      = *.c *.h *.cpp *.hpp
 RECURSIVE          = YES
 EXTRACT_ALL        = YES
+EXCLUDE_PATTERNS   = tmp
 
 #---------------------------------------------------------------------------
 # Output formats

Makefile

@@ -1,64 +1,84 @@
+# General Variables
+SHELL := bash
+
 # Build configuration
 CC ?= clang
 ENABLE_ASAN ?= 0
 BUILD_TYPE ?= debug
-CFLAGS := -Wall -Wextra -pedantic -std=c11 -Iinclude
-LDFLAGS :=
-LIBS :=
 
 # Directories
-BIN_DIR := bin
-TEST_DIR := test
-INC_DIR := include
-DOC_DIR := doc
+BIN_DIR    := bin
+TEST_DIR   := test
+INC_DIR    := include
+DOC_DIR    := doc
+ASSET_DIR := assets
+
+# Flags
+CFLAGS_BASE := -Wall -Wextra -pedantic -std=c11 -I$(INC_DIR)
+LDFLAGS :=
+LIBS      :=
 
 # Sanitizer configuration
 ifeq ($(ENABLE_ASAN),1)
-  CFLAGS += -fsanitize=address
-  LDFLAGS += -fsanitize=address
+  CFLAGS_SAN := -fsanitize=address
+  LDFLAGS   += -fsanitize=address
   export ASAN_OPTIONS=verbosity=0:detect_leaks=1:log_path=asan.log
 endif
 
 # Build type configuration
 ifeq ($(BUILD_TYPE),release)
-  CFLAGS += -O2 -DNDEBUG
+  CFLAGS_TYPE := -O2 -DNDEBUG
 else
-  CFLAGS += -g -O0
+  CFLAGS_TYPE := -g -O0
 endif
 
-# Test and benchmark binaries
-TEST_BINARY := $(BIN_DIR)/test_bptree
-BENCH_BINARY := $(BIN_DIR)/bench_bptree
+# Combine flags
+CFLAGS := $(CFLAGS_BASE) $(CFLAGS_SAN) $(CFLAGS_TYPE)
+
+# Binary names
+TEST_BINARY    := $(BIN_DIR)/test_bptree
+BENCH_BINARY   := $(BIN_DIR)/bench_bptree
 EXAMPLE_BINARY := $(BIN_DIR)/example
 
+# Default target
 .DEFAULT_GOAL := help
 
 .PHONY: help
-help: ## Show the targets and their descriptions
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; \
- 	{printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+help: ## Show available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+	awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
 
 $(BIN_DIR):
 	mkdir -p $(BIN_DIR)
 
+##############################################################################################################
+## Pattern Rule for Building Binaries
+##############################################################################################################
+# This rule compiles a C file in the TEST_DIR into a binary in BIN_DIR
+$(BIN_DIR)/%: $(TEST_DIR)/%.c | $(BIN_DIR)
+	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS) $(LIBS)
+
+##############################################################################################################
+## Conventional Targets
+##############################################################################################################
+
 .PHONY: all
-all: clean doc test bench example ## Build all targets and run tests and benchmarks
+all: clean test bench example doc ## Build everything, run tests, benchmarks, and generate docs
 
 .PHONY: test
 test: $(TEST_BINARY) ## Build and run tests
 	@echo "Running tests..."
 	./$(TEST_BINARY)
 
-$(TEST_BINARY): $(TEST_DIR)/test_bptree.c $(INC_DIR)/bptree.h | $(BIN_DIR)
-	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS) $(LIBS)
-
 .PHONY: bench
 bench: $(BENCH_BINARY) ## Build and run benchmarks
 	@echo "Running benchmarks..."
 	./$(BENCH_BINARY)
 
-$(BENCH_BINARY): $(TEST_DIR)/bench_bptree.c $(INC_DIR)/bptree.h | $(BIN_DIR)
-	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS) $(LIBS)
+.PHONY: example
+example: $(EXAMPLE_BINARY) ## Run example program
+	@echo "Running the example..."
+	./$(EXAMPLE_BINARY)
 
 .PHONY: clean
 clean: ## Remove build artifacts
@@ -68,7 +88,7 @@ clean: ## Remove build artifacts
 .PHONY: format
 format: ## Format source code
 	@echo "Formatting source code..."
-	@command -v clang-format >/dev/null 2>&1 || { echo >&2 "clang-format not found."; exit 1; }
+	@command -v clang-format >/dev/null 2>&1 || { echo "clang-format not found."; exit 1; }
 	clang-format -i $(TEST_DIR)/*.c $(INC_DIR)/*.h
 
 .PHONY: lint
@@ -77,8 +97,8 @@ lint: ## Run linter checks
 	cppcheck --enable=all --inconclusive --quiet --std=c11 -I$(INC_DIR) $(TEST_DIR)
 
 .PHONY: install
-install: ## Install header file
-	@echo "Installing bptree.h system-wide..."
+install: ## Install header file system-wide
+	@echo "Installing bptree.h..."
 	install -d /usr/local/include
 	install -m 0644 $(INC_DIR)/bptree.h /usr/local/include/
 
@@ -88,10 +108,11 @@ uninstall: ## Remove installed header file
 	rm -f /usr/local/include/bptree.h
 
 .PHONY: install-deps
-install-deps: ## Install development dependencies (for Debian-based systems)
+install-deps: ## Install development dependencies (Debian-based)
 	@echo "Installing development dependencies..."
 	sudo apt-get update && sudo apt-get install -y \
-		gcc gdb clang clang-format cppcheck valgrind
+		gcc gdb clang clang-format clang-tools cppcheck valgrind graphviz \
+		kcachegrind graphviz linux-tools-common linux-tools-generic linux-tools-$(shell uname -r)
 
 .PHONY: coverage
 coverage: CFLAGS += -fprofile-arcs -ftest-coverage
@@ -103,33 +124,76 @@ coverage: clean $(TEST_BINARY) ## Generate code coverage report
 	gcov -o $(BIN_DIR) $(TEST_DIR)/test_bptree.c
 	@echo "Coverage report generated"
 
-.PHONY: memcheck
-memcheck: $(EXAMPLE_BINARY) $(TEST_BINARY) $(BENCH_BINARY) ## Run memory checks with Valgrind
-	@echo "Running memory checks..."
-	@echo "Running example with Valgrind..."
-	valgrind --leak-check=full --show-leak-kinds=all ./$(EXAMPLE_BINARY)
-	@echo "Running tests with Valgrind..."
-	valgrind --leak-check=full --show-leak-kinds=all ./$(TEST_BINARY)
-	@echo "Running benchmarks with Valgrind..."
-	valgrind --leak-check=full --show-leak-kinds=all ./$(BENCH_BINARY)
-	@echo "Valgrind checks completed"
-
 .PHONY: doc
-doc: ## Generate documentation
+doc: ## Generate documentation using Doxygen
 	@echo "Generating documentation..."
 	@test -f Doxyfile || { echo "Error: Doxyfile not found."; exit 1; }
 	doxygen Doxyfile
 
-.PHONY: example
-example: $(EXAMPLE_BINARY) ## Run examples
-	@echo "Running the example..."
-	./$(EXAMPLE_BINARY)
+.PHONY: figure
+figure: ## Generate figures using Graphviz
+	@echo "Generating figures..."
+	@$(SHELL) $(ASSET_DIR)/make_figures.sh $(ASSET_DIR)
 
-$(EXAMPLE_BINARY): $(TEST_DIR)/example.c $(INC_DIR)/bptree.h | $(BIN_DIR)
-	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS) $(LIBS)
+##############################################################################################################
+## Release and Debugging Targets
+##############################################################################################################
 
 .PHONY: release
 release: BUILD_TYPE=release
-release: all ## Build everything in release mode (optimized)
-	@echo "Building in release mode..."
-	@$(MAKE) all
+release: all ## Like 'all', but builds with code optimizations
+	@echo "Built in release mode."
+
+.PHONY: memcheck
+memcheck: $(EXAMPLE_BINARY) $(TEST_BINARY) $(BENCH_BINARY) ## Run Valgrind memory checks
+	@echo "Running Valgrind memory checks..."
+	valgrind --leak-check=full --show-leak-kinds=all ./$(EXAMPLE_BINARY)
+	valgrind --leak-check=full --show-leak-kinds=all ./$(TEST_BINARY)
+	valgrind --leak-check=full --show-leak-kinds=all ./$(BENCH_BINARY)
+	@echo "Valgrind checks completed"
+
+.PHONY: profile
+profile: CFLAGS += -pg
+profile: LDFLAGS += -pg
+profile: clean $(BENCH_BINARY) ## Build and run with gprof profiling
+	@echo "Running profiling (gprof)..."
+	./$(BENCH_BINARY)
+	gprof $(BENCH_BINARY) gmon.out > profile_report.txt
+	@echo "Profile report saved as profile_report.txt"
+
+.PHONY: ubsan
+ubsan: CFLAGS += -fsanitize=undefined
+ubsan: LDFLAGS += -fsanitize=undefined
+ubsan: clean $(TEST_BINARY) ## Run tests with UndefinedBehaviorSanitizer
+	@echo "Running UBSan tests..."
+	UBSAN_OPTIONS=print_stacktrace=1 ./$(TEST_BINARY)
+
+.PHONY: analyze
+analyze: ## Run Clang Static Analyzer
+	@echo "Running Clang Static Analyzer..."
+	scan-build --status-bugs $(MAKE) clean all
+
+.PHONY: perf
+perf: $(BENCH_BINARY) ## Profile using Linux perf
+	@echo "Recording perf data..."
+	@echo "If necessary, run: sudo sh -c 'echo 1 > /proc/sys/kernel/perf_event_paranoid'"
+	perf record -g ./$(BENCH_BINARY)
+	@echo "Launching perf report..."
+	perf report
+
+.PHONY: callgrind
+callgrind: $(BENCH_BINARY) ## Profile using Valgrind's callgrind
+	valgrind --tool=callgrind --callgrind-out-file=callgrind.out ./$(BENCH_BINARY)
+	@echo "Callgrind output saved to callgrind.out"
+	@echo "Use 'kcachegrind callgrind.out' to visualize"
+
+.PHONY: cachegrind
+cachegrind: $(BENCH_BINARY) ## Profile CPU cache usage using Valgrind's cachegrind
+	valgrind --tool=cachegrind --cachegrind-out-file=cachegrind.out ./$(BENCH_BINARY)
+	@echo "Cachegrind output saved to cachegrind.out"
+	@echo "Use 'cg_annotate cachegrind.out' to read the report"
+
+.PHONY: trace
+trace: $(BENCH_BINARY) ## Trace syscalls using strace
+	strace -o trace.log -T -tt ./$(BENCH_BINARY)
+	@echo "Syscall trace saved to trace.log"