Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 33 commits into from
Oct 29, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
dc0485b
sketch driver stub recipe
paleolimbot Sep 24, 2024
e4936a3
more complete stubs
paleolimbot Sep 24, 2024
fc3d63a
maybe?
paleolimbot Sep 24, 2024
70d1dda
dev
paleolimbot Sep 24, 2024
de9f860
remove
paleolimbot Sep 24, 2024
71a94b5
add back as executable
paleolimbot Sep 24, 2024
029329d
include what you use
paleolimbot Sep 24, 2024
0c1281c
much prose
paleolimbot Sep 24, 2024
b141b72
implement driver
paleolimbot Sep 25, 2024
24ab3d7
high level explain
paleolimbot Sep 25, 2024
99815db
consolidate recipe build script
paleolimbot Oct 17, 2024
d070c99
maybe make it build
paleolimbot Oct 17, 2024
b71f7cb
maybe fix python doc build
paleolimbot Oct 17, 2024
1cc1580
spelling
paleolimbot Oct 17, 2024
07d6b8e
see if one more pic works
paleolimbot Oct 18, 2024
1793e31
try global pic
paleolimbot Oct 18, 2024
fc9b19a
maybe?
paleolimbot Oct 18, 2024
2ee161e
used shared driver manager?
paleolimbot Oct 18, 2024
6d53dc3
maybe example for test
paleolimbot Oct 19, 2024
c307b55
fix uninitialized ptr
paleolimbot Oct 19, 2024
3823ef5
more docs
paleolimbot Oct 19, 2024
ec96756
revert "fix"
paleolimbot Oct 21, 2024
f004583
lint
paleolimbot Oct 21, 2024
64aade2
typos
paleolimbot Oct 21, 2024
6ac4ee9
set up nanoarrow
paleolimbot Oct 28, 2024
d202e89
attempt linking
paleolimbot Oct 28, 2024
caa8d04
fingers crossed
paleolimbot Oct 28, 2024
27504b7
maybe fill in missing link
paleolimbot Oct 28, 2024
3a549b6
Fix parsing of C++ doxygen entities
lidavidm Oct 29, 2024
9b38eae
More parsing fixes
lidavidm Oct 29, 2024
bb4664c
Fix indent
lidavidm Oct 29, 2024
4db29f7
Make example debuggable
lidavidm Oct 29, 2024
78b3622
fix
lidavidm Oct 29, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 3 additions & 8 deletions c/apidoc/Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 \
Expand Down
1 change: 1 addition & 0 deletions c/driver/framework/status.h
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,7 @@ class Status {
#undef STATUS_CTOR

private:
/// \brief Private Status implementation details
struct Impl {
// invariant: code is never OK
AdbcStatusCode code;
Expand Down
17 changes: 10 additions & 7 deletions ci/scripts/cpp_recipe.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand All @@ -49,4 +51,5 @@ main() {
--no-tests=error
}

main "$@"
test_recipe "docs/source/cpp/recipe" "$@"
test_recipe "docs/source/cpp/recipe_driver" "$@"
4 changes: 4 additions & 0 deletions ci/scripts/r_build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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 "$@"
49 changes: 49 additions & 0 deletions docs/source/cpp/driver_example.rst
Original file line number Diff line number Diff line change
@@ -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")
1 change: 1 addition & 0 deletions docs/source/cpp/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -25,4 +25,5 @@ C and C++
quickstart
driver_manager
concurrency
driver_example
api/index
69 changes: 69 additions & 0 deletions docs/source/cpp/recipe_driver/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -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()
Loading
Loading