feat: Context APIs and the related Settings API

.github/workflows/ci.yml

@@ -46,5 +46,10 @@ jobs:
         run: |
           which make
           make --version
-      - name: Run tests
+
+      - name: Run tests (debug build)
         run: make test
+
+      - name: Run tests (debug build, with sanitizers)
+        if: runner.os != 'Windows'
+        run: make test-san

.gitignore

@@ -1,5 +1,5 @@
 /build
-/include/c2pa.h
+/target
 
 _deps
 # CMake files
@@ -16,4 +16,4 @@ CMakeLists.txt.user
 .vscode
 # Mac OS X files
 .DS_Store
-.idea
+.idea

CMakeLists.txt

@@ -21,7 +21,7 @@ set(C2PA_VERSION "0.75.19")
 
 set(CMAKE_POLICY_DEFAULT_CMP0135 NEW)
 set(CMAKE_C_STANDARD 17)
-set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_OSX_DEPLOYMENT_TARGET "13.3")
 
 if(MSVC)
@@ -46,6 +46,64 @@ else()
     add_compile_options(-Wall -Wextra -Werror)
 endif()
 
+# Sanitizers (for debug/verification builds)
+option(ENABLE_SANITIZERS "Enable AddressSanitizer, UndefinedBehaviorSanitizer, and LeakSanitizer" OFF)
+option(ENABLE_MSAN "Enable MemorySanitizer (mutually exclusive with ASAN)" OFF)
+
+if(ENABLE_SANITIZERS AND ENABLE_MSAN)
+    message(FATAL_ERROR "ENABLE_SANITIZERS and ENABLE_MSAN are mutually exclusive - choose one")
+endif()
+
+if(ENABLE_SANITIZERS)
+    if(MSVC)
+        message(WARNING "Sanitizers are not supported with MSVC in this configuration")
+    elseif(WIN32)
+        # MinGW on Windows doesn't have sanitizer libraries available
+        message(WARNING "Sanitizers are not available on Windows with MinGW - skipping sanitizer build")
+    else()
+        # AddressSanitizer, UndefinedBehaviorSanitizer, and LeakSanitizer for GCC/Clang
+        # Note: LeakSanitizer is not supported on macOS (both x86_64 and ARM64)
+        # On Linux, LeakSanitizer is integrated with AddressSanitizer
+        if(APPLE)
+            add_compile_options(-fsanitize=address,undefined -fno-omit-frame-pointer -g)
+            add_link_options(-fsanitize=address,undefined)
+            message(STATUS "Sanitizers enabled on macOS: ASAN and UBSAN (LSan not supported on macOS)")
+        else()
+            add_compile_options(-fsanitize=address,undefined,leak -fno-omit-frame-pointer -g)
+            add_link_options(-fsanitize=address,undefined,leak)
+            message(STATUS "Sanitizers enabled: ASAN, UBSAN, and LSan")
+        endif()
+        # Allow macro redefinition for _FORTIFY_SOURCE which conflicts with sanitizers
+        add_compile_options(-Wno-macro-redefined)
+    endif()
+endif()
+
+if(ENABLE_MSAN)
+    if(NOT MSVC)
+        # MemorySanitizer for detecting uninitialized memory reads
+        # WARNING: Requires all dependencies to be built with MSan
+        add_compile_options(-fsanitize=memory -fno-omit-frame-pointer -g)
+        add_compile_options(-Wno-macro-redefined)
+        add_link_options(-fsanitize=memory)
+        message(STATUS "MemorySanitizer enabled (MSan)")
+    else()
+        message(WARNING "MemorySanitizer is not supported with MSVC")
+    endif()
+endif()
+
+# Code coverage instrumentation
+option(ENABLE_COVERAGE "Enable code coverage instrumentation" OFF)
+
+if(ENABLE_COVERAGE)
+    if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang|AppleClang")
+        add_compile_options(--coverage -fprofile-arcs -ftest-coverage)
+        add_link_options(--coverage)
+        message(STATUS "Code coverage enabled")
+    else()
+        message(WARNING "Code coverage is only supported with GCC or Clang")
+    endif()
+endif()
+
 enable_testing()
 
 ADD_SUBDIRECTORY(src)

Makefile

@@ -5,29 +5,112 @@ BUILD_DIR = build
 DEBUG_BUILD_DIR = build/debug
 RELEASE_BUILD_DIR = build/release
 
+# CMake options (can be overridden via environment)
+CMAKE_OPTS :=
+ifdef C2PA_BUILD_FROM_SOURCE
+	CMAKE_OPTS += -DC2PA_BUILD_FROM_SOURCE=$(C2PA_BUILD_FROM_SOURCE)
+endif
+ifdef C2PA_RS_PATH
+	CMAKE_OPTS += -DC2PA_RS_PATH=$(C2PA_RS_PATH)
+endif
+
 # Default target
-all: test examples
+all: clean test examples
+
+clean:
+	rm -rf $(BUILD_DIR)
 
 # Debug build
 debug:
-	cmake -S . -B $(DEBUG_BUILD_DIR) -G "Ninja" -DCMAKE_BUILD_TYPE=Debug
+	cmake -S . -B $(DEBUG_BUILD_DIR) -G "Ninja" -DCMAKE_BUILD_TYPE=Debug $(CMAKE_OPTS)
 	cmake --build $(DEBUG_BUILD_DIR)
 
 # Release build
 release:
-	cmake -S . -B $(RELEASE_BUILD_DIR) -G "Ninja" -DCMAKE_BUILD_TYPE=Release
+	cmake -S . -B $(RELEASE_BUILD_DIR) -G "Ninja" -DCMAKE_BUILD_TYPE=Release $(CMAKE_OPTS)
 	cmake --build $(RELEASE_BUILD_DIR)
 
 # Legacy cmake target (uses release build)
 cmake: release
 
 # Test targets
-test: debug
+test: clean debug
 	cd $(DEBUG_BUILD_DIR) && ctest --output-on-failure
 
-test-release: release
+test-release: clean release
 	cd $(RELEASE_BUILD_DIR) && ctest --output-on-failure
 
+# Test with sanitizers (ASAN + UBSAN)
+test-san: clean
+	cmake -S . -B $(DEBUG_BUILD_DIR) -G "Ninja" -DCMAKE_BUILD_TYPE=Debug -DENABLE_SANITIZERS=ON $(CMAKE_OPTS)
+	cmake --build $(DEBUG_BUILD_DIR)
+	cd $(DEBUG_BUILD_DIR) && ctest --output-on-failure
+
+# Run only the C test (test.c)
+test-c: clean release
+	@echo "Running C test only..."
+ifeq ($(OS),Darwin)
+	DYLD_LIBRARY_PATH=$(RELEASE_BUILD_DIR)/tests:$$DYLD_LIBRARY_PATH ./$(RELEASE_BUILD_DIR)/tests/ctest
+else
+	LD_LIBRARY_PATH=$(RELEASE_BUILD_DIR)/tests:$$LD_LIBRARY_PATH ./$(RELEASE_BUILD_DIR)/tests/ctest
+endif
+
+# Run only the C++ tests
+test-cpp: clean release
+	@echo "Running C++ tests only..."
+ifeq ($(OS),Darwin)
+	DYLD_LIBRARY_PATH=$(RELEASE_BUILD_DIR)/tests:$$DYLD_LIBRARY_PATH ./$(RELEASE_BUILD_DIR)/tests/c2pa_c_tests
+else
+	LD_LIBRARY_PATH=$(RELEASE_BUILD_DIR)/tests:$$LD_LIBRARY_PATH ./$(RELEASE_BUILD_DIR)/tests/c2pa_c_tests
+endif
+
+# Run a single test by fully qualified name
+# Like this: make run-single-test TEST=BuilderTest.MergingBuildersThenSignMerged
+run-single-test: release
+	@if [ -z "$(TEST)" ]; then echo "Usage: make run-single-test TEST=SuiteName.TestName"; exit 1; fi
+	@echo "Running single test: $(TEST)"
+ifeq ($(OS),Darwin)
+	DYLD_LIBRARY_PATH=$(RELEASE_BUILD_DIR)/tests:$$DYLD_LIBRARY_PATH ./$(RELEASE_BUILD_DIR)/tests/c2pa_c_tests --gtest_filter="$(TEST)"
+else
+	LD_LIBRARY_PATH=$(RELEASE_BUILD_DIR)/tests:$$LD_LIBRARY_PATH ./$(RELEASE_BUILD_DIR)/tests/c2pa_c_tests --gtest_filter="$(TEST)"
+endif
+
+# Test with coverage reporting
+# THis verifies necessary tooling for coverage check is also installed
+test-coverage: clean
+	cmake -S . -B build/coverage -G "Ninja" -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON $(CMAKE_OPTS)
+	cmake --build build/coverage
+	cd build/coverage && ctest --output-on-failure
+	@echo ""
+	@echo "Generating coverage report..."
+	@lcov --capture --directory build/coverage --output-file build/coverage/coverage.info \
+		--ignore-errors mismatch,inconsistent,unsupported,format 2>&1 \
+		| grep -v "WARNING:" || { echo "Error: lcov capture failed"; exit 1; }
+	@lcov --remove build/coverage/coverage.info \
+		'/usr/*' '*/googletest/*' '*/json-src/*' '*/c2pa_prebuilt-src/*' '*/tests/*' \
+		--output-file build/coverage/coverage_filtered.info \
+		--ignore-errors unused,mismatch,inconsistent,format 2>&1 \
+		| grep -v "WARNING:" || { echo "Error: lcov filter failed"; exit 1; }
+	@echo ""
+	@echo "=== Coverage Summary ==="
+	@lcov --summary build/coverage/coverage_filtered.info \
+		--ignore-errors inconsistent,format 2>&1 \
+		| grep -E "(lines|functions|branches)" || true
+	@echo "========================"
+	@echo ""
+	@if command -v genhtml > /dev/null 2>&1; then \
+		genhtml build/coverage/coverage_filtered.info --output-directory build/coverage/html \
+			--ignore-errors inconsistent,corrupt,unsupported,format,category 2>&1 \
+			| grep -v "WARNING:" || true; \
+		if [ -f build/coverage/html/index.html ]; then \
+			echo "HTML report: build/coverage/html/index.html"; \
+		else \
+			echo "Warning: HTML report was not generated (genhtml may have failed)"; \
+		fi; \
+	else \
+		echo "Note: genhtml not found, skipping HTML report (install lcov for HTML reports)"; \
+	fi
+
 # Demo targets
 demo: release
 	cmake --build $(RELEASE_BUILD_DIR) --target demo
@@ -39,12 +122,8 @@ training: release
 
 examples: training demo
 
-clean:
-	rm -rf $(BUILD_DIR)
-
-.PHONY: all debug release cmake test test-release demo training examples clean
+.PHONY: all debug release cmake test test-release test-san test-c test-cpp test-coverage demo training examples clean
 
 # Build C API docs with Doxygen
 docs:
 	./scripts/generate_api_docs.sh
-

README.md

@@ -11,12 +11,12 @@ Although this library works for plain C applications, the documentation assumes
 
 For the best experience, read the docs on the [CAI Open Source SDK documentation website](https://opensource.contentauthenticity.org/docs/c2pa-c).  If you want to view the documentation in GitHub, see:
 - [Using the C++ library](docs/usage.md)
-- [Supported formats](https://github.com/contentauth/c2pa-rs/blob/crandmck/reorg-docs/docs/supported-formats.md)
+- [Supported formats](https://github.com/contentauth/c2pa-rs/blob/main/docs/supported-formats.md)
 
 </div>
 </div>
 
-## Using c2pa_cpp 
+## Using c2pa_cpp
 
 The recommended way to use this library in your own CMake project is with [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html):
 
@@ -34,45 +34,70 @@ add_executable(myapp main.cpp)
 target_link_libraries(myapp PRIVATE c2pa_cpp)
 ```
 
-This will automatically fetch, build, and link the `c2pa_cpp` library and its dependencies.  
+This will automatically fetch, build, and link the `c2pa_cpp` library and its dependencies.
 
-> **Note:**  
+> **Note:**
 > This project uses pre-built dynamic libraries from the [c2pa-rs](https://github.com/contentauth/c2pa-rs) repository. It should select the correct library for your platform. If your platform is not supported, you can build your own library using the c2pa_rs repo.
 
 ### Example usage
 
-See the [`examples/`](examples/) directory for sample applications that demonstrate how to use the library in practice.  
+See the [`examples/`](examples/) directory for sample applications that demonstrate how to use the library in practice.
 
 ## Development
 
 This project has been tested on macOS and should also work on common Linux distributions.
 
+You must install the [Ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages) build system to run the unit tests.
 
-You must install the [Ninja](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages) build system to run the unit tests. 
+### Building using pre-built C FFI libraries
 
-### Building 
+Building the library holding the C++ SDK requires [GNU make](https://www.gnu.org/software/make/), which is installed on most macOS systems.
 
-Building the library requires [GNU make](https://www.gnu.org/software/make/), which is installed on most macOS systems.
-
-Enter this command to build the C library: 
+Enter this command to build the SDK:
 
 ```
 make release
 ```
 
+This will download the [pre-build libraries published with c2pa releases](https://github.com/contentauth/c2pa-rs/releases), build and link the C++ code.
+
 The Makefile has a number of other targets; for example:
-- `unit-tests` to run C++ unit tests
+- `test` to run unit tests
 - `examples` to build and run the C++ examples.
-- `all` to run everything.
+- `all` to build and run everything.
 
 Results are saved in the `build` directory.
 
+### Building using local sources
+
+This project can also be built entirely from source (without pre-built library download), with the pre-requisite that you will also need [c2pa-rs](https://github.com/contentauth/c2pa-rs) on the local machine, as well as the [Rust toolchain](https://rust-lang.org/tools/install/).
+
+To build in this case, the build scripts need to be able to locate the `c2pa-rs` sources as well as the library this builds for linking. This is done by setting environment variables in the terminal where the builds will run.
+
+```sh
+# Enable local c2pa-rs build
+export C2PA_BUILD_FROM_SOURCE=ON
+
+# If local build is enabled, set this environment variable to contain the path to c2pa-rs sources
+export C2PA_RS_PATH=path_to_c2pa_rs_sources
+
+# Since this is going to build Rust code, the build system needs to locate cargo, the tool to build Rust code
+# Add Rust cargo to PATH if not already there
+export PATH="$HOME/.cargo/bin:$PATH"
+
+# macOs: Set built library path for running tests
+export DYLD_LIBRARY_PATH="$(pwd)/build/release/tests:$DYLD_LIBRARY_PATH"
+
+# Linux: Set built library path for running tests
+export LD_LIBRARY_PATH="$(pwd)/build/release/tests:$LD_LIBRARY_PATH"
+```
+
 ### Testing
 
 Build the [unit tests](https://github.com/contentauth/c2pa-c/tree/main/tests) by entering this `make` command:
 
 ```
-make unit-test
+make test
 ```
 
 ### Building API documentation
@@ -81,7 +106,7 @@ API documentation generated by Doxygen is automatically built on each PR.
 
 To generate API docs locally, these are the main files:
 
-- Configuration file: `c2pa-c/Doxyfile` 
+- Configuration file: `c2pa-c/Doxyfile`
 - Script: `c2pa-c/scripts/generate_api_docs.sh`
 - Output directory: `docs/_build/html`
 
@@ -111,5 +136,3 @@ Note that some components and dependent crates are licensed under different term
 ### Contributions and feedback
 
 We welcome contributions to this project.  For information on contributing, providing feedback, and about ongoing work, see [Contributing](https://github.com/contentauth/c2pa-c/blob/main/CONTRIBUTING.md).
-
-

ci-cd/lsan_suppressions.txt

@@ -0,0 +1,13 @@
+# LeakSanitizer suppression file for c2pa-c tests.
+#
+# On first use Tokio allocates process-global singleton state (signal handler
+# registry, thread-local handles via OnceLock/Lazy) that is intentionally never
+# freed. The allocation is bounded, does not grow, and is reclaimed by the OS on process exit.
+#
+# Observed on Ubuntu 22.04 aarch64 where LSan classifies the allocation as a
+# "direct leak" rather than "still reachable".
+#
+# Similar if not same as https://github.com/tokio-rs/tokio/issues/4756
+# Happens only on some Linxues as it depends on the OS/glibc version too it seems!
+#
+leak:libc2pa_c