| Message ID | 20260114052914.26432-1-kieran.bingham@ideasonboard.com |
|---|---|
| State | New |
| Headers | show |
| Series |
|
| Related | show |
2026. 01. 14. 6:29 keltezéssel, Kieran Bingham írta: > Changes between releases may require updates to user applications > and ABI changes will require a recompilation of applications. > > Track changes which have an impact on the ABI or API to support > users migrating to a newer release. > > Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> > --- I was under the impression that we want to make this part of the documentation? In a kind of "version history" / "release notes" style. I actually quite like how meson does this[0]. And in the repository, they have a folder[1] that contains every release note chunk. When a release is made, these files are merged together into a final "Release-notes-for-X.Y.Z.md". And additionally, release notes for the development version can also be generated easily. Thoughts? [0]: https://mesonbuild.com/Release-notes.html [1]: https://github.com/mesonbuild/meson/tree/master/docs/markdown/snippets [2]: https://github.com/mesonbuild/meson/blob/master/docs/genrelnotes.py > ABI | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 50 insertions(+) > create mode 100644 ABI > > diff --git a/ABI b/ABI > new file mode 100644 > index 000000000000..f2772402225f > --- /dev/null > +++ b/ABI > @@ -0,0 +1,50 @@ > +# ABI/API Compatibility log > + > +This file reports on ABI and API changes which occur between releases. > + > +The ABI can be checked and verified with the abi-checker tool. To report on the > +ABI and API compatibility of your local tree against the latest release, simply > +run: > + > + ./utils/abi-compat.sh > + > +To check the API and ABI compatibility of a single commit specify the previous > +commit as the start point: > + > + ./utils/abi-compat.sh $COMMIT^ $COMMIT > + > +## v0.7 > + > +Commit: b7ed763f0dfb ("libcamera: request: Make controls_ a class instance") > + struct Request > + - Size of this type has been changed from 80 bytes to 152 bytes. The specific sizes are quite platform dependent, so I wouldn't list them. > + The fields or parameters of such data type may be incorrectly initialized or > + accessed by old client applications. > + > + - Type of field controls_ has been changed from struct ControlList* (8 bytes) > + to struct ControlList (80 bytes). > + Size of the inclusive type has been changed. > + > + Impact: > + > + The Request->controls() now has the ControlList allocated directly inside the > + Request object. There is no API impact, but the change to the size and > + offsets of the Request object is an ABI breakage and requires re-compilation > + of users. > + > + > +Commit: dce2ef36f2ef ("libcamera: request: Move metadata_ to Private") > + struct Request > + - Size of this type has been changed from 88 bytes to 80 bytes. > + The fields or parameters of such data type may be incorrectly initialized or > + accessed by old client applications. > + > + - Field metadata_ has been removed from this type. > + Size of the inclusive type has been changed. > + > + Impact: > + > + The Request->metadata() usage now returns a const reference to the underlying > + metadata control list. Users can not modify this data. The size and offsets > + of the Request object is an ABI breakage and requires re-compilation of users. > +
Quoting Barnabás Pőcze (2026-01-14 08:45:17) > 2026. 01. 14. 6:29 keltezéssel, Kieran Bingham írta: > > Changes between releases may require updates to user applications > > and ABI changes will require a recompilation of applications. > > > > Track changes which have an impact on the ABI or API to support > > users migrating to a newer release. > > > > Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> > > --- > > I was under the impression that we want to make this part of the documentation? > In a kind of "version history" / "release notes" style. Yes - I thought this was a starting point for that. But you're right - instead of a text file - it could go directly to the generated documentation. > I actually quite like how meson does this[0]. And in the repository, they have a folder[1] > that contains every release note chunk. When a release is made, these files are merged > together into a final "Release-notes-for-X.Y.Z.md". And additionally, release notes for > the development version can also be generated easily. > > Thoughts? > > [0]: https://mesonbuild.com/Release-notes.html > [1]: https://github.com/mesonbuild/meson/tree/master/docs/markdown/snippets > [2]: https://github.com/mesonbuild/meson/blob/master/docs/genrelnotes.py I already have a script to semi-automate releases and release notes - so indeed we could extend that with something like this! Are the snippets removed at release time to start again when they are merged or such then ? > > ABI | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 50 insertions(+) > > create mode 100644 ABI > > > > diff --git a/ABI b/ABI > > new file mode 100644 > > index 000000000000..f2772402225f > > --- /dev/null > > +++ b/ABI > > @@ -0,0 +1,50 @@ > > +# ABI/API Compatibility log > > + > > +This file reports on ABI and API changes which occur between releases. > > + > > +The ABI can be checked and verified with the abi-checker tool. To report on the > > +ABI and API compatibility of your local tree against the latest release, simply > > +run: > > + > > + ./utils/abi-compat.sh > > + > > +To check the API and ABI compatibility of a single commit specify the previous > > +commit as the start point: > > + > > + ./utils/abi-compat.sh $COMMIT^ $COMMIT > > + > > +## v0.7 > > + > > +Commit: b7ed763f0dfb ("libcamera: request: Make controls_ a class instance") > > + struct Request > > + - Size of this type has been changed from 80 bytes to 152 bytes. > > The specific sizes are quite platform dependent, so I wouldn't list them. They come directly from the abi-compat tool. Indeed, they'll be platform specific - but I was trying to be as clear as possible about what the impact was. Ideally perhaps the snippets could be automatically generated by the tooling too - so I'm probably not too concerned about the specific numbers ... but reporting how it changes (size went up/ size went down) etc ... is probably helpful context ? > > > + The fields or parameters of such data type may be incorrectly initialized or > > + accessed by old client applications. > > + > > + - Type of field controls_ has been changed from struct ControlList* (8 bytes) > > + to struct ControlList (80 bytes). > > + Size of the inclusive type has been changed. > > + The impact section I wrote myself, as an example for showing what we might say about a change - but the section above is the generated text from the tool reformatted. > > + Impact: > > + > > + The Request->controls() now has the ControlList allocated directly inside the > > + Request object. There is no API impact, but the change to the size and > > + offsets of the Request object is an ABI breakage and requires re-compilation > > + of users. > > + > > + > > +Commit: dce2ef36f2ef ("libcamera: request: Move metadata_ to Private") > > + struct Request > > + - Size of this type has been changed from 88 bytes to 80 bytes. > > + The fields or parameters of such data type may be incorrectly initialized or > > + accessed by old client applications. > > + > > + - Field metadata_ has been removed from this type. > > + Size of the inclusive type has been changed. > > + > > + Impact: > > + > > + The Request->metadata() usage now returns a const reference to the underlying > > + metadata control list. Users can not modify this data. The size and offsets > > + of the Request object is an ABI breakage and requires re-compilation of users. > > + >
Quoting Barnabás Pőcze (2026-01-14 09:45:17) > 2026. 01. 14. 6:29 keltezéssel, Kieran Bingham írta: > > Changes between releases may require updates to user applications > > and ABI changes will require a recompilation of applications. > > > > Track changes which have an impact on the ABI or API to support > > users migrating to a newer release. > > > > Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> > > --- > > I was under the impression that we want to make this part of the documentation? > In a kind of "version history" / "release notes" style. > > I actually quite like how meson does this[0]. And in the repository, they have a folder[1] > that contains every release note chunk. When a release is made, these files are merged > together into a final "Release-notes-for-X.Y.Z.md". And additionally, release notes for > the development version can also be generated easily. I also think it would be nice to have that as part of the documentation (and it should be updated for release v0.x during development). Maybe splitting and adding tooling like meson does is an overkill for now? We might risk to not get it in at all. > > Thoughts? > > [0]: https://mesonbuild.com/Release-notes.html > [1]: https://github.com/mesonbuild/meson/tree/master/docs/markdown/snippets > [2]: https://github.com/mesonbuild/meson/blob/master/docs/genrelnotes.py > > > > ABI | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 50 insertions(+) > > create mode 100644 ABI > > > > diff --git a/ABI b/ABI > > new file mode 100644 > > index 000000000000..f2772402225f > > --- /dev/null > > +++ b/ABI > > @@ -0,0 +1,50 @@ > > +# ABI/API Compatibility log > > + > > +This file reports on ABI and API changes which occur between releases. > > + > > +The ABI can be checked and verified with the abi-checker tool. To report on the > > +ABI and API compatibility of your local tree against the latest release, simply > > +run: > > + > > + ./utils/abi-compat.sh > > + > > +To check the API and ABI compatibility of a single commit specify the previous > > +commit as the start point: > > + > > + ./utils/abi-compat.sh $COMMIT^ $COMMIT > > + > > +## v0.7 > > + > > +Commit: b7ed763f0dfb ("libcamera: request: Make controls_ a class instance") > > + struct Request > > + - Size of this type has been changed from 80 bytes to 152 bytes. > > The specific sizes are quite platform dependent, so I wouldn't list them. > > > > + The fields or parameters of such data type may be incorrectly initialized or > > + accessed by old client applications. > > + > > + - Type of field controls_ has been changed from struct ControlList* (8 bytes) > > + to struct ControlList (80 bytes). > > + Size of the inclusive type has been changed. > > + > > + Impact: > > + > > + The Request->controls() now has the ControlList allocated directly inside the > > + Request object. There is no API impact, but the change to the size and > > + offsets of the Request object is an ABI breakage and requires re-compilation > > + of users. Maybe we should keep these notes as short as possible as the information is basically "No API change, ABI changed, recompilation necessary". I don't know if we should do that per commit or only per release. But that can evolve over time. > > + > > + > > +Commit: dce2ef36f2ef ("libcamera: request: Move metadata_ to Private") > > + struct Request > > + - Size of this type has been changed from 88 bytes to 80 bytes. > > + The fields or parameters of such data type may be incorrectly initialized or > > + accessed by old client applications. > > + > > + - Field metadata_ has been removed from this type. > > + Size of the inclusive type has been changed. > > + > > + Impact: > > + > > + The Request->metadata() usage now returns a const reference to the underlying > > + metadata control list. Users can not modify this data. The size and offsets Do we need to explain that the size and offsets is the ABI break or just that there is an ABI break? > > + of the Request object is an ABI breakage and requires re-compilation of users. Does it require re-compilation "of users" or "of applications"? Best regards, Stefan > > + >
2026. 01. 14. 10:15 keltezéssel, Kieran Bingham írta: > Quoting Barnabás Pőcze (2026-01-14 08:45:17) >> 2026. 01. 14. 6:29 keltezéssel, Kieran Bingham írta: >>> Changes between releases may require updates to user applications >>> and ABI changes will require a recompilation of applications. >>> >>> Track changes which have an impact on the ABI or API to support >>> users migrating to a newer release. >>> >>> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> >>> --- >> >> I was under the impression that we want to make this part of the documentation? >> In a kind of "version history" / "release notes" style. > > Yes - I thought this was a starting point for that. But you're right - > instead of a text file - it could go directly to the generated > documentation. > >> I actually quite like how meson does this[0]. And in the repository, they have a folder[1] >> that contains every release note chunk. When a release is made, these files are merged >> together into a final "Release-notes-for-X.Y.Z.md". And additionally, release notes for >> the development version can also be generated easily. >> >> Thoughts? >> >> [0]: https://mesonbuild.com/Release-notes.html >> [1]: https://github.com/mesonbuild/meson/tree/master/docs/markdown/snippets >> [2]: https://github.com/mesonbuild/meson/blob/master/docs/genrelnotes.py > > I already have a script to semi-automate releases and release notes - so > indeed we could extend that with something like this! > > Are the snippets removed at release time to start again when they are > merged or such then ? They are removed when a release is made. > > > >>> ABI | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ >>> 1 file changed, 50 insertions(+) >>> create mode 100644 ABI >>> >>> diff --git a/ABI b/ABI >>> new file mode 100644 >>> index 000000000000..f2772402225f >>> --- /dev/null >>> +++ b/ABI >>> @@ -0,0 +1,50 @@ >>> +# ABI/API Compatibility log >>> + >>> +This file reports on ABI and API changes which occur between releases. >>> + >>> +The ABI can be checked and verified with the abi-checker tool. To report on the >>> +ABI and API compatibility of your local tree against the latest release, simply >>> +run: >>> + >>> + ./utils/abi-compat.sh >>> + >>> +To check the API and ABI compatibility of a single commit specify the previous >>> +commit as the start point: >>> + >>> + ./utils/abi-compat.sh $COMMIT^ $COMMIT >>> + >>> +## v0.7 >>> + >>> +Commit: b7ed763f0dfb ("libcamera: request: Make controls_ a class instance") >>> + struct Request >>> + - Size of this type has been changed from 80 bytes to 152 bytes. >> >> The specific sizes are quite platform dependent, so I wouldn't list them. > > They come directly from the abi-compat tool. Indeed, they'll be platform > specific - but I was trying to be as clear as possible about what the > impact was. Ideally perhaps the snippets could be automatically > generated by the tooling too - so I'm probably not too concerned about > the specific numbers ... but reporting how it changes (size went up/ > size went down) etc ... is probably helpful context ? I also agree with Stefan that these are probably a bit too long. I think "The type libcamera::Request has changed in an ABI incompatible way." is sufficient. If the API changes, then we could add some notes about migration, but an ABI change requires recompilation, and I suppose most people are not too interested in the specifics, so I would keep it short. > > >> >>> + The fields or parameters of such data type may be incorrectly initialized or >>> + accessed by old client applications. >>> + >>> + - Type of field controls_ has been changed from struct ControlList* (8 bytes) >>> + to struct ControlList (80 bytes). >>> + Size of the inclusive type has been changed. >>> + > > The impact section I wrote myself, as an example for showing what we > might say about a change - but the section above is the generated text > from the tool reformatted. > > >>> + Impact: >>> + >>> + The Request->controls() now has the ControlList allocated directly inside the >>> + Request object. There is no API impact, but the change to the size and >>> + offsets of the Request object is an ABI breakage and requires re-compilation >>> + of users. >>> + >>> + >>> +Commit: dce2ef36f2ef ("libcamera: request: Move metadata_ to Private") >>> + struct Request >>> + - Size of this type has been changed from 88 bytes to 80 bytes. >>> + The fields or parameters of such data type may be incorrectly initialized or >>> + accessed by old client applications. >>> + >>> + - Field metadata_ has been removed from this type. >>> + Size of the inclusive type has been changed. >>> + >>> + Impact: >>> + >>> + The Request->metadata() usage now returns a const reference to the underlying >>> + metadata control list. Users can not modify this data. The size and offsets >>> + of the Request object is an ABI breakage and requires re-compilation of users. >>> + >>
diff --git a/ABI b/ABI new file mode 100644 index 000000000000..f2772402225f --- /dev/null +++ b/ABI @@ -0,0 +1,50 @@ +# ABI/API Compatibility log + +This file reports on ABI and API changes which occur between releases. + +The ABI can be checked and verified with the abi-checker tool. To report on the +ABI and API compatibility of your local tree against the latest release, simply +run: + + ./utils/abi-compat.sh + +To check the API and ABI compatibility of a single commit specify the previous +commit as the start point: + + ./utils/abi-compat.sh $COMMIT^ $COMMIT + +## v0.7 + +Commit: b7ed763f0dfb ("libcamera: request: Make controls_ a class instance") + struct Request + - Size of this type has been changed from 80 bytes to 152 bytes. + The fields or parameters of such data type may be incorrectly initialized or + accessed by old client applications. + + - Type of field controls_ has been changed from struct ControlList* (8 bytes) + to struct ControlList (80 bytes). + Size of the inclusive type has been changed. + + Impact: + + The Request->controls() now has the ControlList allocated directly inside the + Request object. There is no API impact, but the change to the size and + offsets of the Request object is an ABI breakage and requires re-compilation + of users. + + +Commit: dce2ef36f2ef ("libcamera: request: Move metadata_ to Private") + struct Request + - Size of this type has been changed from 88 bytes to 80 bytes. + The fields or parameters of such data type may be incorrectly initialized or + accessed by old client applications. + + - Field metadata_ has been removed from this type. + Size of the inclusive type has been changed. + + Impact: + + The Request->metadata() usage now returns a const reference to the underlying + metadata control list. Users can not modify this data. The size and offsets + of the Request object is an ABI breakage and requires re-compilation of users. +
Changes between releases may require updates to user applications and ABI changes will require a recompilation of applications. Track changes which have an impact on the ABI or API to support users migrating to a newer release. Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> --- ABI | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 ABI