Discussion: Formalizing the deprecation process in GDB

Discussion: Formalizing the deprecation process in GDB

[Joel Brobecker]

Per Andrew Cagney's request, I am reposting here a message I sent on
gdb-patches after a long discussion between Andrew and Eli Zaretskii
on when parts of GDB's code can be marked as deprecated and how they
should be marked as deprecated.

Andrew also asked me to post Eli's answer, but I can't find it in
the archives. Sorry Eli, you'll have to resend them.

>It seems to me that the whole discussion between Eli and yourself has
>been beaten to death. We're basically stuck in a disagrement where both
>point of views have their merit.
>
>I think it's time all global maintainers get involved in this discussion
>and make a decision. Once the decision is taken, it needs to be
>documented (gdb.texinfo for instance) so that people can refer to it.
>
>As a developper, I personally dislike to have to check the ARI everytime
>I use anything in GDB for fear of using something deprecated. So marking
>each instance as explicitly deprecated directly in the code is a good
>move. Two questions were asked and need to be answered. I am adding my
>proposed answers, as a starting point for your discussion:
>
>  1. When can some code be declared deprecated?
>
>     IMO, some code should be declared deprecated when it has been
>     recognized that it should no longer be used in new changes.
>     It means that some code can be identified as deprecated before
>     a replacement has been implemented.
>
>     There is a judgement call to make, obviously, as we don't want to
>     deprecate a central piece of GDB that makes it impossible for
>     somebody to submit a new port for instance without doing man-years
>     of work required to implement an alternate to the deprecated
>     feature.
>
>  2. How to identify deprecated code?
>
>     Deprecated code should be explicitly marked as such directly
>     in the code, to avoid any accidental future usage, by prepending
>     "depreated_" to the entity names.
>     
>     Deprecated code can only be removed when no longer used. There can
>     be no time limit imposed between the time some code is deprecated,
>     and the time when it is removed.
>
>     (the alternate solution suggested by Eli is the ARI)
>
>You should decide how the discussion will be held (privately or on
>gdb-patches?), and whether it should include the steering committee
>or not.


-- 
Joel

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> Date: Mon, 27 Sep 2004 10:55:39 -0700
> From: Joel Brobecker <brobecker@gnat.com>
> Cc: Andrew Cagney <cagney@redhat.com>, Eli Zaretskii <eliz@gnu.org>
> 
> Andrew also asked me to post Eli's answer, but I can't find it in
> the archives. Sorry Eli, you'll have to resend them.

I moved the thread to gdb@ right there and then, so my response is
in the archives of this mailing list rather than in gdb-patches:

  http://sources.redhat.com/ml/gdb/2004-09/msg00120.html

Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney]

> Per Andrew Cagney's request, I am reposting here a message I sent on
> gdb-patches after a long discussion between Andrew and Eli Zaretskii
> on when parts of GDB's code can be marked as deprecated and how they
> should be marked as deprecated.
> 
> Andrew also asked me to post Eli's answer, but I can't find it in
> the archives. Sorry Eli, you'll have to resend them.

Over the years GDB's evolved three related processes for addressing the 
problem of old or dead code:

- deprecate
- obsolete
- garbage collect
- end-of-life

each serves a purpose (but only the middle one is currently documented).

- deprecate

This is a flagging mechanisms (namely for interfaces).  It doesn't come 
with any time table and hence there's no exit strategy for their 
elimination.

This mechanism has proved extreemly effective, in particular in 
addressing the problem of contributors trying to add new, but largely 
self contained, components such as architectures needing to know what is 
in and what is out.  It's taken away the oportunity to flip-flop over 
what can and can not be used by such a contribution.

- obsolete

This was introduced during multi-arch and went with a long and bloody 
battle - there was much debate over the relative merits of removing old 
code (rather than retaining it "just in case").  It was so that we could 
could remove old targets and architectures that were being identified as 
multi-arch was progressing.

- garbage collect

While different people use different names, the principle is the same - 
if it's no longer reachable, it can be removed.

- end-of-life

GDB 6.2 saw the old frame code reaching its end of life.  It let us 
remove a huge chunk code propping up old, and clearly unmaintained 
architectures.  GDB 6.3 will do similar with deprecated_registers[].

With out this we'd have been forced to support those old architectures 
indefinitly.

>>>It seems to me that the whole discussion between Eli and yourself has
>>>been beaten to death. We're basically stuck in a disagrement where both
>>>point of views have their merit.
>>>
>>>I think it's time all global maintainers get involved in this discussion
>>>and make a decision. Once the decision is taken, it needs to be
>>>documented (gdb.texinfo for instance) so that people can refer to it.
>>>
>>>As a developper, I personally dislike to have to check the ARI everytime
>>>I use anything in GDB for fear of using something deprecated. So marking
>>>each instance as explicitly deprecated directly in the code is a good
>>>move. Two questions were asked and need to be answered. I am adding my
>>>proposed answers, as a starting point for your discussion:
>>>
>>>  1. When can some code be declared deprecated?
>>>
>>>     IMO, some code should be declared deprecated when it has been
>>>     recognized that it should no longer be used in new changes.
>>>     It means that some code can be identified as deprecated before
>>>     a replacement has been implemented.

>>>     There is a judgement call to make, obviously, as we don't want to
>>>     deprecate a central piece of GDB that makes it impossible for
>>>     somebody to submit a new port for instance without doing man-years
>>>     of work required to implement an alternate to the deprecated
>>>     feature.

Right.

In general though the basic mechanism is implemented and demonstrated.

>>>  2. How to identify deprecated code?
>>>
>>>     Deprecated code should be explicitly marked as such directly
>>>     in the code, to avoid any accidental future usage, by prepending
>>>     "depreated_" to the entity names.
>>>     
>>>     Deprecated code can only be removed when no longer used. There can
>>>     be no time limit imposed between the time some code is deprecated,
>>>     and the time when it is removed.
>>>
>>>     (the alternate solution suggested by Eli is the ARI)

Right.

I think it is important that we all remember that this mechanism is 
strictly internal (to the user, nothing is visible) and in no way is 
ment to demean a specific architecture, system, or developer concerned 
with that area.  We should be careful to not interpret it as such.

Working through Eli's reply ...

>>   1. When can some code be declared deprecated?
>> 
>>      IMO, some code should be declared deprecated when it has been
>>      recognized that it should no longer be used in new changes.
>>      It means that some code can be identified as deprecated before
>>      a replacement has been implemented.
> 
> "Identified as deprecated" and "declared deprecated" need not happen
> at the same time.  That time might (and IMHO should) be used to
> implement the replacement.
> 
>>      There is a judgement call to make, obviously, as we don't want to
>>      deprecate a central piece of GDB that makes it impossible for
>>      somebody to submit a new port for instance without doing man-years
>>      of work required to implement an alternate to the deprecated
>>      feature.
> 
> I note that you didn't suggest any way out of this contradiction.  I
> did suggest such a way: implement and commit the alternate mechanism
> before or together with the patch that marks the old code deprecated.

We went through a very much the same debate with obsolete:

- should we blindly convert the obsolete code to new mechanisms

- or should we leave that task for someone with both the motivation to 
take on the challenge and the facilities to test it

we choose the latter, and with good reason.

- any blindly converted mechanism wasn't tested and didn't work - wasted 
effort

- we can't be requireing contributors to be expected to maintan/fix each 
and every system when many of those same systems have no relevance 
(think many of the more obscure architectures or targets)

In theory deprecation should be initiated by the relevant maintaner - 
arch, targ, symtab - but here reality is that I do it.  The process is 
that they are posted one week and committed the next which gives plenty 
of time for objection (and we've seen a few of them).

We should document this.

>>   2. How to identify deprecated code?
>> 
>>      Deprecated code should be explicitly marked as such directly
>>      in the code, to avoid any accidental future usage, by prepending
>>      "depreated_" to the entity names.
> 
> This doesn't ensure that accidental future use is avoided, because not
> all contributors have the latest CVS before their eyes when they work
> on their contribution.

There are rarely absolutes.

On the other hand this mechansm has proven its self very effective. 
People contributing new architectures, natives and systems are very 
aware of the expectation that they can't use deprecated mechanisms. 
People maintaining existing architectures et.al. are equally aware of 
this and they too focus on the need to get things updated.

> A requirement that everything important for the contributor to get
> his/her code right the first time be in the code is IMHO ridiculous:
> it will, for example, cause us to spill a large part of gdbint.texinfo
> into the sources, as well as the contents of MAINTAINERS and PROBLEMS.
> 
> The correct (IMHO) way out of this predicament is to request that
> contributors read all the relevant pieces of code and documentation
> (if they don't know, they can ask where to look).  Of course, this
> doesn't eliminate a possibility that they will overlook, but I'm not
> aware of any project that avoided that with a 100% insurance; I don't
> see why this should be such a great deal here.

We're programmers.  We speak through the code.  The internals document 
has its place, but the bottom line is that the code and not the 
internals document determines how GDB works.  Hence, that is what 
programmers read.

> More generally, AFAIR the "depreated_" stunt was invented mainly as an
> aid to the maintainer(s): to make their job easier when they want to
> know what stuff is candidate for deletion.  It is a bit funny to see
> this convenience trick sudenly being inflated with so much ideology.

Who's recollection?

Real deprecation started with multi-arch in '98 (your first post was in 
'99) vs:

- as architecture macro's were were replaced by architecture methods the 
old macros were deprecated.

- as old poorly designed architecture-interfaces were re-implemented 
(allowing us to fix long standing bugs) the old were deprecated.

- as redundant architecture methods were identified, they were deprecated.

Yes, it did make my job easier - I didn't have to chase after people 
constantly reminding them that the're using deprecated methods and plead 
with them not to.

This effort has been been going on for years, it's hardly a stunt.

Andrew

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> Date: Wed, 06 Oct 2004 01:08:13 -0400
> From: Andrew Cagney <cagney@gnu.org>
> Cc: gdb@sources.redhat.com, Andrew Cagney <cagney@redhat.com>

Andrew, thank you for an informative message.

Unfortunately, it doesn't help in making a progress in this
discussion, since all it does is reiterate your opinions that were
clear (at least to me) during the XM_FILE debate, or else explaining
principles and generalities that don't need to be explained.

I'm fully aware that you, and at least some of the other maintainers,
are eager to deprecate and remove code that you think is not
maintained quickly enough for your liking.  It is probably not news to
you that I don't like that eagerness; we had enough discussions in the
past along those lines, and I didn't make a secret out of my views.  I
think such tendencies are harsh on the users and on sysadmins (in
fact, they are harsh on everybody but GDB developers), and are not at
all justified by the added maintenance burden they are allegedly
supposed to magically remove.

So saying once again that you don't want to request patch contributors
(which is mostly yourself in the case of "deprecated_" stuff) to fix
the affected portions of the code as a perequisite for accepting the
patch, and that you don't want to maintain obsolete code, does not
change anything in what is already known as a serious disagreement.
If that is all we can say, let's just agree to disagree, and be done
with that.

If you do want to try to convince me, you (or someone else who thinks
like you) will have to do better than that.

> In theory deprecation should be initiated by the relevant maintaner - 
> arch, targ, symtab - but here reality is that I do it.  The process is 
> that they are posted one week and committed the next which gives plenty 
> of time for objection (and we've seen a few of them).

I'm not sure a week is enough for automatic commits of this kind, but
I'm not sure I'm willing to start another debate about that.

> We're programmers.  We speak through the code.  The internals document 
> has its place, but the bottom line is that the code and not the 
> internals document determines how GDB works.  Hence, that is what 
> programmers read.

I'm not sure what is it that you are saying here.  Should we abandon
gdbint.texinfo and instead rely on the code to explain itself, because
``we are programmers and thus code is the only thing we read''?  Maybe
I should stop trying so hard to review each documentation patch in a
matter of days, because the code already says all there is to tell?

I agree with the principle that we should draw a line somewhere
between the part of the documentation that should go into a manual and
the part that should stay in the code, so the argument is not over the
principle.  I hope you will agree that, in principle, _some_
information _can_ be put in a manual, because otherwise I don't
understand why you just pinged me to review your gdbint patches about
branching and versioning; why not have that as comments to version.in,
for example?

The issue at hand is not the principle, but rather my very specific
suggestion that the fact some code or method is deprecated could be
stated in the manual.  If you object to that specific suggestion,
please back up your opinion by specific arguments, not by reiterating
abstract principles to which we all agree.

> Real deprecation started with multi-arch in '98 (your first post was in 
> '99)

What does the date of my first post have to do with the issue at hand?
Isn't it possible that I've also read the archives, even beyond the
days I started to be an active GDB maintainer?

> Yes, it did make my job easier - I didn't have to chase after people 
> constantly reminding them that the're using deprecated methods and plead 
> with them not to.

Chasing after people vs deprecating every code portion you don't want
to try to fix are not the only two alternatives to solve the problem.
And even if those _are_ the only two alternatives, there's still a lot
of leeway as to the point where you stop chasing and start deprecating.
And the location of that point is _exactly_ what we disagree about.

Once again, to have a meaningful and potentially useful discussion,
specific arguments about practical criteria to reach the decision
between these two alternatives are needed, not reiteration of general
principles.

Re: Discussion: Formalizing the deprecation process in GDB

[Joel Brobecker]

> Unfortunately, it doesn't help in making a progress in this
> discussion, since all it does is reiterate your opinions that were
> clear (at least to me) during the XM_FILE debate, or else explaining
> principles and generalities that don't need to be explained.

The reason why I sent my message was that I felt that both parties
had exposed their views and that both had their merits. So I felt
that it was necessary to bring more people in the discussion and
decide one way or the other. I suggested that the discussion group
be the global maintainers for instance.

> I'm not sure what is it that you are saying here.  Should we abandon
> gdbint.texinfo and instead rely on the code to explain itself, because
> ``we are programmers and thus code is the only thing we read''?  Maybe
> I should stop trying so hard to review each documentation patch in a
> matter of days, because the code already says all there is to tell?

Just my two cents on this specific topic:

I do agree with Andrew that the place were developers search
for documentation is the code. I would love to see a lot of the
documentation contained in gdbint.texinfo be moved as comments
into the code. Having the documentation embedded inside the code
is very convenient, and also where I have been trained to look
first.

This does not mean that I am suggesting that we get rid of gdbint
entirely. I see chapters and sections that can only be placed in
a separate documentation, such as how to add support for a new
host for instance. But the documentation about partial symbol
tables, for instance, would be much more useful directly in
symtab.h or symtab.c.

I don't know about others, but I have read the gdbint manual once
from cover to cover almost 4 years ago, and never refered to it
anymore.

-- 
Joel

RE: Discussion: Formalizing the deprecation process in GDB

[Dave Korn]

> -----Original Message-----
> From: gdb-owner On Behalf Of Joel Brobecker
> Sent: 07 October 2004 03:41

> I do agree with Andrew that the place were developers search
> for documentation is the code. 

  Not me!  I look for the internals docs!  And complain bitterly when I
can't find them (because they don't exist) or they're years out of date!

> This does not mean that I am suggesting that we get rid of gdbint
> entirely. I see chapters and sections that can only be placed in
> a separate documentation, such as how to add support for a new
> host for instance. But the documentation about partial symbol
> tables, for instance, would be much more useful directly in
> symtab.h or symtab.c.

  Ok, I also read the code, but I very much appreciate having good
documentation in book format.  If you've got a serious chunk of architecture
to learn about, it's a lot easier if it's all in one file that you can print
out and browse through at your leisure rather than a page here and a page
there scattered across many files.

  FWIW I reckon gcc is getting it very right these days.  There's a
heavyweight internals manual that explains the architecture and big picture
issues.  Each file that implements a substantial module of functionality
then also has documentation about its internals and implementation at the
top of the file.  Usually you only need the internals manual, and only if
you find yourself rummaging around in the depths of alias analysis or
something chasing a bug do you find yourself needing the per-file-internal
documentation.

> I don't know about others, but I have read the gdbint manual once
> from cover to cover almost 4 years ago, and never refered to it
> anymore.

  Since opinions are being invited, I'll just mention that I'm currently
working on an internal version of gdb for which I'm having to up-port a
5.x-compatible backend to 6.x series.  I sometimes find it *ever* so hard
when faced with yet another deprecated__ this or obsoleted_ that to know
what the new and approved replacement is, and it often takes a combination
of the internals manual, the in-source documentation and comments, and much
searching of the list archive for the actual patch that made the deprecation
to see how it was done at the time and understand the background and
reasoning to it.  I understand the reasons for using this technique and
agree that it's sound engineering practice and necessary for the onward
development of gdb, but I would like an easier solution to the general
problem of knowing what to replace something with, and one that could be
used off-line or on those occasions when sourceware goes down and you can't
get at the list archive!


    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

Re: Discussion: Formalizing the deprecation process in GDB

[Joel Brobecker]

(this discussion about the internals documentation is for the purpose
of formalizing the deprecation mechanism)

> > I do agree with Andrew that the place were developers search
> > for documentation is the code. 
> 
>   Not me!  I look for the internals docs!  And complain bitterly when I
> can't find them (because they don't exist) or they're years out of date!

Well, one of the contributing factors of docs guetting out of date
is that they are out of the developer's view. You can thank Eli for
his tremendous job at keeping the gdbint doc in great shape, but also
alerting us when some documentation needs to be added/modified in that
manual.

But in any case, my point was not that we should get rid of the
internals manual entirely. There are parts that are more useful
in this manual rather than the in the code. Parts that explain
the big pictures, for instance, how everything fits together, etc.

However, sections such as the section that explain what observers
are, which ones are implemented, and what they should be used for,
in my opinion, should be documented in the code. (actually, now that
I think of it, the observer code is now generated from the doc -
but I'm sure I can find other examples).

-- 
Joel

Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney]

>   Ok, I also read the code, but I very much appreciate having good
> documentation in book format.  If you've got a serious chunk of architecture
> to learn about, it's a lot easier if it's all in one file that you can print
> out and browse through at your leisure rather than a page here and a page
> there scattered across many files.

(An architecture document is no more than 2 A4 pages, and one diagram - 
that is extreemly highlevel but gets across the concepts.)

>   FWIW I reckon gcc is getting it very right these days.  There's a
> heavyweight internals manual that explains the architecture and big picture
> issues.  Each file that implements a substantial module of functionality
> then also has documentation about its internals and implementation at the
> top of the file.  Usually you only need the internals manual, and only if
> you find yourself rummaging around in the depths of alias analysis or
> something chasing a bug do you find yourself needing the per-file-internal
> documentation.

Yes, it's useful to understand why this is.

GCC has a simple pipeline architecture <frontend>-<middleend>-<backend>. 
  It's details can be described at two levels: the interfaces between 
each "end" (ssa / rtl?); and the internals of a specific "end" (this 
implements algorithm X).

GDB doesn't have that luxury.  It's internals model the state of a 
running program using objects and their interactions.  In such a system 
it is the complex relationships between the objects that is important, 
and not the details of a specific bit of code.

For GCC typically a new "end" (or pass) can simply be plugged in, or an 
existing "end" rewritten.

For GDB, fixing the hard problems involves making changes to those 
complex object relationships and such requires significant and regular 
refactoring.

A system that is being continuously re-factored is not well suited for 
detailed internals documentation - the effort is wasted.  Instead the 
high level architecture and medium level object models that are important.

>   Since opinions are being invited, I'll just mention that I'm currently
> working on an internal version of gdb for which I'm having to up-port a
> 5.x-compatible backend to 6.x series.  I sometimes find it *ever* so hard
> when faced with yet another deprecated__ this or obsoleted_ that to know
> what the new and approved replacement is, and it often takes a combination
> of the internals manual, the in-source documentation and comments, and much
> searching of the list archive for the actual patch that made the deprecation
> to see how it was done at the time and understand the background and
> reasoning to it.  I understand the reasons for using this technique and
> agree that it's sound engineering practice and necessary for the onward
> development of gdb, but I would like an easier solution to the general
> problem of knowing what to replace something with, and one that could be
> used off-line or on those occasions when sourceware goes down and you can't
> get at the list archive!

For multi-arch I wrote a migration document.  This time I did not. 
There is no "migration" path.  The correct approach is:
- delete all deprecated code
- build
- run testsuite
- add a missing architecture vector method
- repeat
Instead of migrating, trying to reproduce each refactoring step, you 
should leap frog.

A running joke between several of the GDB developers at the last GCC 
summit was that we should present a 1hr paper titled "porting GDB to a 
new architecture".  Only instead of presenting slides, we'd just write 
the code.

Andrew

Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney]

> (this discussion about the internals documentation is for the purpose
> of formalizing the deprecation mechanism)
> 
> 
>>>> > I do agree with Andrew that the place were developers search
>>>> > for documentation is the code. 
>>
>>> 
>>>   Not me!  I look for the internals docs!  And complain bitterly when I
>>> can't find them (because they don't exist) or they're years out of date!
> 
> 
> Well, one of the contributing factors of docs guetting out of date
> is that they are out of the developer's view. You can thank Eli for
> his tremendous job at keeping the gdbint doc in great shape, but also
> alerting us when some documentation needs to be added/modified in that
> manual.
> 
> But in any case, my point was not that we should get rid of the
> internals manual entirely. There are parts that are more useful
> in this manual rather than the in the code. Parts that explain
> the big pictures, for instance, how everything fits together, etc.
> 
> However, sections such as the section that explain what observers
> are, which ones are implemented, and what they should be used for,
> in my opinion, should be documented in the code. (actually, now that
> I think of it, the observer code is now generated from the doc -
> but I'm sure I can find other examples).

Yea, bad example :-)

"observer.texi" illustrates a [contraversial?] compromise, at least the 
documentation is in a single place.  (BTW, JeffJ pointed out to me that 
the observer.texi doco has a bug - it doesn't document how to add a new 
observer - knowing to modify observer.texi isn't "obvious" :-).

"gdbarch.sh", "target.h", "inferior.h", ... are all better examples. 
For those, my things to do one day include get them into a format 
similar to observer.texi so that at least the interface is single source.

I think separate documentation is good for recording processes such as 
releasing gdb or version numbers; and higher level architecture and 
perhaps even some medium level models (showing how it is ment to be not 
how bu----ed it currently is :-).

Andrew

RE: Discussion: Formalizing the deprecation process in GDB

[Dave Korn]

> -----Original Message-----
> From: Andrew Cagney 
> Sent: 07 October 2004 16:38

> >   Ok, I also read the code, but I very much appreciate having good
> > documentation in book format.  If you've got a serious 
> chunk of architecture
> > to learn about, it's a lot easier if it's all in one file 
> that you can print
> > out and browse through at your leisure rather than a page 
> here and a page
> > there scattered across many files.
> 
> (An architecture document is no more than 2 A4 pages, and one 
> diagram - 
> that is extreemly highlevel but gets across the concepts.)

  Um, OK, that wasn't the kind of document I was talking about.  I was
thinking of something more like (frex) the set of manuals that describe and
specify the abstract PPC operating environment (without reference to any
specific ppc cpu implementation).

> A system that is being continuously re-factored is not well 
> suited for 
> detailed internals documentation - the effort is wasted.  Instead the 
> high level architecture and medium level object models that 
> are important.

  This is something more like what I meant to describe by the term "chunk of
architecture".  Or something like (to use another gcc example) rtl and the
chapter on rtl in the gccint manual.  As you say, high-to-mid range
overview.  Design decisions, system architecture, but not low-level
implementation specifics.

> There is no "migration" path.  The correct approach is:
> - delete all deprecated code
> - build
> - run testsuite
> - add a missing architecture vector method
> - repeat
> Instead of migrating, trying to reproduce each refactoring step, you 
> should leap frog.

  I'm not trying to migrate; I haven't been trying to get a stable working
version and make incremental changes that recapitulate the history of gdb's
recent development, I've been trying to do it all in one go as you suggest.
However, in order to do it all in one go, you still need to know *what* to
replace all the deprecated-and-deleted things with; that's not immediately
obvious by just browsing through the arch vector.  And it's quite easy to
implement some but not all of a set of mutually interacting or
interdependent arch methods and not know until you hit some particular
runtime combination of circumstances.

> A running joke between several of the GDB developers at the last GCC 
> summit was that we should present a 1hr paper titled "porting 
> GDB to a 
> new architecture".  Only instead of presenting slides, we'd 
> just write the code.

  I find it hard to believe that's possible for anyone who comes to the code
from fresh.  You have spent years working with gdb and have the advantage of
knowing your way round the code, and what the replacements for each
deprecated thing are; anyone else has to do lots of research.  If there's
going to be a formalization of the deprecation process, my 'feature request'
would be that there be one single central place where all deprecated
features are listed together with brief pointers to the new functionality
that has taken their place.

    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

RE: Discussion: Formalizing the deprecation process in GDB

[Dave Korn]

> -----Original Message-----
> From: Andrew Cagney 
> Sent: 07 October 2004 16:49
> To: Joel Brobecker; Dave Korn; 'Eli Zaretskii'

> >>>> > I do agree with Andrew that the place were developers search
> >>>> > for documentation is the code. 
> >>
> >>> 
> >>>   Not me!  I look for the internals docs!  And complain 
> bitterly when I
> >>> can't find them (because they don't exist) or they're 
> years out of date!

  It's just occurred to me that this could be read as a specific complaint
or accusation against gdb's documentation, rather than a comment on the
generally sorry state of documentation as a whole in the software industry.
No such inference was implied nor intended; sorry if anyone thought I was
criticising gdb with that statement!

> > Well, one of the contributing factors of docs guetting out of date
> > is that they are out of the developer's view. 

  Things like the doxygen format are good for that: you keep the doco for
(eg) a function right inline with the code, so it stands a good chance of
being kept up-to-date whenever anyone works on that bit of code, but then
there's an automated process that gathers all the documentation from its
many-and-widely-scattered locations in the source, and compiles it into one
nice neat help file.  I mention it because I think it's a good idea, but
have to say that I can't see any way it could be reasonably retrofitted to a
project on the scale of gdb, so I'm not sure if it was even worth mentioning
except out of academic interest....

> "gdbarch.sh", "target.h", "inferior.h", ... are all better examples. 
> For those, my things to do one day include get them into a format 
> similar to observer.texi so that at least the interface is 
> single source.

...  although maybe it could be useful in limited areas of application such
as this one!

  Thing is, coming newly to gdb, there isn't even anything to tell you to
look in any of those files.  It can be quite disheartening when you read

"This section is pretty much obsolete. The functionality described here has
largely been replaced by pseudo-registers and the mechanisms described in
Chapter 9 [Using Different Register and Memory Data Representations], page
30."

and you go to the reference and see

"The way GDB manipulates registers is undergoing significant change.
Many of the macros and functions refered to in this section are likely to be
subject to further revision."

and then you're left wondering "Well, what revision?  Which macros and
functions?  What should I actually _do_ about this?".  Or when you see lots
of things to do with registers have been deprecated, and there's this new
high-level mechanism called regcache, which is some kind of cache of the
inferiors registers, but there's no overview of the new scheme anywhere - or
at any rate, not in regcache.[ch].  Part of my problem is undoubtedly just
unfamiliarity with the code, so take my opinions on this matter as relating
particularly to the situation for someone getting to grips with gdb's
sources for the first time: it's very hard to break into.
 
> I think separate documentation is good for recording 
> processes such as 
> releasing gdb or version numbers; and higher level architecture and 
> perhaps even some medium level models (showing how it is ment 
> to be not 
> how bu----ed it currently is :-).

  Heh, basically this is indeed what I'm wishing for.

    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

Re: Discussion: Formalizing the deprecation process in GDB

[Joel Brobecker]

> > A running joke between several of the GDB developers at the last GCC 
> > summit was that we should present a 1hr paper titled "porting 
> > GDB to a 
> > new architecture".  Only instead of presenting slides, we'd 
> > just write the code.
> 
>   I find it hard to believe that's possible for anyone who comes to
>   the code from fresh.  You have spent years working with gdb and have
>   the advantage of knowing your way round the code, and what the
>   replacements for each deprecated thing are; anyone else has to do
>   lots of research.  If there's going to be a formalization of the
>   deprecation process, my 'feature request' would be that there be one
>   single central place where all deprecated features are listed
>   together with brief pointers to the new functionality that has taken
>   their place.

Yes, it would be hard for a newbie to port GDB to a different
architecture in an hour. Or I'd be very impressed :-).

Anyway, like in any project, there is a learning curve, and that
curve can be reduced to a certain degree by good documentation.
However, you have to balance the amount of document your write
and *maintain* with the amount of work this saves for some potential
contributor. I think that maintaining the list of deprecated features
in a separate document is going to be a large amount of work.
GDB is changing so fast.  It's simpler to put that information directly
in the code, and most of the time, the information is actually already
there.

I have to say that GDB's learning curve is not that steep, compared
to other projects I have worked on. You don't necessarily need to
grab the whole picture before you can actually start working effectively
on it. I have been contributing to GDB for several years now, and
I honestly still think that I don't have a complete global view of
GDB yet. Some areas I know very well, I have a rough idea of the major
components, how they interact, but some important areas are still
unexplored territory. If I had this global view, I think I could
be promoted as global maintainer :-).

-- 
Joel

RE: Discussion: Formalizing the deprecation process in GDB

[Dave Korn]

> -----Original Message-----
> From: Joel Brobecker 
> Sent: 07 October 2004 19:01

> Anyway, like in any project, there is a learning curve, and that
> curve can be reduced to a certain degree by good documentation.
> However, you have to balance the amount of document your write
> and *maintain* with the amount of work this saves for some potential
> contributor. 

  Yeh, of course, and being a relative newbie, it's hard for me to tell how
much (if any) of the difficulty I face is down to not having the right
balance (or just not enough docs), and how much of it is just inevitable
learning curve stuff.

>  I think that maintaining the list of deprecated features
> in a separate document is going to be a large amount of work.
> GDB is changing so fast.  

  Erm... things that get deprecated don't often get un-deprecated, do they?
Wouldn't it largely be a matter of just adding a couple of lines each time
something gets deprecated, just enough to say "All this stuff is now
replaced by the new XXXX mechanism; use XXXXX_do_whatever in place of
deprecated_OLDXXXXXX_do_somethingelse, or see gdb-XXXXX.h for more
information."  Or words to that effect.  Shouldn't it be possible for the
old entries in that document to then remain more or less static?  I'm
envisaging something that's a bit like a specialized changelog, but rather
than file-by-file and function-by-function descriptions of changes, which
are a bit low-level, it would have a list of deprecated functionalities and
their replacements.


    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

Re: Discussion: Formalizing the deprecation process in GDB

[Joel Brobecker]

>   Erm... things that get deprecated don't often get un-deprecated, do they?

No, they are supposed to disappear over time :-).

> Wouldn't it largely be a matter of just adding a couple of lines each time
> something gets deprecated, just enough to say "All this stuff is now
> replaced by the new XXXX mechanism; use XXXXX_do_whatever in place of
> deprecated_OLDXXXXXX_do_somethingelse, or see gdb-XXXXX.h for more
> information."  Or words to that effect.

But why is it better to write this in a document that's separate from
the code, instead of directly putting this in the code in an absolutely
clear way? If you rename the entity that's deprecated from "entity" to
"deprecated_entity", then it's pretty clear that you should no longer
be using it in new code, or else have a good reason for still using it.
Then if you want to know more, you just go to where the entity is
defined, and look at the comments there. If you put this in some
written document separate from the code, then you have to: change one
other file, ask for review from a different maintainer, then commit.
And then, you have to constantly remember from the doc which entities
are deprecated when you write code and when you review a change.
And then you have to remove it from the doc when the entity is finaly
removed.

In any case, the main debate between Andrew and Eli is not about where
to put the information, but *when* it is ok to decide that something
is declared deprecated.

-- 
Joel

RE: Discussion: Formalizing the deprecation process in GDB

[Fabian Cenedese]

>> A running joke between several of the GDB developers at the last GCC 
>> summit was that we should present a 1hr paper titled "porting 
>> GDB to a 
>> new architecture".  Only instead of presenting slides, we'd 
>> just write the code.
>
>  I find it hard to believe that's possible for anyone who comes to the code
>from fresh.  You have spent years working with gdb and have the advantage of
>knowing your way round the code, and what the replacements for each
>deprecated thing are; anyone else has to do lots of research.  If there's
>going to be a formalization of the deprecation process, my 'feature request'
>would be that there be one single central place where all deprecated
>features are listed together with brief pointers to the new functionality
>that has taken their place.

I also have been looking for this kind of document as I have come across
deprecated functions. As I couldn't find something I started using them
knowing that the code won't be accepted like this. Following now this
discussion that would mean that I haven't read the accompanying
comments of the deprecated functions or I would have seen the proposed
replacements. I guess I need to look harder. So even if you don't come
to a conclusion you have helped a newbie :)

Thanks

bye  Fabi

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> Date: Wed, 6 Oct 2004 19:40:48 -0700
> From: Joel Brobecker <brobecker@gnat.com>
> Cc: Andrew Cagney <cagney@gnu.org>, gdb@sources.redhat.com
> 
> I do agree with Andrew that the place were developers search
> for documentation is the code. I would love to see a lot of the
> documentation contained in gdbint.texinfo be moved as comments
> into the code. Having the documentation embedded inside the code
> is very convenient, and also where I have been trained to look
> first.
> 
> This does not mean that I am suggesting that we get rid of gdbint
> entirely. I see chapters and sections that can only be placed in
> a separate documentation, such as how to add support for a new
> host for instance. But the documentation about partial symbol
> tables, for instance, would be much more useful directly in
> symtab.h or symtab.c.

The problem with having documentation in the code is that there's no
easy way of organizing such a documentation: no cross-references, no
chapter/section/subsection structure, and no index.  For someone who
is on the learning curve looking for a more-or-less complete
description of a specific GDB mechanism, let alone a high-level
architectural overview, these disadvantages are IMO significant and
grave.

In addition, code comments in many cases have a loophole view of the
code, and so higher-level aspects tend to be not documented at all.
Code comments are also not reviewed as formally as docs submissions
are.

As an illustration to these deficiencies, please see how many
questions we have on this mailing list asking to explain how some
specific GDB feature works, and how they are almost _never_ answered
by pointing people to the code comments, nor to the docs.  Does anyone
need a better demonstration of the fact that our code is largely
undocumented?

If we are willing to move in the direction of making the docs and the
code closer (and assuming volunteers will step forward to do the job),
we could look at the various systems that generate code and manuals
from the same source.  Failing that, I'd rather support having _more_
of the explanations in the manual and less in the comments, and adding
references in the comments to relevant gdbint.texinfo places.  I think
that on balance this is a better alternative than the opposite one,
where we prefer comments to Texinfo docs.

> I don't know about others, but I have read the gdbint manual once
> from cover to cover almost 4 years ago, and never refered to it
> anymore.

That is simply because of the poor quality (in terms of coverage of
the relevant subject matter) of gdbint.texinfo.  We should do much
better.

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> From: "Dave Korn" <dk@artimi.com>
> Cc: "'Andrew Cagney'" <cagney@gnu.org>,
> 	<gdb@sources.redhat.com>
> Date: Thu, 7 Oct 2004 13:42:24 +0100
> 
> I look for the internals docs!  And complain bitterly when I can't
> find them

Please don't hesitate to complain here whenever you find missing or
outdated docs in GDB.  Thanks!

>   Since opinions are being invited, I'll just mention that I'm currently
> working on an internal version of gdb for which I'm having to up-port a
> 5.x-compatible backend to 6.x series.  I sometimes find it *ever* so hard
> when faced with yet another deprecated__ this or obsoleted_ that to know
> what the new and approved replacement is

Andrew, should we have a section in gdbint.texinfo that lists obsolete
techniques and their modern replacements, with short examples of both
the old and new code, like we did for ui_* stuff?

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> Date: Thu, 07 Oct 2004 11:37:45 -0400
> From: Andrew Cagney <cagney@gnu.org>
> Cc: gdb@sources.redhat.com
> 
> A system that is being continuously re-factored is not well suited for 
> detailed internals documentation - the effort is wasted.

Can we say that the features that are not going to change any time
soon are sufficiently documented?  For example, the CLI is not going
to be refactored any time soon (AFAIK), and yet its documentation
includes only 3 functions out of at least 10 it exports.  The
completion features (I mean their GDB-specific aspects, not the
general Readline mechanism) are not documented at all.

Another example is DWARF-2 support, whose ``documentation'' is 2
rather unhelpful sentences.

Core files are completely undocumented.

Etc., etc.  So I submit that our internal documentation's coverage is
very poor even in those non-contradictory parts where refactoring is
not a problem at all.

As for the refactoring factor (pun intended): I don't agree with the
``wasted effort'' argument.  Some areas are refactored very slowly, so
clearly things are quasy-stable enough to have them documented even to
the detailed level.  And in those areas which are in transition, we
can always decide to stop at the sufficiently high level to avoid
wasting the effort.  So this is IMHO not an excuse for failing to
document even the areas where development and change are facts of
life.

> Instead the high level architecture and medium level object models
> that are important.

Do we have these?

> There is no "migration" path.  The correct approach is:
> - delete all deprecated code
> - build
> - run testsuite
> - add a missing architecture vector method
> - repeat
> Instead of migrating, trying to reproduce each refactoring step, you 
> should leap frog.

As Dave explained, this paradigm is inappropriate for at least the
case of someone who is trying to introduce a new feature, not refactor
an old one.  In that case, there's no guidance a developer can find to
what code she should be using instaed of the deprecated one.

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> Date: Thu, 7 Oct 2004 11:01:21 -0700
> From: Joel Brobecker <brobecker@gnat.com>
> Cc: 'Andrew Cagney' <cagney@gnu.org>, 'Eli Zaretskii' <eliz@gnu.org>,
> 	gdb@sources.redhat.com
> 
> I think that maintaining the list of deprecated features in a
> separate document is going to be a large amount of work.  GDB is
> changing so fast.

I don't see why it should be a large amount of work.  Features are
deprecated one at a time.  Each time a feature gets deprecated, all we
need is a short addition to the documentation stating (1) what is
being deprecated, and (2) an example of the old code using the
deprecated feature and a new code that should replace it.

This list will grow as more features are deprecated and OTOH
deprecated features that are deleted from the code will be deleted
from this list.

So where's that large amount of work you are afraid of?

> It's simpler to put that information directly
> in the code, and most of the time, the information is actually already
> there.

It maybe there, but there's no easy way to find it.

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> Date: Thu, 7 Oct 2004 16:17:35 -0700
> From: Joel Brobecker <brobecker@gnat.com>
> Cc: 'Andrew Cagney' <cagney@gnu.org>, 'Eli Zaretskii' <eliz@gnu.org>,
> 	gdb@sources.redhat.com
> 
> Then if you want to know more, you just go to where the entity is
> defined, and look at the comments there.

Reality check: could you please look thru the files that define those
deprecated functions and tell how many of them have comments which
actually tell what code should replace them?  I just took a quick look
and found that the vast majority of them don't have any such
commentary at all.

> In any case, the main debate between Andrew and Eli is not about where
> to put the information, but *when* it is ok to decide that something
> is declared deprecated.

Indeed.

RE: Discussion: Formalizing the deprecation process in GDB

[Dave Korn]

> -----Original Message-----
> From: halo1 On Behalf Of Eli Zaretskii
> Sent: 08 October 2004 11:11

> > From: "Dave Korn" 
> > Cc: "'Andrew Cagney'" ,
> > 	<gdb>
> > Date: Thu, 7 Oct 2004 13:42:24 +0100
> > 
> > I look for the internals docs!  And complain bitterly when I can't
> > find them
> 
> Please don't hesitate to complain here whenever you find missing or
> outdated docs in GDB.  Thanks!

  Eli, I was particularly thinking of you when I wrote

"  It's just occurred to me that this could be read as a specific complaint
or accusation against gdb's documentation, rather than a comment on the
generally sorry state of documentation as a whole in the software industry.
No such inference was implied nor intended; sorry if anyone thought I was
criticising gdb with that statement! "

  However, since we mention it, sections 3.3-3.6, 4.3-4.4, 9.7-9.9,
10.3-10.6, 11.2-11.5, 12.3-12.4 and 12.7 of gdbint are missing.  I imagine
you knew that already though!

  Also, 9.5 and 9.6 are both prefixed with disclaimers; 9.5 says "This
section is pretty much obsolete. The functionality described here has
largely been replaced by pseudo-registers and the mechanisms described [...
in 9.6 ...] " and refers the reader to 9.6, which says "The way GDB
manipulates registers is undergoing significant change.  Many of the macros
and functions refered to in this section are likely to be subject to further
revision.".  The combined effect of these two sections is to leave the
reader (well, this one, at any rate) with no idea how you're supposed to
manipulate registers (or indeed, what a pseudo-register even is, since the
term is not used nor defined anywhere else in the documentation).  And I
didn't find that browsing the comments in regcache.h makes up for that.

> >   Since opinions are being invited, I'll just mention that 
> I'm currently
> > working on an internal version of gdb for which I'm having 
> to up-port a
> > 5.x-compatible backend to 6.x series.  I sometimes find it 
> *ever* so hard
> > when faced with yet another deprecated__ this or obsoleted_ 
> that to know
> > what the new and approved replacement is
> 
> Andrew, should we have a section in gdbint.texinfo that lists obsolete
> techniques and their modern replacements, with short examples of both
> the old and new code, like we did for ui_* stuff?

  I think such a section would be a great resource for people working on
ports, and I would hope that it wouldn't impose too great a maintenance
burden.

    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> From: "Dave Korn" <dk@artimi.com>
> Cc: <cagney@gnu.org>,
> 	<gdb@sources.redhat.com>
> Date: Fri, 8 Oct 2004 13:40:31 +0100
> 
>   Eli, I was particularly thinking of you when I wrote
> 
> "  It's just occurred to me that this could be read as a specific complaint
> or accusation against gdb's documentation, rather than a comment on the
> generally sorry state of documentation as a whole in the software industry.
> No such inference was implied nor intended; sorry if anyone thought I was
> criticising gdb with that statement! "

I, for one, don't see your criticism as a Bad Thing; on the contrary.

>   However, since we mention it, sections 3.3-3.6, 4.3-4.4, 9.7-9.9,
> 10.3-10.6, 11.2-11.5, 12.3-12.4 and 12.7 of gdbint are missing.

Just so it is easier for me to find those places, could you please
tell the names of these sections, instead of just numbers?

>   Also, 9.5 and 9.6 are both prefixed with disclaimers; 9.5 says "This
> section is pretty much obsolete. The functionality described here has
> largely been replaced by pseudo-registers and the mechanisms described [...
> in 9.6 ...] " and refers the reader to 9.6, which says "The way GDB
> manipulates registers is undergoing significant change.  Many of the macros
> and functions refered to in this section are likely to be subject to further
> revision.".  The combined effect of these two sections is to leave the
> reader (well, this one, at any rate) with no idea how you're supposed to
> manipulate registers (or indeed, what a pseudo-register even is, since the
> term is not used nor defined anywhere else in the documentation).  And I
> didn't find that browsing the comments in regcache.h makes up for that.

I agree that such ``documentation'' is very unhelpful.  Would someone
please volunteer to write something more useful?

RE: Discussion: Formalizing the deprecation process in GDB

[Dave Korn]

> -----Original Message-----
> From: halo1 On Behalf Of Eli Zaretskii
> Sent: 08 October 2004 14:13

> >   However, since we mention it, sections 3.3-3.6, 4.3-4.4, 9.7-9.9,
> > 10.3-10.6, 11.2-11.5, 12.3-12.4 and 12.7 of gdbint are missing.
> 
> Just so it is easier for me to find those places, could you please
> tell the names of these sections, instead of just numbers?

  Certainly can:

[ Section 3 Algorithms ]

3.3 Single Stepping 
3.4 Signal Handling 
3.5 Thread Handling 
3.6 Inferior Function Calls

[ Section 4 User Interface ]

4.3 Console Printing 
4.4 TUI

[ Section 9 Target Architecture Definition ]

9.7 Frame Interpretation 
9.8 Inferior Call Setup
9.9 Compiler Characteristics

[ Section 10 Target Vector Definition ]

10.3 ROM Monitor Interface 
10.4 Custom Protocols
10.5 Transport Layer

[ Section 11 Native Debugging ]

11.2 ptrace
11.3 /proc
11.4 win32
11.5 shared libraries

[ Section 12 Support Libraries ]
12.3 readline 
12.4 mmalloc

12.7 include


  :)  As you see, there are some fairly fundamental gdb-internals there that
could really do with a bit of explaining.  Things like "Frame
interpretation" and "Inferior call setup" are IMO among the most basic and
important aspects of gdb<->target interaction that a newbie approaching the
code really needs to have a clear understanding of.

> I agree that such ``documentation'' is very unhelpful.  Would someone
> please volunteer to write something more useful?

  I find myself in something of a catch-22: I'd love to offer to write some
docs, but in order to do so I'd need to understand the underlying gdb
mechanics much better, and in order to do that, I feel that I'd need.....
some docs!  

  I actually had to put aside the in-house gdb I was working on a while back
as other priorities came up.  If nobody's gotten down to this as/when I get
back to it, I guess I'll try and keep some notes as I go along trying to
work it all out from the code that might be able to serve as a starting
point.  However, I have 'issues' with my assign paperwork at the moment that
mean this could be some way off in the future.....

    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

RE: Discussion: Formalizing the deprecation process in GDB

[Dave Korn]

> -----Original Message-----
> From: gdb-owner On Behalf Of Dave Korn
> Sent: 08 October 2004 14:31

> > >   However, since we mention it, sections 3.3-3.6, 
> 4.3-4.4, 9.7-9.9,
> > > 10.3-10.6, 11.2-11.5, 12.3-12.4 and 12.7 of gdbint are missing.
> > 
> > Just so it is easier for me to find those places, could you please
> > tell the names of these sections, instead of just numbers?
> 
>   Certainly can:

  Oops.  Forgot one.  Here's a unidiff:

Index: <NUTMEG7sFoai8XKPl5G0000032c@NUTMEG.CAM.ARTIMI.COM>
===================================================
  10.3 ROM Monitor Interface 
  10.4 Custom Protocols
  10.5 Transport Layer
+ 10.6 Builtin Simulator

  [ Section 11 Native Debugging ]


  Please apply the patch to my last email!

    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> From: "Dave Korn" <dk@artimi.com>
> Cc: <cagney@gnu.org>,
> 	<gdb@sources.redhat.com>
> Date: Fri, 8 Oct 2004 14:30:36 +0100
> 
> 3.3 Single Stepping 
> 3.4 Signal Handling 
> 3.5 Thread Handling 
> 3.6 Inferior Function Calls
> 
> [ Section 4 User Interface ]
> 
> 4.3 Console Printing 
> 4.4 TUI
> 
> [ Section 9 Target Architecture Definition ]
> 
> 9.7 Frame Interpretation 
> 9.8 Inferior Call Setup
> 9.9 Compiler Characteristics
> 
> [ Section 10 Target Vector Definition ]
> 
> 10.3 ROM Monitor Interface 
> 10.4 Custom Protocols
> 10.5 Transport Layer
> 
> [ Section 11 Native Debugging ]
> 
> 11.2 ptrace
> 11.3 /proc
> 11.4 win32
> 11.5 shared libraries
> 
> [ Section 12 Support Libraries ]
> 12.3 readline 
> 12.4 mmalloc
> 
> 12.7 include

Thanks for the footwork.

Yes, these are the empty sections, sigh.  They await volunteers to
document the related features.

The one for readline could use part of the Readline's docs, though.  I
will try to make that happen.

Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney]

>>> Date: Thu, 07 Oct 2004 11:37:45 -0400
>>> From: Andrew Cagney <cagney@gnu.org>
>>> Cc: gdb@sources.redhat.com
>>> 
>>> A system that is being continuously re-factored is not well suited for 
>>> detailed internals documentation - the effort is wasted.
> 
> 
> Can we say that the features that are not going to change any time
> soon are sufficiently documented?  For example, the CLI is not going
> to be refactored any time soon (AFAIK), and yet its documentation
> includes only 3 functions out of at least 10 it exports.  The
> completion features (I mean their GDB-specific aspects, not the
> general Readline mechanism) are not documented at all.

The way the current CLI code works is i18n busted.  I recently 
deprecated several key CLI functions just to stop people adding code 
using them..  While there are new "draft" interfaces available they are 
just draft, the corresponding internals (and perhaps the interfaces) 
face significant change.

Even the frame code isn't safe, which left the old design in the dust, 
is now its self reaching its limits.  It's looking at a refactoring that 
will fundmentally change both it and the symtab.  From frame has-a 
unwinder; to frame has-a function (is a symbol) has-a unwinder.

etc, etc, etc,

Andrew

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> Date: Fri, 08 Oct 2004 18:31:13 +0200
> From: "Eli Zaretskii" <eliz@gnu.org>
> CC: cagney@gnu.org, gdb@sources.redhat.com
> 
> > [ Section 12 Support Libraries ]
> > 12.3 readline 
> > 12.4 mmalloc
> > 
> > 12.7 include
> 
> Thanks for the footwork.
> 
> Yes, these are the empty sections, sigh.  They await volunteers to
> document the related features.
> 
> The one for readline could use part of the Readline's docs, though.  I
> will try to make that happen.

Does anyone see a problem if I make gdbint.texinfo include
rltech.texinfo and hstech.texinfo?

As for mmalloc, I'd simply remove that section from gdbint.texinfo, as
we no longer use mmalloc.  Okay?

Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney]

>   Also, 9.5 and 9.6 are both prefixed with disclaimers; 9.5 says "This
> section is pretty much obsolete. The functionality described here has
> largely been replaced by pseudo-registers and the mechanisms described [...
> in 9.6 ...] " and refers the reader to 9.6, which says "The way GDB
> manipulates registers is undergoing significant change.  Many of the macros
> and functions refered to in this section are likely to be subject to further
> revision.".  The combined effect of these two sections is to leave the
> reader (well, this one, at any rate) with no idea how you're supposed to
> manipulate registers (or indeed, what a pseudo-register even is, since the
> term is not used nor defined anywhere else in the documentation).  And I
> didn't find that browsing the comments in regcache.h makes up for that.

Like the below?

http://sources.redhat.com/ml/gdb/2002-07/msg00202.html
@node Registers
@chapter Registers

@section Register Spaces

@value{GDBN} internally has two register spaces:

@table @emph
@item cooked
@itemize @bullet
@item
manipulated by core @value{GDBN}
@item
correspond to user level, or abi registers
@end itemize
@item raw
@itemize @bullet
@item
manipulated by target backends
@item
correspond to physical registers
@end itemize
@end table

@subsection Raw Registers

The raw register space, containing @code{NUM_REGS}
@c index NUM_REGS
raw registers, abstracts the instruction set architectures physical
register set. @value{GDBN}'s register cache contains raw registers.
Each raw register is mapped, one-to-one, onto a corresponding physical
register. For instance:

@itemize @bullet

@item
For 64 bit architecture that has 32 general purpose registers, the
register cache, and the raw register space would include space for those
32 registers.

@item
For an architectures that has register banks, the register cache, and
raw register space would contain space for registers from all banks.
The one-to-one relationship between the raw registers and the
architecture's physical registers being preserved.

@item
For a 64 bit architecture that is running in 32 bit mode, the register
cache and raw register space would contain the 64 bit hardware
registers. The raw register space would not include cut down 32 bit
registers.

@item
For an architecture that determines the program-counter by examining the
value of severaal hardware registers, the register cache and raw
register space will contain the separate hardware values. The raw
register space would not include the program-counter.

@item
For an architecture that has memory mapped registers, those registers
are not be part of the register cache or raw register space (there is no
corresponding hardware register).

@end itemize

@emph{Maintainer note: Old architectures, since they didn't know better,
broke all of the above rules, sigh!}

The raw registers are not necessarily directly visible to the user.

@emph{Maintainer note: There should be be a @samp{maint info registers}
command so that the raw register cache is visible.}

@section Cooked Registers

The core of @value{GDBN} manipulates registers in the cooked register
space. Any external or user visible register is mapped onto the cooked
register space, in particular:

@itemize @bullet
@item
registers refered to by debug information
@item
user visible registers (specified by name)
@item
mode dependant registers (e.g., a 64 bit architecture in 32 bit mode may
need to manipulate the 32 bits of 64 bit registers)
@item
memory mapped registers
space.
@item
state dependant registers (e.g., bank registers)
@end itemize

Architecture methods then map the @code{NUM_REGS + NUM_PSEUDO_REGS}
cooked registers onto raw registers or memory. While arbitrary mappings
are possible, the first @code{NUM_REGS} registers should be be mapped
direct to the raw registers. The remaining @code{NUM_PSEUDO_REGS then
having more arbitrary mappings. That is:

@smallexample
cooked: [0..NUM_REGS) [..NUM_REGS+NUM_PSEUDO_REGS)
| / |
| / |
| / |
| / |
raw: RAW REGISTERS MEMORY
@end smallexample

@section The Register Cache

@value{GDBN} stores the target register state in a register cache
(@code{struct regcache}).

The register cache has three separate interfaces:

@itemize @bullet
@item
cooked
@item
raw
@item
target
@end itemize

Core @value{GDBN} manipulates the register cache using the cooked
interfaces:

@deftypefun void regcache_cooked_read (struct regcache *@var{regcache}, 
int @var{regnum}, void *@var{buf})
Read a cooked register value from the register cache (or memory).
@end deftypefun
@deftypefun void regcache_cooked_write (struct regcache *@var{regcache}, 
int @var{regnum}, const void *@var{buf})
Write a cooked register value to the register cache (or memory).
@end deftypefun

These methods then use corresponding architecture methods to map the
cooked registers onto either raw registers or memory:

@deftypefun void gdbarch_cooked_register_read (struct gdbarch 
*@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, void 
*@var{buf})
Read the specified @var{regnum} register value from the @var{regcache}
(or memory for memory mapped registers).
@end deftypefun
@deftypefun void gdbarch_cooked_register_write (struct gdbarch 
*@var{gdbarch}, struct regcache *@var{regcache}, int @var{regnum}, const 
void *@var{buf})
Write the specified @var{regnum} register value into the @var{regcache}
(or memory for memory mapped registers).
@end deftypefun

The raw register values being manipulated using:

@deftypefun void regcache_raw_read (struct regcache *@var{regcache}, int 
@var{regnum}, void *@var{buf})
Read a cooked register value from the register cache (or memory).
@end deftypefun
@deftypefun void regcache_raw_write (struct regcache *@var{regcache}, 
int @var{regnum}, const void *@var{buf})
Write a raw register value to the register cache (or memory).
@end deftypefun

When a raw register read or write needs to go through to the target (the
value isn't yet in the cache or a modification needs to be written to
the target) the register cache state is then manipulated by the target
using the methods:

@deftypefun regcache_collect (struct regcache *@var{regcache}, int 
@var{regnum}, void *@var{buf})
@end deftypefun
@deftypefun regcache_supply (struct regcache *@var{regcache}, int 
@var{regnum}, const void *@var{buf})
@end deftypefun

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> Date: Fri, 08 Oct 2004 14:47:47 -0400
> From: Andrew Cagney <cagney@gnu.org>
> Cc: dk@artimi.com, brobecker@gnat.com, gdb@sources.redhat.com
> 
> The way the current CLI code works is i18n busted.  I recently 
> deprecated several key CLI functions just to stop people adding code 
> using them.

Of the functions that are not marked deprecated, do we envision that
their APIs (as opposed to their inner workings) will undergo
significant changes?  If not, there's nothing to prevent us from
documenting the API.

> While there are new "draft" interfaces available they are 
> just draft, the corresponding internals (and perhaps the interfaces) 
> face significant change.

When is that change planned, approximately, and did someone start
working on its design?  If the change is not close, or if we don't
even know yet how to make the CLI i18n compatible, it could be years
before the real change will happen, and we again can document the
internals now.

> Even the frame code isn't safe, which left the old design in the dust, 
> is now its self reaching its limits.  It's looking at a refactoring that 
> will fundmentally change both it and the symtab.  From frame has-a 
> unwinder; to frame has-a function (is a symbol) has-a unwinder.
> 
> etc, etc, etc,

Are you saying that I chose bad examples or are you saying that
there's nothing in the GDB internals that can be documented because
everything is under development?  If the former, can we please go back
to talking about the original issue: should we prefer Texinfo
documentation to the code comments or the other way around?

If you do mean the latter, then perhaps I should think seriously
whether I want to be responsible for documentation of a project whose
head maintainer thinks that internal documentation is more or less a
waste of time.

Btw, the ``under construction, subject to change without notice''
argument flies in the face of the code comments preference as well: if
the code is so temporary, it isn't worth commenting.

Re: Discussion: Formalizing the deprecation process in GDB

[Andrew Cagney]

>>> Date: Wed, 06 Oct 2004 01:08:13 -0400
>>> From: Andrew Cagney <cagney@gnu.org>
>>> Cc: gdb@sources.redhat.com, Andrew Cagney <cagney@redhat.com>
> 
> 
> Andrew, thank you for an informative message.
> 
> Unfortunately, it doesn't help in making a progress in this
> discussion, since all it does is reiterate your opinions that were
> clear (at least to me) during the XM_FILE debate, or else explaining
> principles and generalities that don't need to be explained.

> I'm fully aware that you, and at least some of the other maintainers,
> are eager to deprecate and remove code that you think is not
> maintained quickly enough for your liking.  It is probably not news to
> you that I don't like that eagerness; we had enough discussions in the
> past along those lines, and I didn't make a secret out of my views.  I
> think such tendencies are harsh on the users and on sysadmins (in
> fact, they are harsh on everybody but GDB developers), and are not at
> all justified by the added maintenance burden they are allegedly
> supposed to magically remove.

I can only guess or suspect.  E-mail being a primative medium doesn't 
let us read between the lines and identify when there's an underlying 
issue.  Here we've again made progress, we've gone from XM_FILE, to 
deprecation, to the agressive removal of code.   What of the overall 
rate of change, and release cycles, ...?  This is also why I've been 
stating principals and generalities - trying to figure out what the 
underlying issue is.

"deprecation", since it is all internal, is hardest on the developers 
yet many are the ones expressing a certain appreciation.

The "users" I interact with appreciate the more timely releases that 
give them faster acces to fixes, so I don't know what is "harsh" here. 
Can you explain?

> So saying once again that you don't want to request patch contributors
> (which is mostly yourself in the case of "deprecated_" stuff) to fix
> the affected portions of the code as a perequisite for accepting the
> patch, and that you don't want to maintain obsolete code, does not
> change anything in what is already known as a serious disagreement.
> If that is all we can say, let's just agree to disagree, and be done
> with that.
> 
> If you do want to try to convince me, you (or someone else who thinks
> like you) will have to do better than that.

Now that cuts both ways, you've not convinced anyone either :-(

>>> We're programmers.  We speak through the code.  The internals document 
>>> has its place, but the bottom line is that the code and not the 
>>> internals document determines how GDB works.  Hence, that is what 
>>> programmers read.
> 
> 
> I'm not sure what is it that you are saying here.  Should we abandon
> gdbint.texinfo and instead rely on the code to explain itself, because
> ``we are programmers and thus code is the only thing we read''?  Maybe
> I should stop trying so hard to review each documentation patch in a
> matter of days, because the code already says all there is to tell?

[Sarcasm] Obviously, that's why I'm spending part of my time on 
internals documentation.

> I agree with the principle that we should draw a line somewhere
> between the part of the documentation that should go into a manual and
> the part that should stay in the code, so the argument is not over the
> principle.  I hope you will agree that, in principle, _some_
> information _can_ be put in a manual, because otherwise I don't
> understand why you just pinged me to review your gdbint patches about
> branching and versioning; why not have that as comments to version.in,
> for example?

> The issue at hand is not the principle, but rather my very specific
> suggestion that the fact some code or method is deprecated could be
> stated in the manual.  If you object to that specific suggestion,
> please back up your opinion by specific arguments, not by reiterating
> abstract principles to which we all agree.

The internals documentation should contain the process, or the overview. 
  The code, the specifics.  Unless of course I get around to doing to 
gdbarch.sh what I did for the observers (i.e., single source in 
observer.texi).

>>> Real deprecation started with multi-arch in '98 (your first post was in 
>>> '99)
> 
> 
> What does the date of my first post have to do with the issue at hand?
> Isn't it possible that I've also read the archives, even beyond the
> days I started to be an active GDB maintainer?

You wrote:

 > More generally, AFAIR the "depreated_" stunt was invented mainly as an
 > aid to the maintainer(s): to make their job easier when they want to
 > know what stuff is candidate for deletion.  It is a bit funny to see
 > this convenience trick sudenly being inflated with so much ideology.

Besides being a slur, I find it really troubling that you've somehow 
become convinced of this.  Back in '98 and '99, all significant 
technical discussion, and all technical decisions,  were being made on 
cynus-internal mailing lists and in cygnus-internal meetings (It wasn't 
until '00 that things really improved) :-(  Beyond the ChangeLogs 
there's little (other than hearsay) to go by.

Looking in 4.18 (, I'd been adding comments and code marking various 
pieces of gdb as "deprecated.

By 5.0 (2000-05) I was explicitly deprecating things.

>>> Yes, it did make my job easier - I didn't have to chase after people 
>>> constantly reminding them that the're using deprecated methods and plead 
>>> with them not to.
> 
> 
> Chasing after people vs deprecating every code portion you don't want
> to try to fix are not the only two alternatives to solve the problem.

First, from the point of view of GDB's core.  Everything is typically 
fixed.  The problem is with the frindges - architecture / target / 
symtab / ... / specific code - that continues to use or rely on 
mechanisms long after the're no longer needed.

Are you suggesting that I should be required to fix the fringes?

We've debated that in the past and it was agreed (eventually even by 
some of the protractors) that we're better off having the person in a 
position to test the changes make the changes - the rationale is simple 
- we've consistently demonstrated that untested changes don't work.  We 
just end up retaining totally broken but still buildable code.

 > And even if those _are_ the only two alternatives, there's still a lot
 > of leeway as to the point where you stop chasing and start deprecating.
 > And the location of that point is _exactly_ what we disagree about.

I'm lost.

To my knowledge the "point where you stop chasing and start deprecating" 
is _not_ what this debate is about.  Rather it is about what action 
should be taken when deprecating something:

I believe your position is that:
- something is identified as deprecated
- it's recorded somewhere other than the code
- we "fix" all [remining?] uses
- the code is marked up
while mine is:
- something is identified as deprecated
- the code is marked up
- we "fix" all remaining uses

The problem I have with your suggested change, and the reason I 
originally started explicitly deprecating was that I found it doesn't 
work - very early on I was recording things in just the documentation. 
The only effective way I've found of stopping the "breeding" of 
deprecated code is by having it explicitly identified in the code itself 
using markup.

This clarification has had other benefits: it for instance has given us 
a more objective metric against which new contributions and updates can 
be measured - in the past it was very much a hit or miss (reviewer 
dependant) afair.

I know it's also suffered from a few persistant grypes:

- it makes merging hard
During the period 2000 (when CVS went live) to mid 2003 (my role was 
changed) I was responsible for merging the public repository into "the 
cygnus tree".  Given that I was performing weekly merges without problem 
I don't see what the problem is (and I was definitly eating my own dog 
food).

- the bar keeps moving (up)
As I've noted in another post, GDB's code base needs to advance and 
advancing it means continuous change.  One consequence of that change is 
deprecation.  We have to live with it.

Andrew

Re: Discussion: Formalizing the deprecation process in GDB

[Eli Zaretskii]

> Date: Mon, 11 Oct 2004 02:10:02 -0400
> From: Andrew Cagney <cagney@gnu.org>
> Cc: gdb@sources.redhat.com
> 
> I can only guess or suspect.  E-mail being a primative medium doesn't 
> let us read between the lines and identify when there's an underlying 
> issue.

I don't know why you insist on trying to read between the lines and
look for hidden issues.  I try very hard to make the issues that
bother me as explicit as I possibly can.

> The "users" I interact with appreciate the more timely releases that 
> give them faster acces to fixes, so I don't know what is "harsh" here. 
> Can you explain?

When we retire some code or feature or platform, we hurt users of that
code or feature or platform.

> > If you do want to try to convince me, you (or someone else who thinks
> > like you) will have to do better than that.
> 
> Now that cuts both ways, you've not convinced anyone either :-(

I didn't start this thread.  If we have nothing new to say to each
other, perhaps we should just stop, since no one else seems to be
interested.

> > I'm not sure what is it that you are saying here.  Should we abandon
> > gdbint.texinfo and instead rely on the code to explain itself, because
> > ``we are programmers and thus code is the only thing we read''?  Maybe
> > I should stop trying so hard to review each documentation patch in a
> > matter of days, because the code already says all there is to tell?
> 
> [Sarcasm] Obviously, that's why I'm spending part of my time on 
> internals documentation.

And I know that, so I'm stunned to read words you've written that
discourage documentation efforts.

> The internals documentation should contain the process, or the overview. 

I think it can contain whatever we find useful to have there.  There's
nothing wrong with the idea that the internals docs will serve us a
little, not just people outside the GDB development team.  The
documentation of the GDB release and branching processes are very good
examples.

> Looking in 4.18 (, I'd been adding comments and code marking various 
> pieces of gdb as "deprecated.
> 
> By 5.0 (2000-05) I was explicitly deprecating things.

My involvement with GDB goes back to 4.16 (although you probably won't
find the traces in the logs).

Perhaps my memory betrays me, but the massive use of deprecated_ is
something that didn't start until 5.x.  You seem to confirm that,
although not in so many words.

No slur was intended, of course; sorry if it sounded like that.

> Are you suggesting that I should be required to fix the fringes?

Not necessarily you.

In every other GNU project that I was involved with, the person who
wants to make a change is required to make sure nothing is broken by
the change without an overall agreement that it is okay to break it.
Breaking things just because no one is willing to make an effort to
fix them is something I find to be very wrong.

> - we've consistently demonstrated that untested changes don't work.

Then the person who makes the changes needs to test them, or ask
someone else to do that for them, if access to some specific platform
is an issue.

Yes, that _is_ harder than leaving things unmodified (i.e. broken),
but that is the price we pay for the fun of being maintainers.

Re: Discussion: Formalizing the deprecation process in GDB

[Mark Kettenis]

   Date: Mon, 11 Oct 2004 22:42:57 +0200
   From: "Eli Zaretskii" <eliz@gnu.org>

   > Date: Mon, 11 Oct 2004 02:10:02 -0400
   > From: Andrew Cagney <cagney@gnu.org>
   > Cc: gdb@sources.redhat.com
   > 
   > I can only guess or suspect.  E-mail being a primative medium doesn't 
   > let us read between the lines and identify when there's an underlying 
   > issue.

   I don't know why you insist on trying to read between the lines and
   look for hidden issues.  I try very hard to make the issues that
   bother me as explicit as I possibly can.

I can't speak for Andrew, but what personally surprised me is why all
of I sudden you seem to be opposed to deprecating things.

   > The "users" I interact with appreciate the more timely releases that 
   > give them faster acces to fixes, so I don't know what is "harsh" here. 
   > Can you explain?

   When we retire some code or feature or platform, we hurt users of that
   code or feature or platform.

Only to the extent that we rob them of any further improvements for
their platform.  In my experience though we're not actually
deliberately retiring features or platforms.  Yes, we've been
obsoleting stuff, but in almost all cases this has actually been a
service to our users, since we save them the disappointment of
discovering that GDB doesn't work at all on their platform after they
built it.  So I'm afraid you haven't actually answered Andrew's
question :-(.

   > The internals documentation should contain the process, or the overview. 

   I think it can contain whatever we find useful to have there.  There's
   nothing wrong with the idea that the internals docs will serve us a
   little, not just people outside the GDB development team.  The
   documentation of the GDB release and branching processes are very good
   examples.

Yes, but if there's an obvious place for documentation in the code
it's probably better to but it there.  For example, SPARC-specific
stuff is better documented in sparc-tdep.c, core file related stuff
probably belongs in corelow.c.

   > Looking in 4.18 (, I'd been adding comments and code marking various 
   > pieces of gdb as "deprecated.
   > 
   > By 5.0 (2000-05) I was explicitly deprecating things.

   My involvement with GDB goes back to 4.16 (although you probably won't
   find the traces in the logs).

   Perhaps my memory betrays me, but the massive use of deprecated_ is
   something that didn't start until 5.x.  You seem to confirm that,
   although not in so many words.

Yup.  Using deprecated_ is "explicitly deprecating" in my book.  I
understand your revulsion against the use of deprecated_ in the source
code, and I did oppose to it in the past.  However, it really has the
benefits Andrew describes.  I think that sometimes he goes to far.
For eah deprecation there should be an alternative that's somewhat
easy to implement.  The DEPRECATED_TM_FILE is bad in this sense, since
it is impossible to add a platform with SVR4-style shared libraries
without using it, unless you refactor the shared library code.  On the
other hand, that's about the only thing that needs it, and
DEPRECATED_TM_FILE serves the purpose of keeping people from using it
liberally.  I don't thing we should only deprecate things if all
that's needed to undeprecate is a simple substitution.

If maintainers do their job right they'll undeprecate the code they're
maintaining as soon as possible.  I think I've proven that this can be
done.  But I think the deprecator has at least an equal burden to
undeprecate if he's able to do so.

   > Are you suggesting that I should be required to fix the fringes?

   Not necessarily you.

   In every other GNU project that I was involved with, the person who
   wants to make a change is required to make sure nothing is broken by
   the change without an overall agreement that it is okay to break it.
   Breaking things just because no one is willing to make an effort to
   fix them is something I find to be very wrong.

I think it is unavoidable if we want to keep GDB maintainable.  In the
end if no-one undeprecates a particular feauture or platform, we can
conclude that no-one is actively maintaining that part of code.

   > - we've consistently demonstrated that untested changes don't work.

   Then the person who makes the changes needs to test them, or ask
   someone else to do that for them, if access to some specific platform
   is an issue.

There are quite a few platforms for which no active GDB developer has
access to a usable system.  Enforcing this would actually slow down
development to a crawl.  We really have to find a balance here.

Mark