Re: [PATCH libgpiod RFC 3/3] bindings: rust: build against pkg-config info

[Erik Schilling <erik.schilling@linaro.org>]

On 5/23/23 13:25, Erik Schilling wrote:
> This change replaces building against "bundled" headers by always
> building agains system headers (while following standard conventions to
> allow users to specify the version to build against).
> 
> Reasoning:
> 
> Previously, the code generated the bindings based on the headers, but
> then links against `-lgpiod` without further specifying where that is
> coming from.
> 
> This results in some challenges and problems:
> 
> 1. Packaging a Rust crate with `cargo package` requires the folder
>     containing the Cargo.toml to be self-contained. Essentially, a tar
>     ball with all the sources of that folder is created. Building against
>     that tar ball fails, since the headers files passed to bindgen are
>     a relative path pointing outside of that folder.
> 
> 2. While, for example, the cxx bindings are built AND linked against
>     the build results, the packaging situation for C++ libraries is a
>     bit different compared to Rust libs. The C++ libs will likely get
>     built as part of the larger libgpiod build and published together
>     with the C variant.
> 
>     In Rust, the vast majority of people will want to build the glue-code
>     during the compilation of the applications that consume this lib.
> 
>     This may lead to inconsistencies between the bundled headers and the
>     libraries shipped by the user's distro. While ABI should hopefully
>     be forward-compatible within the same MAJOR number of the .so,
>     using too new headers will likely quickly lead to mismatches with
>     symbols defined in the lib.
> 
> 3. Trying to build the core lib as part of the Rust build quickly runs
>     into similar packaging issues as the existing solution. The source
>     code of the C lib would need to become part of some package
>     (often people opt to pull it in as a submodule under their -sys crate
>     or even create a separate -src package [1]). This clearly does not
>     work well with the current setup...
> 
> Since building against system libs is probably? what 90%+ of the people
> want, this change hopefully addresses the problems above. The
> system-deps dependency honors pkg-config conventions, but also allows
> users flexible ways to override the defaults [2]. Overall, this keeps
> things simple while still allowing maximum flexibility.
> 
> Since the pkg-config interface is just telling us which include paths to
> use, we switch back to a wrapper.h file that includes the real gpiod.h.
> 
> Once Rust bindings require a lower version floor, the version metadata
> can also be updated to help telling users that their system library is
> too old.
> 
> Drawback:
> 
> People hacking on the Rust bindings, need to either have a reasonably
> up-to-date system lib, previously install the lib to some folder and
> specify PKG_CONFIG_PATH or set the relevant SYSTEM_DEPS_* environment
> variables. Instructions for developers are documented in the README.
> 
> [1] https://github.com/alexcrichton/openssl-src-rs
> [2] https://docs.rs/system-deps/latest/system_deps/#overriding-build-flags
> 
> Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
> ---
>   README                                | 13 +++++++++++-
>   bindings/rust/libgpiod-sys/Cargo.toml |  4 ++++
>   bindings/rust/libgpiod-sys/build.rs   | 40 +++++++++++++++++++++++------------
>   3 files changed, 42 insertions(+), 15 deletions(-)

Viresh told me on IRC that I forgot the wrapper.h:

diff --git a/bindings/rust/libgpiod-sys/wrapper.h 
b/bindings/rust/libgpiod-sys/wrapper.h
new file mode 100644
index 0000000..8a8bd41
--- /dev/null
+++ b/bindings/rust/libgpiod-sys/wrapper.h
@@ -0,0 +1 @@
+#include <gpiod.h>