gdb: new --with-pkgversion-suffix configure option

  Once GDB 13.1 is released, then the version string, for a build of GDB
made from the release branch should look like this:

  $ gdb --version
  GNU gdb (GDB) 13.1

We provide a configure option, --with-pkgversion, which allows control
over the 'GDB' string within '(GDB) ', and so, if we configure like
this:

  $ ../src/configure --with-pkgversion="My Distro"

then the final GDB's version string would look like this:

  $ gdb --version
  GNU gdb (My Distro) 13.1

It is not unreasonable to think that somebody building a distribution
specific version of GDB like this might want to also augment the
version number (13.1) in order to indicate a local patch level.

Now, the existing configure option, --with-pkgversion, clearly seems
to indicate that the package specific version number should be
included here, however, I don't find this result satisfactory.

Here are some possibilities.  I could include the full version number,
including my local patch number, like this:

  GNU gdb (My Distro 13.1.5) 13.1

I don't like this because of the duplication.  I could drop the
upstream version number, like this:

  GNU gdb (My Distro 5) 13.1

But I don't like this because it (IMHO) can lead to confusion, is this
GDB version 5?  Version 13.1?  I think this can potentially cause
confusion for a user.

I propose that a far better solution is to add a new configure option
that will allow me to attach additional content at the end of the
version string, like this:

  GNU gdb (My Distro) 13.1.5

This, I think, is much clearer.  To support this I propose adding a
new configure option, --with-pkgversion-suffix.  This option takes a
string, which is then appended to the version number.  And so, we now
configure like this:

  $ ../src/configure --with-pkgversion="My Distro" \
                     --with-pkgversion-suffix=".xx.yy"

And we now get the desired version output from both GDB and GDBServer:

  $ gdb --version
  GNU gdb (My Distro) 13.1.xx.yy
  $ gdbserver --version
  GNU gdbserver (My Distro) 13.1.xx.yy

Obviously, the new configure option is optional.  When it is not used
the suffix defaults to the empty string, so GDB's output will be
unchanged.
---
 gdb/acinclude.m4                |  3 +++
 gdb/config.in                   |  3 +++
 gdb/configure                   | 27 +++++++++++++++++++++++++--
 gdb/configure.ac                |  2 ++
 gdb/top.c                       |  3 ++-
 gdbserver/acinclude.m4          |  3 +++
 gdbserver/config.in             |  3 +++
 gdbserver/configure             | 23 +++++++++++++++++++++++
 gdbserver/configure.ac          |  2 ++
 gdbserver/server.cc             |  4 ++--
 gdbsupport/pkgversion-suffix.m4 | 33 +++++++++++++++++++++++++++++++++
 11 files changed, 101 insertions(+), 5 deletions(-)
 create mode 100644 gdbsupport/pkgversion-suffix.m4


base-commit: db2e277d1a840091f56185d94f9d39c6736d2556
  

>>>>> "Andrew" == Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org> writes:

Andrew> I propose that a far better solution is to add a new configure option
Andrew> that will allow me to attach additional content at the end of the
Andrew> version string, like this:

Andrew>   GNU gdb (My Distro) 13.1.5

Andrew> This, I think, is much clearer.  To support this I propose adding a
Andrew> new configure option, --with-pkgversion-suffix.  This option takes a
Andrew> string, which is then appended to the version number.  And so, we now
Andrew> configure like this:

This seems fine to me.

thanks,
Tom
  

On 11 Nov 2022 11:24, Andrew Burgess via Gdb-patches wrote:
> Once GDB 13.1 is released, then the version string, for a build of GDB
> made from the release branch should look like this:
> 
>   $ gdb --version
>   GNU gdb (GDB) 13.1
> 
> We provide a configure option, --with-pkgversion, which allows control
> over the 'GDB' string within '(GDB) ', and so, if we configure like
> this:
> 
>   $ ../src/configure --with-pkgversion="My Distro"
> 
> then the final GDB's version string would look like this:
> 
>   $ gdb --version
>   GNU gdb (My Distro) 13.1
> 
> It is not unreasonable to think that somebody building a distribution
> specific version of GDB like this might want to also augment the
> version number (13.1) in order to indicate a local patch level.
> 
> Now, the existing configure option, --with-pkgversion, clearly seems
> to indicate that the package specific version number should be
> included here, however, I don't find this result satisfactory.
> 
> Here are some possibilities.  I could include the full version number,
> including my local patch number, like this:
> 
>   GNU gdb (My Distro 13.1.5) 13.1
> 
> I don't like this because of the duplication.  I could drop the
> upstream version number, like this:
> 
>   GNU gdb (My Distro 5) 13.1
> 
> But I don't like this because it (IMHO) can lead to confusion, is this
> GDB version 5?  Version 13.1?  I think this can potentially cause
> confusion for a user.
> 
> I propose that a far better solution is to add a new configure option
> that will allow me to attach additional content at the end of the
> version string, like this:
> 
>   GNU gdb (My Distro) 13.1.5

i strongly dislike this proposal because it's smooshing distro versions and
official versions with no clear separation at all.  this is bad for us, bad
for our users, and imo bad for even the distros/vendors.

if --with-pkgversion= isn't specified, the users will see the bare version only.
(yes, i'm aware people can patch the source to display whatever they want, but
that doesn't mean we have to encourage or make it easy to do)

even if it is specified, users will say things like "i'm using GDB 13.1.5",
and then we'll have to figure out whose "13.1.5" that is.  users will also do
things like search for "GDB version 13.1.5" and then get confused when no such
release exists.

it also means once we release a GDB version X, we can never release a point
version after that (e.g. X.Y).  which is what these docs, albeit perhaps
outdated, explain:
https://sourceware.org/gdb/wiki/Internals%20Versions
i'm aware that currently we've moved to X.Y and don't seem to ever plan on
doing plain X or X.Y.Z, but that doesn't mean we should cede the entire
future to random vendors.

backing up a bit, the example you provided is:
> GNU gdb (My Distro 13.1.5) 13.1
first off, i don't see a problem with the duplication, but that's me.
second, it sounds like your distro is claiming version numbers it shouldn't ?
why are you calling it version "13.1.5" instead of "13.1 patch 5" or "13.1-5"
or something like that ?  this sounds like a bug in the distro/vendor that
you're working on.

in Gentoo we use:
> GNU gdb (Gentoo 12.1 p3) 12.1
> GNU gdb (Gentoo 12.1 vanilla) 12.1
to make it very clear to everyone involved:
(1) it's a Gentoo build
(2) what our upstream base version is
(3) what the Gentoo packaging version is
(4) how we've patched it, or not

personally i've never found the "(GDB)" to be useful information.  seems like
we could do away with it entirely ?  i'll admit i haven't looked at the history
of it at all though.

if we want to avoid changing existing behavior/format in the --version strings,
maybe we should have a new configure option that inserts a new line so it's
very clear what's going on ?

$ gdb --version
GNU gdb (GDB) 12.1
Vendor: Gentoo 12.1 p3
Copyright (C) 2022 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

> --- /dev/null
> +++ b/gdbsupport/pkgversion-suffix.m4
> +
> +dnl Add support for the --with-pkgversion-suffix configure option.  Allows
> +dnl the user to specify a string that is appended to the version number.
> +AC_DEFUN([GDB_PKGVERSION_SUFFIX],[
> +  AC_ARG_WITH(pkgversion-suffix,
> +    AS_HELP_STRING([--with-pkgversion-suffix=STRING],
> +                   [Append STRING to the end of the version number]),

i really dislike how this is made into a gdb-only thing.  the existing options
--with-pkgversion= & --with-bugurl= are pretty standard across the GNU toolchain
project space and are extremely helpful to keep consistent.  can we please look
for a solution that maintains that consistency ?
-mike
  

Mike Frysinger <vapier@gentoo.org> writes:

> On 11 Nov 2022 11:24, Andrew Burgess via Gdb-patches wrote:
>> Once GDB 13.1 is released, then the version string, for a build of GDB
>> made from the release branch should look like this:
>> 
>>   $ gdb --version
>>   GNU gdb (GDB) 13.1
>> 
>> We provide a configure option, --with-pkgversion, which allows control
>> over the 'GDB' string within '(GDB) ', and so, if we configure like
>> this:
>> 
>>   $ ../src/configure --with-pkgversion="My Distro"
>> 
>> then the final GDB's version string would look like this:
>> 
>>   $ gdb --version
>>   GNU gdb (My Distro) 13.1
>> 
>> It is not unreasonable to think that somebody building a distribution
>> specific version of GDB like this might want to also augment the
>> version number (13.1) in order to indicate a local patch level.
>> 
>> Now, the existing configure option, --with-pkgversion, clearly seems
>> to indicate that the package specific version number should be
>> included here, however, I don't find this result satisfactory.
>> 
>> Here are some possibilities.  I could include the full version number,
>> including my local patch number, like this:
>> 
>>   GNU gdb (My Distro 13.1.5) 13.1
>> 
>> I don't like this because of the duplication.  I could drop the
>> upstream version number, like this:
>> 
>>   GNU gdb (My Distro 5) 13.1
>> 
>> But I don't like this because it (IMHO) can lead to confusion, is this
>> GDB version 5?  Version 13.1?  I think this can potentially cause
>> confusion for a user.
>> 
>> I propose that a far better solution is to add a new configure option
>> that will allow me to attach additional content at the end of the
>> version string, like this:
>> 
>>   GNU gdb (My Distro) 13.1.5
>
> i strongly dislike this proposal because it's smooshing distro versions and
> official versions with no clear separation at all.  this is bad for us, bad
> for our users, and imo bad for even the distros/vendors.
>
> if --with-pkgversion= isn't specified, the users will see the bare version only.

I guess you mean the new --with-pkgversion-suffix here?

> (yes, i'm aware people can patch the source to display whatever they want, but
> that doesn't mean we have to encourage or make it easy to do)
>
> even if it is specified, users will say things like "i'm using GDB 13.1.5",
> and then we'll have to figure out whose "13.1.5" that is.

I disagree with your use of "have" here.  I think it's a subtle but
important distinction.  So long as vendor version numbers are different
from upstream version numbers, "we" (the upstream GDB community) can
just refer users to their vendors (For issues that are not reproducible
in upstream GDB - we are after all a pretty helpful community I think).

>                                                              users will also do
> things like search for "GDB version 13.1.5" and then get confused when no such
> release exists.

I think my choice of ".5" here as an example was not a good choice.  The
configure option takes any string and just appends it at the end of the
version number.  So we could use "-p5", or " patch 5".  You talk about
this more below and list strings like that as being a better choice than
something like ".5".

If a vendor chooses to use a particular version number, and that ends up
confusing users, then that is unfortunate, but surely that's a vendor
issue?

>
> it also means once we release a GDB version X, we can never release a point
> version after that (e.g. X.Y).  which is what these docs, albeit perhaps
> outdated, explain:

I'm not sure who you mean by "we" in this sentence.  I really don't see
the existence of some additional customisation as being a blocker for
upstream GDB making whatever releases it wants, so I reject your
assertion that having this feature would mean "...we can never release a
point version after that...".

> https://sourceware.org/gdb/wiki/Internals%20Versions
> i'm aware that currently we've moved to X.Y and don't seem to ever plan on
> doing plain X or X.Y.Z, but that doesn't mean we should cede the entire
> future to random vendors.

I think this is the idea that confuses me the most: by what mechanism do
you think vendors would block us making a point release?

These vendors are downstream of us, we make a release and they pick that
up.  Those vendors are free to come to this list and express an opinion,
just like anyone else, but at the end of the day, we'll continue to make
decisions as a group, in the best interest of GDB, just like we always
have.

>
> backing up a bit, the example you provided is:
>> GNU gdb (My Distro 13.1.5) 13.1
> first off, i don't see a problem with the duplication, but that's me.
> second, it sounds like your distro is claiming version numbers it shouldn't ?
> why are you calling it version "13.1.5" instead of "13.1 patch 5" or "13.1-5"

As I said above, maybe using ".5" as an example was a poor choice.  I
could just as easily configure --with-pkgversion-suffix=" patch 5" to
get:

  GNU gdb (GDB) 13.1 patch 5

that's why the new option takes a string, not a version number.  And
notice, in the example I give, the '.' is included in the configure
option, it's not being added within GDB.  I'm free at configure time to
customise the output how I see fit.

> or something like that ?  this sounds like a bug in the distro/vendor that
> you're working on.

I'd disagree with "bug" here, surely it's just a choice that you
personally disagree with?  I'd like to discuss the benefits and/or
drawbacks of the proposal on its technical merits, rather than just
dismissing it as a bug.

>
> in Gentoo we use:
>> GNU gdb (Gentoo 12.1 p3) 12.1
>> GNU gdb (Gentoo 12.1 vanilla) 12.1
> to make it very clear to everyone involved:
> (1) it's a Gentoo build
> (2) what our upstream base version is
> (3) what the Gentoo packaging version is
> (4) how we've patched it, or not

That's great.  And can continue unchanged if that's your preference.
This proposal is about choice, not about trying to force all distros to
do things one particular way.

Some distros might want the version number to match the version number
from the package that was used to install GDB.  I don't think either
approach is wrong, it's just, right now, one approach is supported in
upstream GDB, and one approach is not.

>
> personally i've never found the "(GDB)" to be useful information.  seems like
> we could do away with it entirely ?  i'll admit i haven't looked at the history
> of it at all though.

I agree it seems a little weird.  But I certainly don't want to get off
track looking at that right now.  My interest is the other end of the
version string.

>
> if we want to avoid changing existing behavior/format in the --version strings,
> maybe we should have a new configure option that inserts a new line so it's
> very clear what's going on ?

I was hoping to propose a plan that would allow distros to continue to
operate as they currently do, while at the same time offering more
flexibility.

When I started thinking about this work, I did initially wonder about a
totally generic "version format" type idea, e.g. configure with:

  --with-version-format="GNU gdb {pkgversion} {version_number} patch 5" \
  --with-pkgversion="My Distro"

which would give:

  GNU gdb (My Distro) 13.1 patch 5

But could also allow:

  --with-version-format="GNU gdb (GDB) {version_number}\nVendor: My Distro 13.1 patch 5" \
  --with-pkgversion="My Distro"

Which would give:

  GNU gdb (GDB) 13.1
  Vendor: My Distro 13.1 patch 5

But I rejected this idea because (a) totally over the top for what I
actually wanted (append to the version string), and (b) would allow
vendors to easily drop the 'GNU gdb' string, which I didn't think was a
good idea, and (c) a vendor might even drop the major version number,
which seemed like a bad plan.

>
> $ gdb --version
> GNU gdb (GDB) 12.1
> Vendor: Gentoo 12.1 p3

Personally, not a fan of information duplication like this.

> Copyright (C) 2022 Free Software Foundation, Inc.
> License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
> This is free software: you are free to change and redistribute it.
> There is NO WARRANTY, to the extent permitted by law.
>
>> --- /dev/null
>> +++ b/gdbsupport/pkgversion-suffix.m4
>> +
>> +dnl Add support for the --with-pkgversion-suffix configure option.  Allows
>> +dnl the user to specify a string that is appended to the version number.
>> +AC_DEFUN([GDB_PKGVERSION_SUFFIX],[
>> +  AC_ARG_WITH(pkgversion-suffix,
>> +    AS_HELP_STRING([--with-pkgversion-suffix=STRING],
>> +                   [Append STRING to the end of the version number]),
>
> i really dislike how this is made into a gdb-only thing.  the existing options
> --with-pkgversion= & --with-bugurl= are pretty standard across the GNU toolchain
> project space and are extremely helpful to keep consistent.  can we please look
> for a solution that maintains that consistency ?

I guess by this you mean adding the macro to config/acx.m4?  I'm not
super keen to rush off to do that right from the start.  I'd much rather
get something that working (and acceptable) for GDB, and then have folk
generalise it if it works.

I deliberately picked the --with-pkgversion-suffix name to be consistent
with the existing --with-pkgversion option, so if at some future time to
macro was moved into acx.m4, the configure interface would remain the
same.

If I rewrote the proposal, but changed my example from ".5" to " patch
5", it feels like a lot of the issues you raised above would disappear.
Would you feel more comfortable with that approach?

I think your second concern, about where the autoconf macro lives can be
put aside until we reach agreement on the core of the issue.

Thanks,
Andrew
  

> On 16 Nov 2022, at 16:58, Mike Frysinger via Gdb-patches <gdb-patches@sourceware.org> wrote:
> 
> On 11 Nov 2022 11:24, Andrew Burgess via Gdb-patches wrote:
>> Once GDB 13.1 is released, then the version string, for a build of GDB
>> made from the release branch should look like this:
>> 
>>  $ gdb --version
>>  GNU gdb (GDB) 13.1
>> 
>> We provide a configure option, --with-pkgversion, which allows control
>> over the 'GDB' string within '(GDB) ', and so, if we configure like
>> this:
>> 
>>  $ ../src/configure --with-pkgversion="My Distro"
>> 
>> then the final GDB's version string would look like this:
>> 
>>  $ gdb --version
>>  GNU gdb (My Distro) 13.1
>> 
>> It is not unreasonable to think that somebody building a distribution
>> specific version of GDB like this might want to also augment the
>> version number (13.1) in order to indicate a local patch level.
>> 
>> Now, the existing configure option, --with-pkgversion, clearly seems
>> to indicate that the package specific version number should be
>> included here, however, I don't find this result satisfactory.
>> 
>> Here are some possibilities.  I could include the full version number,
>> including my local patch number, like this:
>> 
>>  GNU gdb (My Distro 13.1.5) 13.1
>> 
>> I don't like this because of the duplication.  I could drop the
>> upstream version number, like this:
>> 
>>  GNU gdb (My Distro 5) 13.1
>> 
>> But I don't like this because it (IMHO) can lead to confusion, is this
>> GDB version 5?  Version 13.1?  I think this can potentially cause
>> confusion for a user.
>> 
>> I propose that a far better solution is to add a new configure option
>> that will allow me to attach additional content at the end of the
>> version string, like this:
>> 
>>  GNU gdb (My Distro) 13.1.5
> 
> i strongly dislike this proposal because it's smooshing distro versions and
> official versions with no clear separation at all.  this is bad for us, bad
> for our users, and imo bad for even the distros/vendors.
> 
> if --with-pkgversion= isn't specified, the users will see the bare version only.
> (yes, i'm aware people can patch the source to display whatever they want, but
> that doesn't mean we have to encourage or make it easy to do)
> 
> even if it is specified, users will say things like "i'm using GDB 13.1.5",
> and then we'll have to figure out whose "13.1.5" that is.  users will also do
> things like search for "GDB version 13.1.5" and then get confused when no such
> release exists.
> 
> it also means once we release a GDB version X, we can never release a point
> version after that (e.g. X.Y).  which is what these docs, albeit perhaps
> outdated, explain:
> https://sourceware.org/gdb/wiki/Internals%20Versions
> i'm aware that currently we've moved to X.Y and don't seem to ever plan on
> doing plain X or X.Y.Z, but that doesn't mean we should cede the entire
> future to random vendors.
> 
> backing up a bit, the example you provided is:
>> GNU gdb (My Distro 13.1.5) 13.1
> first off, i don't see a problem with the duplication, but that's me.
> second, it sounds like your distro is claiming version numbers it shouldn't ?
> why are you calling it version "13.1.5" instead of "13.1 patch 5" or "13.1-5"
> or something like that ?  this sounds like a bug in the distro/vendor that
> you're working on.
> 
> in Gentoo we use:
>> GNU gdb (Gentoo 12.1 p3) 12.1
>> GNU gdb (Gentoo 12.1 vanilla) 12.1
> to make it very clear to everyone involved:
> (1) it's a Gentoo build
> (2) what our upstream base version is
> (3) what the Gentoo packaging version is
> (4) how we've patched it, or not
> 
> personally i've never found the "(GDB)" to be useful information.  seems like
> we could do away with it entirely ?  i'll admit i haven't looked at the history
> of it at all though.
> 
> if we want to avoid changing existing behavior/format in the --version strings,
> maybe we should have a new configure option that inserts a new line so it's
> very clear what's going on ?
> 
> $ gdb --version
> GNU gdb (GDB) 12.1
> Vendor: Gentoo 12.1 p3
> Copyright (C) 2022 Free Software Foundation, Inc.
> License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
> This is free software: you are free to change and redistribute it.
> There is NO WARRANTY, to the extent permitted by law.
> 
>> --- /dev/null
>> +++ b/gdbsupport/pkgversion-suffix.m4
>> +
>> +dnl Add support for the --with-pkgversion-suffix configure option.  Allows
>> +dnl the user to specify a string that is appended to the version number.
>> +AC_DEFUN([GDB_PKGVERSION_SUFFIX],[
>> +  AC_ARG_WITH(pkgversion-suffix,
>> +    AS_HELP_STRING([--with-pkgversion-suffix=STRING],
>> +                   [Append STRING to the end of the version number]),
> 
> i really dislike how this is made into a gdb-only thing.  the existing options
> --with-pkgversion= & --with-bugurl= are pretty standard across the GNU toolchain
> project space and are extremely helpful to keep consistent.  can we please look
> for a solution that maintains that consistency ?

I feel the same. The approach we use in Gentoo seems to work well enough
And diverting from the standard autotools way of doing this feels unfortunate.

It's really nice to be able to bang these options in to GNU projects and
have it just work.

I agree the suggested output change might be a bit neater though.

When I first saw the patch, I assumed that someone had just missed
the existing options existed.

Best,
sam