[C++] Add SDK examples (JSON, proto, Arrow Flight)

cpp/NEXT_CHANGELOG.md

@@ -27,6 +27,12 @@
 - Documented running the tests in `README.md`: the sanitizer runs
   (`make test SANITIZE=address` / `thread`) and the env-var-gated
   `integration_test` (which variables it needs and that it skips without them).
+- Added runnable examples under `examples/` covering all three record formats —
+  JSON, protobuf (dynamic schema built at runtime from Unity Catalog metadata via
+  `ProtoSchema::from_uc_json`, no `protoc` required), and Arrow Flight (Beta) —
+  each with a single-record and a batch variant. They build with the SDK via
+  `ZEROBUS_BUILD_EXAMPLES` (the Arrow example is skipped when Apache Arrow C++ is
+  not installed). Includes a top-level `examples/README.md` and per-format guides.
 
 ### Internal Changes
 

cpp/README.md

@@ -38,8 +38,8 @@ make build        # configure + build the SDK and tests
 make test         # build + run the test suite
 ```
 
-(`make build` also builds an `examples/` directory once one is added; none
-ships yet.)
+(`make build` also builds the runnable examples under `examples/`; see
+[Examples](#examples).)
 
 Or drive CMake directly:
 
@@ -365,10 +365,15 @@ the FFI defaults.
 
 ## Examples
 
-Runnable examples will live under `examples/`, covering the three ingestion
-paths (JSON, dynamic proto, and static proto). Until they land, the
-[Quickstart](#quickstart) above demonstrates the JSON and dynamic-proto paths
-end to end.
+Runnable examples live under [`examples/`](examples/README.md), covering all
+three record formats — JSON, protobuf (dynamic schema from Unity Catalog), and
+Arrow Flight (Beta) — each with a single-record and a batch variant. Every
+example reads its OAuth secrets (`DATABRICKS_CLIENT_ID` /
+`DATABRICKS_CLIENT_SECRET`) from the environment and keeps its non-secret
+connection info as placeholder constants at the top of the source file. They
+build as part of the top-level CMake build (`ZEROBUS_BUILD_EXAMPLES`, on by
+default) into `build/examples/`. See the [examples README](examples/README.md)
+for setup and per-format guides.
 
 ## A note on credentials
 

cpp/examples/CMakeLists.txt

@@ -0,0 +1,61 @@
+# Example binaries for the Zerobus C++ SDK.
+#
+# Built when ZEROBUS_BUILD_EXAMPLES is on (the default for a top-level build).
+# Each example links the zerobus::zerobus target, which transitively pulls in
+# the Rust C FFI archive and the platform system libraries it needs.
+#
+# Every example reads its two OAuth secrets (DATABRICKS_CLIENT_ID /
+# DATABRICKS_CLIENT_SECRET) from the environment; the proto examples additionally
+# read the Unity Catalog table metadata JSON (ZEROBUS_UC_TABLE_JSON). All other
+# connection info is placeholder constants at the top of each source file. See
+# each file's header for the variables it expects and a sample invocation.
+#
+# The JSON and proto examples need no protobuf toolchain: the proto examples use
+# dynamic ProtoSchema::from_uc_json(), which builds the descriptor at runtime.
+# Only the Arrow example has an external dependency (Apache Arrow C++), and it is
+# skipped gracefully when Arrow is not installed.
+
+# ---------------------------------------------------------------------------
+# JSON examples
+# ---------------------------------------------------------------------------
+add_executable(json_single json/single.cpp)
+target_link_libraries(json_single PRIVATE zerobus::zerobus)
+
+add_executable(json_batch json/batch.cpp)
+target_link_libraries(json_batch PRIVATE zerobus::zerobus)
+
+# ---------------------------------------------------------------------------
+# Protocol Buffers examples (dynamic schema — no protoc required)
+# ---------------------------------------------------------------------------
+add_executable(proto_single proto/single.cpp)
+target_link_libraries(proto_single PRIVATE zerobus::zerobus)
+
+add_executable(proto_batch proto/batch.cpp)
+target_link_libraries(proto_batch PRIVATE zerobus::zerobus)
+
+if(DEFINED ZEROBUS_FFI_BUILD_TARGET)
+  add_dependencies(json_single ${ZEROBUS_FFI_BUILD_TARGET})
+  add_dependencies(json_batch ${ZEROBUS_FFI_BUILD_TARGET})
+  add_dependencies(proto_single ${ZEROBUS_FFI_BUILD_TARGET})
+  add_dependencies(proto_batch ${ZEROBUS_FFI_BUILD_TARGET})
+endif()
+
+# ---------------------------------------------------------------------------
+# Arrow Flight example (arrow_ingest) — Beta
+# ---------------------------------------------------------------------------
+# Uses the Apache Arrow C++ library to build RecordBatches and serialize them to
+# Arrow IPC bytes for ArrowStream::ingest_batch. Skipped if Arrow is not
+# installed — a machine without libarrow still gets every other example.
+find_package(Arrow QUIET)
+if(Arrow_FOUND)
+  add_executable(arrow_ingest arrow/arrow_ingest.cpp)
+  target_link_libraries(arrow_ingest PRIVATE zerobus::zerobus Arrow::arrow_shared)
+  if(DEFINED ZEROBUS_FFI_BUILD_TARGET)
+    add_dependencies(arrow_ingest ${ZEROBUS_FFI_BUILD_TARGET})
+  endif()
+else()
+  message(STATUS
+      "Zerobus examples: Apache Arrow C++ not found; skipping arrow_ingest "
+      "example (install libarrow-dev to enable). The JSON and proto examples "
+      "still build.")
+endif()