lidavidm commented on code in PR #2186: URL: https://github.com/apache/arrow-adbc/pull/2186#discussion_r1818004126
########## docs/source/cpp/recipe_driver/driver_example.cc: ########## @@ -0,0 +1,304 @@ +// 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. + +// RECIPE STARTS HERE + +/// Here we'll show the structure of building an ADBC driver in C++ using +/// the ADBC driver framework library. This is the same library that ADBC +/// uses to build its SQLite and PostgreSQL drivers and abstracts away +/// the details of C callables and catalog/metadata functions that can be +/// difficult to implement but are essential for efficiently leveraging +/// the rest of the ADBC ecosystem. +/// +/// At a high level, we'll be building a driver whose "database" is a directory +/// where each "table" in the database is a file containing an Arrow IPC stream. +/// Tables can be written using the bulk ingest feature and tables can be read +/// with a simple query in the form ``SELECT * FROM (the file)``. +/// +/// Installation +/// ============ +/// +/// This quickstart is actually a literate C++ file. You can clone +/// the repository, build the sample, and follow along. +/// +/// We'll assume you're using conda-forge_ for dependencies. CMake, a +/// C++17 compiler, and the ADBC libraries are required. They can be +/// installed as follows: +/// +/// .. code-block:: shell +/// +/// mamba install cmake compilers libadbc-driver-manager +/// +/// .. _conda-forge: https://conda-forge.org/ +/// +/// Building +/// ======== +/// +/// We'll use CMake_ here. From a source checkout of the ADBC repository: +/// +/// .. code-block:: shell +/// +/// mkdir build +/// cd build +/// cmake ../docs/source/cpp/recipe_driver -DADBC_DRIVER_EXAMPLE_BUILD_TESTS=ON +/// cmake --build . +/// ctest +/// +/// .. _CMake: https://cmake.org/ +/// +/// Building an ADBC Driver using C++ +/// ================================= +/// +/// Let's start with some includes. Notably, we'll need the driver framework +/// header files and nanoarrow_, which we'll use to create and consume the +/// Arrow C data interface structures in this example driver. + +/// .. _nanoarrow: https://arrow.apache.org/nanoarrow + +#include "driver_example.h" + +#include <cstdio> +#include <string> + +#include "driver/framework/connection.h" +#include "driver/framework/database.h" +#include "driver/framework/statement.h" + +#include "nanoarrow/nanoarrow.hpp" +#include "nanoarrow/nanoarrow_ipc.hpp" + +#include "arrow-adbc/adbc.h" + +/// Next, we'll bring a few essential framework types into the namespace +/// to reduce the verbosity of the implementation: +/// +/// * ``Option``: Options can be set on an ADBC database, connection, and Review Comment: I _think_ something like ``` :cpp:class:`adbc::driver::Option` ``` should work now (and eventually result in a proper link to the API docs from the prose docs), though no big deal either way (it can be finicky to set up and test locally) ########## docs/source/cpp/recipe_driver/CMakeLists.txt: ########## @@ -0,0 +1,71 @@ +# 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) + +# TODO: This currently depends on about-to-be-released nanoarrow, which allows +# access to both nanoarrow and the IPC reader using a single fetchcontent. Review Comment: Can we update this now? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
