Skip to content

install.md

Latest commit

 

History

History
87 lines (66 loc) · 3.78 KB

install.md

File metadata and controls

87 lines (66 loc) · 3.78 KB
Raw

Build, install and the driver manifest

The repository build, the install layout on each platform, and how driver="odbc" resolves by name. Per-platform walkthroughs: Linux, macOS, Windows.

Build

sudo apt install unixodbc-dev cmake        # Debian/Ubuntu
brew install unixodbc cmake                # macOS
# Windows: the ODBC driver manager ships with the OS
cmake -S . -B build && cmake --build build
# -> build/libadbc_driver_odbc.so

Install

For a no-root user install, use install.sh (see Quick start); it wraps the CMake commands below with PREFIX=~/.local and the manifest going to the ADBC user config directory. PREFIX, MANIFEST_DIR, BUILD_DIR, BUILD_TYPE and JOBS override the defaults. Otherwise, install by hand:

cmake --install build --prefix /usr/local

This installs two things:

  • <prefix>/lib/libadbc_driver_odbc.so (lib64 on Fedora/RHEL-style 64-bit systems, per CMake's GNUInstallDirs; bin\libadbc_driver_odbc.dll on Windows)
  • <prefix>/etc/adbc/drivers/odbc.toml — an ADBC driver manifest pointing at the installed library

The manifest is what lets applications ask for the driver by name instead of by path (see below). Pass -DADBCBRIDGE_INSTALL_MANIFEST=OFF to skip it, or -DADBCBRIDGE_MANIFEST_DIR=<dir> to install it elsewhere — relative to the install prefix (share/adbc/drivers) or absolute (/etc/adbc/drivers).

The absolute library path inside the manifest is computed while cmake --install runs, not at configure time. A single build tree can therefore be installed into as many prefixes as you like — /usr/local, "$VIRTUAL_ENV", a packaging staging root via DESTDIR= — and every installed manifest points at its own copy of the library.

Use by name (driver manifest)

With the manifest installed somewhere the ADBC driver manager searches, every binding can load adbcBridge as simply odbc:

import adbc_driver_manager.dbapi as dbapi

conn = dbapi.connect(
    driver="odbc",   # resolved via <prefix>/etc/adbc/drivers/odbc.toml
    db_kwargs={"uri": "Driver=SQLite3;Database=my.db;"},
)

The driver manager looks for odbc.toml in, among others:

location how to use it
$ADBC_DRIVER_PATH colon-separated list of directories (;-separated on Windows)
<sys.prefix>/etc/adbc/drivers added by the Python driver manager inside a virtualenv: cmake --install build --prefix "$VIRTUAL_ENV"
~/.config/adbc/drivers per-user install: what ./install.sh uses ($XDG_CONFIG_HOME/adbc/drivers if set); by hand, -DADBCBRIDGE_MANIFEST_DIR="$HOME/.config/adbc/drivers"
/etc/adbc/drivers system-wide install: configure with -DADBCBRIDGE_MANIFEST_DIR=/etc/adbc/drivers, then cmake --install build --prefix /usr

On macOS the user/system directories are ~/Library/Application Support/ADBC/Drivers and /Library/Application Support/ADBC/Drivers; on Windows the driver manager also reads HKEY_CURRENT_USER\SOFTWARE\ADBC\Drivers and the machine-wide equivalent.

Loading by path keeps working, and is what you want for a build tree: driver="/path/to/libadbc_driver_odbc.so".

If driver="odbc" fails with

dlsym(AdbcDriverInit) failed: .../libodbc.so: undefined symbol: AdbcDriverInit

then no manifest was found, and the driver manager fell back to loading a plain shared library named odbc — which on Unix is unixODBC's own driver manager, not this driver. Check that the directory holding odbc.toml is one of the locations above, and that the path recorded inside odbc.toml exists.