Allow usage of rusqlite unbundled feature

[svenstaro]

Summary 💡

We use both sqlx and gitoxide in the same project. Or rather, we're trying to use this but it fails with:

error: failed to select a version for `libsqlite3-sys`.
    ... required by package `rusqlite v0.36.0`
    ... which satisfies dependency `rusqlite = "^0.36.0"` of package `gitoxide-core v0.48.0`
    ... which satisfies dependency `gitoxide-core = "^0.48.0"` of package `gitoxide v0.45.0`
...
versions that meet the requirements `^0.34.0` are: 0.34.0

package `libsqlite3-sys` links to the native library `sqlite3`, but it conflicts with a previous package which links to `sqlite3` as well:
package `libsqlite3-sys v0.30.1`
    ... which satisfies dependency `libsqlite3-sys = "^0.30.1"` of package `sqlx-sqlite v0.8.6`
    ... which satisfies dependency `sqlx-sqlite = "=0.8.6"` of package `sqlx v0.8.6`
...
Only one package in the dependency graph may specify the same links value. This helps ensure that only one copy of a native library is linked in the final binary. Try to adjust your dependencies so that only one package uses the `links = "sqlite3"` value. For more information, see https://doc.rust-lang.org/cargo/reference/resolver.html#links.

failed to select a version for `libsqlite3-sys` which could resolve this conflict

The problem is that this is a statically linked C dependency and both sqlx and gitoxide try to pull in the bundled version of sqlite by default.

However, this has a somewhat easy fix in that rusqlite supports the unbundled more where it will try to find a system libsqlite3 and will merely provide the bindings to that library. sqlx already supports using this but gitoxide-core hardcodes it to bundled. I think it would be great if the gitoxide feature flags allowed for using the system-installed version via the rusqlite unbundled feature.

Motivation 🔦

Allow for using multiple libraries that depend on sqlite in a single Rust project.

[Skgland]

The problem appears to be a conflict between libsqlite3-sys 0.34 and libsqlite3-sys 0.30 which should have nothing to do with bundled/unbundled-ness.

Not wanting to discount the usefulness of supporting unbundled, but it isn't the cause/solution for the conflict.

[Byron]

Thanks for reporting.

Could you explain how you are using the gitoxide crate? As a matter of fact, nobody should use it as it's a binary crate. gitoxide-core is the implementation of CLI invocations, and gix is the library crate that people would want to use.

[svenstaro]

Yeah, I switched to gix after fighting with this for a bit. Frankly, it wasn't so clear to me which one was for library users and which one was for CLI users. As such, I'm not sure this issue is actually still valid.

[Byron]

Thanks for the clarification!

Even though the issue reflects a valid usability issues, I have to close it as no action is possible.
However, if you were to remember how you got the idea of using gitoxide, maybe there was reading material on your way that could be improved? In that case, please do submit a PR with clarifications or some bold text to help prevent such issues in future.
Thanks again.

[svenstaro]

There currently isn't really a user guide on where to go if you want to use this as a library. The repo README should acknowledge that there are two different entrypoints and currently I don't see it doing that. Would be great if it could be improved in that way. I'm not knowledgeable enough with this project yet to suggest a good way to structure such a fundamental guide.

[Byron]

Thanks!

The first two sentences of the readme are:

gitoxide is an implementation of git written in Rust for developing future-proof applications which strive for correctness and performance while providing a pleasant and unsurprising developer experience.

gitoxide provides the gix and ein binaries for use on the command-line to allow experimentation with key features like fetch and clone, and to validate the usability and control of the API offered by the gix crate.

There it mentions the gix crate. Maybe it should explicitly discourage using the gitoxide crate?

[svenstaro]

I think therein lies the problem for me:

gitoxide provides the gix and ein binaries for use on the command-line to allow experimentation with key features like fetch and clone, and to validate the usability and control of the API offered by the gix crate.

It mentions the gix binary and then the gix crate. If I have no idea about this tool then I would suppose that the gix crate is responsible for the gix binary (which is not the case).

I think the two entrypoints should be explicitly called out. Maybe something like:

gitoxide is an implementation of git written in Rust for developing future-proof applications which strive for correctness and performance while providing a pleasant and unsurprising developer experience.

There are two primary ways to use gitoxide:

1. As CLI binaries: The provided binaries gix and ein for use on the command-line allow experimentation with key features like fetch and clone, and to validate the usability.
2. As a Rust library: Use the gix crate in your project to access the features offered by gitoxide programmatically.

Maybe the wording can be improved but something along these lines perhaps. You can see my emphasis on making the user understands these are different things right away.

[Byron]

That's great, thanks so much!

Could you create a PR for this? Otherwise I would do that, but I'd have trouble to specify the correct Co-authored-by string to match with your GitHub persona, while not wanting to claim I authored it.

[svenstaro]

Alright, see #2096.