[libcamera-devel] versioning
Matthias Fend
matthias.fend at emfend.at
Thu Sep 8 08:51:10 CEST 2022
Am 15.08.2022 um 00:10 schrieb Kieran Bingham:
> Quoting Christian Rauch via libcamera-devel (2022-08-14 22:26:38)
> > Hi Kieran,
> >
> > Am 14.08.22 um 19:01 schrieb Kieran Bingham:
> > > Quoting Christian Rauch (2022-08-14 17:25:48)
> > >> Hi Kieran,
> > >>
> > >> Am 14.08.22 um 16:12 schrieb Kieran Bingham:
> > >>> Hi Christian,
> > >>>
> > >>> Quoting Christian Rauch via libcamera-devel (2022-08-13 22:14:44)
> > >>>> Hi all,
> > >>>>
> > >>>> I am aware that the libcamera API is unstable and because of
> this, there
> > >>>> is no versioning. I am using libcamera in another project, and
> it would
> > >>>> be helpful if I could check some version constraints in order to
> prevent
> > >>>> compiling with an incompatible API.
> > >>>
> > >>> I've been long advocating that we should have a version number, even
> > >>> with an unstable API. The last time I tried to push on this topic we
> > >>> added 0.0.0 at the very first commit which gives us some degree of
> > >>> patchlevel versioning for every commit. It has taken a long time to
> > >>> identify clear reasons /why/ we should have more specific
> versions, when
> > >>> we have a clear unstable API, and we refer to the latest.
> > >>>
> > >>> However as you have reported here, with more API breakages
> recently -
> > >>> having other pacakges compiling against libcamera, they likely
> want to
> > >>> check what is installed. It's not always under the control and can
> > >>> depend upon the installation of the distro.
> > >>>
> > >>>
> > >>>> Would you be willing to start versioning the minor or
> patch-level of
> > >>>> libcamera? I imagine that the major version will stay at "0"
> until the
> > >>>
> > >>> I believe the answer is 'yes' now. But we still need to implement
> the
> > >>> 'how'.
> > >>>
> > >>> Personally - I would like to use something like
> abi-compliance-checker
> > >>> to automatically detect any ABI/API change, and automatically
> increment
> > >>> the minor patch level. libabigail looks interesting and relevant
> too:
> > >>>
> https://developers.redhat.com/blog/2020/04/02/how-to-write-an-abi-compliance-checker-using-libabigail#
>
> > >>>
> > >>> That would give us a version scheme of:
> > >>>
> > >>> 0.a[bp]i.patch
> > >>>
> > >>> Where other packages and applications could then use the second
> value to
> > >>> determine if they are compatible, (or to make conditional changes
> to be
> > >>> compilation compatible).
> > >>>
> > >>> The patch level of course would just be the number of patches
> since that
> > >>> change, and the leading version 0, would not be incremented until we
> > >>> were at a point that we could be comfortable stating we are 'ABI
> stable'.
> > >>>
> > >>>
> > >>>> API is stable, but that either the minor or patch-level could be
> > >>>> incremented (0.1, 0.2, ...) every time the API changes, or
> simply on a
> > >>>> monthly or quarterly basis.
> > >>>
> > >>> Every time I've suggested we should start making release versions, I
> > >>> always face push back of "What decrees a release, when should it be
> > >>> made?".
> > >>>
> > >>> To me time based milestones are acceptable, but don't make it
> > >>> easy/straightforwards to perform the version specific compilation
> > >>> changes required.
> > >>>
> > >>> I think they help users understand how new or old the library is
> though,
> > >>> and at least that is more helpful than our current versioning scheme
> > >>> where comparing 074fa98ac4e against 18d61deb3c0 is just not human
> > >>> readable, and doesn't convey any useful information. We have
> tagged our
> > >>> first commit as 0.0.0 which does now at least provide version
> strings
> > >>> generated by utils/gen-version.sh:
> > >>>
> > >>> - 0.0.0+2819-18d61deb
> > >>> - 0.0.0+3459-074fa98a
> > >>>
> > >>> So we could already say we could (manually) identify API/ABI changes
> > >>> between the patch level numbers after the + (2819, to 3459) - but
> that's
> > >>> quite labour intensive otherwise and prone to error, which is why
> I'd
> > >>> really like to see API/ABI breakages identifiable through
> something like
> > >>>
> > >>>
> > >>> - 0.25.245-18d61deb
> > >>> - 0 29.15-074fa98a
> > >>>
> > >>> Which we can then parse and extract more useful information from.
> > >>>
> > >>> I would envisage the automatic abi checker to be able to provide the
> > >>> 0.<abi> tags automatically on every change if run on every commit
> (and
> > >>> could be back dated right to the beginning of the tree history) ...
> > >>> however the point I have difficulty with is how we get those tags to
> > >>> then convey the correct information about the release in external
> > >>> systems.
> > >>>
> > >>> Is a 'tag' sufficient? or do we have to (for every 'release')
> manually
> > >>> edit the meson.build version string, or make other manual explicit
> > >>> changes.
> > >>>
> > >>> If we can do something around simply adding a tag on every abi/api
> > >>> version change, - I think that would provide the
> cleanest/simplest way
> > >>> forwards for now.
> > >>>
> > >>> Any ideas or extended comments?
> > >>
> > >> I have seen CMake projects generating the version information from
> git.
> > >> This somehow works that a git command is executed as part of the
> build
> > >> process and then the stdout is parsed. Of course, this only works
> when
> > >> the source is checked out as a git repo. But I think something
> similar
> > >> could be done in meson. Then, you only need to create a new git
> tag and
> > >
> > > We already do this.
> > >
> > > https://git.libcamera.org/libcamera/libcamera.git/tree/meson.build#n13
> > >
> > > meson calls utils/gen-version.sh which generates a version string such
> > > as :
> > >
> > > 0.0.0+3829-f88d73af
> > >
> > > But it only works when the source is checked out as a git repo indeed.
> > >
> > > How does that compare for your current needs against the discussions
> > > above?
> >
> > I overlooked that, but this is generally how I've seen this in CMake.
> > But the git repo does not have version tags yet, so there is nothing to
>
> Really? It should.
>
> kbingham at Q:/tmp$ git clone
> https://git.libcamera.org/libcamera/libcamera.git
> Cloning into 'libcamera'...
> remote: Enumerating objects: 31196, done.
> remote: Counting objects: 100% (31196/31196), done.
> remote: Compressing objects: 100% (11093/11093), done.
> remote: Total 31196 (delta 24129), reused 26079 (delta 19945)
> Receiving objects: 100% (31196/31196), 5.65 MiB | 7.29 MiB/s, done.
> Resolving deltas: 100% (24129/24129), done.
> kbingham at Q:/tmp$ cd libcamera/
> kbingham at Q:/tmp/libcamera$ ./utils/gen-version.sh
> 0.0.0+3830-dfc6d711
>
> kbingham at Q:/tmp/libcamera$ cd ..
> kbingham at Q:/tmp$ rm -rf libcamera/
> kbingham at Q:/tmp$ git clone https://git.linuxtv.org/libcamera.git/
> Cloning into 'libcamera'...
> remote: Enumerating objects: 31197, done.
> remote: Counting objects: 100% (31197/31197), done.
> remote: Compressing objects: 100% (6802/6802), done.
> remote: Total 31197 (delta 24237), reused 31197 (delta 24237)
> Receiving objects: 100% (31197/31197), 5.84 MiB | 5.37 MiB/s, done.
> Resolving deltas: 100% (24237/24237), done.
> kbingham at Q:/tmp$ cd libcamera/
> kbingham at Q:/tmp/libcamera$ ./utils/gen-version.sh
> 0.0.0+3829-dfc6d711
I also have a small note on this.
In cases where libcamera is downloaded and built as a snapshot (without
a git repository) but libcamera is in a subdirectory of another git
repository, then the git information from that repository is used for
version generation and the version is accordingly wrong.
This can be the case, for example, when libcamera is built by a build
system.
A possible solution to this would be to modify the git check during
version generation so that it not only checks whether the script is in a
git work tree, but whether it is actually in the version management
itself.
As an alternative a meson option to disable git based version generation
could also be a way.
I know this is an edge case, but if the versioning is likely to change
anyway, then maybe this point could be considered as well.
Thanks
~Matthias
>
> Are you using one of the official sources above? I've just seen that my
> personal fork on github doesn't have a tag, so I'll update it there.
>
> > extract. The *.pc file ("libcamera.pc") just contains "Version: 0.0.0".
>
> > > Kieran
> > >
> > >
> > >> the next time libcamera is compiled, it would generate the version.
> > >>
> > >>>
> > >>>
> > >>>> This way, projects could check for a specific version before
> compiling
> > >>>> or search for a specific "API version". It wouldn't guarantee
> that the
> > >>>> API is compatible between versions, it's just useful to know which
> > >>>> version you have to use to compile a project.
> > >>>
> > >>> Agreed!
> > >>>
> > >>> It's also clear from other recent discussions that we should bump
> the
> > >>> SONAME for every ABI breakage, so again - if this can be handled
> through
> > >>> automatically detecting those breakages - I think that would help
> too.
> > >>> Having the SONAME as 0.<abi-version> as above would be a great
> benefit
> > >>> already I think.
> > >>>
> > >>> --
> > >>> Kieran
> > >>>
> > >>>
> > >>>> Best,
> > >>>> Christian
> > >>>>
More information about the libcamera-devel
mailing list