@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
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,
* Support Libraries::
* Coding::
* Porting GDB::
+* Releasing GDB::
* Testsuite::
* Hints::
+
+* GNU Free Documentation License:: The license for this documentation
* Index::
@end menu
machine-independent part of @value{GDBN}, except that it is used when
setting up a new frame from scratch, as follows:
-@example
- create_new_frame (read_register (FP_REGNUM), read_pc ()));
-@end example
+@smallexample
+create_new_frame (read_register (FP_REGNUM), read_pc ()));
+@end smallexample
@cindex frame pointer register
Other than that, all the meaning imparted to @code{FP_REGNUM} is
Since they depend on hardware resources, hardware breakpoints may be
limited in number; when the user asks for more, @value{GDBN} will
start trying to set software breakpoints. (On some architectures,
-notably the 32-bit x86 platforms, @value{GDBN} cannot alsways know
+notably the 32-bit x86 platforms, @value{GDBN} cannot always know
whether there's enough hardware resources to insert all the hardware
breakpoints and watchpoints. On those platforms, @value{GDBN} prints
an error message only when the program being debugged is continued.)
the page-level memory protection that implements hardware watchpoints
on that platform.
-@findex TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT
-@item TARGET_RANGE_PROFITABLE_FOR_HW_WATCHPOINT (@var{pid},@var{start},@var{len})
-Some addresses may not be profitable to use hardware to watch, or may
-be difficult to understand when the addressed object is out of scope,
-and hence should not be watched with hardware watchpoints. On some
-targets, this may have severe performance penalties, such that we
-might as well use regular watchpoints, and save (possibly precious)
-hardware watchpoints for other locations.
-
@findex target_insert_watchpoint
@findex target_remove_watchpoint
@item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})
possible values of the enumerated data type @code{target_hw_bp_type},
defined by @file{breakpoint.h} as follows:
-@example
+@smallexample
enum target_hw_bp_type
@{
hw_write = 0, /* Common (write) HW watchpoint */
hw_access = 2, /* Access (read or write) HW watchpoint */
hw_execute = 3 /* Execute HW breakpoint */
@};
-@end example
+@end smallexample
@noindent
These two macros should return 0 for success, non-zero for failure.
region for the same access types; if found, it just increments the
reference count of that debug register, thus implementing debug
register sharing between watchpoints. If no such register is found,
-the function looks for a vacant debug register, sets its mirrorred
-value to @var{addr}, sets the mirrorred value of DR7 Debug Control
+the function looks for a vacant debug register, sets its mirrored
+value to @var{addr}, sets the mirrored value of DR7 Debug Control
register as appropriate for the @var{len} and @var{type} parameters,
and then passes the new values of the debug register and DR7 to the
inferior by calling @code{I386_DR_LOW_SET_ADDR} and
each debug register.
@code{i386_remove_watchpoint} does the opposite: it resets the address
-in the mirrorred value of the debug register and its read/write and
-length bits in the mirrorred value of DR7, then passes these new
+in the mirrored value of the debug register and its read/write and
+length bits in the mirrored value of DR7, then passes these new
values to the inferior via @code{I386_DR_LOW_RESET_ADDR} and
@code{I386_DR_LOW_SET_CONTROL}. If a register is shared by several
watchpoints, each time a @code{i386_remove_watchpoint} is called, it
The overall structure of the table output code is something like this:
-@example
+@smallexample
ui_out_table_begin
ui_out_table_header
@dots{}
ui_out_tuple_end
@dots{}
ui_out_table_end
-@end example
+@end smallexample
Here is the description of table-, tuple- and list-related @code{ui_out}
functions:
The original code was:
-@example
+@smallexample
if (!found_a_breakpoint++)
@{
annotate_breakpoints_headers ();
annotate_breakpoints_table ();
@}
-@end example
+@end smallexample
Here's the new version:
-@example
+@smallexample
nr_printable_breakpoints = @dots{};
if (addressprint)
ui_out_table_body (uiout);
if (nr_printable_breakpoints > 0)
annotate_breakpoints_table ();
-@end example
+@end smallexample
This example, from the @code{print_one_breakpoint} function, shows how
to produce the actual data for the table whose structure was defined
in the above example. The original code was:
-@example
+@smallexample
annotate_record ();
annotate_field (0);
printf_filtered ("%-3d ", b->number);
annotate_field (3);
printf_filtered ("%-3c ", bpenables[(int)b->enable]);
@dots{}
-@end example
+@end smallexample
This is the new version:
-@example
+@smallexample
annotate_record ();
ui_out_tuple_begin (uiout, "bkpt");
annotate_field (0);
annotate_field (3);
ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
@dots{}
-@end example
+@end smallexample
This example, also from @code{print_one_breakpoint}, shows how to
produce a complicated output field using the @code{print_expression}
functions which requires a stream to be passed. It also shows how to
automate stream destruction with cleanups. The original code was:
-@example
+@smallexample
annotate_field (5);
print_expression (b->exp, gdb_stdout);
-@end example
+@end smallexample
The new version is:
-@example
+@smallexample
struct ui_stream *stb = ui_out_stream_new (uiout);
struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
...
annotate_field (5);
print_expression (b->exp, stb->stream);
ui_out_field_stream (uiout, "what", local_stream);
-@end example
+@end smallexample
This example, also from @code{print_one_breakpoint}, shows how to use
@code{ui_out_text} and @code{ui_out_field_string}. The original code
was:
-@example
+@smallexample
annotate_field (5);
if (b->dll_pathname == NULL)
printf_filtered ("<any library> ");
else
printf_filtered ("library \"%s\" ", b->dll_pathname);
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (5);
if (b->dll_pathname == NULL)
@{
ui_out_field_string (uiout, "what", b->dll_pathname);
ui_out_text (uiout, "\" ");
@}
-@end example
+@end smallexample
The following example from @code{print_one_breakpoint} shows how to
use @code{ui_out_field_int} and @code{ui_out_spaces}. The original
code was:
-@example
+@smallexample
annotate_field (5);
if (b->forked_inferior_pid != 0)
printf_filtered ("process %d ", b->forked_inferior_pid);
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (5);
if (b->forked_inferior_pid != 0)
@{
ui_out_field_int (uiout, "what", b->forked_inferior_pid);
ui_out_spaces (uiout, 1);
@}
-@end example
+@end smallexample
Here's an example of using @code{ui_out_field_string}. The original
code was:
-@example
+@smallexample
annotate_field (5);
if (b->exec_pathname != NULL)
printf_filtered ("program \"%s\" ", b->exec_pathname);
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (5);
if (b->exec_pathname != NULL)
@{
ui_out_field_string (uiout, "what", b->exec_pathname);
ui_out_text (uiout, "\" ");
@}
-@end example
+@end smallexample
Finally, here's an example of printing an address. The original code:
-@example
+@smallexample
annotate_field (4);
printf_filtered ("%s ",
local_hex_string_custom ((unsigned long) b->address, "08l"));
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (4);
ui_out_field_core_addr (uiout, "Address", b->address);
-@end example
+@end smallexample
@section Console Printing
@strong{must} be included at the top of the YACC parser, to prevent the
various parsers from defining the same global names:
-@example
+@smallexample
#define yyparse @var{lang}_parse
#define yylex @var{lang}_lex
#define yyerror @var{lang}_error
#define yyexca @var{lang}_exca
#define yyerrflag @var{lang}_errflag
#define yynerrs @var{lang}_nerrs
-@end example
+@end smallexample
At the bottom of your parser, define a @code{struct language_defn} and
initialize it with the right values for your language. Define an
@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
@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
@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.
The target architecture object is implemented as the C structure
@code{struct gdbarch *}. The structure, and its methods, are generated
-using the Bourn shell script @file{gdbarch.sh}.
+using the Bourne shell script @file{gdbarch.sh}.
@section Registers and Memory
will signal an internal error.
@end deftypefun
-@deftypefun CORE_ADDR value_as_pointer (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.
@item CALL_DUMMY_P
@findex CALL_DUMMY_P
-A C expresson that is non-zero when the target suports inferior function
+A C expression that is non-zero when the target supports inferior function
calls.
@item CALL_DUMMY_WORDS
@item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual})
@findex COERCE_FLOAT_TO_DOUBLE
@cindex promotion to @code{double}
-If we are calling a function by hand, and the function was declared
-(according to the debug info) without a prototype, should we
-automatically promote @code{float}s to @code{double}s? This macro
-must evaluate to non-zero if we should, or zero if we should leave the
-value alone.
-
-The argument @var{actual} is the type of the value we want to pass to
-the function. The argument @var{formal} is the type of this argument,
-as it appears in the function's definition. Note that @var{formal} may
-be zero if we have no debugging information for the function, or if
-we're passing more arguments than are officially declared (for example,
-varargs). This macro is never invoked if the function definitely has a
-prototype.
-
-@findex set_gdbarch_coerce_float_to_double
+@cindex @code{float} arguments
+@cindex prototyped functions, passing arguments to
+@cindex passing arguments to prototyped functions
+Return non-zero if GDB should promote @code{float} values to
+@code{double} when calling a non-prototyped function. The argument
+@var{actual} is the type of the value we want to pass to the function.
+The argument @var{formal} is the type of this argument, as it appears in
+the function's definition. Note that @var{formal} may be zero if we
+have no debugging information for the function, or if we're passing more
+arguments than are officially declared (for example, varargs). This
+macro is never invoked if the function definitely has a prototype.
+
+How you should pass arguments to a function depends on whether it was
+defined in K&R style or prototype style. If you define a function using
+the K&R syntax that takes a @code{float} argument, then callers must
+pass that argument as a @code{double}. If you define the function using
+the prototype syntax, then you must pass the argument as a @code{float},
+with no promotion.
+
+Unfortunately, on certain older platforms, the debug info doesn't
+indicate reliably how each function was defined. A function type's
+@code{TYPE_FLAG_PROTOTYPED} flag may be unset, even if the function was
+defined in prototype style. When calling a function whose
+@code{TYPE_FLAG_PROTOTYPED} flag is unset, GDB consults the
+@code{COERCE_FLOAT_TO_DOUBLE} macro to decide what to do.
+
@findex standard_coerce_float_to_double
-The default behavior is to promote only when we have no type information
-for the formal parameter. This is different from the obvious behavior,
-which would be to promote whenever we have no prototype, just as the
-compiler does. It's annoying, but some older targets rely on this. If
-you want @value{GDBN} to follow the typical compiler behavior---to always
-promote when there is no prototype in scope---your gdbarch @code{init}
-function can call @code{set_gdbarch_coerce_float_to_double} and select
-the @code{standard_coerce_float_to_double} function.
+For modern targets, it is proper to assume that, if the prototype flag
+is unset, that can be trusted: @code{float} arguments should be promoted
+to @code{double}. You should use the function
+@code{standard_coerce_float_to_double} to get this behavior.
+
+@findex default_coerce_float_to_double
+For some older targets, if the prototype flag is unset, that doesn't
+tell us anything. So we guess that, if we don't have a type for the
+formal parameter (@i{i.e.}, the first argument to
+@code{COERCE_FLOAT_TO_DOUBLE} is null), then we should promote it;
+otherwise, we should leave it alone. The function
+@code{default_coerce_float_to_double} provides this behavior; it is the
+default value, for compatibility with older configurations.
@item CPLUS_MARKER
@findex CPLUS_MARKERz
@findex DO_REGISTERS_INFO
If defined, use this to print the value of a register or all registers.
+@item PRINT_FLOAT_INFO()
+#findex PRINT_FLOAT_INFO
+If defined, then the @samp{info float} command will print information about
+the processor's floating point unit.
+
@item DWARF_REG_TO_REGNUM
@findex DWARF_REG_TO_REGNUM
Convert DWARF register number into @value{GDBN} regnum. If not defined,
@item FLOAT_INFO
@findex FLOAT_INFO
-If defined, then the @samp{info float} command will print information about
-the processor's floating point unit.
+Deprecated in favor of @code{PRINT_FLOAT_INFO}.
@item FP_REGNUM
@findex FP_REGNUM
If the virtual frame pointer is kept in a register, then define this
macro to be the number (greater than or equal to zero) of that register.
-This should only need to be defined if @code{TARGET_READ_FP} and
-@code{TARGET_WRITE_FP} are not defined.
+This should only need to be defined if @code{TARGET_READ_FP} is not
+defined.
@item FRAMELESS_FUNCTION_INVOCATION(@var{fi})
@findex FRAMELESS_FUNCTION_INVOCATION
@findex FRAME_CHAIN
Given @var{frame}, return a pointer to the calling frame.
-@item FRAME_CHAIN_COMBINE(@var{chain}, @var{frame})
-@findex FRAME_CHAIN_COMBINE
-Define this to take the frame chain pointer and the frame's nominal
-address and produce the nominal address of the caller's frame.
-Presently only defined for HP PA.
-
@item FRAME_CHAIN_VALID(@var{chain}, @var{thisframe})
@findex FRAME_CHAIN_VALID
Define this to be an expression that returns zero if the given frame is
@item @value{GDBN}_MULTI_ARCH
@findex @value{GDBN}_MULTI_ARCH
-If defined and non-zero, enables suport for multiple architectures
+If defined and non-zero, enables support for multiple architectures
within @value{GDBN}.
This support can be enabled at two levels. At level one, only
definitions for previously undefined macros are provided; at level two,
-a multi-arch definition of all architecture dependant macros will be
+a multi-arch definition of all architecture dependent macros will be
defined.
@item @value{GDBN}_TARGET_IS_HPPA
@findex GET_LONGJMP_TARGET
For most machines, this is a target-dependent parameter. On the
DECstation and the Iris, this is a native-dependent parameter, since
-trhe header file @file{setjmp.h} is needed to define it.
+the header file @file{setjmp.h} is needed to define it.
This macro determines the target PC address that @code{longjmp} will jump to,
assuming that we have just stopped at a @code{longjmp} breakpoint. It takes a
Define this if you need to supply your own definition for the function
@code{get_saved_register}.
-@item HAVE_REGISTER_WINDOWS
-@findex HAVE_REGISTER_WINDOWS
-Define this if the target has register windows.
-
@item REGISTER_IN_WINDOW_P (@var{regnum})
@findex REGISTER_IN_WINDOW_P
Define this to be an expression that is 1 if the given register is in
@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
the target's stack grows downward in memory, or @code{lhs > rsh} if the
stack grows upward.
+@item gdbarch_in_function_epilogue_p (@var{gdbarch}, @var{pc})
+@findex gdbarch_in_function_epilogue_p
+Returns non-zero if the given @var{pc} is in the epilogue of a function.
+The epilogue of a function is defined as the part of a function where
+the stack frame of the function already has been destroyed up to the
+final `return from function call' instruction.
+
@item IN_SIGTRAMP (@var{pc}, @var{name})
@findex IN_SIGTRAMP
Define this to return non-zero if the given @var{pc} and/or @var{name}
A C expression that returns the address of the ``real'' code beyond the
function entry prologue found at @var{pc}.
-@item SKIP_PROLOGUE_FRAMELESS_P
-@findex SKIP_PROLOGUE_FRAMELESS_P
-A C expression that should behave similarly, but that can stop as soon
-as the function is known to have a frame. If not defined,
-@code{SKIP_PROLOGUE} will be used instead.
-
@item SKIP_TRAMPOLINE_CODE (@var{pc})
@findex SKIP_TRAMPOLINE_CODE
If the target machine has trampoline code that sits between callers and
The default value of the ``symbol-reloading'' variable. (Never defined in
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{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}.
@findex TARGET_WRITE_SP
@itemx TARGET_READ_FP
@findex TARGET_READ_FP
-@itemx TARGET_WRITE_FP
-@findex TARGET_WRITE_FP
@findex read_pc
@findex write_pc
@findex read_sp
@findex write_sp
@findex read_fp
-@findex write_fp
These change the behavior of @code{read_pc}, @code{write_pc},
-@code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}.
-For most targets, these may be left undefined. @value{GDBN} will call the read
-and write register functions with the relevant @code{_REGNUM} argument.
+@code{read_sp}, @code{write_sp} and @code{read_fp}. For most targets,
+these may be left undefined. @value{GDBN} will call the read and write
+register functions with the relevant @code{_REGNUM} argument.
These macros are useful when a target keeps one of these registers in a
hard to get at place; for example, part in a segment register and part
@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. Perhaps 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
If defined, this is the name of the shell to use to run the inferior.
Defaults to @code{"/bin/sh"}.
-@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ})
+@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms})
@findex SOLIB_ADD
Define this to expand into an expression that will cause the symbols in
-@var{filename} to be added to @value{GDBN}'s symbol table.
+@var{filename} to be added to @value{GDBN}'s symbol table. If
+@var{readsyms} is zero symbols are not read but any necessary low level
+processing for @var{filename} is still done.
@item SOLIB_CREATE_INFERIOR_HOOK
@findex SOLIB_CREATE_INFERIOR_HOOK
@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.:
-
-@example
-make_cleanup (a, 0);
-old = make_cleanup (b, 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
+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});
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.:
+
+@smallexample
+make_cleanup (a, 0);
+@{
+ struct cleanup *old = make_cleanup (b, 0);
+ make_cleanup (c, 0)
+ ...
+ do_cleanups (old);
+@}
+@end smallexample
+
+@noindent
+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:
+
+@smallexample
+struct cleanup *old = make_cleanup (null_cleanup, 0);
+data = xmalloc (sizeof blah);
+make_cleanup (xfree, data);
+... blah blah ...
+do_cleanups (old);
+@end smallexample
+
+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:
+
+@smallexample
+FILE *file = fopen ("afile", "r");
+struct cleanup *old = make_cleanup (close_file, file);
+... blah blah ...
+discard_cleanups (old);
+return file;
+@end smallexample
+
Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
that they ``should not be called when cleanups are not in place''. This
means that any actions you need to reverse in the case of an error or
A function declaration should not have its name in column zero. A
function definition should have its name in column zero.
-@example
+@smallexample
/* Declaration */
static void foo (void);
/* Definition */
foo (void)
@{
@}
-@end example
+@end smallexample
@emph{Pragmatics: This simplifies scripting. Function definitions can
be found using @samp{^function-name}.}
Pointers are declared using the traditional K&R C style:
-@example
+@smallexample
void *foo;
-@end example
+@end smallexample
@noindent
and not:
-@example
+@smallexample
void * foo;
void* foo;
-@end example
+@end smallexample
@subsection Comments
Block comments must appear in the following form, with no @code{/*}- or
@code{*/}-only lines, and no leading @code{*}:
-@example
+@smallexample
/* Wait for control to return from inferior to debugger. If inferior
gets a signal, we may decide to start it up again instead of
returning. That is why there is a loop in this function. When
this function actually returns it means the inferior should be left
stopped and @value{GDBN} should read more commands. */
-@end example
+@end smallexample
(Note that this format is encouraged by Emacs; tabbing for a multi-line
comment works correctly, and @kbd{M-q} fills the block consistently.)
User errors and internal errors. User errors include not only a user
entering an incorrect command but also problems arising from corrupt
object files and system errors when interacting with the target.
-Internal errors include situtations where @value{GDBN} has detected, at
-run time, a corrupt or erroneous situtation.
+Internal errors include situations where @value{GDBN} has detected, at
+run time, a corrupt or erroneous situation.
When reporting an internal error, @value{GDBN} uses
@code{internal_error} and @code{gdb_assert}.
included indirectly.
With the exception of the global definitions supplied by @file{defs.h},
-a header file should explictily include the header declaring any
+a header file should explicitly include the header declaring any
@code{typedefs} et.al.@: it refers to.
@code{extern} declarations should never appear in @code{.c} files.
All include files should be wrapped in:
-@example
+@smallexample
#ifndef INCLUDE_FILE_NAME_H
#define INCLUDE_FILE_NAME_H
header body
#endif
-@end example
+@end smallexample
@subsection Clean Design and Portable Implementation
such hosts.
@findex IS_DIR_SEPARATOR
-@item IS_DIR_SEPARATOR (@var{c}
+@item IS_DIR_SEPARATOR (@var{c})
Evaluates to a non-zero value if @var{c} is a directory separator
character. On Unix and GNU/Linux systems, only a slash @file{/} is
such a character, but on Windows, both @file{/} and @file{\} will
@code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
running
-@example
+@smallexample
./config.sub @var{xyz}
-@end example
+@end smallexample
@noindent
and
-@example
+@smallexample
./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
-@end example
+@end smallexample
@noindent
which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
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
From the top level directory (containing @file{gdb}, @file{bfd},
@file{libiberty}, and so on):
-@example
+@smallexample
make -f Makefile.in gdb.tar.gz
-@end example
+@end smallexample
@noindent
This will properly configure, clean, rebuild any files that are
@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 Versions and Branches
+
+@subsection Version Identifiers
+
+@value{GDBN}'s version is determined by the file @file{gdb/version.in}.
+
+@value{GDBN}'s mainline uses ISO dates to differentiate between
+versions. The CVS repository uses @var{YYYY}-@var{MM}-@var{DD}-cvs
+while the corresponding snapshot uses @var{YYYYMMDD}.
+
+@value{GDBN}'s release branch uses a slightly more complicated scheme.
+When the branch is first cut, the mainline version identifier is
+prefixed with the @var{major}.@var{minor} from of the previous release
+series but with .90 appended. As draft releases are drawn from the
+branch, the minor minor number (.90) is incremented. Once the first
+release (@var{M}.@var{N}) has been made, the version prefix is updated
+to @var{M}.@var{N}.0.90 (dot zero, dot ninety). Follow on releases have
+an incremented minor minor version number (.0).
+
+Using 5.1 (previous) and 5.2 (current), the example below illustrates a
+typical sequence of version identifiers:
+
+@table @asis
+@item 5.1.1
+final release from previous branch
+@item 2002-03-03-cvs
+main-line the day the branch is cut
+@item 5.1.90-2002-03-03-cvs
+corresponding branch version
+@item 5.1.91
+first draft release candidate
+@item 5.1.91-2002-03-17-cvs
+updated branch version
+@item 5.1.92
+second draft release candidate
+@item 5.1.92-2002-03-31-cvs
+updated branch version
+@item 5.1.93
+final release candidate (see below)
+@item 5.2
+official release
+@item 5.2.0.90-2002-04-07-cvs
+updated CVS branch version
+@item 5.2.1
+second official release
+@end table
+
+Notes:
+
+@itemize @bullet
+@item
+Minor minor minor draft release candidates such as 5.2.0.91 have been
+omitted from the example. Such release candidates are, typically, never
+made.
+@item
+For 5.1.93 the bziped tar ball @file{gdb-5.1.93.tar.bz2} is just the
+official @file{gdb-5.2.tar} renamed and compressed.
+@end itemize
+
+To avoid version conflicts, vendors are expected to modify the file
+@file{gdb/version.in} to include a vendor unique alphabetic identifier
+(an official @value{GDBN} release never uses alphabetic characters in
+its version identifer).
+
+Since @value{GDBN} does not make minor minor minor releases (e.g.,
+5.1.0.1) the conflict between that and a minor minor draft release
+identifier (e.g., 5.1.0.90) is avoided.
+
+
+@subsection Branches
+
+@value{GDBN} draws a release series (5.2, 5.2.1, @dots{}) from a single
+release branch (gdb_5_2-branch). Since minor minor minor releases
+(5.1.0.1) are not made, the need to branch the release branch is avoided
+(it also turns out that the effort required for such a a branch and
+release is significantly greater than the effort needed to create a new
+release from the head of the release branch).
+
+Releases 5.0 and 5.1 used branch and release tags of the form:
+
+@smallexample
+gdb_N_M-YYYY-MM-DD-branchpoint
+gdb_N_M-YYYY-MM-DD-branch
+gdb_M_N-YYYY-MM-DD-release
+@end smallexample
+
+Release 5.2 is trialing the branch and release tags:
+
+@smallexample
+gdb_N_M-YYYY-MM-DD-branchpoint
+gdb_N_M-branch
+gdb_M_N-YYYY-MM-DD-release
+@end smallexample
+
+@emph{Pragmatics: The branchpoint and release tags need to identify when
+a branch and release are made. The branch tag, denoting the head of the
+branch, does not have this criteria.}
+
+
+@section Branch Commit Policy
+
+The branch commit policy is pretty slack. @value{GDBN} releases 5.0,
+5.1 and 5.2 all used the below:
+
+@itemize @bullet
+@item
+The @file{gdb/MAINTAINERS} file still holds.
+@item
+Don't fix something on the branch unless/until it is also fixed in the
+trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS}
+file is better than committing a hack.
+@item
+When considering a patch for the branch, suggested criteria include:
+Does it fix a build? Does it fix the sequence @kbd{break main; run}
+when debugging a static binary?
+@item
+The further a change is from the core of @value{GDBN}, the less likely
+the change will worry anyone (e.g., target specific code).
+@item
+Only post a proposal to change the core of @value{GDBN} after you've
+sent individual bribes to all the people listed in the
+@file{MAINTAINERS} file @t{;-)}
+@end itemize
+
+@emph{Pragmatics: Provided updates are restricted to non-core
+functionality there is little chance that a broken change will be fatal.
+This means that changes such as adding a new architectures or (within
+reason) support for a new host are considered acceptable.}
+
+
+@section Obsolete any code
+
+Before anything else, poke the other developers (and around the source
+code) to see if there is anything that can be removed from @value{GDBN}
+(an old target, an unused file).
+
+Obsolete code is identified by adding an @code{OBSOLETE} prefix to every
+line. Doing this means that it is easy to identify obsolete code when
+grepping through the sources.
+
+The process has a number of steps and is intentionally slow --- this is
+to mainly 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 or so
+@item
+announce the change on @email{gdb-announce@@sources.redhat.com, GDB
+Announcement mailing list}
+@item
+wait a week or so
+@item
+go through and edit all relevant files and lines (e.g., in
+@file{configure.tgt}) so that they are prefixed with the word
+@code{OBSOLETE}.
+@end itemize
+
+@emph{Maintainer note: Removing old code, while regrettable, is a good
+thing. Firstly it helps the developers by removing code that is either
+no longer relevant or simply wrong. Secondly since it removes any
+history associated with the file (effectively clearing the slate) the
+developer has a much freer hand when it comes to fixing broken files.}
+
+
+@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{gdb/PROBLEMS} file.
+
+@subheading Prompt for @file{gdb/NEWS}
+
+People always forget. Send a post reminding them but also if you know
+something interesting happened add it yourself. The @code{schedule}
+script will mention this in its e-mail.
+
+@subheading Review @file{gdb/README}
+
+Grab one of the nightly snapshots and then walk through the
+@file{gdb/README} looking for anything that can be improved. The
+@code{schedule} script will mention this in its e-mail.
+
+@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.@: (see the top-level @file{MAINTAINERS}
+file)
+@item
+@file{etc/standards.texi}, @file{etc/make-stds.texi}
+@end itemize
+
+@subheading Check the ARI
+
+@uref{http://sources.redhat.com/gdb/ari,,A.R.I.} is an @code{awk} script
+(Awk Regression Index ;-) that checks for a number of errors and coding
+conventions. The checks include things like using @code{malloc} instead
+of @code{xmalloc} and file naming problems. There shouldn't be any
+regressions.
+
+@subsection Review the bug data base
+
+Close anything obviously fixed.
+
+@subsection Check all cross targets build
+
+The targets are listed in @file{gdb/MAINTAINERS}.
+
+
+@section Cut the branch
+
+@subheading The dirty work
+
+I think something like the below was used:
+
+@smallexample
+$ d=`date -u +%Y-%m-%d`
+$ echo $d
+2002-01-24
+$ cvs -f -d /cvs/src rtag -D $d-gmt \
+gdb_5_1-$d-branchpoint insight+dejagnu
+$ cvs -f -d /cvs/src rtag -b -r gdb_V_V-$d-branchpoint \
+gdb_5_1-$d-branch insight+dejagnu
+$
+@end smallexample
+
+@itemize @bullet
+@item
+the @kbd{-D YYYY-MM-DD-gmt} forces the branch to an exact date/time.
+@item
+the trunk is first tagged so that the branch point can easily be found
+@item
+Insight (which includes GDB) and dejagnu are tagged at the same time
+@end itemize
+
+@subheading Post the branch info
+
+@subheading Update the web and news pages
+
+@subheading Tweak cron to track the new branch
+
+@section Stabilize the branch
+
+Something goes here.
+
+@section Create a Release
+
+This procedure can be followed when creating beta and final final
+releases. With a beta many of the steps can be skipped.
+
+@subheading Establish a few defaults.
+
+@smallexample
+$ b=gdb_5_1-2001-07-29-branch
+$ v=5.1.1
+$ t=/sourceware/snapshot-tmp/gdbadmin-tmp
+$ echo $t/$b/$v
+$ mkdir -p $t/$b/$v
+$ cd $t/$b/$v
+$ pwd
+/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_1-2001-07-29-branch/5.1.1
+$ which autoconf
+/home/gdbadmin/bin/autoconf
+$
+@end smallexample
+
+NB: Check the autoconf version carefully. You want to be using the
+version taken from the binutils snapshot directory. It is most likely
+that your system's installed version (@file{/usr/bin}?) is probably
+correct.
+
+@subheading Check out the relevant modules:
+
+@smallexample
+$ 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 smallexample
+
+NB: The reading of @file{.cvsrc} is disabled (@file{-f}) so that there
+isn't any confusion between what is written here and what your local CVS
+really does.
+
+@subheading Update relevant files.
+
+@subsubheading @file{gdb/NEWS}
+
+Major releases get their comments added as part of the mainline. Minor
+releases should probably mention any significant bugs that were fixed.
+
+Don't forget to update the ChangeLog.
+
+@smallexample
+$ emacs gdb/src/gdb/NEWS
+...
+c-x 4 a
+...
+c-x c-s c-x c-c
+$ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS
+$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
+@end smallexample
+
+@subsubheading @file{gdb/README}
+
+You'll need to update: the version, the update date, and who did it.
+
+@smallexample
+$ emacs gdb/src/gdb/README
+...
+c-x 4 a
+...
+c-x c-s c-x c-c
+$ cp gdb/src/gdb/README insight/src/gdb/README
+$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
+@end smallexample
+
+@emph{Maintainer note: Hopefully the README file was reviewed before the
+initial branch was cut so just a simple substitute is needed to get it
+updated.}
+
+@emph{Maintainer note: Other projects generate @file{README} and
+@file{INSTALL} from the core documentation. This might be worth
+pursuing.}
+
+@subsubheading @file{gdb/version.in}
+
+@smallexample
+$ echo $v > gdb/src/gdb/version.in
+$ emacs gdb/src/gdb/version.in
+...
+c-x 4 a
+...
+c-x c-s c-x c-c
+$ cp gdb/src/gdb/version.in insight/src/gdb/version.in
+$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
+@end smallexample
+
+@subsubheading @file{dejagnu/src/dejagnu/configure.in}
+
+Dejagnu is more complicated. The version number is a parameter to
+@var{AM_INIT_AUTOMAKE}. Tweak it to read something like
+@var{gdb-5.1.1}.
+
+Re-generate configure.
+
+Add a ChangeLog.
+
+@subheading Do the dirty work
+
+This is identical to the process used when creating the daily snapshot.
+
+@smallexample
+$ for m in gdb insight dejagnu
+do
+( cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+done
+@end smallexample
+
+@subheading Check the source files
+
+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 @kbd{cronjob}.
+
+@smallexample
+$ ( cd gdb/src && cvs -f -q -n update )
+M djunpack.bat
+? proto-toplev
+? gdb-5.1.1.tar.bz2
+M gdb/ChangeLog
+M gdb/NEWS
+M gdb/README
+M gdb/version.in
+? gdb/p-exp.tab.c
+? gdb/doc/gdb.info-11
+? gdb/doc/gdb.info-12
+? gdb/doc/gdb.info-13
+? gdb/doc/gdb.info-14
+? gdb/doc/gdb.info-15
+? gdb/doc/gdbint.info-4
+? gdb/doc/gdbint.info-5
+$
+@end smallexample
+
+@emph{Don't worry about the @file{gdb.info-??} or
+@file{gdb/p-exp.tab.c}. They were generated (and yes @file{gdb.info-1}
+was also generated only something strange with CVS means that they
+didn't get supressed). Fixing it would be nice though.}
+
+@subheading Re-pack the release with @code{gzip}
+
+@smallexample
+$ cp */*/*.bz2 .
+$ bunzip2 -k -v *.bz2
+$ gzip -9 -v *.tar
+@end smallexample
+
+NB: A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} shouldn't
+be used since, in that mode, gzip doesn't know the file name information
+and consequently can't include it. This is also why the release process
+runs @code{tar} and @code{bzip2} as separate passes.
+
+@emph{Maintainer note: The release process could be changed to create
+@file{.tar} rather than @file{.tar.bz2} files.}
+
+@section Check the release
+
+Grab the @file{gdb.tar.bz2}, copy it to your local machine and then try
+a simple build using it.
+
+If this is a pre-release just copy the @file{.bz2} files to the snapshot
+directory and skip the remaining steps.
+
+If it is a final release, also make it available under a bogus name so
+that others can download and check it.
+
+@emph{Maintainer note: This adds an extra day to the release process but
+is very much worth it. Other developers are given the opportunity to
+check that things like your @file{NEWS} entries are correct or that
+other changes actually work.}
+
+@section Release the tar ball
+
+This is where, unfortunately, the notes just get vague.
+
+@subheading Install on sware
+
+@smallexample
+$ cp *.bz2 *.gz ~ftp/pub/gdb/releases
+@end smallexample
+
+@subheading Create and update the web pages.
+
+Try the following:
+
+@itemize @bullet
+@item
+create the directory @file{htdocs/@var{version}} (e.g., @file{htdocs/5.1.1}
+@item
+copy @file{index.html} and @file{ANNOUNCE} from the previous release
+into the @file{htdocs/@var{version}} directory and edit for content.
+Things like the MD5 sums, @kbd{ls -l} output, the version number and so
+on will need updating. Add NEWS entries to the @file{ANNOUNCE}. This
+ensures that the previous announcement is kept somewhere handy.
+@item
+copy the @file{NEWS} from the distro into the
+@file{htdocs/@var{version}} directory, trim down to just the most recent
+news items
+@item
+Add a short (identical) announcement to both @file{htdocs/index.html}
+and @file{htdocs/news/index.html}
+@item
+edit the script @file{htdocs/index.sh} to link in the new release
+number. Run it across all @file{index.html} files vis @kbd{./index.sh
+index.html */index.html}.
+@item
+grep the @file{htdocs} tree for references to the previous release
+version (@file{htdocs/download/index.html})
+@end itemize
+
+@emph{Maintainer note: This step is too fragile --- it is too easy to
+mis one of the entries and forget to update it.}
+
+@subheading Generate online docs
+
+You need to find the magic command that is used to generate the online
+docs from the @file{.tar.bz2}. The best way is to look in the output
+from one of the nightly cronjobs and then just edit accordingly.
+Something like:
+
+@smallexample
+$ ~/ss/update-web-docs \
+ ~ftp/pub/gdb/releases/gdb-5.1.1.tar.bz2 \
+ $PWD/www \
+ /www/sourceware/htdocs/gdb/5.1.1/onlinedocs \
+ gdb
+@end smallexample
+
+@subheading Something about @file{ANNOUNCEMENT}
+
+Send the @file{ANNOUNCEMENT} file you created above to:
+
+@itemize @bullet
+@item
+@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
+@item
+The gnu announce list (but delay it a day or so to let things get out).
+@end itemize
+
+@subheading Install it on GNU
+
+At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in
+@file{~ftp/gnu/gdb} (I think, I'm still waiting for it to copy into my
+home directory).
+
+@section Cleanup
+
+@subheading Commit outstanding changes
+
+In particular you'll need to commit the changes to:
+
+@itemize @bullet
+@item
+@file{gdb/ChangeLog}
+@item
+@file{gdb/version.in}
+@item
+@file{gdb/NEWS}
+@item
+@file{gdb/README}
+@end itemize
+
+@subheading Tag the release
+
+Something like:
+
+@smallexample
+$ d=`date -u +%Y-%m-%d`
+$ echo $d
+2002-01-24
+$ ( cd insight/src/gdb && cvs -f -q update )
+$ ( cd insight/src && cvs -f -q tag gdb_5_1_1-$d-release )
+@end smallexample
+
+Insight is used since that contains more of the release than GDB (yes
+dejagnu doesn't get tagged but I think we can live with that.).
+
+@subheading Restart @file{gdb/version.in}
+
+If @file{gdb/version.in} does not contain an ISO date such as
+@kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having
+committed all the release changes it can be set to
+@file{5.1.0_0000-00-00-cvs} which will restart things (yes the @kbd{_}
+is important - it affects the snapshot process).
+
+Don't forget the @file{ChangeLog}.
+
+@subheading Merge into trunk
+
+The files committed to the branch may also need changes merged into the
+trunk.
+
+@section Post release
+
+Remove any @code{OBSOLETE} code.
+
@node Testsuite
@chapter Testsuite
and a mention of any unexpected passes or fails. When the testsuite is
finished, you'll get a summary that looks like this:
-@example
+@smallexample
=== gdb Summary ===
# of expected passes 6016
# of expected failures 183
# of unresolved testcases 3
# of untested testcases 5
-@end example
+@end smallexample
The ideal test run consists of expected passes only; however, reality
conspires to keep us from this ideal. Unexpected failures indicate
be for quite some time.
Please send patches directly to
-@email{gdb-patches@@sourceware.cygnus.com, the @value{GDBN} maintainers}.
+@email{gdb-patches@@sources.redhat.com, the @value{GDBN} maintainers}.
@section Obsolete Conditionals
@cindex obsolete code
Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
is so old that it has never been converted to use BFD. Now that's old!
-@item PYRAMID_CONTROL_FRAME_DEBUGGING
-pyr-xdep.c
-@item PYRAMID_CORE
-pyr-xdep.c
-@item PYRAMID_PTRACE
-pyr-xdep.c
-
-@item REG_STACK_SEGMENT
-exec.c
-
@end table
+@include fdl.texi
+
@node Index
@unnumbered Index
@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
projects / deliverable / binutils-gdb.git / blobdiff