docs(c/driver/framework): Add documentation for building a driver using the driver framework

.gitignore

@@ -57,6 +57,7 @@ cpp/.idea/
 c/apidoc/html/
 c/apidoc/latex/
 c/apidoc/xml/
+c/apidoc/objects.inv
 docs/example.gz
 docs/example1.dat
 docs/example3.dat

c/apidoc/Doxyfile

@@ -500,7 +500,7 @@ EXTRACT_ALL            = NO
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
 # methods of a class will be included in the documentation.
@@ -891,7 +891,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../../c/include/arrow-adbc/adbc.h ../../README.md ../../c/include/arrow-adbc/adbc_driver_manager.h
+INPUT                  = ../../c/include/arrow-adbc/adbc.h ../../README.md ../../c/include/arrow-adbc/adbc_driver_manager.h ../../c/driver/framework/
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -920,12 +920,7 @@ INPUT_ENCODING         = UTF-8
 # comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd,
 # *.vhdl, *.ucf, *.qsf and *.ice.
 
-FILE_PATTERNS          = *.c \
-                         *.cc \
-                         *.cxx \
-                         *.cpp \
-                         *.c++ \
-                         *.java \
+FILE_PATTERNS          = *.java \
                          *.ii \
                          *.ixx \
                          *.ipp \

c/driver/framework/status.h

@@ -147,6 +147,7 @@ class Status {
 #undef STATUS_CTOR
 
  private:
+  /// \brief Private Status implementation details
   struct Impl {
     // invariant: code is never OK
     AdbcStatusCode code;

ci/scripts/cpp_recipe.sh

@@ -23,10 +23,11 @@ set -e
 : ${ADBC_CMAKE_ARGS:=""}
 : ${CMAKE_BUILD_TYPE:=Debug}
 
-main() {
-    local -r source_dir="${1}"
-    local -r install_dir="${2}"
-    local -r build_dir="${3}"
+test_recipe() {
+    local -r recipe="${1}"
+    local -r source_dir="${2}"
+    local -r install_dir="${3}"
+    local -r build_dir="${4}"
 
     export DYLD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${install_dir}/lib"
     export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:${install_dir}/lib"
@@ -36,11 +37,12 @@ main() {
     pushd "${build_dir}"
 
     set -x
-    cmake "${source_dir}/docs/source/cpp/recipe/" \
+    cmake "${source_dir}/${recipe}/" \
           ${ADBC_CMAKE_ARGS} \
           -DCMAKE_BUILD_TYPE="${CMAKE_BUILD_TYPE}" \
           -DCMAKE_INSTALL_LIBDIR=lib \
-          -DCMAKE_PREFIX_PATH="${install_dir}"
+          -DCMAKE_PREFIX_PATH="${install_dir}" \
+          -DADBC_DRIVER_EXAMPLE_BUILD_TESTS=ON
     set +x
 
     cmake --build . -j
@@ -49,4 +51,5 @@ main() {
         --no-tests=error
 }
 
-main "$@"
+test_recipe "docs/source/cpp/recipe" "$@"
+test_recipe "docs/source/cpp/recipe_driver" "$@"

ci/scripts/r_build.sh

@@ -63,6 +63,10 @@ main() {
     if [[ "${BUILD_DRIVER_SNOWFLAKE}" -gt 0 ]]; then
         install_pkg "${source_dir}" "${install_dir}" adbcsnowflake
     fi
+
+    if [[ "${BUILD_DRIVER_BIGQUERY}" -gt 0 ]]; then
+        install_pkg "${source_dir}" "${install_dir}" adbcbigquery
+    fi
 }
 
 main "$@"

docs/source/cpp/driver_example.rst

@@ -0,0 +1,49 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements.  See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership.  The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License.  You may obtain a copy of the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied.  See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+==============
+Driver Example
+==============
+
+.. recipe:: recipe_driver/driver_example.cc
+   :language: cpp
+
+Low-level testing
+=================
+
+.. recipe:: recipe_driver/driver_example_test.cc
+   :language: cpp
+
+High-level testing
+==================
+
+.. recipe:: recipe_driver/driver_example.py
+
+High-level tests can also be written in R using the ``adbcdrivermanager``
+package.
+
+.. code-block:: r
+
+   library(adbcdrivermanager)
+
+   drv <- adbc_driver("build/libdriver_example.dylib")
+   db <- adbc_database_init(drv, uri = paste0("file://", getwd()))
+   con <- adbc_connection_init(db)
+
+   data.frame(col = 1:3) |> write_adbc(con, "example.arrows")
+   con |> read_adbc("SELECT * FROM example.arrows") |> as.data.frame()
+   unlink("example.arrows")

docs/source/cpp/index.rst

@@ -25,4 +25,5 @@ C and C++
    quickstart
    driver_manager
    concurrency
+   driver_example
    api/index

docs/source/cpp/recipe_driver/CMakeLists.txt

@@ -0,0 +1,69 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+cmake_minimum_required(VERSION 3.18)
+
+project(adbc_cookbook_recipes_driver
+        VERSION "1.0.0"
+        LANGUAGES CXX)
+
+include(CTest)
+include(FetchContent)
+
+set(CMAKE_CXX_STANDARD 17)
+
+set(NANOARROW_IPC ON)
+set(NANOARROW_NAMESPACE "DriverExamplePrivate")
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+fetchcontent_declare(nanoarrow
+                     URL "https://www.apache.org/dyn/closer.lua?action=download&filename=arrow/apache-arrow-nanoarrow-0.6.0/apache-arrow-nanoarrow-0.6.0.tar.gz"
+                     URL_HASH SHA256=e4a02ac51002ad1875bf09317e70adb959005fad52b240ff59f73b970fa485d1
+)
+fetchcontent_makeavailable(nanoarrow)
+
+# TODO: We could allow this to be installed + linked to as a target; however,
+# fetchcontent is a little nicer for this kind of thing (statically linked
+# pinned version of something that doesn't rely on a system library).
+add_library(adbc_driver_framework ../../../../c/driver/framework/utility.cc
+                                  ../../../../c/driver/framework/objects.cc)
+target_include_directories(adbc_driver_framework PRIVATE ../../../../c
+                                                         ../../../../c/include)
+target_link_libraries(adbc_driver_framework PRIVATE nanoarrow::nanoarrow)
+
+add_library(driver_example SHARED driver_example.cc)
+target_include_directories(driver_example PRIVATE ../../../../c ../../../../c/include)
+target_link_libraries(driver_example PRIVATE adbc_driver_framework
+                                             nanoarrow::nanoarrow_ipc)
+
+if(ADBC_DRIVER_EXAMPLE_BUILD_TESTS)
+  fetchcontent_declare(googletest
+                       URL https://github.com/google/googletest/archive/refs/tags/v1.15.1.tar.gz
+                       URL_HASH SHA256=5052e088b16bdd8c6f0c7f9cafc942fd4f7c174f1dac6b15a8dd83940ed35195
+  )
+  fetchcontent_makeavailable(googletest)
+
+  find_package(AdbcDriverManager REQUIRED)
+
+  add_executable(driver_example_test driver_example_test.cc)
+  target_link_libraries(driver_example_test
+                        PRIVATE gtest_main driver_example
+                                AdbcDriverManager::adbc_driver_manager_shared)
+
+  include(GoogleTest)
+  gtest_discover_tests(driver_example_test)
+
+endif()