[doc] Avoid conflicts between gdb and cross-gdb.

  Hello,

On Tue, Jul 01, 2014 at 05:18:25PM +0900, Masaki Muranaka wrote:
> Hello,
> 
> After applied hash 43662968, gdb.1 and other man pages are not added
> target triplet even if we configure with --target=.
> 
> It causes conflicts on some distributions.
> And uninstall rules requires $(transform) variable.
> 
> I think this should be fixed by adding the target triplet.
> 
> 
> >From e89f13505363c41b683a1b02125f1fea02aa486c Mon Sep 17 00:00:00 2001
> From: Masaki Muranaka <monaka@monami-software.com>
> Date: Tue, 1 Jul 2014 17:08:15 +0900
> Subject: [PATCH] Add target triplet to man files.
> 
> ---
>  gdb/doc/ChangeLog   | 4 ++++
>  gdb/doc/Makefile.in | 6 ++++--
>  2 files changed, 8 insertions(+), 2 deletions(-)
> 
> diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
> index 7c1d1bb..10b1114 100644
> --- a/gdb/doc/ChangeLog
> +++ b/gdb/doc/ChangeLog
> @@ -1,3 +1,7 @@
> +2014-07-01  Masaki Muranaka  <monaka@monami-software.com>
> +
> + * Makefile.in : Add target triplet to man files.
> +

I am sorry for the late review. In the future, please do not hesitate
to ping us after a couple of weeks, and every week or so thereafter.

The patch makes sense to me.  Unfortunately, when I tried to test
the patch, it did not apply.  Attached is what I ended up pushing
(I kept you as the author off the git commit).

Please note also how I wrote the ChangeLog entry. We're expected
to write the names of new variables and modified targets in them.

gdb/doc/ChangeLog:

        * Makefile.in (transform): New variable.
        (install-man1, install-man5): Apply $(transform) to man file names.

Tested by installing both native and cross debugger.
  

On Fri 01 Aug 2014 08:07:22 Joel Brobecker wrote:
> On Tue, Jul 01, 2014 at 05:18:25PM +0900, Masaki Muranaka wrote:
> > After applied hash 43662968, gdb.1 and other man pages are not added
> > target triplet even if we configure with --target=.
> > 
> > It causes conflicts on some distributions.
> > And uninstall rules requires $(transform) variable.
> > 
> > I think this should be fixed by adding the target triplet.
> > 
> > >From e89f13505363c41b683a1b02125f1fea02aa486c Mon Sep 17 00:00:00 2001
> > 
> > From: Masaki Muranaka <monaka@monami-software.com>
> > Date: Tue, 1 Jul 2014 17:08:15 +0900
> > Subject: [PATCH] Add target triplet to man files.
> > 
> > ---
> > 
> >  gdb/doc/ChangeLog   | 4 ++++
> >  gdb/doc/Makefile.in | 6 ++++--
> >  2 files changed, 8 insertions(+), 2 deletions(-)
> > 
> > diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
> > index 7c1d1bb..10b1114 100644
> > --- a/gdb/doc/ChangeLog
> > +++ b/gdb/doc/ChangeLog
> > @@ -1,3 +1,7 @@
> > +2014-07-01  Masaki Muranaka  <monaka@monami-software.com>
> > +
> > + * Makefile.in : Add target triplet to man files.
> 
> The patch makes sense to me.  Unfortunately, when I tried to test
> the patch, it did not apply.  Attached is what I ended up pushing
> (I kept you as the author off the git commit).

along these lines, should we also transform the default gdb datadir (for 
python and xml files) ?  and info pages ?  looking at my cross-debugger 
installs, those are the other big missing pieces.
-mike
  

> along these lines, should we also transform the default gdb datadir (for 
> python and xml files) ?  and info pages ?  looking at my cross-debugger 
> installs, those are the other big missing pieces.

For the default gdb_datadir, I am of two minds on this. It's really
easy to adjust as desired at configure time, and I think that multiple
GDB installs made at the same location should be compatible, and
thus should be able to share their Python/XML files. But as previously
said, it's not a strong opinion.

For GDB's info page, I think we should indeed apply the transformation,
to be consistent.
  

> Date: Wed, 6 Aug 2014 06:24:35 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org,	Masaki Muranaka <monaka@monami-software.com>
> 
> For GDB's info page, I think we should indeed apply the transformation,
> to be consistent.

I'm not sure I agree.  What other projects do that?  I never saw any
transformed Info manual.  And we never did that before, so why now?

Besides, why do that?  The Info manual does not include any
system-specific information, it is valid for all supported systems.
So I see no reason to put it into a system-dependent place or call it
by system-dependent name.

What am I missing?
  

> I'm not sure I agree.  What other projects do that?  I never saw any
> transformed Info manual.  And we never did that before, so why now?
> 
> Besides, why do that?  The Info manual does not include any
> system-specific information, it is valid for all supported systems.
> So I see no reason to put it into a system-dependent place or call it
> by system-dependent name.
> 
> What am I missing?

Maybe you are right. I just found it odd that you'd do "man
powerpc-elf-gdb" but then do "info gdb", even if the debugger
you have is called "powerpc-elf-gdb".
  

> Date: Wed, 6 Aug 2014 10:37:05 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: vapier@gentoo.org, gdb-patches@sourceware.org,
> 	monaka@monami-software.com
> 
> I just found it odd that you'd do "man powerpc-elf-gdb" but then do
> "info gdb", even if the debugger you have is called
> "powerpc-elf-gdb".

That's true, but the main motivation for the issue at hand was
"make uninstall", which I think doesn't apply to the Info manual.
  

> > I just found it odd that you'd do "man powerpc-elf-gdb" but then do
> > "info gdb", even if the debugger you have is called
> > "powerpc-elf-gdb".
> 
> That's true, but the main motivation for the issue at hand was
> "make uninstall", which I think doesn't apply to the Info manual.

I am not sure I understand why gdb.info is any different from
man/gdb.X in that respect. If I do:

  % cd /path/to/native-gdb/build
  % make install
  % cd /path/to/cross-gdb/build
  % make install

... and then do ...

  % make uninstall

... wouldn't that delete gdb.info?
  

On Wed, Aug 6, 2014 at 12:53 PM, Joel Brobecker <brobecker@adacore.com> wrote:
>> > I just found it odd that you'd do "man powerpc-elf-gdb" but then do
>> > "info gdb", even if the debugger you have is called
>> > "powerpc-elf-gdb".
>>
>> That's true, but the main motivation for the issue at hand was
>> "make uninstall", which I think doesn't apply to the Info manual.
>
> I am not sure I understand why gdb.info is any different from
> man/gdb.X in that respect. If I do:
>
>   % cd /path/to/native-gdb/build
>   % make install
>   % cd /path/to/cross-gdb/build
>   % make install
>
> ... and then do ...
>
>   % make uninstall
>
> ... wouldn't that delete gdb.info?

Yeah, but it would also delete all the, e.g., python files (absent
configure args to put them in separate places, but then the sharing is
gone).

So either "make uninstall" has to work differently in a shared
context, or there can be no sharing, or accept the issue and maybe
provide another uninstall rule to skip possibly shared files.

Though reading the original post I'm not sure "make uninstall" was the
main motivation here, rather that the installed man page should match
the installed binary name (and if one went that route then "make
uninstall" would need similar changes).  Could have misread though.

Do we really need to install ${target}-gdb.1 ?
  

> > ... wouldn't that delete gdb.info?
> 
> Yeah, but it would also delete all the, e.g., python files (absent
> configure args to put them in separate places, but then the sharing is
> gone).

Hmmm, that's true.

> So either "make uninstall" has to work differently in a shared
> context, or there can be no sharing, or accept the issue and maybe
> provide another uninstall rule to skip possibly shared files.
> 
> Though reading the original post I'm not sure "make uninstall" was the
> main motivation here, rather that the installed man page should match
> the installed binary name (and if one went that route then "make
> uninstall" would need similar changes).  Could have misread though.

That's what I thought when I approved that patch, and I thought
it did make sense.

> Do we really need to install ${target}-gdb.1 ?

"need" is a matter of degree, IMO :-). Theoretically speaking,
I think that someone using ${target}-gdb should be able to type
"man ${target}-gdb", rather than have to realize that ${target}-gdb
and gdb both have the same interface and thus type "man gdb"
instead.

There are therefore 2 parallel issues:
  (1) Should we support out of the box distinct targets to be installed
      at the same prefix?
  (2) Should the name of some of those files match the name of
      the executable?

For (1), I'm leaning towards a "not necessary", but we can perhaps
find a middle ground. I don't know the various defaults to really
help making a decision without spending some time to look at it.
Either way, I have a fairly neutral opinion, so I am happy following
the group.

For (2), I thought that for the man page, and (to some degree, since
I know little about info) the "info" page as well. But again,
I don't really have much of opinion on that.

I don't feel I have much else to share for discussion, so I think
we should just decide (or decide to not decide ;-)), and let people
send patches following those decisions.
  

On Wed 06 Aug 2014 06:24:35 Joel Brobecker wrote:
> > along these lines, should we also transform the default gdb datadir (for
> > python and xml files) ?  and info pages ?  looking at my cross-debugger
> > installs, those are the other big missing pieces.
> 
> For the default gdb_datadir, I am of two minds on this. It's really
> easy to adjust as desired at configure time, and I think that multiple
> GDB installs made at the same location should be compatible, and
> thus should be able to share their Python/XML files. But as previously
> said, it's not a strong opinion.

i'm not sure that's a good idea.  how do you deal with version skews ?  if i 
have gdb-7.8 installed as my native version and i have sh4-linux-gnu-
gdb-7.0.1, i think it's unreasonable to expect that the data files installed 
with my latest version will work fine with the older one.  we're talking the 
python files and cpu definitions and such.  i don't think the project wants to 
commit to maintaining backwards compatibility forever :).

further, distros already have to deal with this.  their choice is either:
(1) delete the data files for all non-native gdbs since they can't all install 
over top of each other
 -> cross gdb doesn't work unless you first install the native gdb
 -> distro commits to it working :)
(2) install the gdb files into a target-specific path
 -> cross gdb always works
 -> diff distros will probably pick a different path standard

i think it's best if the default gdb datadir automatically selected a unique 
location.  i just mean the default -- certainly if someone set the datadir via 
configure, that path should always be used.

in Gentoo, i was doing (1), but then i got reports about things breaking, so 
i've gone with (2) now.  i'm using ${datadir}/gdb/${target}, but i don't 
particularly care about the name :).
-mike
  

On Wed 06 Aug 2014 20:05:20 Eli Zaretskii wrote:
> > Date: Wed, 6 Aug 2014 06:24:35 -0700
> > From: Joel Brobecker <brobecker@adacore.com>
> > Cc: gdb-patches@sourceware.org,	Masaki Muranaka
> > <monaka@monami-software.com>
> > 
> > For GDB's info page, I think we should indeed apply the transformation,
> > to be consistent.
> 
> I'm not sure I agree.  What other projects do that?  I never saw any
> transformed Info manual.  And we never did that before, so why now?
> 
> Besides, why do that?  The Info manual does not include any
> system-specific information, it is valid for all supported systems.
> So I see no reason to put it into a system-dependent place or call it
> by system-dependent name.

it's not system-dependent, but it is version dependent.  reading the 
documentation for the native version can be wildly inaccurate than the 
documentation for the cross version.  it's probably less of an issue for gdb 
as features/flags don't change wildly quickly, but it makes a huge difference 
for gcc (e.g. 4.7 to 4.8 to 4.9).
-mike
  

> Date: Wed, 6 Aug 2014 14:34:12 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, Mike Frysinger <vapier@gentoo.org>,
> 	gdb-patches <gdb-patches@sourceware.org>,
> 	monaka@monami-software.com
> 
>   (1) Should we support out of the box distinct targets to be installed
>       at the same prefix?
>   (2) Should the name of some of those files match the name of
>       the executable?
> 
> For (1), I'm leaning towards a "not necessary", but we can perhaps
> find a middle ground. I don't know the various defaults to really
> help making a decision without spending some time to look at it.
> Either way, I have a fairly neutral opinion, so I am happy following
> the group.
> 
> For (2), I thought that for the man page, and (to some degree, since
> I know little about info) the "info" page as well. But again,
> I don't really have much of opinion on that.

But "info FOO" does not mean "show me the file FOO", it means "show me
the manual whose DIR entry is FOO".  (Although the stand-alone Info
reader falls back to the file interpretation if it doesn't find FOO in
the DIR menu.)

And the Info system doesn't really support more than one manual for
the same tool anyway.

So I think, unlike the man pages, the Info manual should not be
renamed.
  

> From: Mike Frysinger <vapier@gentoo.org>
> Cc: Joel Brobecker <brobecker@adacore.com>, gdb-patches@sourceware.org, monaka@monami-software.com
> Date: Wed, 06 Aug 2014 20:21:13 -0400
> 
> > Besides, why do that?  The Info manual does not include any
> > system-specific information, it is valid for all supported systems.
> > So I see no reason to put it into a system-dependent place or call it
> > by system-dependent name.
> 
> it's not system-dependent, but it is version dependent.  reading the 
> documentation for the native version can be wildly inaccurate than the 
> documentation for the cross version.  it's probably less of an issue for gdb 
> as features/flags don't change wildly quickly, but it makes a huge difference 
> for gcc (e.g. 4.7 to 4.8 to 4.9).

As I wrote elsewhere, Info doesn't support different versions of the
same manual installed on the same system, without some non-trivial
tinkering.
  

> So I think, unlike the man pages, the Info manual should not be
> renamed.

OK, as far as I am concerned, that's a decision.

Thanks, Eli.
  

On Thu 07 Aug 2014 18:50:43 Eli Zaretskii wrote:
> > From: Mike Frysinger <vapier@gentoo.org>
> > Cc: Joel Brobecker <brobecker@adacore.com>, gdb-patches@sourceware.org,
> > monaka@monami-software.com Date: Wed, 06 Aug 2014 20:21:13 -0400
> > 
> > > Besides, why do that?  The Info manual does not include any
> > > system-specific information, it is valid for all supported systems.
> > > So I see no reason to put it into a system-dependent place or call it
> > > by system-dependent name.
> > 
> > it's not system-dependent, but it is version dependent.  reading the
> > documentation for the native version can be wildly inaccurate than the
> > documentation for the cross version.  it's probably less of an issue for
> > gdb as features/flags don't change wildly quickly, but it makes a huge
> > difference for gcc (e.g. 4.7 to 4.8 to 4.9).
> 
> As I wrote elsewhere, Info doesn't support different versions of the
> same manual installed on the same system, without some non-trivial
> tinkering.

i'm aware of the info indexing collisions.  i deal with this with a lot of 
system packages in Gentoo.  but a problem being hard doesn't mean we shouldn't 
try to make it work if it's the right thing to do ;).

so the first question is, is this scenario important to us ?  or do we 
consider people dealing with cross-gdb's to be on their own and to figure out 
documentation skew problems themselves ?  lumping it into the category of "if 
you're cross-compiling/debugging, you know what you're doing" doesn't fly as 
there a _lot_ of people who do cross work and know very little here -- someone 
else is responsible for building/packaging the toolchain and they were just 
given it and told "use xxx-gcc and xxx-gdb".

i think it's useful to have the full manual with the right version available 
on a per-target basis, but maybe others here don't think it's useful enough to 
justify the work to make the info pages work.  i.e. more of the ongoing 
maintenance cost rather than just the initial up-front cost.  maybe we can get 
assistance from the texinfo project to make this scenario easier so we don't 
have to implement & deploy the same hack in every project ...
-mike
  

> From: Mike Frysinger <vapier@gentoo.org>
> Cc: brobecker@adacore.com, gdb-patches@sourceware.org, monaka@monami-software.com
> Date: Thu, 07 Aug 2014 22:52:57 -0400
> 
> so the first question is, is this scenario important to us ?  or do we 
> consider people dealing with cross-gdb's to be on their own and to figure out 
> documentation skew problems themselves ?

I see no documentation skews here.  The GDB manual documents (barring
errors that should be reported and fixed) describes all of its
versions, including cross-gdb.  The names of the Info files that
constitute the manual are not important.  If we want to do anything
that really matters, we should add rules to insert menu items into the
DIR menu that name the cross-gdb that is being installed, and point to
the same GDB manual whose file name is always gdb.info.  And even this
is a minor issue, as a person who builds and uses cross-gdb surely
knows that she builds and uses GDB.

> lumping it into the category of "if you're
> cross-compiling/debugging, you know what you're doing" doesn't fly
> as there a _lot_ of people who do cross work and know very little
> here -- someone else is responsible for building/packaging the
> toolchain and they were just given it and told "use xxx-gcc and
> xxx-gdb".

I don't see how people who know very little could ever be able to work
with GDB, or even with a cross-compiler, for that matter.  But I guess
we will have to agree to disagree here.

> i think it's useful to have the full manual with the right version available 
> on a per-target basis, but maybe others here don't think it's useful enough to 
> justify the work to make the info pages work.  i.e. more of the ongoing 
> maintenance cost rather than just the initial up-front cost.  maybe we can get 
> assistance from the texinfo project to make this scenario easier so we don't 
> have to implement & deploy the same hack in every project ...

Like I said, I object.  If and when Texinfo makes it possible to
seamlessly have several versions of the same manual on the same
system, I will certainly reconsider (if I'm still around).
  

On Thu 07 Aug 2014 18:43:34 Eli Zaretskii wrote:
> >   (1) Should we support out of the box distinct targets to be installed
> >       at the same prefix?
> >   (2) Should the name of some of those files match the name of
> >       the executable?
> > 
> > For (1), I'm leaning towards a "not necessary", but we can perhaps
> > find a middle ground. I don't know the various defaults to really
> > help making a decision without spending some time to look at it.
> > Either way, I have a fairly neutral opinion, so I am happy following
> > the group.
> > 
> > For (2), I thought that for the man page, and (to some degree, since
> > I know little about info) the "info" page as well. But again,
> > I don't really have much of opinion on that.
> 
> But "info FOO" does not mean "show me the file FOO", it means "show me
> the manual whose DIR entry is FOO".  (Although the stand-alone Info
> reader falls back to the file interpretation if it doesn't find FOO in
> the DIR menu.)
> 
> And the Info system doesn't really support more than one manual for
> the same tool anyway.
> 
> So I think, unlike the man pages, the Info manual should not be
> renamed.

yes, you'd actually have to rewrite the base node name so that instead of 
identifying itself as "gdb" it'd be "${target}-gdb" (i.e. apply the program 
transformation).  then doing `info sh4-linux-gnu-gdb` would give you the 
correct man page.  this matches the man page behavior where you can do `man 
sh4-linux-gnu-gdb` and such.
-mike
  

On Fri 08 Aug 2014 09:05:10 Eli Zaretskii wrote:
> > From: Mike Frysinger <vapier@gentoo.org>
> > Cc: brobecker@adacore.com, gdb-patches@sourceware.org,
> > monaka@monami-software.com Date: Thu, 07 Aug 2014 22:52:57 -0400
> > 
> > so the first question is, is this scenario important to us ?  or do we
> > consider people dealing with cross-gdb's to be on their own and to figure
> > out documentation skew problems themselves ?
> 
> I see no documentation skews here.  The GDB manual documents (barring
> errors that should be reported and fixed) describes all of its
> versions, including cross-gdb.

i described the skews in my other e-mail which you responded to.  your `info 
gdb` obviously only describes that specific version of gdb.  the further away 
your cross version gets (newer or older), the more the manual does not help 
but even confuses.  you can't even use the online gdb manual because that only 
reflects the very latest versions (unlike say gcc which archives the manual 
for every release online).  that leaves people with `man $target-gdb` which 
only describes the command line interface.

> > lumping it into the category of "if you're
> > cross-compiling/debugging, you know what you're doing" doesn't fly
> > as there a _lot_ of people who do cross work and know very little
> > here -- someone else is responsible for building/packaging the
> > toolchain and they were just given it and told "use xxx-gcc and
> > xxx-gdb".
> 
> I don't see how people who know very little could ever be able to work
> with GDB, or even with a cross-compiler, for that matter.  But I guess
> we will have to agree to disagree here.

then you obviously haven't dealt with real world customers ;).  it isn't that 
they can't look up and find information (eventually).  but providing a state 
where they predestined to fail isn't exactly great.
-mike
  

On 08/08/2014 07:19 AM, Mike Frysinger wrote:
> On Thu 07 Aug 2014 18:43:34 Eli Zaretskii wrote:
>>>   (1) Should we support out of the box distinct targets to be installed
>>>       at the same prefix?
>>>   (2) Should the name of some of those files match the name of
>>>       the executable?
>>>
>>> For (1), I'm leaning towards a "not necessary", but we can perhaps
>>> find a middle ground. I don't know the various defaults to really
>>> help making a decision without spending some time to look at it.
>>> Either way, I have a fairly neutral opinion, so I am happy following
>>> the group.
>>>
>>> For (2), I thought that for the man page, and (to some degree, since
>>> I know little about info) the "info" page as well. But again,
>>> I don't really have much of opinion on that.
>>
>> But "info FOO" does not mean "show me the file FOO", it means "show me
>> the manual whose DIR entry is FOO".  (Although the stand-alone Info
>> reader falls back to the file interpretation if it doesn't find FOO in
>> the DIR menu.)
>>
>> And the Info system doesn't really support more than one manual for
>> the same tool anyway.
>>
>> So I think, unlike the man pages, the Info manual should not be
>> renamed.
> 
> yes, you'd actually have to rewrite the base node name so that instead of 
> identifying itself as "gdb" it'd be "${target}-gdb" (i.e. apply the program 
> transformation).  then doing `info sh4-linux-gnu-gdb` would give you the 
> correct man page.  this matches the man page behavior where you can do `man 
> sh4-linux-gnu-gdb` and such.

Eh, I always assumed this sort of thing is why we write @value{GDBN} all
over the manual, and that we were already transforming that, but indeed
seems like we aren't.

Thanks,
Pedro Alves
  

On 08/08/2014 08:17 AM, Mike Frysinger wrote:
> you can't even use the online gdb manual because that only 
> reflects the very latest versions (unlike say gcc which archives the manual 
> for every release online).

Yeah, kind of off topic, but we really should fix that...

Any brave soul wants to take that?

Thanks,
Pedro Alves
  

> Date: Thu, 21 Aug 2014 15:26:22 +0100
> From: Pedro Alves <palves@redhat.com>
> CC: Joel Brobecker <brobecker@adacore.com>, dje@google.com,
>         gdb-patches@sourceware.org, monaka@monami-software.com
> 
> > yes, you'd actually have to rewrite the base node name so that instead of 
> > identifying itself as "gdb" it'd be "${target}-gdb" (i.e. apply the program 
> > transformation).  then doing `info sh4-linux-gnu-gdb` would give you the 
> > correct man page.  this matches the man page behavior where you can do `man 
> > sh4-linux-gnu-gdb` and such.
> 
> Eh, I always assumed this sort of thing is why we write @value{GDBN} all
> over the manual, and that we were already transforming that, but indeed
> seems like we aren't.

In addition, we would need to use @value{GDBN} in the @direntry
section of gdb.texinfo.