From 3cef4119f368b9df9cb65523898e0405ae75f987 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Thu, 25 Jul 2024 16:53:39 -0700 Subject: [PATCH] README: document when libgit2 is statically linked I found the previous paragraph in the current version of the README quite confusing. The text follows my understanding of https://github.com/rust-lang/git2-rs/blob/f1f09cee7b332d2b494d14d46fd2ec8e5203916a/libgit2-sys/build.rs#L25-L56. I hope it's OK to hide the bit about `zlib` under the case where an "appropriate version of libgit2 cannot be found". Feel free to edit this further. Cc: commit 59a81cac I looked into this because I was confused that, after upgrading the Homebrew version of libgit2, my builds of https://github.com/martinvonz/jj started linking libgit2 statically. I'm planning to try enabling `vendored_libgit2` in that project permanently and recommending that people use the environment variable `LIBGIT2_NO_VENDOR=1` if they want dynamic linking. --- README.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e66c049d37..e909e4a53b 100644 --- a/README.md +++ b/README.md @@ -19,12 +19,17 @@ stable release as well. Currently this library requires libgit2 1.7.2 (or newer patch versions). The source for libgit2 is included in the libgit2-sys crate so there's no need to pre-install the libgit2 library, the libgit2-sys crate will figure that and/or -build that for you. +build that for you. On the other hand, if an appropriate version of `libgit2` +is present, `git2` will attempt to dynamically link it. -You can enable the Cargo feature `vendored-libgit2` to always compile and -statically link to a copy of libgit2. Sometimes the libgit2 on the system is -required to be found and used even when `vendored-libgit2` is activated. In -this case, you shall set the environment variable `LIBGIT2_NO_VENDOR=1`. +To be more precise, the vendored `libgit2` is linked statically if two +conditions both hold: + +- The enviornment variable `LIBGIT2_NO_VENDOR=1` is **not** set +- **and** either a) The Cargo feature `vendored-libgit2` is set or b) an + appropriate version of `libgit2` cannot be found on the system. + +In particular, note that the environment variable overrides the Cargo feature. ## Building git2-rs