[OSS-Tools] [PATCH dt-utils] meson: align libdt-utils version with autotools'

[OSS-Tools] [PATCH dt-utils] meson: align libdt-utils version with autotools'

[Ahmad Fatoum]

Makefile.am has:

  LIBDT_CURRENT=6
  LIBDT_REVISION=0
  LIBDT_AGE=0

along with a comment on how the values were chosen. Copy the comment and
the values into the meson.build as well, so appropriate symlinks
pointing at the versioned library are created. We forego the extra
complexity of having a common file that's read from both build systems
as we are intent on phasing out autotools anyway, once wrinkles such as
what's fixed here are ironed out.

Reported-by: Enrico Jörns <e.joerns@pengutronix.de>
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 meson.build | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/meson.build b/meson.build
index 9579e712dfea..9894d7311bb3 100644
--- a/meson.build
+++ b/meson.build
@@ -133,6 +133,15 @@ libdt = shared_library('dt-utils',
   c_args : ['-include', meson.current_build_dir() / 'version.h'],
   dependencies : [udevdep, versiondep],
   gnu_symbol_visibility : 'default',
+# If the library source code has changed at all since the last release,
+#   then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
+# If any interfaces have been added/removed/changed since the last release,
+#   then increment current, and set revision to 0.
+# If any public interfaces have been added since the last public release,
+#   then increment age.
+# If any interfaces have been removed or changed since the last release,
+#   then set age to 0.
+  version: '6.0.0',
   install : true)
 
 executable('barebox-state',
-- 
2.39.2

Re: [OSS-Tools] [PATCH dt-utils] meson: align libdt-utils version with autotools'

[Roland Hieber]

On Mon, Nov 06, 2023 at 12:58:22PM +0100, Ahmad Fatoum wrote:
> Makefile.am has:
> 
>   LIBDT_CURRENT=6
>   LIBDT_REVISION=0
>   LIBDT_AGE=0
> 
> along with a comment on how the values were chosen. Copy the comment and
> the values into the meson.build as well, so appropriate symlinks
> pointing at the versioned library are created. We forego the extra
> complexity of having a common file that's read from both build systems
> as we are intent on phasing out autotools anyway, once wrinkles such as
> what's fixed here are ironed out.
> 
> Reported-by: Enrico Jörns <e.joerns@pengutronix.de>
> Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>

Reviewed-by: Roland Hieber <rhi@pengutronix.de>

> ---
>  meson.build | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/meson.build b/meson.build
> index 9579e712dfea..9894d7311bb3 100644
> --- a/meson.build
> +++ b/meson.build
> @@ -133,6 +133,15 @@ libdt = shared_library('dt-utils',
>    c_args : ['-include', meson.current_build_dir() / 'version.h'],
>    dependencies : [udevdep, versiondep],
>    gnu_symbol_visibility : 'default',
> +# If the library source code has changed at all since the last release,
> +#   then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
> +# If any interfaces have been added/removed/changed since the last release,
> +#   then increment current, and set revision to 0.
> +# If any public interfaces have been added since the last public release,
> +#   then increment age.
> +# If any interfaces have been removed or changed since the last release,
> +#   then set age to 0.
> +  version: '6.0.0',
>    install : true)
>  
>  executable('barebox-state',
> -- 
> 2.39.2
> 
> 
> 

-- 
Roland Hieber, Pengutronix e.K.          | r.hieber@pengutronix.de     |
Steuerwalder Str. 21                     | https://www.pengutronix.de/ |
31137 Hildesheim, Germany                | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686         | Fax:   +49-5121-206917-5555 |

Re: [OSS-Tools] [PATCH dt-utils] meson: align libdt-utils version with autotools'

[Enrico Jörns]

Am Montag, dem 06.11.2023 um 13:04 +0100 schrieb Roland Hieber:
> On Mon, Nov 06, 2023 at 12:58:22PM +0100, Ahmad Fatoum wrote:
> > Makefile.am has:
> > 
> >   LIBDT_CURRENT=6
> >   LIBDT_REVISION=0
> >   LIBDT_AGE=0
> > 
> > along with a comment on how the values were chosen. Copy the comment and
> > the values into the meson.build as well, so appropriate symlinks
> > pointing at the versioned library are created. We forego the extra
> > complexity of having a common file that's read from both build systems
> > as we are intent on phasing out autotools anyway, once wrinkles such as
> > what's fixed here are ironed out.
> > 
> > Reported-by: Enrico Jörns <e.joerns@pengutronix.de>
> > Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
> 
> Reviewed-by: Roland Hieber <rhi@pengutronix.de>
> 
> > ---
> >  meson.build | 9 +++++++++
> >  1 file changed, 9 insertions(+)
> > 
> > diff --git a/meson.build b/meson.build
> > index 9579e712dfea..9894d7311bb3 100644
> > --- a/meson.build
> > +++ b/meson.build
> > @@ -133,6 +133,15 @@ libdt = shared_library('dt-utils',
> >    c_args : ['-include', meson.current_build_dir() / 'version.h'],
> >    dependencies : [udevdep, versiondep],
> >    gnu_symbol_visibility : 'default',
> > +# If the library source code has changed at all since the last release,
> > +#   then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
> > +# If any interfaces have been added/removed/changed since the last release,
> > +#   then increment current, and set revision to 0.

Does this make sense?
Isn't "current" meant to mark *incompatible* public API changes?
This might be valid for "removed" or "changed", but not for "added".

How does "interfaces" differ from "public interfaces" below?

Regards, Enrico

> > +# If any public interfaces have been added since the last public release,
> > +#   then increment age.
> > +# If any interfaces have been removed or changed since the last release,
> > +#   then set age to 0.
> > +  version: '6.0.0',
> >    install : true)
> >  
> >  executable('barebox-state',
> > -- 
> > 2.39.2
> > 
> > 
> > 
> 

-- 
Pengutronix e.K.                           | Enrico Jörns                |
Embedded Linux Consulting & Support        | https://www.pengutronix.de/ |
Steuerwalder Str. 21                       | Phone: +49-5121-206917-180  |
31137 Hildesheim, Germany                  | Fax:   +49-5121-206917-9    |

Re: [OSS-Tools] [PATCH dt-utils] meson: align libdt-utils version with autotools'

[Ahmad Fatoum]

Hello Enrico,

On 06.11.23 13:12, Enrico Jörns wrote:
> Am Montag, dem 06.11.2023 um 13:04 +0100 schrieb Roland Hieber:
>> On Mon, Nov 06, 2023 at 12:58:22PM +0100, Ahmad Fatoum wrote:
>>> Makefile.am has:
>>>
>>>   LIBDT_CURRENT=6
>>>   LIBDT_REVISION=0
>>>   LIBDT_AGE=0
>>>
>>> along with a comment on how the values were chosen. Copy the comment and
>>> the values into the meson.build as well, so appropriate symlinks
>>> pointing at the versioned library are created. We forego the extra
>>> complexity of having a common file that's read from both build systems
>>> as we are intent on phasing out autotools anyway, once wrinkles such as
>>> what's fixed here are ironed out.
>>>
>>> Reported-by: Enrico Jörns <e.joerns@pengutronix.de>
>>> Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
>>
>> Reviewed-by: Roland Hieber <rhi@pengutronix.de>
>>
>>> ---
>>>  meson.build | 9 +++++++++
>>>  1 file changed, 9 insertions(+)
>>>
>>> diff --git a/meson.build b/meson.build
>>> index 9579e712dfea..9894d7311bb3 100644
>>> --- a/meson.build
>>> +++ b/meson.build
>>> @@ -133,6 +133,15 @@ libdt = shared_library('dt-utils',
>>>    c_args : ['-include', meson.current_build_dir() / 'version.h'],
>>>    dependencies : [udevdep, versiondep],
>>>    gnu_symbol_visibility : 'default',
>>> +# If the library source code has changed at all since the last release,
>>> +#   then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
>>> +# If any interfaces have been added/removed/changed since the last release,
>>> +#   then increment current, and set revision to 0.
> 
> Does this make sense?

It was copied into Makefile.am verbatim from the libtool documentation:
https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html

> Isn't "current" meant to mark *incompatible* public API changes?

libtool numbering is new to me as well, but apparently "Current" is the most recent
interface number that this library implements.

The major version number should thus be current - age, not just current.
I will fix that in v2. See
https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html
https://gitlab.gnome.org/GNOME/gcab/-/merge_requests/6/diffs?commit_id=2c8048f74ec8c088397d47730aa47c574526918f

> This might be valid for "removed" or "changed", but not for "added".
> 
> How does "interfaces" differ from "public interfaces" below?

No difference AFAIK.

Cheers,
Ahmad

> 
> Regards, Enrico
> 
>>> +# If any public interfaces have been added since the last public release,
>>> +#   then increment age.
>>> +# If any interfaces have been removed or changed since the last release,
>>> +#   then set age to 0.
>>> +  version: '6.0.0',
>>>    install : true)
>>>  
>>>  executable('barebox-state',
>>> -- 
>>> 2.39.2
>>>
>>>
>>>
>>
> 

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Re: [OSS-Tools] [PATCH dt-utils] meson: align libdt-utils version with autotools'

[Roland Hieber]

On Mon, Nov 06, 2023 at 01:12:48PM +0100, Enrico Jörns wrote:
> Am Montag, dem 06.11.2023 um 13:04 +0100 schrieb Roland Hieber:
> > On Mon, Nov 06, 2023 at 12:58:22PM +0100, Ahmad Fatoum wrote:
> > > Makefile.am has:
> > > 
> > >   LIBDT_CURRENT=6
> > >   LIBDT_REVISION=0
> > >   LIBDT_AGE=0
> > > 
> > > along with a comment on how the values were chosen. Copy the comment and
> > > the values into the meson.build as well, so appropriate symlinks
> > > pointing at the versioned library are created. We forego the extra
> > > complexity of having a common file that's read from both build systems
> > > as we are intent on phasing out autotools anyway, once wrinkles such as
> > > what's fixed here are ironed out.
> > > 
> > > Reported-by: Enrico Jörns <e.joerns@pengutronix.de>
> > > Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
> > 
> > Reviewed-by: Roland Hieber <rhi@pengutronix.de>
> > 
> > > ---
> > >  meson.build | 9 +++++++++
> > >  1 file changed, 9 insertions(+)
> > > 
> > > diff --git a/meson.build b/meson.build
> > > index 9579e712dfea..9894d7311bb3 100644
> > > --- a/meson.build
> > > +++ b/meson.build
> > > @@ -133,6 +133,15 @@ libdt = shared_library('dt-utils',
> > >    c_args : ['-include', meson.current_build_dir() / 'version.h'],
> > >    dependencies : [udevdep, versiondep],
> > >    gnu_symbol_visibility : 'default',
> > > +# If the library source code has changed at all since the last release,
> > > +#   then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
> > > +# If any interfaces have been added/removed/changed since the last release,
> > > +#   then increment current, and set revision to 0.
> 
> Does this make sense?
> Isn't "current" meant to mark *incompatible* public API changes?
> This might be valid for "removed" or "changed", but not for "added".
> 
> How does "interfaces" differ from "public interfaces" below?
> 
> Regards, Enrico
> 
> > > +# If any public interfaces have been added since the last public release,
> > > +#   then increment age.
> > > +# If any interfaces have been removed or changed since the last release,
> > > +#   then set age to 0.
> > > +  version: '6.0.0',

Wait. Enrico has a point. The "version" field in meson has the usual
"major.minor.patch" semantics [1], which does not relate to autotools'
current/revision/age scheme, which in autotools is used to calculate the
soversion (by some strange formula that I can never memorise). meson
however assumes the major number as soversion if nothing else is
specified.

Also [2] notes:

  > To set the version of the library, libtool provides the
  > -version-info parameter, which accepts three numbers, separated by
  > colons, that are called respectively, current, revision and age.
  > Both their name and their behaviour, nowadays, have to be considered
  > fully arbitrary, as the explanation provided in the official
  > documentation is confusing to say the least, and can be, in some
  > cases, considered completely wrong. 

As we want to get rid of autotools in the foreseeable future anyway, I
suggest that we drop the current/revision/age scheme and use semantic
versioning instead (i.e., increase major for ABI-incompatible changes,
increase minor for ABI-compatible new features, increase patch for
ABI-compatible bugfixes), which for versions like "6.1.2" results in
library names like "libdt-utils.so.6.1.2" and soversion of 6.

  [1]: https://mesonbuild.com/Reference-manual_functions.html#shared_library_version
  [2]: https://autotools.info/libtool/version.html#idm1602

(Please disregard my premature Reviewed-by.)

 - Roland

> > >    install : true)
> > >  
> > >  executable('barebox-state',
> > > -- 
> > > 2.39.2
> > > 
> > > 
> > > 
> > 
> 
> -- 
> Pengutronix e.K.                           | Enrico Jörns                |
> Embedded Linux Consulting & Support        | https://www.pengutronix.de/ |
> Steuerwalder Str. 21                       | Phone: +49-5121-206917-180  |
> 31137 Hildesheim, Germany                  | Fax:   +49-5121-206917-9    |
> 
> 

-- 
Roland Hieber, Pengutronix e.K.          | r.hieber@pengutronix.de     |
Steuerwalder Str. 21                     | https://www.pengutronix.de/ |
31137 Hildesheim, Germany                | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686         | Fax:   +49-5121-206917-5555 |

Re: [OSS-Tools] [PATCH dt-utils] meson: align libdt-utils version with autotools'

[Enrico Jörns]

Hi Ahmad,

Am Montag, dem 06.11.2023 um 14:44 +0100 schrieb Ahmad Fatoum:
> Hello Enrico,
> 
> On 06.11.23 13:12, Enrico Jörns wrote:
> > Am Montag, dem 06.11.2023 um 13:04 +0100 schrieb Roland Hieber:
> > > On Mon, Nov 06, 2023 at 12:58:22PM +0100, Ahmad Fatoum wrote:
> > > > Makefile.am has:
> > > > 
> > > >   LIBDT_CURRENT=6
> > > >   LIBDT_REVISION=0
> > > >   LIBDT_AGE=0
> > > > 
> > > > along with a comment on how the values were chosen. Copy the comment and
> > > > the values into the meson.build as well, so appropriate symlinks
> > > > pointing at the versioned library are created. We forego the extra
> > > > complexity of having a common file that's read from both build systems
> > > > as we are intent on phasing out autotools anyway, once wrinkles such as
> > > > what's fixed here are ironed out.
> > > > 
> > > > Reported-by: Enrico Jörns <e.joerns@pengutronix.de>
> > > > Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
> > > 
> > > Reviewed-by: Roland Hieber <rhi@pengutronix.de>
> > > 
> > > > ---
> > > >  meson.build | 9 +++++++++
> > > >  1 file changed, 9 insertions(+)
> > > > 
> > > > diff --git a/meson.build b/meson.build
> > > > index 9579e712dfea..9894d7311bb3 100644
> > > > --- a/meson.build
> > > > +++ b/meson.build
> > > > @@ -133,6 +133,15 @@ libdt = shared_library('dt-utils',
> > > >    c_args : ['-include', meson.current_build_dir() / 'version.h'],
> > > >    dependencies : [udevdep, versiondep],
> > > >    gnu_symbol_visibility : 'default',
> > > > +# If the library source code has changed at all since the last release,
> > > > +#   then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
> > > > +# If any interfaces have been added/removed/changed since the last release,
> > > > +#   then increment current, and set revision to 0.
> > 
> > Does this make sense?
> 
> It was copied into Makefile.am verbatim from the libtool documentation:
> https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html

thank you for the link, I guess this clarifies the versioning purpose for me a bit better.
Haven't looked at this topic in that detail yet either. 😉

Maybe it would make sense to just refer to generic libtool versioning scheme (and probably include
the link) instead of duplicating the text here?

Anyway, I would be fine with both variants in the first round!


Best regards

Enrico

> > Isn't "current" meant to mark *incompatible* public API changes?
> 
> libtool numbering is new to me as well, but apparently "Current" is the most recent
> interface number that this library implements.
> 
> The major version number should thus be current - age, not just current.
> I will fix that in v2. See
> https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html
> https://gitlab.gnome.org/GNOME/gcab/-/merge_requests/6/diffs?commit_id=2c8048f74ec8c088397d47730aa47c574526918f
> 
> > This might be valid for "removed" or "changed", but not for "added".
> > 
> > How does "interfaces" differ from "public interfaces" below?
> 
> No difference AFAIK.
> 
> Cheers,
> Ahmad
> 
> > 
> > Regards, Enrico
> > 
> > > > +# If any public interfaces have been added since the last public release,
> > > > +#   then increment age.
> > > > +# If any interfaces have been removed or changed since the last release,
> > > > +#   then set age to 0.
> > > > +  version: '6.0.0',
> > > >    install : true)
> > > >  
> > > >  executable('barebox-state',
> > > > -- 
> > > > 2.39.2
> > > > 
> > > > 
> > > > 
> > > 
> > 
> 

-- 
Pengutronix e.K.                           | Enrico Jörns                |
Embedded Linux Consulting & Support        | https://www.pengutronix.de/ |
Steuerwalder Str. 21                       | Phone: +49-5121-206917-180  |
31137 Hildesheim, Germany                  | Fax:   +49-5121-206917-9    |

Re: [OSS-Tools] [PATCH dt-utils] meson: align libdt-utils version with autotools'

[Enrico Jörns]

Hi Roland,

Am Montag, dem 06.11.2023 um 14:56 +0100 schrieb Roland Hieber:
> On Mon, Nov 06, 2023 at 01:12:48PM +0100, Enrico Jörns wrote:
> > Am Montag, dem 06.11.2023 um 13:04 +0100 schrieb Roland Hieber:
> > > On Mon, Nov 06, 2023 at 12:58:22PM +0100, Ahmad Fatoum wrote:
> > > > Makefile.am has:
> > > > 
> > > >   LIBDT_CURRENT=6
> > > >   LIBDT_REVISION=0
> > > >   LIBDT_AGE=0
> > > > 
> > > > along with a comment on how the values were chosen. Copy the comment and
> > > > the values into the meson.build as well, so appropriate symlinks
> > > > pointing at the versioned library are created. We forego the extra
> > > > complexity of having a common file that's read from both build systems
> > > > as we are intent on phasing out autotools anyway, once wrinkles such as
> > > > what's fixed here are ironed out.
> > > > 
> > > > Reported-by: Enrico Jörns <e.joerns@pengutronix.de>
> > > > Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
> > > 
> > > Reviewed-by: Roland Hieber <rhi@pengutronix.de>
> > > 
> > > > ---
> > > >  meson.build | 9 +++++++++
> > > >  1 file changed, 9 insertions(+)
> > > > 
> > > > diff --git a/meson.build b/meson.build
> > > > index 9579e712dfea..9894d7311bb3 100644
> > > > --- a/meson.build
> > > > +++ b/meson.build
> > > > @@ -133,6 +133,15 @@ libdt = shared_library('dt-utils',
> > > >    c_args : ['-include', meson.current_build_dir() / 'version.h'],
> > > >    dependencies : [udevdep, versiondep],
> > > >    gnu_symbol_visibility : 'default',
> > > > +# If the library source code has changed at all since the last release,
> > > > +#   then increment revision (‘c:r:a’ becomes ‘c:r+1:a’).
> > > > +# If any interfaces have been added/removed/changed since the last release,
> > > > +#   then increment current, and set revision to 0.
> > 
> > Does this make sense?
> > Isn't "current" meant to mark *incompatible* public API changes?
> > This might be valid for "removed" or "changed", but not for "added".
> > 
> > How does "interfaces" differ from "public interfaces" below?
> > 
> > Regards, Enrico
> > 
> > > > +# If any public interfaces have been added since the last public release,
> > > > +#   then increment age.
> > > > +# If any interfaces have been removed or changed since the last release,
> > > > +#   then set age to 0.
> > > > +  version: '6.0.0',
> 
> Wait. Enrico has a point. The "version" field in meson has the usual
> "major.minor.patch" semantics [1], which does not relate to autotools'
> current/revision/age scheme, which in autotools is used to calculate the
> soversion (by some strange formula that I can never memorise). meson
> however assumes the major number as soversion if nothing else is
> specified.

mh, but this is just the 'library version' and may thus be changed by hand and independent from any
other release version, right?

And "soversion" is just the first component of "version" by default if I get the documentation
right:

> If this is not specified, the first part of version is used instead (see below). For example, if
> version is 3.6.0 and soversion is not defined, it is set to 3.

https://mesonbuild.com/Reference-manual_functions.html#shared_library

Regards, Enrico

> Also [2] notes:
> 
>   > To set the version of the library, libtool provides the
>   > -version-info parameter, which accepts three numbers, separated by
>   > colons, that are called respectively, current, revision and age.
>   > Both their name and their behaviour, nowadays, have to be considered
>   > fully arbitrary, as the explanation provided in the official
>   > documentation is confusing to say the least, and can be, in some
>   > cases, considered completely wrong. 
> 
> As we want to get rid of autotools in the foreseeable future anyway, I
> suggest that we drop the current/revision/age scheme and use semantic
> versioning instead (i.e., increase major for ABI-incompatible changes,
> increase minor for ABI-compatible new features, increase patch for
> ABI-compatible bugfixes), which for versions like "6.1.2" results in
> library names like "libdt-utils.so.6.1.2" and soversion of 6.
> 
>   [1]: https://mesonbuild.com/Reference-manual_functions.html#shared_library_version
>   [2]: https://autotools.info/libtool/version.html#idm1602
> 
> (Please disregard my premature Reviewed-by.)
> 
>  - Roland
> 
> > > >    install : true)
> > > >  
> > > >  executable('barebox-state',
> > > > -- 
> > > > 2.39.2
> > > > 
> > > > 
> > > > 
> > > 
> > 
> > -- 
> > Pengutronix e.K.                           | Enrico Jörns                |
> > Embedded Linux Consulting & Support        | https://www.pengutronix.de/ |
> > Steuerwalder Str. 21                       | Phone: +49-5121-206917-180  |
> > 31137 Hildesheim, Germany                  | Fax:   +49-5121-206917-9    |
> > 
> > 
> 

-- 
Pengutronix e.K.                           | Enrico Jörns                |
Embedded Linux Consulting & Support        | https://www.pengutronix.de/ |
Steuerwalder Str. 21                       | Phone: +49-5121-206917-180  |
31137 Hildesheim, Germany                  | Fax:   +49-5121-206917-9    |