* Discussion: Formalizing the deprecation process in GDB
@ 2004-09-27 17:55 Joel Brobecker
2004-09-27 20:35 ` Eli Zaretskii
2004-10-06 6:14 ` Andrew Cagney
0 siblings, 2 replies; 32+ messages in thread
From: Joel Brobecker @ 2004-09-27 17:55 UTC (permalink / raw)
To: gdb; +Cc: Andrew Cagney, Eli Zaretskii
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
^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-09-27 17:55 Discussion: Formalizing the deprecation process in GDB Joel Brobecker @ 2004-09-27 20:35 ` Eli Zaretskii 2004-10-06 6:14 ` Andrew Cagney 1 sibling, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2004-09-27 20:35 UTC (permalink / raw) To: Joel Brobecker; +Cc: gdb, cagney > 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-09-27 17:55 Discussion: Formalizing the deprecation process in GDB Joel Brobecker 2004-09-27 20:35 ` Eli Zaretskii @ 2004-10-06 6:14 ` Andrew Cagney 2004-10-06 13:39 ` Eli Zaretskii 1 sibling, 1 reply; 32+ messages in thread From: Andrew Cagney @ 2004-10-06 6:14 UTC (permalink / raw) To: Joel Brobecker, Eli Zaretskii; +Cc: 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-06 6:14 ` Andrew Cagney @ 2004-10-06 13:39 ` Eli Zaretskii 2004-10-07 4:48 ` Joel Brobecker 2004-10-11 15:11 ` Andrew Cagney 0 siblings, 2 replies; 32+ messages in thread From: Eli Zaretskii @ 2004-10-06 13:39 UTC (permalink / raw) To: Andrew Cagney; +Cc: gdb > 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-06 13:39 ` Eli Zaretskii @ 2004-10-07 4:48 ` Joel Brobecker 2004-10-07 14:27 ` Dave Korn 2004-10-08 10:38 ` Eli Zaretskii 2004-10-11 15:11 ` Andrew Cagney 1 sibling, 2 replies; 32+ messages in thread From: Joel Brobecker @ 2004-10-07 4:48 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Andrew Cagney, gdb > 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* RE: Discussion: Formalizing the deprecation process in GDB 2004-10-07 4:48 ` Joel Brobecker @ 2004-10-07 14:27 ` Dave Korn 2004-10-07 15:12 ` Joel Brobecker ` (2 more replies) 2004-10-08 10:38 ` Eli Zaretskii 1 sibling, 3 replies; 32+ messages in thread From: Dave Korn @ 2004-10-07 14:27 UTC (permalink / raw) To: 'Joel Brobecker', 'Eli Zaretskii' Cc: 'Andrew Cagney', gdb > -----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.... ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-07 14:27 ` Dave Korn @ 2004-10-07 15:12 ` Joel Brobecker 2004-10-07 16:16 ` Andrew Cagney 2004-10-07 16:14 ` Andrew Cagney 2004-10-08 10:45 ` Eli Zaretskii 2 siblings, 1 reply; 32+ messages in thread From: Joel Brobecker @ 2004-10-07 15:12 UTC (permalink / raw) To: Dave Korn; +Cc: 'Eli Zaretskii', 'Andrew Cagney', gdb (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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-07 15:12 ` Joel Brobecker @ 2004-10-07 16:16 ` Andrew Cagney 2004-10-07 18:50 ` Dave Korn 0 siblings, 1 reply; 32+ messages in thread From: Andrew Cagney @ 2004-10-07 16:16 UTC (permalink / raw) To: Joel Brobecker, Dave Korn, 'Eli Zaretskii'; +Cc: gdb > (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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* RE: Discussion: Formalizing the deprecation process in GDB 2004-10-07 16:16 ` Andrew Cagney @ 2004-10-07 18:50 ` Dave Korn 0 siblings, 0 replies; 32+ messages in thread From: Dave Korn @ 2004-10-07 18:50 UTC (permalink / raw) To: 'Andrew Cagney', 'Joel Brobecker', 'Eli Zaretskii' Cc: gdb > -----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.... ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-07 14:27 ` Dave Korn 2004-10-07 15:12 ` Joel Brobecker @ 2004-10-07 16:14 ` Andrew Cagney 2004-10-07 18:08 ` Dave Korn 2004-10-08 11:45 ` Eli Zaretskii 2004-10-08 10:45 ` Eli Zaretskii 2 siblings, 2 replies; 32+ messages in thread From: Andrew Cagney @ 2004-10-07 16:14 UTC (permalink / raw) To: Dave Korn, 'Joel Brobecker', 'Eli Zaretskii'; +Cc: gdb > 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* RE: Discussion: Formalizing the deprecation process in GDB 2004-10-07 16:14 ` Andrew Cagney @ 2004-10-07 18:08 ` Dave Korn 2004-10-07 19:18 ` Joel Brobecker 2004-10-08 8:54 ` Fabian Cenedese 2004-10-08 11:45 ` Eli Zaretskii 1 sibling, 2 replies; 32+ messages in thread From: Dave Korn @ 2004-10-07 18:08 UTC (permalink / raw) To: 'Andrew Cagney', 'Joel Brobecker', 'Eli Zaretskii' Cc: gdb > -----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.... ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-07 18:08 ` Dave Korn @ 2004-10-07 19:18 ` Joel Brobecker 2004-10-07 19:28 ` Dave Korn 2004-10-08 12:05 ` Eli Zaretskii 2004-10-08 8:54 ` Fabian Cenedese 1 sibling, 2 replies; 32+ messages in thread From: Joel Brobecker @ 2004-10-07 19:18 UTC (permalink / raw) To: Dave Korn; +Cc: 'Andrew Cagney', 'Eli Zaretskii', gdb > > 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* RE: Discussion: Formalizing the deprecation process in GDB 2004-10-07 19:18 ` Joel Brobecker @ 2004-10-07 19:28 ` Dave Korn 2004-10-08 7:08 ` Joel Brobecker 2004-10-08 12:05 ` Eli Zaretskii 1 sibling, 1 reply; 32+ messages in thread From: Dave Korn @ 2004-10-07 19:28 UTC (permalink / raw) To: 'Joel Brobecker' Cc: 'Andrew Cagney', 'Eli Zaretskii', gdb > -----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.... ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-07 19:28 ` Dave Korn @ 2004-10-08 7:08 ` Joel Brobecker 2004-10-08 12:13 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Joel Brobecker @ 2004-10-08 7:08 UTC (permalink / raw) To: Dave Korn; +Cc: 'Andrew Cagney', 'Eli Zaretskii', gdb > 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-08 7:08 ` Joel Brobecker @ 2004-10-08 12:13 ` Eli Zaretskii 0 siblings, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2004-10-08 12:13 UTC (permalink / raw) To: Joel Brobecker; +Cc: dk, cagney, gdb > 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-07 19:18 ` Joel Brobecker 2004-10-07 19:28 ` Dave Korn @ 2004-10-08 12:05 ` Eli Zaretskii 1 sibling, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2004-10-08 12:05 UTC (permalink / raw) To: Joel Brobecker; +Cc: dk, cagney, gdb > 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* RE: Discussion: Formalizing the deprecation process in GDB 2004-10-07 18:08 ` Dave Korn 2004-10-07 19:18 ` Joel Brobecker @ 2004-10-08 8:54 ` Fabian Cenedese 1 sibling, 0 replies; 32+ messages in thread From: Fabian Cenedese @ 2004-10-08 8:54 UTC (permalink / raw) To: gdb >> 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-07 16:14 ` Andrew Cagney 2004-10-07 18:08 ` Dave Korn @ 2004-10-08 11:45 ` Eli Zaretskii 2004-10-08 19:22 ` Andrew Cagney 1 sibling, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2004-10-08 11:45 UTC (permalink / raw) To: Andrew Cagney; +Cc: dk, brobecker, gdb > 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-08 11:45 ` Eli Zaretskii @ 2004-10-08 19:22 ` Andrew Cagney 2004-10-10 21:31 ` Eli Zaretskii 0 siblings, 1 reply; 32+ messages in thread From: Andrew Cagney @ 2004-10-08 19:22 UTC (permalink / raw) To: Eli Zaretskii; +Cc: dk, brobecker, gdb >>> 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-08 19:22 ` Andrew Cagney @ 2004-10-10 21:31 ` Eli Zaretskii 0 siblings, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2004-10-10 21:31 UTC (permalink / raw) To: Andrew Cagney; +Cc: dk, brobecker, gdb > 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-07 14:27 ` Dave Korn 2004-10-07 15:12 ` Joel Brobecker 2004-10-07 16:14 ` Andrew Cagney @ 2004-10-08 10:45 ` Eli Zaretskii 2004-10-08 13:31 ` Dave Korn 2 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2004-10-08 10:45 UTC (permalink / raw) To: Dave Korn; +Cc: cagney, gdb > 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? ^ permalink raw reply [flat|nested] 32+ messages in thread
* RE: Discussion: Formalizing the deprecation process in GDB 2004-10-08 10:45 ` Eli Zaretskii @ 2004-10-08 13:31 ` Dave Korn 2004-10-08 13:38 ` Eli Zaretskii 2004-10-08 22:10 ` Andrew Cagney 0 siblings, 2 replies; 32+ messages in thread From: Dave Korn @ 2004-10-08 13:31 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: cagney, gdb > -----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.... ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-08 13:31 ` Dave Korn @ 2004-10-08 13:38 ` Eli Zaretskii 2004-10-08 13:43 ` Dave Korn 2004-10-08 22:10 ` Andrew Cagney 1 sibling, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2004-10-08 13:38 UTC (permalink / raw) To: Dave Korn; +Cc: cagney, gdb > 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? ^ permalink raw reply [flat|nested] 32+ messages in thread
* RE: Discussion: Formalizing the deprecation process in GDB 2004-10-08 13:38 ` Eli Zaretskii @ 2004-10-08 13:43 ` Dave Korn 2004-10-08 13:44 ` Dave Korn 2004-10-08 19:16 ` Eli Zaretskii 0 siblings, 2 replies; 32+ messages in thread From: Dave Korn @ 2004-10-08 13:43 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: cagney, gdb > -----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.... ^ permalink raw reply [flat|nested] 32+ messages in thread
* RE: Discussion: Formalizing the deprecation process in GDB 2004-10-08 13:43 ` Dave Korn @ 2004-10-08 13:44 ` Dave Korn 2004-10-08 19:16 ` Eli Zaretskii 1 sibling, 0 replies; 32+ messages in thread From: Dave Korn @ 2004-10-08 13:44 UTC (permalink / raw) To: 'Dave Korn', 'Eli Zaretskii'; +Cc: cagney, gdb > -----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.... ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-08 13:43 ` Dave Korn 2004-10-08 13:44 ` Dave Korn @ 2004-10-08 19:16 ` Eli Zaretskii 2004-10-08 19:45 ` Eli Zaretskii 1 sibling, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2004-10-08 19:16 UTC (permalink / raw) To: Dave Korn; +Cc: cagney, gdb > 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-08 19:16 ` Eli Zaretskii @ 2004-10-08 19:45 ` Eli Zaretskii 0 siblings, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2004-10-08 19:45 UTC (permalink / raw) To: Eli Zaretskii; +Cc: cagney, gdb > 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? ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-08 13:31 ` Dave Korn 2004-10-08 13:38 ` Eli Zaretskii @ 2004-10-08 22:10 ` Andrew Cagney 1 sibling, 0 replies; 32+ messages in thread From: Andrew Cagney @ 2004-10-08 22:10 UTC (permalink / raw) To: Dave Korn; +Cc: 'Eli Zaretskii', gdb > 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-07 4:48 ` Joel Brobecker 2004-10-07 14:27 ` Dave Korn @ 2004-10-08 10:38 ` Eli Zaretskii 1 sibling, 0 replies; 32+ messages in thread From: Eli Zaretskii @ 2004-10-08 10:38 UTC (permalink / raw) To: Joel Brobecker; +Cc: cagney, gdb > 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-06 13:39 ` Eli Zaretskii 2004-10-07 4:48 ` Joel Brobecker @ 2004-10-11 15:11 ` Andrew Cagney 2004-10-12 7:34 ` Eli Zaretskii 1 sibling, 1 reply; 32+ messages in thread From: Andrew Cagney @ 2004-10-11 15:11 UTC (permalink / raw) To: Eli Zaretskii; +Cc: gdb >>> 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-11 15:11 ` Andrew Cagney @ 2004-10-12 7:34 ` Eli Zaretskii 2004-10-12 13:42 ` Mark Kettenis 0 siblings, 1 reply; 32+ messages in thread From: Eli Zaretskii @ 2004-10-12 7:34 UTC (permalink / raw) To: Andrew Cagney; +Cc: gdb > 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. ^ permalink raw reply [flat|nested] 32+ messages in thread
* Re: Discussion: Formalizing the deprecation process in GDB 2004-10-12 7:34 ` Eli Zaretskii @ 2004-10-12 13:42 ` Mark Kettenis 0 siblings, 0 replies; 32+ messages in thread From: Mark Kettenis @ 2004-10-12 13:42 UTC (permalink / raw) To: eliz; +Cc: cagney, gdb 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 ^ permalink raw reply [flat|nested] 32+ messages in thread
end of thread, other threads:[~2004-10-11 22:00 UTC | newest] Thread overview: 32+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2004-09-27 17:55 Discussion: Formalizing the deprecation process in GDB Joel Brobecker 2004-09-27 20:35 ` Eli Zaretskii 2004-10-06 6:14 ` Andrew Cagney 2004-10-06 13:39 ` Eli Zaretskii 2004-10-07 4:48 ` Joel Brobecker 2004-10-07 14:27 ` Dave Korn 2004-10-07 15:12 ` Joel Brobecker 2004-10-07 16:16 ` Andrew Cagney 2004-10-07 18:50 ` Dave Korn 2004-10-07 16:14 ` Andrew Cagney 2004-10-07 18:08 ` Dave Korn 2004-10-07 19:18 ` Joel Brobecker 2004-10-07 19:28 ` Dave Korn 2004-10-08 7:08 ` Joel Brobecker 2004-10-08 12:13 ` Eli Zaretskii 2004-10-08 12:05 ` Eli Zaretskii 2004-10-08 8:54 ` Fabian Cenedese 2004-10-08 11:45 ` Eli Zaretskii 2004-10-08 19:22 ` Andrew Cagney 2004-10-10 21:31 ` Eli Zaretskii 2004-10-08 10:45 ` Eli Zaretskii 2004-10-08 13:31 ` Dave Korn 2004-10-08 13:38 ` Eli Zaretskii 2004-10-08 13:43 ` Dave Korn 2004-10-08 13:44 ` Dave Korn 2004-10-08 19:16 ` Eli Zaretskii 2004-10-08 19:45 ` Eli Zaretskii 2004-10-08 22:10 ` Andrew Cagney 2004-10-08 10:38 ` Eli Zaretskii 2004-10-11 15:11 ` Andrew Cagney 2004-10-12 7:34 ` Eli Zaretskii 2004-10-12 13:42 ` Mark Kettenis
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).