Document the procedure for bumping to a newer aravis version?

[Ekleog]

In the process of trying to get an aravis-rs build with the new functions from AravisProject/aravis#404, I tried to just copy the .gir from my aravis folder and the ones from gtk-rs/gir-files, run gir in the aravis and aravis-sys folders, and then tried to build with it.

However, this eventually led to borrow-checker errors, which makes me assume there's something wrong with what I tried doing (and/or in my gir version).

Would it be possible for you to document what your process for updating to a newer aravis version is, including maybe the version of gir that you use, eg. in the readme? This way other people could maybe more easily contribute version bumps when a new aravis version gets out, and test it locally when it's not out yet :)

Either way, thank you for aravis-rs!

[de-vri-es]

Righty, I'll have to get round to documenting it properly sometime soon, but until then here's what I do:

1. Build Aravis itself from source and copy the Aravis-*.gir to the gir-files folder.
2. Install Aravis so that the build script for the FFI crate can find it. You should be able to install it in a user directory, as long as pkgconf/pkg-config can find it.
3. If you want to update the gtk-rs gir files, you should just update the submodule to the current master. The relevant files are symlinked, so you don't have to copy anything manually.
4. Run the gir tool from gtk-rs in the root of the aravis-sys crate. All required options are taken from the Gir.toml file. You probably need to fix some things in the build script. The generated script from the gir tool writes version checks pkgconf queries that don't actually work for Aravis. You need to tweak aravis-sys/tests/abi.rs for the same reason. Your best bet is to look at the diff and undo anything other than actual version changes. You could try to build first if you want to see how it fails, of course.
5. Run the gir tool in the aravis crate. This time there should be no manual intervention needed.
6. Run cargo fmt in both crates after re-generating the files. Or maybe the gir tool already does that. Can't hurt though :)

If you run into issues with the compiler or borrow checker with this procedure, there may be updates that are incompatible with the manual code in the aravis crate.

[de-vri-es]

Oh, I forget, we also want to put the documentation back. It's stripped by default for licensing reasons, but I think we attribute the documentation to the original Aravis project. (If not, that should still be done.)

7. Run gir -m doc in each crate followed by rust-doc-stripper -g -o vendor.md. You can install rust-doc-stripper from https://crates.io. Don't commit vendor.md itself. Run cargo fmt again after :)

[EmmanuelP]

Hi Maarten,

Oh, I forget, we also want to put the documentation back. It's stripped by default for licensing reasons

What is the issue with the documentation license ?

[de-vri-es]

Hey :)

I don't think there is an issue with the license here. But the gir tool from gtk-rs strips all documentation by default because they're covered by the license of the upstream project, and not the license of the generated bindings. As a safe default, they just remove it.

I think the Aravis license permits redistributing the documentation though, so I prefer to have it included in the code and therefore the autogenerated Rust documentation :)

Although I see now that this is all I included in the LICENSE.md file here:

This license applies to the Rust bindings, not to the Aravis library itself.

That is not very explicit about the license of the documentation. I'll think I'll make it more explicit and also include something in the documentation itself here: https://docs.rs/aravis/.

[de-vri-es]

I updated the Rust crate to Aravis 0.8.1 now. This should provide you with a smaller diff when testing custom versions of Aravis based on 0.8.1.

I also clarified the license/copyright situation a bit. The LICENSE.md file now includes this:

This copyright notice and license apply to the Rust bindings.
They do not apply to the Aravis library itself or it's documentation.
See https://github.com/AravisProject/aravis for more information.

And on docs.rs it says this:

This crate contains (mostly) safe bindings to the Aravis library.

The bindings are mostly auto-generated with the gir tool from the gtk-rs project.

This crate currently targets version 0.8.1 of the Aravis library.

This documentation constist mainly of original documentation of the Aravis project. The copyright and license of the Aravis project apply to those parts. The full original documentation is also available online and might help if the translation to Rust made things unclear.

It's released as 0.4.1 on https://crates.io (I messed up the documentation for 0.4.0).

[Ekleog]

This is awesome, thank you! And sorry for not having answered sooner, I'm just now remembering of this issue ^^' I just wanted to say I no longer personally have a need for this, as I was able to make the crate work properly with a version of aravis that worked too.

Do you want to keep this issue open to track the addition of documentation that'd explain how to bump to a newer aravis version (basically what you wrote in this issue, but in some .md file in the repo), or should we close this? :)