docs: document driver binary and entrypoint naming convention

[abonander]

What feature or improvement would you like to see?

When I first set up adbc_clickhouse, I didn't realize that there was an expected naming convention for ADBC drivers: ClickHouse/adbc_clickhouse#66

As of writing, this is not really documented anywhere:

• https://arrow.apache.org/adbc/24/driver/authoring.html
• https://arrow.apache.org/adbc/24/format/driver_manifests.html

The only discussion I found regarding naming conventions in my initial research was in the docs for adbc_ffi::export_driver!(), which doesn't prescribe a naming convention but just explains how the entrypoint symbol lookup works: https://docs.rs/adbc_ffi/0.23.0/adbc_ffi/macro.export_driver.html

I chose adbc_clickhouse (and AdbcClickhouseInit) because it felt more concise than adbc_driver_clickhouse (and AdbcDriverClickhouseInit) while still seeming to work for the rules laid out by export_driver!(). It loaded just fine with the Rust adbc_driver_manager crate.

The example dummy driver for Rust appears to support this choice:

• arrow-adbc/rust/driver/dummy/Cargo.toml

  Line 19 in f1d6412

  name = "adbc_dummy"

• arrow-adbc/rust/driver/dummy/src/lib.rs

  Line 941 in f1d6412

  adbc_ffi::export_driver!(AdbcDummyInit, DummyDriver);

However, it sounds like some driver managers specifically look for AdbcDriver*Init and break if you try to load a driver that doesn't follow that convention. Unfortunately, ClickHouse/adbc_clickhouse#66 is all the context I have here.

To work around this, the driver binary ends up getting renamed during the release process to libadbc_driver_clickhouse.so: https://github.com/adbc-drivers/clickhouse/blob/main/src/ci/scripts/build.sh#L46

And an additional AdbcDriverClickhouseInit entrypoint gets added for compatibility with old driver managers that don't recognize the entrypoint manifest key: https://github.com/adbc-drivers/clickhouse/blob/41ef9369dae4c594edc926cdf6858140a949cdb3/src/ci/scripts/pre-build.sh#L33-L39

I'm not really comfortable with this situation because it means the driver installed through dbc has a different filename and entrypoint than if the driver is built manually, which could confuse and frustrate users trying to contribute to the driver or test the latest changes on main.

We're prepared to resolve this for good on our end (ClickHouse/adbc_clickhouse#75). However, this could have been avoided if the expected naming conventions were documented better.

[ianmcook]

Thanks @abonander. Let's also document this in https://adbc-drivers.org/building-drivers/.

[zeroshade]

After some discussion, I've come to the following result:

We should definitely update the documentation of adbc-drivers.org/building-drivers/ to state that while adbc_driver_{name} is recommended it is by no means required. The documentation should point out that if there is no entrypoint defined in the manifest, the way that we derive the default entrypoint is as follows:

1. Remove the extensions and any lib prefix from the library name
2. Split the name at all hyphens and underscores and then join it together using PascalCase with an Init suffix
3. If the entrypoint doesn't start with Adbc we prepend Adbc to it

as a result you get the following:

libadbc_driver_sqlite.so.2.0.0 -> AdbcDriverSqliteInit
adbc_driver_sqlite.dll -> AdbcDriverSqliteInit
proprietary_driver.dll -> AdbcProprietaryDriverInit

Second: We need to fix the C# driver manager which derives an incorrect default entrypoint see

arrow-adbc/csharp/src/Apache.Arrow.Adbc/DriverManager/AdbcDriverManager.cs

Lines 635 to 648 in f1d6412

	const string adbcDriverPrefix = "adbc_driver_";
	const string adbcPrefix = "adbc_";
	if (baseName.StartsWith(adbcDriverPrefix, StringComparison.OrdinalIgnoreCase))
	baseName = baseName.Substring(adbcDriverPrefix.Length);
	else if (baseName.StartsWith(adbcPrefix, StringComparison.OrdinalIgnoreCase))
	baseName = baseName.Substring(adbcPrefix.Length);
	if (string.IsNullOrEmpty(baseName))
	return "AdbcDriverInit";
	// Convert snake_case to PascalCase.
	string pascal = ToPascalCase(baseName);
	return $"AdbcDriver{pascal}Init";

It shouldn't be explicitly removing the adbc_ or adbc_driver_ prefixes and shouldn't be injecting Driver into the final entrypoint name.

@CurtHagenlocher @davidhcoe would one of you be able to please fix the C# Driver Manager so that it matches the behavior mentioned above and thus matches the behavior of all the other driver managers?

Once the C# Driver manager is fixed, and the docs are updated, it shoudn't be necessary to rename or create aliases during the build for the clickhouse driver (unless you want to shift to the recommended adbc_driver_clickhouse anyway.

[CurtHagenlocher]

@CurtHagenlocher @davidhcoe would one of you be able to please fix the C# Driver Manager so that it matches the behavior mentioned above and thus matches the behavior of all the other driver managers?

I'll take a look at this in the next week or so.