Merge pull request #45 from flyingrobots/feat/dependency-placeholders

feat: add dependency toggles and libgit2 detection

Author: flyingrobots

ACTIVITY.log.jsonl

@@ -72,3 +72,6 @@
 {"who": "AGENT", "what": "Debrief request acknowledged", "where": ["ACTIVITY.log.jsonl"], "when": "2025-10-24T10:22:09Z", "why": "Closing out the clang-tidy cleanup session", "how": "Ready to summarize findings and next steps for the branch", "protip": "Keep the ledger current even when the work shifts to review"}
 {"who": "AGENT", "what": "Re-enabled tidy checks with absolute header filter", "where": [".clang-tidy", "tools/lint/run_clang_tidy.sh"], "when": "2025-10-24T17:50:28Z", "why": "Review caught the over-broad disable—restored checks and confined analysis to project headers", "how": "Anchored HeaderFilterRegex, injected header filter path in run_clang_tidy.sh, and reran clang-tidy/make lint", "protip": "Let tidy focus on your tree via --header-filter instead of muting diagnostics"}
 {"who": "AGENT", "what": "Clarified clang-tidy baseline and restored checks", "where": [".clang-tidy", "tools/lint/run_clang_tidy.sh"], "when": "2025-10-24T19:28:49Z", "why": "Earlier log entries (lines 66-69) overstated system-header issues; review confirmed the real problem was over-broad disables", "how": "Re-enabled the security/readability checks, anchored the header filter to the repo root, and added validation so clang-tidy stays scoped", "protip": "Capture the actual diagnostic numbers next time—assumptions about system headers masked the real issue"}
+{"who": "AGENT", "what": "Added dependency toggles and documentation", "where": ["CMakeLists.txt", "meson.build", "meson_options.txt", "README.md", "CONTRIBUTING.md"], "when": "2025-10-25T06:16:07Z", "why": "Issue #3 requires libgit2 detection plus placeholders for CRoaring/BLAKE3", "how": "Hooked libgit2 via pkg-config in CMake/Meson, stubbed vendor options, and documented install commands", "protip": "Keep build options mirrored across CMake and Meson so contributors aren’t surprised"}
+{"who": "AGENT", "what": "Handled pkg-config absence on Windows", "where": ["CMakeLists.txt", "README.md"], "when": "2025-10-25T07:06:13Z", "why": "CI showed MSVC job missing pkg-config", "how": "Made pkg-config optional in CMake with a helpful error and documented Windows install command", "protip": "If CI uses MSVC, assume pkg-config isn’t preinstalled"}
+{"who": "AGENT", "what": "Made libgit2 optional across build systems", "where": ["CMakeLists.txt", "meson.build", "tools/container/Dockerfile", "README.md", "AGENTS.md"], "when": "2025-10-25T07:45:10Z", "why": "CI and reviewers flagged hard pkg-config/libgit2 dependency failures (esp. MSVC)", "how": "Added AUTO/ON/OFF toggle, fallback detection, private linkage, meson auto feature, pinned Docker install", "protip": "Treat optional deps as features: detect, warn, and gate definitions"}

AGENTS.md

@@ -14,6 +14,12 @@ If you were expecting a YAML schema, go cry into your `.gitlab-ci.yml`.
 
 ## REPO RULES (READ THIS TWICE)
 
+> **ABSOLUTELY NO HISTORY REWRITES**
+
+Do not use `git commit --amend`, do not force-push, do not rebase. Ever.
+If you need to fix something, add a new commit and push normally. If
+upstream moved, pull and merge. The ledger is append-only.
+
 > **NO REBASING.**  
 
 Rebasing is revisionist history. This is a ledger. Not a TED talk.

CMakeLists.txt

@@ -6,6 +6,21 @@ set(CMAKE_C_STANDARD_REQUIRED ON)
 set(CMAKE_C_EXTENSIONS OFF)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
+option(GITLEDGER_VENDOR_LIBGIT2 "Build against a vendored libgit2 copy (placeholder)" OFF)
+option(GITLEDGER_WITH_CROARING "Enable CRoaring integration (placeholder)" OFF)
+option(GITLEDGER_WITH_BLAKE3 "Enable BLAKE3 support (placeholder)" OFF)
+set(GITLEDGER_WITH_LIBGIT2 "AUTO" CACHE STRING "Use libgit2 (values: AUTO, ON, OFF)")
+set_property(CACHE GITLEDGER_WITH_LIBGIT2 PROPERTY STRINGS AUTO ON OFF)
+string(TOUPPER "${GITLEDGER_WITH_LIBGIT2}" GITLEDGER_WITH_LIBGIT2_MODE)
+
+if(GITLEDGER_WITH_CROARING)
+    message(STATUS "CRoaring support is not implemented yet; continuing without it.")
+endif()
+
+if(GITLEDGER_WITH_BLAKE3)
+    message(STATUS "BLAKE3 support is not implemented yet; continuing without it.")
+endif()
+
 if(MSVC)
     set(PROJECT_WARNING_FLAGS /W4 /WX /we4244 /we4267 /we4456 /we4457 /we4458 /we4459)
 else()
@@ -26,6 +41,48 @@ set(LIBGITLEDGER_HEADERS
 add_library(gitledger STATIC ${LIBGITLEDGER_SOURCES} ${LIBGITLEDGER_HEADERS})
 target_compile_options(gitledger PRIVATE ${PROJECT_WARNING_FLAGS})
 
+if(GITLEDGER_VENDOR_LIBGIT2)
+    message(FATAL_ERROR "Vendored libgit2 support is not implemented yet.\n"
+                           "Install libgit2 on your system or rerun with -DGITLEDGER_VENDOR_LIBGIT2=OFF to continue.")
+endif()
+
+set(GITLEDGER_LIBGIT2_TARGET "")
+
+if(NOT GITLEDGER_WITH_LIBGIT2_MODE STREQUAL "OFF")
+    find_package(LibGit2 QUIET)
+    if(LibGit2_FOUND)
+        set(GITLEDGER_LIBGIT2_TARGET LibGit2::LibGit2)
+    else()
+        find_package(PkgConfig QUIET)
+        if(PKG_CONFIG_FOUND)
+            pkg_check_modules(LIBGIT2 IMPORTED_TARGET libgit2)
+            if(LIBGIT2_FOUND)
+                set(GITLEDGER_LIBGIT2_TARGET PkgConfig::LIBGIT2)
+            endif()
+        endif()
+    endif()
+
+    if(GITLEDGER_LIBGIT2_TARGET STREQUAL "")
+        if(GITLEDGER_WITH_LIBGIT2_MODE STREQUAL "ON")
+            message(FATAL_ERROR "libgit2 development files were not found.\n"
+                               "Install libgit2 and pkg-config using one of:\n"
+                               "  sudo apt-get install libgit2-dev pkg-config\n"
+                               "  brew install libgit2 pkg-config\n"
+                               "  choco install libgit2 pkgconfiglite\n"
+                               "Then rerun CMake, or pass -DGITLEDGER_WITH_LIBGIT2=OFF to continue without libgit2.")
+        else()
+            message(STATUS "libgit2 not found; continuing without libgit2 integration."
+                           " Set -DGITLEDGER_WITH_LIBGIT2=ON after installing libgit2 to enable it.")
+        endif()
+    else()
+        message(STATUS "libgit2 dependency detected via ${GITLEDGER_LIBGIT2_TARGET}.")
+        target_link_libraries(gitledger PRIVATE ${GITLEDGER_LIBGIT2_TARGET})
+        target_compile_definitions(gitledger PRIVATE GITLEDGER_HAVE_LIBGIT2=1)
+    endif()
+else()
+    message(STATUS "libgit2 support disabled via -DGITLEDGER_WITH_LIBGIT2=OFF")
+endif()
+
 target_include_directories(gitledger
     PUBLIC
         $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/libgitledger/include>

CONTRIBUTING.md

@@ -14,6 +14,7 @@ Thanks for helping build `libgitledger`! This document complements the roadmap a
 - Maintain both build systems. Preferred: run the containerised make targets (`make cmake`, `make meson`, `make test-both`) so you exercise the same matrix CI runs. These jobs copy the repo into isolated workspaces, prepare sandbox Git fixtures, and remove all remotes before mutating anything.
 - If you must run directly on the host checkout, export `I_KNOW_WHAT_I_AM_DOING=1` before invoking host targets. The makefile will otherwise abort unless it detects the container guard. Manual command sequences for CMake/Meson live in the README if you need to craft bespoke invocations.
 - Align tooling: warning flags, optional dependencies, and targets must stay consistent across CMake and Meson.
+- Install prerequisites (at minimum `libgit2` and `pkg-config`) before running host builds. Examples: `sudo apt-get install libgit2-dev pkg-config` or `brew install libgit2 pkg-config`.
 - When adding dependencies, update both build descriptions and mention the change in the relevant issue.
 - Run `make lint` (containerised clang-format + clang-tidy) before submitting a PR. CI enforces the same suite on GCC, Clang, and MSVC.
 - Need to bypass clang-tidy for a quick repro? Run `RUN_TIDY=0 make host-tidy` locally, but flip it back to 1 before shipping anything.

README.md

@@ -91,6 +91,40 @@ make format       # apply clang-format in-place (runs on the host)
 make markdownlint # lint Markdown docs using markdownlint-cli
 ```
 
+## Dependencies
+
+`libgitledger` links against [`libgit2`](https://libgit2.org/). Ensure the development
+headers are available before configuring either build system:
+
+- **Debian/Ubuntu**
+
+  ```bash
+  sudo apt-get update
+  sudo apt-get install libgit2-dev pkg-config
+  ```
+
+- **macOS (Homebrew)**
+
+  ```bash
+  brew install libgit2 pkg-config
+  ```
+
+- **Windows (Chocolatey)**
+
+  ```powershell
+  choco install libgit2 pkgconfiglite
+  ```
+
+Optional knobs surface in both build systems:
+
+- CMake: `-DGITLEDGER_WITH_LIBGIT2=OFF` to configure without libgit2, (future)
+  `-DGITLEDGER_VENDOR_LIBGIT2=ON` for vendoring once implemented, plus
+  placeholders `-DGITLEDGER_WITH_CROARING=ON` and `-DGITLEDGER_WITH_BLAKE3=ON`.
+- Meson: `-Dvendor_libgit2=true`, `-Dwith_croaring=enabled`, and `-Dwith_blake3=enabled`.
+
+The CRoaring and BLAKE3 switches are stubs for future work and simply log that
+the integration is pending.
+
 ## Coding Standards
 
 - `.clang-format` defines the canonical formatting rules; run `make format` to apply them and

meson.build

@@ -3,17 +3,55 @@ project('libgitledger', 'c',
   default_options: ['c_std=c17', 'warning_level=3', 'werror=true']
 )
 
+vendor_libgit2 = get_option('vendor_libgit2')
+with_libgit2_opt = get_option('with_libgit2')
+
+if vendor_libgit2
+  error('Vendored libgit2 support is not yet implemented. Install libgit2 or configure with -Dvendor_libgit2=false.')
+endif
+
+libgit2_required = with_libgit2_opt.enabled()
+libgit2_dep = dependency('libgit2', required: libgit2_required)
+
+if not libgit2_dep.found()
+  if with_libgit2_opt.disabled()
+    message('libgit2 disabled by configuration; continuing without it.')
+  else
+    message('libgit2 development files not found; install via your package manager (e.g. apt install libgit2-dev, brew install libgit2, or choco install libgit2).')
+    if libgit2_required
+      error('libgit2 was requested but could not be located.')
+    endif
+  endif
+endif
+
+if not get_option('with_croaring').disabled()
+  message('CRoaring support is not implemented yet; option is currently informational only.')
+endif
+
+if not get_option('with_blake3').disabled()
+  message('BLAKE3 support is not implemented yet; option is currently informational only.')
+endif
+
 lib_sources = [
   'libgitledger/core/domain/gitledger.c',
   'src/version.c',
 ]
 
 include_dir = include_directories('libgitledger/include', 'include')
 
+lib_deps = []
+lib_c_args = []
+if libgit2_dep.found()
+  lib_deps += libgit2_dep
+  lib_c_args += ['-DGITLEDGER_HAVE_LIBGIT2=1']
+endif
+
 libgitledger = static_library(
   'gitledger',
   lib_sources,
   include_directories: include_dir,
+  dependencies: lib_deps,
+  c_args: lib_c_args,
 )
 
 tests_version = executable(

meson_options.txt

@@ -1,3 +1,4 @@
+option('vendor_libgit2', type: 'boolean', value: false, description: 'Build against vendored libgit2 (placeholder)')
 option('with_libgit2', type: 'feature', value: 'auto', description: 'Enable libgit2 integration when available')
 option('with_croaring', type: 'feature', value: 'disabled', description: 'Enable CRoaring integration when available')
 option('with_blake3', type: 'feature', value: 'disabled', description: 'Enable BLAKE3 checksum support')

tools/container/Dockerfile

@@ -14,6 +14,7 @@ RUN apt-get update \
         python3-pip=24.0+dfsg-1ubuntu1.3 \
         rsync=3.2.7-1ubuntu1.2 \
         meson=1.3.2-1ubuntu1 \
+        libgit2-dev=1.7.2+ds-1ubuntu3 \
         gcc-14=14.2.0-4ubuntu2~24.04 \
         g++-14=14.2.0-4ubuntu2~24.04 \
         clang-18=1:18.1.3-1ubuntu1 \