This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new ca4b7a36f docs: add a short page about new drivers (#1737)
ca4b7a36f is described below
commit ca4b7a36fa417d46f49597cafa1e794628e4c17a
Author: David Li <[email protected]>
AuthorDate: Mon Apr 22 10:33:23 2024 +0900
docs: add a short page about new drivers (#1737)
Fixes #1718.
---
docs/source/driver/authoring.rst | 44 ++++++++++++++++++++++++++++++++++++++++
docs/source/index.rst | 1 +
2 files changed, 45 insertions(+)
diff --git a/docs/source/driver/authoring.rst b/docs/source/driver/authoring.rst
new file mode 100644
index 000000000..419d7dd3b
--- /dev/null
+++ b/docs/source/driver/authoring.rst
@@ -0,0 +1,44 @@
+.. 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.
+
+===================
+Writing New Drivers
+===================
+
+Currently, new drivers can be written in C#, C/C++, Go, and Java. A driver
+written in C/C++ or Go can be used from either of those languages, as well as
+C#, Python, R, and Ruby. (C# can experimentally export drivers to the same
+set of languges as well.) The Rust API definitions for ADBC are still under
+development, but we plan for them to be on par with C#, C/C++, and Go in this
+respect.
+
+It is so far preferable to write new drivers in Go. C/C++ have had issues
+with dependencies and in particular some not uncommon dependencies in that
+ecosystem tend to cause conflicts when loaded into Python processes and
+elsewhere. (For example, the ADBC Flight SQL driver was originally written in
+C++ but would have conflicted with the grpcio and pyarrow Python packages.)
+It also tends to be easier for us to package and distribute additional Go
+libraries than it is for C/C++.
+
+In Go, some frameworks are available for driver
+authors. `go/adbc/driver/internal/driverbase`_ manages much of the boilerplate
+and basic state management for drivers. `go/adbc/pkg`_ can template out a C
+ABI wrapper around the Go driver. Especially if the driver is planned to go
+upstream, we recommend driver authors consider using these frameworks.
+
+.. _go/adbc/driver/internal/driverbase:
https://github.com/apache/arrow-adbc/tree/main/go/adbc/driver/internal/driverbase
+.. _go/adbc/pkg: https://github.com/apache/arrow-adbc/tree/main/go/adbc/pkg
diff --git a/docs/source/index.rst b/docs/source/index.rst
index e29d26c48..651d54232 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -235,6 +235,7 @@ Why ADBC?
driver/postgresql
driver/snowflake
driver/sqlite
+ driver/authoring
.. toctree::
:maxdepth: 1
