🚀 go-pugleaf

> I was just going to install gdb-4.7 and went through my gnu.gdb.bugs folder,
> and behold! there are quite a lot of bugs reported for gdb-4.6 but
> (apparently) not yet fixed in gdb-4.7. Not only a few ones or the ones "this
> works for me, dunno if it breaks other configurations.", but even quite solid
> fixes. This one is an excellent example. Now, may I ask if the poor GDB
> maintainer is plainly overloaded or are there sound reasons behind this
> "conservative" fix politic? (No, I'm not upset, so don't misunderstand me !
> This is *not* a flame!!!) 8-)

A good question!  The poor GDB maintainer is plainly overloaded.

The current policy on GDB fixes is that someone in the GDB maintenance group
actually has to examine, install, and test each fix.  I continue to think
that this is wise.

I have been attempting to install *simple* fixes that are cleanly
designed and clearly presented, immediately when I read them in email.
I installed Mr. Farrell's fix this way tonight (though he didn't
include a test case -- that was in the message he was originally
replying to, which I had to dig out of the archives -- and though I
had to write my own ChangeLog entry); the code is still compiling on
the MIPS to see that it works before I check it in to the master
sources.

I've added a section to the next release of the GDB Internals manual
(gdb-4.x/gdb/doc/gdbint.texinfo) that describes guidelines for clean
design of GDB changes, and how to submit patches to GDB.  I've
appended those sections below.  Please read it over and comment to me
(or, if truly of general interest, to bug-gdb).

	John Gilmore

Submitting Patches
******************

   Thanks for thinking of offering your changes back to the community of
GDB users.  In general we like to get well designed enhancements.
Thanks also for checking in advance about the best way to transfer the
changes.

   The two main problems with getting your patches in are,

*
     The GDB maintainers will only install "cleanly designed" patches.
     You may not always agree on what is clean design. *note Coding
     Style::., *note Clean Design::..

*
     If the maintainers don't have time to put the patch in when it
     arrives, or if there is any question about a patch, it goes into a
     large queue with everyone else's patches and bug reports.

   I don't know how to get past these problems except by continuing to
try.

   There are two issues here -- technical and legal.

   The legal issue is that to incorporate substantial changes requires a
copyright assignment from you and/or your employer, granting ownership
of the changes to the Free Software Foundation.  You can get the
standard document for doing this by sending mail to
`gnu@prep.ai.mit.edu' and asking for it. I recommend that people write
in "All programs owned by the Free Software Foundation" as "NAME OF
PROGRAM", so that changes in many programs (not just GDB, but GAS,
Emacs, GCC, etc) can be contributed with only one piece of legalese
pushed through the bureacracy and filed with the FSF.  I can't start
merging changes until this paperwork is received by the FSF (their
rules, which I follow since I maintain it for them).

   Technically, the easiest way to receive changes is to receive each
feature as a small context diff or unidiff, suitable for "patch". Each
message sent to me should include the changes to C code and header
files for a single feature, plus ChangeLog entries for each directory
where files were modified, and diffs for any changes needed to the
manuals (gdb/doc/gdb.texi or gdb/doc/gdbint.texi).  If there are a lot
of changes for a single feature, they can be split down into multiple
messages.

   In this way, if I read and like the feature, I can add it to the
sources with a single patch command, do some testing, and check it in.
If you leave out the ChangeLog, I have to write one.  If you leave out
the doc, I have to puzzle out what needs documenting.  Etc.

   The reason to send each change in a separate message is that I will
not install some of the changes.  They'll be returned to you with
questions or comments.  If I'm doing my job, my message back to you
will say what you have to fix in order to make the change acceptable.
The reason to have separate messages for separate features is so that
other changes (which I *am* willing to accept) can be installed while
one or more changes are being reworked.  If multiple features are sent
in a single message, I tend to not put in the effort to sort out the
acceptable changes from the unacceptable, so none of the features get
installed until all are acceptable.

   If this sounds painful or authoritarian, well, it is.  But I get a
lot of bug reports and a lot of patches, and most of them don't get
installed because I don't have the time to finish the job that the bug
reporter or the contributor could have done.  Patches that arrive
complete, working, and well designed, tend to get installed on the day
they arrive.  The others go into a queue and get installed if and when
I scan back over the queue -- which can literally take months
sometimes.  It's in both our interests to make patch installation easy
-- you get your changes installed, and I make some forward progress on
GDB in a normal 12-hour day (instead of them having to wait until I
have a 14-hour or 16-hour day to spend cleaning up patches before I can
install them).


Clean Design
************

   In addition to getting the syntax right, there's the little question
of semantics.  Some things are done in certain ways in GDB because long
experience has shown that the more obvious ways caused various kinds of
trouble.  In particular:

*
     You can't assume the byte order of anything that comes from a
     target (including VALUEs, object files, and instructions).  Such
     things must be byte-swapped using `SWAP_HOST_AND_TARGET' in GDB,
     or one of the swap routines defined in `bfd.h', such as
     `bfd_get_32'.

*
     You can't assume that you know what interface is being used to
     talk to the target system.  All references to the target must go
     through the current `target_ops' vector.

*
     You can't assume that the host and target machines are the same
     machine (except in the "native" support modules). In particular,
     you can't assume that the target machine's header files will be
     available on the host machine.  Target code must bring along its
     own header files -- written from scratch or explicitly donated by
     their owner, to avoid copyright problems.

*
     Insertion of new `#ifdef''s will be frowned upon.  It's much better
     to write the code portably than to conditionalize it for various
     systems.

*
     New `#ifdef''s which test for specific compilers or manufacturers
     or operating systems are unacceptable.  All `#ifdef''s should test
     for features.  The information about which configurations contain
     which features should be segregated into the configuration files. 
     Experience has proven far too often that a feature unique to one
     particular system often creeps into other systems; and that a
     conditional based on some predefined macro for your current system
     will become worthless over time, as new versions of your system
     come out that behave differently with regard to this feature.

*
     Adding code that handles specific architectures, operating
     systems, target interfaces, or hosts, is not acceptable in generic
     code.  If a hook is needed at that point, invent a generic hook
     and define it for your configuration, with something like:

          #ifdef	WRANGLE_SIGNALS
             WRANGLE_SIGNALS (signo);
          #endif

     In your host, target, or native configuration file, as appropriate,
     define `WRANGLE_SIGNALS' to do the machine-dependent thing.  Take
     a bit of care in defining the hook, so that it can be used by other
     ports in the future, if they need a hook in the same place.

*
     *Do* write code that doesn't depend on the sizes of C data types,
     the format of the host's floating point numbers, the alignment of
     anything, or the order of evaluation of expressions.  In short,
     follow good programming practices for writing portable C code.