@ifinfo
This file documents the internals of the GNU debugger @value{GDBN}.
-Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001
+Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002
Free Software Foundation, Inc.
Contributed by Cygnus Solutions. Written by John Gilmore.
Second Edition by Stan Shebs.
* Support Libraries::
* Coding::
* Porting GDB::
+* Releasing GDB::
* Testsuite::
* Hints::
* Index::
@chapter Host Definition
-@emph{Maintainer's note: In theory, new targets no longer need to use
-the host framework described below. Instead it should be possible to
-handle everything using autoconf. Patches eliminating this framework
-welcome.}
-
With the advent of Autoconf, it's rarely necessary to have host
-definition machinery anymore.
+definition machinery anymore. The following information is provided,
+mainly, as an historical reference.
@section Adding a New Host
@cindex adding a new host
@cindex host, adding
-Most of @value{GDBN}'s host configuration support happens via
-Autoconf. New host-specific definitions should be rarely needed.
-@value{GDBN} still uses the host-specific definitions and files listed
-below, but these mostly exist for historical reasons, and should
+@value{GDBN}'s host configuration support normally happens via Autoconf.
+New host-specific definitions should not be needed. Older hosts
+@value{GDBN} still use the host-specific definitions and files listed
+below, but these mostly exist for historical reasons, and will
eventually disappear.
-Several files control @value{GDBN}'s configuration for host systems:
-
@table @file
-@vindex XDEPFILES
@item gdb/config/@var{arch}/@var{xyz}.mh
-Specifies Makefile fragments needed when hosting on machine @var{xyz}.
-In particular, this lists the required machine-dependent object files,
-by defining @samp{XDEPFILES=@dots{}}. Also specifies the header file
-which describes host @var{xyz}, by defining @code{XM_FILE=
-xm-@var{xyz}.h}. You can also define @code{CC}, @code{SYSV_DEFINE},
-@code{XM_CFLAGS}, @code{XM_ADD_FILES}, @code{XM_CLIBS}, @code{XM_CDEPS},
-etc.; see @file{Makefile.in}.
+This file once contained both host and native configuration information
+(@pxref{Native Debugging}) for the machine @var{xyz}. The host
+configuration information is now handed by Autoconf.
+
+Host configuration information included a definition of
+@code{XM_FILE=xm-@var{xyz}.h} and possibly definitions for @code{CC},
+@code{SYSV_DEFINE}, @code{XM_CFLAGS}, @code{XM_ADD_FILES},
+@code{XM_CLIBS}, @code{XM_CDEPS}, etc.; see @file{Makefile.in}.
+
+New host only configurations do not need this file.
@item gdb/config/@var{arch}/xm-@var{xyz}.h
-(@file{xm.h} is a link to this file, created by @code{configure}). Contains C
-macro definitions describing the host system environment, such as byte
-order, host C compiler and library.
-
-@item gdb/@var{xyz}-xdep.c
-Contains any miscellaneous C code required for this machine as a host.
-On most machines it doesn't exist at all. If it does exist, put
-@file{@var{xyz}-xdep.o} into the @code{XDEPFILES} line in
-@file{gdb/config/@var{arch}/@var{xyz}.mh}.
+This file once contained definitions and includes required when hosting
+gdb on machine @var{xyz}. Those definitions and includes are now
+handled by Autoconf.
+
+New host and native configurations do not need this file.
+
+@emph{Maintainer's note: Some hosts continue to use the @file{xm-xyz.h}
+file to define the macros @var{HOST_FLOAT_FORMAT},
+@var{HOST_DOUBLE_FORMAT} and @var{HOST_LONG_DOUBLE_FORMAT}. That code
+also needs to be replaced with either an Autoconf or run-time test.}
+
@end table
@subheading Generic Host Support Files
@code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead,
which is the POSIX equivalent.
-@item MALLOC_INCOMPATIBLE
-Define this if the system's prototype for @code{malloc} differs from the
-@sc{ansi} definition.
-
@item MMAP_BASE_ADDRESS
When using HAVE_MMAP, the first mapping should go at this address.
will signal an internal error.
@end deftypefun
-@deftypefun CORE_ADDR value_as_address (value_ptr @var{val})
+@deftypefun CORE_ADDR value_as_address (struct value *@var{val})
Assuming that @var{val} is a pointer, return the address it represents,
as appropriate for the current architecture.
@samp{$} or @samp{$$}. For example, @code{$$dyncall} is a millicode
routine that handles inter-space procedure calls on PA-RISC.
-@item IEEE_FLOAT
-@findex IEEE_FLOAT
-Define this if the target system uses IEEE-format floating point numbers.
-
@item INIT_EXTRA_FRAME_INFO (@var{fromleaf}, @var{frame})
@findex INIT_EXTRA_FRAME_INFO
If additional information about the frame is required this should be
@item TARGET_BYTE_ORDER_DEFAULT
@findex TARGET_BYTE_ORDER_DEFAULT
The ordering of bytes in the target. This must be either
-@code{BIG_ENDIAN} or @code{BFD_ENDIAN_LITTLE}. This macro replaces
+@code{BFD_ENDIAN_BIG} or @code{BFD_ENDIAN_LITTLE}. This macro replaces
@code{TARGET_BYTE_ORDER} which is deprecated.
-@item TARGET_BYTE_ORDER_SELECTABLE_P
-@findex TARGET_BYTE_ORDER_SELECTABLE_P
-Non-zero if the target has both @code{BIG_ENDIAN} and
-@code{BFD_ENDIAN_LITTLE} variants. This macro replaces
-@code{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
-
@item TARGET_CHAR_BIT
@findex TARGET_CHAR_BIT
Number of bits in a char; defaults to 8.
@table @file
@vindex NATDEPFILES
@item gdb/config/@var{arch}/@var{xyz}.mh
-Specifies Makefile fragments needed when hosting @emph{or native} on
+Specifies Makefile fragments needed by a @emph{native} configuration on
machine @var{xyz}. In particular, this lists the required
native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
Also specifies the header file which describes native support on
define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
+@emph{Maintainer's note: The @file{.mh} suffix is because this file
+originally contained @file{Makefile} fragments for hosting @value{GDBN}
+on machine @var{xyz}. While the file is no longer used for this
+purpose, the @file{.mh} suffix remains. Perhaphs someone will
+eventually rename these fragments so that they have a @file{.mn}
+suffix.}
+
@item gdb/config/@var{arch}/nm-@var{xyz}.h
(@file{nm.h} is a link to this file, created by @code{configure}). Contains C
macro definitions describing the native system environment, such as
@cindex cleanups
Cleanups are a structured way to deal with things that need to be done
-later. When your code does something (like @code{malloc} some memory,
-or open a file) that needs to be undone later (e.g., free the memory or
-close the file), it can make a cleanup. The cleanup will be done at
-some future point: when the command is finished, when an error occurs,
-or when your code decides it's time to do cleanups.
+later.
-You can also discard cleanups, that is, throw them away without doing
-what they say. This is only done if you ask that it be done.
+When your code does something (e.g., @code{xmalloc} some memory, or
+@code{open} a file) that needs to be undone later (e.g., @code{xfree}
+the memory or @code{close} the file), it can make a cleanup. The
+cleanup will be done at some future point: when the command is finished
+and control returns to the top level; when an error occurs and the stack
+is unwound; or when your code decides it's time to explicitly perform
+cleanups. Alternatively you can elect to discard the cleanups you
+created.
Syntax:
@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
Make a cleanup which will cause @var{function} to be called with
@var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
-handle that can be passed to @code{do_cleanups} or
-@code{discard_cleanups} later. Unless you are going to call
-@code{do_cleanups} or @code{discard_cleanups} yourself, you can ignore
-the result from @code{make_cleanup}.
+handle that can later be passed to @code{do_cleanups} or
+@code{discard_cleanups}. Unless you are going to call
+@code{do_cleanups} or @code{discard_cleanups}, you can ignore the result
+from @code{make_cleanup}.
@findex do_cleanups
@item do_cleanups (@var{old_chain});
-Perform all cleanups done since @code{make_cleanup} returned
-@var{old_chain}. E.g.:
+Do all cleanups added to the chain since the corresponding
+@code{make_cleanup} call was made.
+
+@findex discard_cleanups
+@item discard_cleanups (@var{old_chain});
+Same as @code{do_cleanups} except that it just removes the cleanups from
+the chain and does not call the specified functions.
+@end table
+
+Cleanups are implemented as a chain. The handle returned by
+@code{make_cleanups} includes the cleanup passed to the call and any
+later cleanups appended to the chain (but not yet discarded or
+performed). E.g.:
@example
make_cleanup (a, 0);
-old = make_cleanup (b, 0);
-do_cleanups (old);
+@{
+ struct cleanup *old = make_cleanup (b, 0);
+ make_cleanup (c, 0)
+ ...
+ do_cleanups (old);
+@}
@end example
@noindent
-will call @code{b()} but will not call @code{a()}. The cleanup that
-calls @code{a()} will remain in the cleanup chain, and will be done
-later unless otherwise discarded.@refill
+will call @code{c()} and @code{b()} but will not call @code{a()}. The
+cleanup that calls @code{a()} will remain in the cleanup chain, and will
+be done later unless otherwise discarded.@refill
+
+Your function should explicitly do or discard the cleanups it creates.
+Failing to do this leads to non-deterministic behavior since the caller
+will arbitrarily do or discard your functions cleanups. This need leads
+to two common cleanup styles.
+
+The first style is try/finally. Before it exits, your code-block calls
+@code{do_cleanups} with the old cleanup chain and thus ensures that your
+code-block's cleanups are always performed. For instance, the following
+code-segment avoids a memory leak problem (even when @code{error} is
+called and a forced stack unwind occurs) by ensuring that the
+@code{xfree} will always be called:
-@findex discard_cleanups
-@item discard_cleanups (@var{old_chain});
-Same as @code{do_cleanups} except that it just removes the cleanups from
-the chain and does not call the specified functions.
-@end table
+@example
+struct cleanup *old = make_cleanup (null_cleanup, 0);
+data = xmalloc (sizeof blah);
+make_cleanup (xfree, data);
+... blah blah ...
+do_cleanups (old);
+@end example
+
+The second style is try/except. Before it exits, your code-block calls
+@code{discard_cleanups} with the old cleanup chain and thus ensures that
+any created cleanups are not performed. For instance, the following
+code segment, ensures that the file will be closed but only if there is
+an error:
+
+@example
+FILE *file = fopen ("afile", "r");
+struct cleanup *old = make_cleanup (close_file, file);
+... blah blah ...
+discard_cleanups (old);
+return file;
+@end example
Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
that they ``should not be called when cleanups are not in place''. This
setting @code{gdb_target} to something appropriate (for instance,
@var{xyz}).
+@emph{Maintainer's note: Work in progress. The file
+@file{gdb/configure.host} originally needed to be modified when either a
+new native target or a new host machine was being added to @value{GDBN}.
+Recent changes have removed this requirement. The file now only needs
+to be modified when adding a new native configuration. This will likely
+changed again in the future.}
+
@item
Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and
target-dependent @file{.h} and @file{.c} files used for your
@code{makeinfo} will split the document into one overall file and five
or so included files.
+@node Releasing GDB
+
+@chapter Releasing @value{GDBN}
+@cindex making a new release of gdb
+
+@section Before the branch
+
+The most important objective at this stage is to find and fix simple
+changes that become a pain to track once the branch is created. For
+instance, configuration problems that stop @value{GDBN} from even
+building. If you can't get the problem fixed, document it in the
+@file{PROBLEMS} file.
+
+@subheading Obsolete any code
+
+Mark as @kbd{OBSOLETE} any uninteresting targets or code files. This
+has a number of steps and is slow --- mainly to ensure that people have
+had a reasonable chance to respond. Remember, everything on the
+internet takes a week.
+
+@itemize @bullet
+@item
+announce the change on @email{gdb@@sources.redhat.com, GDB mailing list}
+@item
+wait a week
+@item
+announce the change on @email{gdb-announce@@sources.redhat.com, GDB
+Announcement mailing list}
+@item
+wait a week or so
+@item
+post / commit the change
+@end itemize
+
+@subheading Refresh any imported files.
+
+A number of files are taken from external repositories. They include:
+
+@itemize @bullet
+@item
+@file{texinfo/texinfo.tex}
+@item
+@file{config.guess} et.@: al.@:
+@end itemize
+
+and should be refreshed.
+
+@subheading Organize and announce the schedule.
+
+The following is a possible schedule. It is based on the rule-of-thumb
+that everything on the Internet takes a week. You may want to even
+increase those times further since an analysis of the actual data
+strongly suggests that the below is far to aggressive.
+
+@itemize @bullet
+@item
+announce it
+@item
+wait a week
+@item
+announce branch date
+@item
+wait a week
+@item
+Cut the branch
+@item
+wait a week
+@item
+start enjoying all the fun
+@end itemize
+
+As an aside, the branch tag name is probably regrettable vis:
+@file{gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}}.
+
+
+@section Building a Release
+
+@subheading Establish a few defaults.
+
+@example
+$ b=gdb_5_1_0_1-2002-01-03-branch
+$ v=5.1.0.1
+$ cd /sourceware/snapshot-tmp/gdbadmin-tmp/$b
+$ which autoconf
+/home/gdbadmin/bin/autoconf
+@end example
+
+NB: Check the autoconf version carefully. You want to be using
+@file{gdbadmin}'s version (which is really the version taken from the
+binutils snapshot). SWARE may have a different version installed.
+
+@subheading Check out the relevant modules:
+
+@example
+$ for m in gdb insight dejagnu; do
+( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m )
+done
+@end example
+
+NB: The reading of @file{.cvsrc} is disabled (@file{-f}) so that there
+isn't any confusion between what is written here and what CVS really
+does.
+
+@subheading Update the file @file{gdb/version.in} where applicable.
+
+@example
+$ for m in gdb insight; do echo $v > $m/src/gdb/version.in ; done
+@end example
+
+
+@subheading Mutter something about creating a @file{ChangeLog} entry. (both trunk and branch).
+
+@example
+$ emacs gdb/src/gdb/version.in
+c-x 4 a
+Bump version to 5.1.0.1.
+c-x c-s c-x c-c
+@end example
+
+ditto for @file{insight/src/gdb/version.in}
+
+@subheading Mutter something about updating @file{README}
+
+For dejagnu, edit @file{dejagnu/src/dejagnu/configure.in} and set it to
+gdb-$v and then regenerate configure. Mention this in the dejagnu
+@file{ChangeLog}.
+
+@example
+$ emacs dejagnu/src/dejagnu/configure.in
+...
+c-x 4 a
+Bump version to 5.1.0.1.
+* configure: Re-generate.
+c-x c-s c-x c-c
+$ ( cd dejagnu/src/dejagnu && autoconf )
+@end example
+
+@subheading Build the snapshot:
+
+@example
+$ for m in gdb insight dejagnu; do
+( cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+done
+@end example
+
+@subheading Do another @kbd{CVS update} to see what the damage is.
+
+@example
+$ ( cd gdb/src && cvs -q update )
+@end example
+
+You're looking for files that have mysteriously disappeared as the
+@kbd{distclean} has the habit of deleting files it shouldn't. Watch out
+for the @file{version.in} update cronjob.
+
+@subheading Copy all the @file{.bz2} files to the ftp directory:
+
+@example
+cp */src/*.bz2 ~ftp/.....
+@end example
+
+@subheading Something about @kbd{gzip}'ing them.
+
+@subheading Something about web pages?
+
+@subheading Something about documentation?
+
+@subheading Cleanup the release tree
+
+In particular you'll need to:
+
+@itemize @bullet
+@item
+Commit the changes to @file{ChangeLog} and @file{version.in}
+@item
+Tag the repository.
+@end itemize
+
+
+@section After the release
+
+Remove any @kbd{OBSOLETE} code.
+
+
@node Testsuite
@chapter Testsuite
projects / binutils.git / blobdiff