fix up c++ cookbook

Author: lidavidm

.github/workflows/native-unix.yml

@@ -710,7 +710,17 @@ jobs:
       - name: Test Recipes (C++)
         run: |
           ./ci/scripts/cpp_recipe.sh $(pwd) ~/local build/recipe
+      - name: Ensure recipes are up to date
+        run: |
+          pip install -e ./docs/source/ext/sphinx_recipe
+          # Exits 1 if any recipes were updated
+          python -m sphinx_recipe.update_output \
+            docs/source/cpp/recipe/*.cc \
+            docs/source/cpp/recipe_driver/driver_example.py \
+            docs/source/python/recipe/*.py
       - name: Test Recipes (Python)
         run: |
           docker compose up --detach --wait dremio dremio-init flightsql-sqlite-test postgres-test
+          # Needed for the combined C++/Python driver example
+          export LD_LIBRARY_PATH=~/local/lib
           pytest -vvs docs/source/tests/

ci/scripts/cpp_recipe.sh

@@ -33,6 +33,7 @@ test_recipe() {
     export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${install_dir}/lib"
     export GOEXPERIMENT=cgocheck2
 
+    rm -rf "${build_dir}"
     mkdir -p "${build_dir}"
     pushd "${build_dir}"
 
@@ -41,11 +42,12 @@ test_recipe() {
           ${ADBC_CMAKE_ARGS} \
           -DCMAKE_BUILD_TYPE="${CMAKE_BUILD_TYPE}" \
           -DCMAKE_INSTALL_LIBDIR=lib \
+          -DCMAKE_INSTALL_PREFIX="${install_dir}" \
           -DCMAKE_PREFIX_PATH="${install_dir}" \
           -DADBC_DRIVER_EXAMPLE_BUILD_TESTS=ON
     set +x
 
-    cmake --build . -j
+    cmake --build . --target install -j
     ctest \
         --output-on-failure \
         --no-tests=error

docs/source/cpp/recipe/CMakeLists.txt

@@ -31,11 +31,13 @@ find_package(AdbcDriverManager REQUIRED)
 fetchcontent_declare(nanoarrow
                      GIT_REPOSITORY https://github.com/apache/arrow-nanoarrow.git
                      GIT_TAG apache-arrow-nanoarrow-0.2.0
-                     GIT_SHALLOW TRUE)
+                     GIT_SHALLOW TRUE
+                     EXCLUDE_FROM_ALL)
 fetchcontent_makeavailable(nanoarrow)
 
-add_executable(quickstart quickstart.cc)
-target_include_directories(quickstart SYSTEM PRIVATE ${nanoarrow_SOURCE_DIR}/dist)
-target_link_libraries(quickstart PRIVATE AdbcDriverManager::adbc_driver_manager_shared
-                                         nanoarrow)
-add_test(NAME quickstart COMMAND quickstart)
+add_executable(recipe-quickstart quickstart.cc)
+target_include_directories(recipe-quickstart SYSTEM PRIVATE ${nanoarrow_SOURCE_DIR}/dist)
+target_link_libraries(recipe-quickstart
+                      PRIVATE AdbcDriverManager::adbc_driver_manager_shared nanoarrow)
+add_test(NAME quickstart COMMAND recipe-quickstart)
+install(TARGETS recipe-quickstart)

docs/source/cpp/recipe/quickstart.stdout.txt

@@ -49,6 +49,8 @@ target_include_directories(driver_example PRIVATE ../../../../c ../../../../c/in
 target_link_libraries(driver_example PRIVATE adbc_driver_framework
                                              nanoarrow::nanoarrow_ipc)
 
+install(TARGETS driver_example)
+
 if(ADBC_DRIVER_EXAMPLE_BUILD_TESTS)
   fetchcontent_declare(googletest
                        URL https://github.com/google/googletest/archive/refs/tags/v1.15.1.tar.gz

docs/source/cpp/recipe_driver/CMakeLists.txt

@@ -45,7 +45,8 @@ def connect(uri: str):
                 driver=str(driver_lib.resolve()), db_kwargs={"uri": uri}
             )
 
-    raise RuntimeError("Can't find driver shared object")
+    # Try to find it on the dynamic loader path
+    return dbapi.connect(driver="driver_example", db_kwargs={"uri": uri})
 
 
 #: Next, we can give our driver a go! The two pieces we implemented in the driver
@@ -63,5 +64,6 @@ def connect(uri: str):
         with con.cursor() as cur:
             cur.execute("SELECT * FROM example.arrows")
             print(cur.fetchall())
+            # Output: [(1,), (2,), (3,)]
 
         os.unlink(Path(__file__).parent / "example.arrows")

docs/source/cpp/recipe_driver/driver_example.py

@@ -15,14 +15,16 @@
 # specific language governing permissions and limitations
 # under the License.
 
+"""Regenerate .stdout.txt files from recipes for the test harness."""
+
 import argparse
 import sys
 from pathlib import Path
 
 from . import parser as recipe_parser
 
 
-def main():
+def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("recipes", nargs="+", type=Path, help="Recipe files to update")
 
@@ -46,11 +48,18 @@ def main():
                     continue
 
         with target.open("w") as sink:
-            sink.writelines(stdout)
+            for line in stdout:
+                sink.write(line)
+                sink.write("\n")
         print(path, "updated")
         updated = True
 
-    return 1 if updated else 0
+    if updated:
+        print("----------------------------------------")
+        print("Some .stdout.txt files were updated.")
+        print("Please commit the result.")
+        return 1
+    return 0
 
 
 if __name__ == "__main__":

docs/source/cpp/recipe_driver/driver_example.stdout.txt

@@ -22,15 +22,18 @@
 
 
 def pytest_generate_tests(metafunc) -> None:
-    root = (Path(__file__).parent.parent / "python/recipe/").resolve()
-    recipes = root.rglob("*.py")
-    metafunc.parametrize(
-        "recipe", [pytest.param(path, id=path.stem) for path in recipes]
-    )
+    params = []
+    for root in (
+        (Path(__file__).parent.parent / "cpp/recipe_driver/").resolve(),
+        (Path(__file__).parent.parent / "python/recipe/").resolve(),
+    ):
+        recipes = root.rglob("*.py")
+        params.extend(pytest.param(path, id=path.stem) for path in recipes)
+    metafunc.parametrize("recipe", params)
 
 
 def test_cookbook_recipe(recipe: Path, capsys: pytest.CaptureFixture) -> None:
-    spec = importlib.util.spec_from_file_location(f"cookbook.{recipe.stem}", recipe)
+    spec = importlib.util.spec_from_file_location("__main__", recipe)
     mod = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(mod)