X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdbint.texinfo;h=a79ce97e9b6e9f4d62c24b0c51075008a9d0da77;hb=6c0e9fb3d229e2c0864e3adceb46e35b0584be0b;hp=2429c49ec0bc2598e5f82df2e14832a235e8de91;hpb=93c2c7505f6f271a99d0396598b7bee020671036;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 2429c49ec0..a79ce97e9b 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -8,17 +8,16 @@ @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. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``Algorithms'' and ``Porting GDB'', with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free @@ -56,20 +55,16 @@ Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001 Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``Algorithms'' and ``Porting GDB'', with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.'' @end titlepage -@c TeX can handle the contents at the start but makeinfo 3.12 can not -@iftex @contents -@end iftex @node Top @c Perhaps this should be the title of the document (but only for info, @@ -95,6 +90,7 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets. * Support Libraries:: * Coding:: * Porting GDB:: +* Releasing GDB:: * Testsuite:: * Hints:: * Index:: @@ -2021,47 +2017,45 @@ distribution! @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 @@ -2166,11 +2160,6 @@ tables. For some machines this allows for sharing and quick updates. @item HAVE_TERMIO Define this if the host system has @code{termio.h}. -@item HOST_BYTE_ORDER -@cindex byte order -The ordering of bytes in the host. This must be defined to be either -@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. - @item INT_MAX @itemx INT_MIN @itemx LONG_MAX @@ -2220,10 +2209,6 @@ This macro is used as the argument to @code{lseek} (or, most commonly, @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. @@ -2432,7 +2417,7 @@ If @var{type} is not a pointer or reference type, then this function 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. @@ -3089,10 +3074,6 @@ On HP-UX, certain system routines (millicode) have names beginning with @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 @@ -3493,19 +3474,24 @@ current sources.) @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{LITTLE_ENDIAN}. 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{LITTLE_ENDIAN} 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. +@item TARGET_CHAR_SIGNED +@findex TARGET_CHAR_SIGNED +Non-zero if @code{char} is normally signed on this architecture; zero if +it should be unsigned. + +The ISO C standard requires the compiler to treat @code{char} as +equivalent to either @code{signed char} or @code{unsigned char}; any +character in the standard execution set is supposed to be positive. +Most compilers treat @code{char} as signed, but @code{char} is unsigned +on the IBM S/390, RS6000, and PowerPC targets. + @item TARGET_COMPLEX_BIT @findex TARGET_COMPLEX_BIT Number of bits in a complex number; defaults to @code{2 * TARGET_FLOAT_BIT}. @@ -3773,7 +3759,7 @@ Several files control @value{GDBN}'s configuration for native support: @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 @@ -3781,6 +3767,13 @@ 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 @@ -4150,14 +4143,16 @@ algorithms of @value{GDBN}. @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: @@ -4169,32 +4164,75 @@ Declare a variable which will hold a cleanup chain handle. @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 @@ -4711,6 +4749,13 @@ desired target is already available) also edit @file{gdb/configure.tgt}, 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 @@ -4772,6 +4817,190 @@ files @file{gdb.info*} in the distribution. Note the plural; @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 @@ -5140,12 +5369,4 @@ exec.c @printindex cp -@c TeX can handle the contents at the start but makeinfo 3.12 can not -@ifinfo -@contents -@end ifinfo -@ifhtml -@contents -@end ifhtml - @bye