Finish C API code generation (continues #14572) (#14868)

Summary:
This continues and finishes **#14572 ("Add semi-automated code generation for RocksDB C API bindings") by xingbowang. The original author is unavailable to finish it, so I've taken it over. **All 13 of the original commits are preserved** (this branch was created from the PR head and builds on top of it — `git log` shows the original `Xingbo Wang` authorship intact); my follow-up work is in the commits prefixed `C API codegen:`.

The underlying design is unchanged and is the original author's: hand-written source templates (`tools/c_api_gen/c_base.h` / `c_base.cc`) plus two generators (auto-discovery from the C++ headers + a spec-driven generator) are inlined into a single, self-contained, `generated` `include/rocksdb/c.h` and `db/c.cc`. This grows the public C API by **668 functions** while keeping `c.h` a single includable header with no `-I` requirement (so `bindgen` and other FFI tools keep working unchanged).

This branch reconciles the PR with ~4 months of `main` and addresses the outstanding review feedback (clang-tidy bot, the automated code review, the `c.h` self-containedness discussion, and pdillinger's points about `include/rocksdb` hygiene and `generated` marking).

## What changed on top of the original PR

### Reconciled with current `main`
- Merged current `main` (conflicts were confined to the generated/test files) and regenerated. Reconciled the 14 C API functions `main` added since the merge-base (e.g. `rocksdb_set_db_options`, the backup-engine rate limiters, `memtable_batch_lookup_optimization`, `optimize_multiget_for_io`, …) and restored 5 enum constants that upstream had added by hand (`rocksdb_txndb_write_policy_*`, `..._index_block_search_type_auto`, `rocksdb_blob_cache_read_byte`).

### Maintainer feedback (pdillinger)
- **No non-user-includable files in `include/rocksdb`.** Moved the hand-written templates out of `include/rocksdb/` and `db/` to `tools/c_api_gen/c_base.{h,cc}`. They were `#include`-ing generated fragments, which broke `make check-headers` and was shipped by `make install`. `include/rocksdb/` now contains only the user-facing, self-contained, `generated` `c.h`.
- `c.h` / `c.cc` carry the `// generated` marker.

### Backward compatibility (zero ABI break)
- The generator derived each wrapper's C type purely from the C++ field, which had silently changed **5 already-shipped signatures** (e.g. `rocksdb_writeoptions_disable_WAL` `int` → `unsigned char`). Added an ABI type-pinning layer (`tools/c_api_gen/abi_type_overrides.json`) so already-shipped functions keep their historical C signature (the body still casts to the real field type). A repo-wide diff against the merge-base now reports **0 ABI drift**.
- New `check_api_compatibility.py` gate (wired into CI + `make`) fails on any removed/changed public function **or** removed enum/typedef symbol, vs a reference revision. Intentional changes go in an allowlist with a reason.

### Correctness (from the automated review)
- Restored 5 option setters that were declared in `c.h` but **defined nowhere** (link failure for downstream bindings such as `rust-rocksdb`). Added `check_api_completeness.py` (dependency-free; runs in CI + `make`) asserting every declared function has exactly one definition — this is the gate that would have caught it.
- `CopyStringVector` now null-checks `malloc`; the WAL filter `std::move`s the `WriteBatch`; the backup exclude-files callback captures by value instead of the wrapper pointer.

### Build / CI robustness
- Removed the dead `C_API_CODEGEN_STAMP` Makefile prerequisite (it was a silent no-op).
- The `make check` staleness check is now opt-out-able (behind `SKIP_FORMAT_BUCK_CHECKS`) and skips gracefully when `clang++` is unavailable, so `make check` works without the codegen toolchain. CI remains the authoritative gate.
- Pinned `clang-format` consistently through `regen_all.py` / `verify_generated_up_to_date.py` (CI uses clang-format-21) so regeneration is byte-reproducible across environments.
- Cleared all 20 `clang-tidy` warnings the bot reported on `db/c.cc` changed lines (fixed in the `c_base.cc` template, not the generated output).
- Updated the internal Buck `c_test_bin` wrapper to expose generated `c_api_gen/*.inc` fragments as headers, so sandboxed Buck builds can compile `db/c_test.c` after the generated round-trip tests are included.

### Test coverage
- Added `gen_roundtrip_tests.py`, which derives **462 set→get→assert round-trip checks across 25 option objects** from the same generated fragments and wires them into `db/c_test.c`. Coverage now tracks the generated surface automatically.

### Docs
- Added the `unreleased_history/public_api_changes` note and fixed `claude_md/add_public_api.md`, which still told contributors to hand-edit the now-`generated` `c.h`/`c.cc`.

Pull Request resolved: #14868

Test Plan:
- `make c_test && ./c_test` — **passes**, including the 462 generated round-trip assertions (a successful link also confirms the API is complete).
- `python3 tools/c_api_gen/check_api_completeness.py` — all 1737 declared functions defined exactly once.
- `python3 tools/c_api_gen/check_api_compatibility.py --ref <release>` — 1070 reference functions + 229 enum/typedef symbols preserved, 0 removed/changed.
- `python3 tools/c_api_gen/verify_generated_up_to_date.py` — generated output is stable.
- `include/rocksdb/c.h` confirmed self-contained (only `<stdbool.h>`, `<stddef.h>`, `<stdint.h>`).

cc xingbowang

- `buck2 build --flagfile fbcode//mode/dev fbcode//internal_repo_rocksdb/repo:c_test_bin` — passes.
- `buck2 build --flagfile fbcode//mode/dev --config fbcode.arch=aarch64 fbcode//internal_repo_rocksdb/repo:c_test_bin` — passes.

Reviewed By: pdillinger

Differential Revision: D109149150

Pulled By: xingbowang

fbshipit-source-id: 3417375345f360a4c78bdfe27e9850b89d0a226a

Author: zaidoon1

.github/workflows/pr-jobs.yml

@@ -314,6 +314,23 @@ jobs:
     - run: CC=clang-21 CXX=clang++-21 USE_CLANG=1 make -j32 all microbench
     - run: make clean
     - run: CC=clang-21 CXX=clang++-21 USE_CLANG=1 DEBUG_LEVEL=0 make -j32 release
+    - name: Install clang-format-21 for C API gen checks
+      run: apt-get update && apt-get install -y clang-format-21
+    - name: Check C API codegen (link-complete, backward-compatible, up to date)
+      # Run the make target in STRICT mode so this core CI job HARD-FAILS rather
+      # than silently skipping if a prerequisite (clang++, clang-format, or the
+      # compat baseline ref) is ever missing. See `make check-c-api-gen`.
+      run: |
+        # The container checkout is owned by a different user, so git refuses to
+        # operate on it ("dubious ownership") -- mark it safe for the `git fetch`
+        # and the `git show` the compat checker runs.
+        git config --global --add safe.directory "$GITHUB_WORKSPACE"
+        git config --global --add safe.directory '*'
+        git fetch --no-tags --depth=1 origin main
+        CXX=clang++-21 make check-c-api-gen \
+          CHECK_C_API_GEN_STRICT=1 \
+          API_COMPAT_REF=FETCH_HEAD \
+          CLANG_FORMAT_BINARY=clang-format-21
     - uses: "./.github/actions/teardown-ccache"
       if: always()
     - uses: "./.github/actions/post-steps"

.gitignore

@@ -88,6 +88,8 @@ fbcode/
 fbcode
 buckifier/*.pyc
 buckifier/__pycache__
+tools/__pycache__/
+tools/c_api_gen/__pycache__/
 .arcconfig
 
 compile_commands.json

Makefile

@@ -764,7 +764,6 @@ util/build_version.cc: $(filter-out $(OBJ_DIR)/util/build_version.o, $(LIB_OBJEC
 	$(AM_V_at)$(gen_build_version) > $@
 endif
 CLEAN_FILES += util/build_version.cc
-
 default: all
 
 #-----------------------------------------------
@@ -809,7 +808,8 @@ endif  # PLATFORM_SHARED_EXT
 .PHONY: check clean coverage ldb_tests package dbg gen-pc build_size \
 	release tags tags0 valgrind_check format static_lib shared_lib all \
 	rocksdbjavastatic rocksdbjava install install-static install-shared \
-	uninstall analyze tools tools_lib check-headers checkout_folly clang-tidy
+	uninstall analyze tools tools_lib check-headers checkout_folly clang-tidy \
+	check-c-api-c_test
 
 # Auto-configure git hooks on first build so developers do not need to run
 # "make install-hooks" manually. This is a no-op if already set.
@@ -1127,8 +1127,89 @@ ifndef SKIP_FORMAT_BUCK_CHECKS
 	$(MAKE) check-buck-targets
 	$(MAKE) check-sources
 	$(MAKE) check-workflow-yaml
+	$(MAKE) check-c-api-gen
 endif
 
+# Check that the auto-generated C API files are up to date. It regenerates the
+# fragments and the inlined c.h/c.cc and compares them against a snapshot of the
+# checked-in copies (no net change when everything is up to date). It requires
+# clang++ (libclang, used to parse the C++ headers) and clang-format. When those
+# are unavailable the staleness/compat sub-checks are SKIPPED with a message so
+# `make check` still works without the codegen toolchain; the link-completeness
+# sub-check always runs (it needs no toolchain).
+#
+# Pin the formatter to match CI by setting CLANG_FORMAT_BINARY, e.g.:
+#   make check-c-api-gen CLANG_FORMAT_BINARY=clang-format-21
+# This target is part of `make check` and is skipped by SKIP_FORMAT_BUCK_CHECKS.
+#
+# Set CHECK_C_API_GEN_STRICT=1 to turn every "skip" below into a hard error, so a
+# core CI job that runs this target cannot silently regress to a no-op if a
+# prerequisite (clang++, or the compat baseline ref) goes missing. The dedicated
+# build-linux-clang-21-no_test_run CI job runs this target with the flag set.
+# Any non-empty value other than 0/no/false enables strict mode.
+CLANG_FORMAT_BINARY ?=
+# Backward-compatibility baseline for the C API (signature-level) check. CI
+# overrides this with the PR's merge target; locally it falls back to main /
+# origin/main and is skipped if neither resolves.
+API_COMPAT_REF ?= main
+CHECK_C_API_GEN_STRICT ?=
+check-c-api-gen:
+	# Link-completeness is a property of the checked-in c.h/c.cc and needs no
+	# clang toolchain, so it always runs: every declared public C API function
+	# must have exactly one definition (guards against dropped wrappers that
+	# would break downstream language bindings at link time).
+	$(PYTHON) tools/c_api_gen/check_api_completeness.py
+	# Backward-compatibility: no public C function may be removed or have its
+	# signature changed vs the baseline. Skipped if the baseline ref is not
+	# resolvable locally (CI passes an explicit ref), unless CHECK_C_API_GEN_STRICT.
+	@strict=""; case "$(CHECK_C_API_GEN_STRICT)" in ""|0|no|NO|false|FALSE) ;; *) strict=1 ;; esac; \
+	ref=""; \
+	if git rev-parse --verify --quiet "$(API_COMPAT_REF)^{commit}" >/dev/null; then ref="$(API_COMPAT_REF)"; \
+	elif git rev-parse --verify --quiet "origin/$(API_COMPAT_REF)^{commit}" >/dev/null; then ref="origin/$(API_COMPAT_REF)"; fi; \
+	if [ -n "$$ref" ]; then \
+	  $(PYTHON) tools/c_api_gen/check_api_compatibility.py --ref "$$ref"; \
+	elif [ -n "$$strict" ]; then \
+	  echo "ERROR: C API compat baseline '$(API_COMPAT_REF)' not resolvable and CHECK_C_API_GEN_STRICT is set" >&2; exit 1; \
+	else \
+	  echo "Skipping C API backward-compatibility check ($(API_COMPAT_REF) not found; set API_COMPAT_REF)"; \
+	fi
+	# Staleness: regenerate and confirm the checked-in output is current. Needs a
+	# clang++ (the generator parses C++ ASTs); detect one the way the generator
+	# does (a clang in $(CXX) -- which may be ccache-prefixed/versioned -- else a
+	# bare/versioned clang++ on PATH) rather than testing $(CXX) verbatim.
+	@strict=""; case "$(CHECK_C_API_GEN_STRICT)" in ""|0|no|NO|false|FALSE) ;; *) strict=1 ;; esac; \
+	cf_arg=""; \
+	if [ -n "$(CLANG_FORMAT_BINARY)" ]; then cf_arg="--clang-format $(CLANG_FORMAT_BINARY)"; fi; \
+	have_clang=""; \
+	for c in $$(printf '%s\n' $(CXX) | grep -i clang) clang++ clang++-21 clang++-20 clang++-19 clang++-18 clang++-17 clang++-16 clang++-15 clang++-14 clang++-13; do \
+	  if command -v "$$c" >/dev/null 2>&1; then have_clang=1; break; fi; \
+	done; \
+	if [ -n "$$have_clang" ]; then \
+	  $(PYTHON) tools/c_api_gen/verify_generated_up_to_date.py $$cf_arg; \
+	elif [ -n "$$strict" ]; then \
+	  echo "ERROR: no clang++ found and CHECK_C_API_GEN_STRICT is set; cannot run the C API staleness check" >&2; exit 1; \
+	else \
+	  echo "Skipping C API codegen staleness check (no clang++ found; install clang++ or set CXX to a clang to enable)"; \
+	fi
+
+# Quick local validation for C API generation plus the focused C API test.
+# This verifies the checked-in generated fragments as well as the inlined
+# include/rocksdb/c.h and db/c.cc outputs, then runs c_test in an isolated
+# TEST_TMPDIR to avoid stale-state failures.
+check-c-api-c_test:
+	$(PYTHON) tools/c_api_gen/verify_generated_up_to_date.py
+	$(MAKE) c_test
+	@tmpdir=$$(mktemp -d); \
+	  trap 'rm -rf "$$tmpdir"' EXIT; \
+	  echo "===== Running c_test with TEST_TMPDIR=$$tmpdir"; \
+	  if command -v timeout >/dev/null 2>&1; then \
+	    TEST_TMPDIR="$$tmpdir" timeout 60 ./c_test; \
+	  elif command -v gtimeout >/dev/null 2>&1; then \
+	    TEST_TMPDIR="$$tmpdir" gtimeout 60 ./c_test; \
+	  else \
+	    TEST_TMPDIR="$$tmpdir" ./c_test; \
+	  fi
+
 # TODO add ldb_tests
 check_some: $(ROCKSDBTESTS_SUBSET)
 	for t in $(ROCKSDBTESTS_SUBSET); do echo "===== Running $$t (`date`)"; ./$$t || exit 1; done

buckifier/targets_builder.py

@@ -118,6 +118,12 @@ def add_binary(
         self.total_bin = self.total_bin + 1
 
     def add_c_test(self):
+        # The actual c_test_bin target is defined by add_c_test_wrapper in the
+        # internal //rocks/buckifier:defs.bzl (not in this OSS repo). db/c_test.c
+        # #includes the generated c_api_gen/*.inc fragments, so under Buck's
+        # hermetic sandbox that wrapper must expose them as headers, e.g.
+        #   headers = native.glob(["c_api_gen/**/*.inc"])
+        # (Make/CMake resolve the include via -I. / PROJECT_SOURCE_DIR.)
         with open(self.path, "ab") as targets_file:
             targets_file.write(
                 b"""

c_api_gen/c_generated_block_based_options_subset.cc.inc

@@ -0,0 +1,39 @@
+// @generated
+// -----------------------------------------------------------------------------
+// Auto-generated by tools/c_api_gen/generate_c_api.py.
+// DO NOT EDIT THIS FILE DIRECTLY.
+// Source: tools/c_api_gen/spec.json
+// -----------------------------------------------------------------------------
+
+// To regenerate this file:
+//   python3 tools/c_api_gen/generate_c_api.py
+//     --spec tools/c_api_gen/spec.json --section 'BlockBasedOptions simple'
+//     --header-out
+//     c_api_gen/c_generated_block_based_options_subset.h.inc
+//     --source-out
+//     c_api_gen/c_generated_block_based_options_subset.cc.inc
+
+/* BlockBasedOptions simple */
+
+void rocksdb_block_based_options_set_data_block_hash_ratio(
+    rocksdb_block_based_table_options_t* options, double v) {
+  options->rep.data_block_hash_table_util_ratio = v;
+}
+
+void rocksdb_block_based_options_set_top_level_index_pinning_tier(
+    rocksdb_block_based_table_options_t* options, int v) {
+  options->rep.metadata_cache_options.top_level_index_pinning =
+      static_cast<ROCKSDB_NAMESPACE::PinningTier>(v);
+}
+
+void rocksdb_block_based_options_set_partition_pinning_tier(
+    rocksdb_block_based_table_options_t* options, int v) {
+  options->rep.metadata_cache_options.partition_pinning =
+      static_cast<ROCKSDB_NAMESPACE::PinningTier>(v);
+}
+
+void rocksdb_block_based_options_set_unpartitioned_pinning_tier(
+    rocksdb_block_based_table_options_t* options, int v) {
+  options->rep.metadata_cache_options.unpartitioned_pinning =
+      static_cast<ROCKSDB_NAMESPACE::PinningTier>(v);
+}

c_api_gen/c_generated_block_based_options_subset.h.inc

@@ -0,0 +1,32 @@
+// @generated
+// -----------------------------------------------------------------------------
+// Auto-generated by tools/c_api_gen/generate_c_api.py.
+// DO NOT EDIT THIS FILE DIRECTLY.
+// Source: tools/c_api_gen/spec.json
+// -----------------------------------------------------------------------------
+
+// To regenerate this file:
+//   python3 tools/c_api_gen/generate_c_api.py
+//     --spec tools/c_api_gen/spec.json --section 'BlockBasedOptions simple'
+//     --header-out
+//     c_api_gen/c_generated_block_based_options_subset.h.inc
+//     --source-out
+//     c_api_gen/c_generated_block_based_options_subset.cc.inc
+
+/* BlockBasedOptions simple */
+
+extern ROCKSDB_LIBRARY_API void
+rocksdb_block_based_options_set_data_block_hash_ratio(
+    rocksdb_block_based_table_options_t* options, double v);
+
+extern ROCKSDB_LIBRARY_API void
+rocksdb_block_based_options_set_top_level_index_pinning_tier(
+    rocksdb_block_based_table_options_t* options, int v);
+
+extern ROCKSDB_LIBRARY_API void
+rocksdb_block_based_options_set_partition_pinning_tier(
+    rocksdb_block_based_table_options_t* options, int v);
+
+extern ROCKSDB_LIBRARY_API void
+rocksdb_block_based_options_set_unpartitioned_pinning_tier(
+    rocksdb_block_based_table_options_t* options, int v);

c_api_gen/c_generated_cuckoo_options_subset.cc.inc

@@ -0,0 +1,21 @@
+// @generated
+// -----------------------------------------------------------------------------
+// Auto-generated by tools/c_api_gen/generate_c_api.py.
+// DO NOT EDIT THIS FILE DIRECTLY.
+// Source: tools/c_api_gen/spec.json
+// -----------------------------------------------------------------------------
+
+// To regenerate this file:
+//   python3 tools/c_api_gen/generate_c_api.py
+//     --spec tools/c_api_gen/spec.json --section 'CuckooOptions simple'
+//     --header-out
+//     c_api_gen/c_generated_cuckoo_options_subset.h.inc
+//     --source-out
+//     c_api_gen/c_generated_cuckoo_options_subset.cc.inc
+
+/* CuckooOptions simple */
+
+void rocksdb_cuckoo_options_set_hash_ratio(
+    rocksdb_cuckoo_table_options_t* options, double v) {
+  options->rep.hash_table_ratio = v;
+}

c_api_gen/c_generated_cuckoo_options_subset.h.inc

@@ -0,0 +1,19 @@
+// @generated
+// -----------------------------------------------------------------------------
+// Auto-generated by tools/c_api_gen/generate_c_api.py.
+// DO NOT EDIT THIS FILE DIRECTLY.
+// Source: tools/c_api_gen/spec.json
+// -----------------------------------------------------------------------------
+
+// To regenerate this file:
+//   python3 tools/c_api_gen/generate_c_api.py
+//     --spec tools/c_api_gen/spec.json --section 'CuckooOptions simple'
+//     --header-out
+//     c_api_gen/c_generated_cuckoo_options_subset.h.inc
+//     --source-out
+//     c_api_gen/c_generated_cuckoo_options_subset.cc.inc
+
+/* CuckooOptions simple */
+
+extern ROCKSDB_LIBRARY_API void rocksdb_cuckoo_options_set_hash_ratio(
+    rocksdb_cuckoo_table_options_t* options, double v);