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,
* 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.)
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
@item gdb/config/@var{arch}/@var{xyz}.mh
-Specifies Makefile fragments needed when hosting on machine @var{xyz}.
-Optionally specifies the header file which describes host @var{xyz}, by
-defining @code{XM_FILE= xm-@var{xyz}.h}. You can also define @code{CC},
+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.
+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
@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.
@end deftypefn
-@section Using Different Register and Memory Data Representations
-@cindex raw representation
-@cindex virtual representation
-@cindex representations, raw and virtual
-@cindex register data formats, converting
-@cindex @code{struct value}, converting register contents to
+@section Raw and Virtual Register Representations
+@cindex raw register representation
+@cindex virtual register representation
+@cindex representations, raw and virtual registers
-@emph{Maintainer's note: The way GDB manipulates registers is undergoing
-significant change. Many of the macros and functions refered to in the
-sections below are likely to be made obsolete. See the file @file{TODO}
-for more up-to-date information.}
+@emph{Maintainer note: This section is pretty much obsolete. The
+functionality described here has largely been replaced by
+pseudo-registers and the mechanisms described in @ref{Target
+Architecture Definition, , Using Different Register and Memory Data
+Representations}. See also @uref{http://www.gnu.org/software/gdb/bugs/,
+Bug Tracking Database} and
+@uref{http://sources.redhat.com/gdb/current/ari/, ARI Index} for more
+up-to-date information.}
Some architectures use one representation for a value when it lives in a
register, but use a different representation when it lives in memory.
the target registers, and the @dfn{virtual} representation is the one
used in memory, and within @value{GDBN} @code{struct value} objects.
+@emph{Maintainer note: Notice that the same mechanism is being used to
+both convert a register to a @code{struct value} and alternative
+register forms.}
+
For almost all data types on almost all architectures, the virtual and
raw representations are identical, and no special handling is needed.
However, they do occasionally differ. For example:
@end deftypefn
+@section Using Different Register and Memory Data Representations
+@cindex register representation
+@cindex memory representation
+@cindex representations, register and memory
+@cindex register data formats, converting
+@cindex @code{struct value}, converting register contents to
+
+@emph{Maintainer's note: The way GDB manipulates registers is undergoing
+significant change. Many of the macros and functions refered to in this
+section are likely to be subject to further revision. See
+@uref{http://sources.redhat.com/gdb/current/ari/, A.R. Index} and
+@uref{http://www.gnu.org/software/gdb/bugs, Bug Tracking Database} for
+further information. cagney/2002-05-06.}
+
+Some architectures can represent a data object in a register using a
+form that is different to the objects more normal memory representation.
+For example:
+
+@itemize @bullet
+
+@item
+The Alpha architecture can represent 32 bit integer values in
+floating-point registers.
+
+@item
+The x86 architecture supports 80-bit floating-point registers. The
+@code{long double} data type occupies 96 bits in memory but only 80 bits
+when stored in a register.
+
+@end itemize
+
+In general, the register representation of a data type is determined by
+the architecture, or @value{GDBN}'s interface to the architecture, while
+the memory representation is determined by the Application Binary
+Interface.
+
+For almost all data types on almost all architectures, the two
+representations are identical, and no special handling is needed.
+However, they do occasionally differ. Your architecture may define the
+following macros to request conversions between the register and memory
+representations of a data type:
+
+@deftypefn {Target Macro} int CONVERT_REGISTER_P (int @var{reg})
+Return non-zero if the representation of a data value stored in this
+register may be different to the representation of that same data value
+when stored in memory.
+
+When non-zero, the macros @code{REGISTER_TO_VALUE} and
+@code{VALUE_TO_REGISTER} are used to perform any necessary conversion.
+@end deftypefn
+
+@deftypefn {Target Macro} void REGISTER_TO_VALUE (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to})
+Convert the value of register number @var{reg} to a data object of type
+@var{type}. The buffer at @var{from} holds the register's value in raw
+format; the converted value should be placed in the buffer at @var{to}.
+
+Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take
+their @var{reg} and @var{type} arguments in different orders.
+
+You should only use @code{REGISTER_TO_VALUE} with registers for which
+the @code{CONVERT_REGISTER_P} macro returns a non-zero value.
+@end deftypefn
+
+@deftypefn {Target Macro} void VALUE_TO_REGISTER (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to})
+Convert a data value of type @var{type} to register number @var{reg}'
+raw format.
+
+Note that @code{REGISTER_TO_VALUE} and @code{VALUE_TO_REGISTER} take
+their @var{reg} and @var{type} arguments in different orders.
+
+You should only use @code{VALUE_TO_REGISTER} with registers for which
+the @code{CONVERT_REGISTER_P} macro returns a non-zero value.
+@end deftypefn
+
+@deftypefn {Target Macro} void REGISTER_CONVERT_TO_TYPE (int @var{regnum}, struct type *@var{type}, char *@var{buf})
+See @file{mips-tdep.c}. It does not do what you want.
+@end deftypefn
+
+
@section Frame Interpretation
@section Inferior Call Setup
@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
@code{default_coerce_float_to_double} provides this behavior; it is the
default value, for compatibility with older configurations.
+@item int CONVERT_REGISTER_P(@var{regnum})
+@findex CONVERT_REGISTER_P
+Return non-zero if register @var{regnum} can represent data values in a
+non-standard form.
+@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+
@item CPLUS_MARKER
@findex CPLUS_MARKERz
Define this to expand into the character that G@t{++} uses to distinguish
@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
-the window.
-
@item IBM6000_TARGET
@findex IBM6000_TARGET
Shows that we are configured for an IBM RS/6000 target. This
@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 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}
-indicates that the current function is a @code{sigtramp}.
-
@item SIGTRAMP_START (@var{pc})
@findex SIGTRAMP_START
@itemx SIGTRAMP_END (@var{pc})
@item REGISTER_CONVERTIBLE (@var{reg})
@findex REGISTER_CONVERTIBLE
Return non-zero if @var{reg} uses different raw and virtual formats.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
+
+@item REGISTER_TO_VALUE(@var{regnum}, @var{type}, @var{from}, @var{to})
+@findex REGISTER_TO_VALUE
+Convert the raw contents of register @var{regnum} into a value of type
+@var{type}.
@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
@item REGISTER_RAW_SIZE (@var{reg})
@findex REGISTER_RAW_SIZE
-Return the raw size of @var{reg}.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+Return the raw size of @var{reg}; defaults to the size of the register's
+virtual type.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item REGISTER_VIRTUAL_SIZE (@var{reg})
@findex REGISTER_VIRTUAL_SIZE
+Return the virtual size of @var{reg}; defaults to the size of the
+register's virtual type.
Return the virtual size of @var{reg}.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item REGISTER_VIRTUAL_TYPE (@var{reg})
@findex REGISTER_VIRTUAL_TYPE
Return the virtual type of @var{reg}.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to})
@findex REGISTER_CONVERT_TO_VIRTUAL
Convert the value of register @var{reg} from its raw form to its virtual
form.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item REGISTER_CONVERT_TO_RAW(@var{type}, @var{reg}, @var{from}, @var{to})
@findex REGISTER_CONVERT_TO_RAW
Convert the value of register @var{reg} from its virtual form to its raw
form.
-@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+@xref{Target Architecture Definition, , Raw and Virtual Register Representations}.
@item RETURN_VALUE_ON_STACK(@var{type})
@findex RETURN_VALUE_ON_STACK
@findex PC_IN_CALL_DUMMY
See @file{inferior.h}.
+@item PC_IN_SIGTRAMP (@var{pc}, @var{name})
+@findex PC_IN_SIGTRAMP
+@cindex sigtramp
+The @dfn{sigtramp} is a routine that the kernel calls (which then calls
+the signal handler). On most machines it is a library routine that is
+linked into the executable.
+
+This function, given a program counter value in @var{pc} and the
+(possibly NULL) name of the function in which that @var{pc} resides,
+returns nonzero if the @var{pc} and/or @var{name} show that we are in
+sigtramp.
+
@item PC_LOAD_SEGMENT
@findex PC_LOAD_SEGMENT
If defined, print information about the load segment for the program
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{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.
@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
for systems where GCC is known to use different calling convention than
other compilers.
+@item VALUE_TO_REGISTER(@var{type}, @var{regnum}, @var{from}, @var{to})
+@findex VALUE_TO_REGISTER
+Convert a value of type @var{type} into the raw contents of register
+@var{regnum}'s.
+@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
+
@item VARIABLES_INSIDE_BLOCK (@var{desc}, @var{gcc_p})
@findex VARIABLES_INSIDE_BLOCK
For dbx-style debugging information, if the compiler puts variable
@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
later cleanups appended to the chain (but not yet discarded or
performed). E.g.:
-@example
+@smallexample
make_cleanup (a, 0);
@{
struct cleanup *old = make_cleanup (b, 0);
...
do_cleanups (old);
@}
-@end example
+@end smallexample
@noindent
will call @code{c()} and @code{b()} but will not call @code{a()}. The
called and a forced stack unwind occurs) by ensuring that the
@code{xfree} will always be called:
-@example
+@smallexample
struct cleanup *old = make_cleanup (null_cleanup, 0);
data = xmalloc (sizeof blah);
make_cleanup (xfree, data);
... blah blah ...
do_cleanups (old);
-@end example
+@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
code segment, ensures that the file will be closed but only if there is
an error:
-@example
+@smallexample
FILE *file = fopen ("afile", "r");
struct cleanup *old = make_cleanup (close_file, file);
... blah blah ...
discard_cleanups (old);
return file;
-@end example
+@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
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 Before the branch
+@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
-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.
+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:
-@subheading Obsolete any code
+@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.}
-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.
+
+@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
+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
-post / commit the change
+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:
@item
@file{texinfo/texinfo.tex}
@item
-@file{config.guess} et.@: al.@:
+@file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS}
+file)
+@item
+@file{etc/standards.texi}, @file{etc/make-stds.texi}
@end itemize
-and should be refreshed.
+@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
-@subheading Organize and announce the schedule.
+Close anything obviously fixed.
-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.
+@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
-announce it
-@item
-wait a week
-@item
-announce branch date
-@item
-wait a week
-@item
-Cut the branch
+the @kbd{-D YYYY-MM-DD-gmt} forces the branch to an exact date/time.
@item
-wait a week
+the trunk is first tagged so that the branch point can easily be found
@item
-start enjoying all the fun
+Insight (which includes GDB) and dejagnu are tagged at the same time
@end itemize
-As an aside, the branch tag name is probably regrettable vis:
-@file{gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}}.
+@subheading Post the branch info
+@subheading Update the web and news pages
-@section Building a Release
+@subheading Tweak cron to track the new branch
-@subheading Establish a few defaults.
+@section Stabilize the branch
-@example
-$ b=gdb_5_1_0_1-2002-01-03-branch
-$ v=5.1.0.1
-$ cd /sourceware/snapshot-tmp/gdbadmin-tmp/$b
+Something goes here.
+
+@section Create a Release
+
+The process of creating and then making available a release is broken
+down into a number of stages. The first part addresses the technical
+process of creating a releasable tar ball. The later stages address the
+process of releasing that tar ball.
+
+When making a release candidate just the first section is needed.
+
+@subsection Create a release candidate
+
+The objective at this stage is to create a set of tar balls that can be
+made available as a formal release (or as a less formal release
+candidate).
+
+@subsubheading Freeze the branch
+
+Send out an e-mail notifying everyone that the branch is frozen to
+@email{gdb-patches@@sources.redhat.com}.
+
+@subsubheading Establish a few defaults.
+
+@smallexample
+$ b=gdb_5_2-branch
+$ v=5.2
+$ t=/sourceware/snapshot-tmp/gdbadmin-tmp
+$ echo $t/$b/$v
+/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
+$ mkdir -p $t/$b/$v
+$ cd $t/$b/$v
+$ pwd
+/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
$ which autoconf
/home/gdbadmin/bin/autoconf
-@end example
+$
+@end smallexample
-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.
+@noindent
+Notes:
-@subheading Check out the relevant modules:
+@itemize @bullet
+@item
+Check the @code{autoconf} version carefully. You want to be using the
+version taken from the @file{binutils} snapshot directory. It is very
+unlikely that a system installed version of @code{autoconf} (e.g.,
+@file{/usr/bin/autoconf}) is correct.
+@end itemize
-@example
-$ for m in gdb insight dejagnu; do
+@subsubheading 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 example
+$
+@end smallexample
+
+@noindent
+Note:
+
+@itemize @bullet
+@item
+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
+@code{cvs} really does.
+@end itemize
+
+@subsubheading Update relevant files.
+
+@table @file
+
+@item 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 include the @file{ChangeLog} entry.
+
+@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
+
+@item gdb/README
-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.
+You'll need to update:
+
+@itemize @bullet
+@item
+the version
+@item
+the update date
+@item
+who did it
+@end itemize
-@subheading Update the file @file{gdb/version.in} where applicable.
+@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
-@example
-$ for m in gdb insight; do echo $v > $m/src/gdb/version.in ; done
-@end example
+@emph{Maintainer note: Hopefully the @file{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.}
-@subheading Mutter something about creating a @file{ChangeLog} entry. (both trunk and branch).
+@item gdb/version.in
-@example
+@smallexample
+$ echo $v > gdb/src/gdb/version.in
+$ cat gdb/src/gdb/version.in
+5.2
$ emacs gdb/src/gdb/version.in
+...
c-x 4 a
-Bump version to 5.1.0.1.
+... Bump to version ...
c-x c-s c-x c-c
-@end example
+$ cp gdb/src/gdb/version.in insight/src/gdb/version.in
+$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
+@end smallexample
-ditto for @file{insight/src/gdb/version.in}
+@item dejagnu/src/dejagnu/configure.in
-@subheading Mutter something about updating @file{README}
+Dejagnu is more complicated. The version number is a parameter to
+@code{AM_INIT_AUTOMAKE}. Tweak it to read something like gdb-5.1.91.
-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}.
+Don't forget to re-generate @file{configure}.
-@example
+Don't forget to include a @file{ChangeLog} entry.
+
+@smallexample
$ 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
+$ ( cd dejagnu/src/dejagnu && autoconf )
+@end smallexample
-@subheading Build the snapshot:
+@end table
-@example
-$ for m in gdb insight dejagnu; do
-( cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
-done
-@end example
+@subsubheading Do the dirty work
-@subheading Do another @kbd{CVS update} to see what the damage is.
+This is identical to the process used to create the daily snapshot.
-@example
-$ ( cd gdb/src && cvs -q update )
-@end example
+@smallexample
+$ for m in gdb insight
+do
+( cd $m/src && gmake -f Makefile.in $m.tar )
+done
+$ ( m=dejagnu; cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+@end smallexample
-You're looking for files that have mysteriously disappeared as the
+@subsubheading Check the source files
+
+You're looking for files that have mysteriously disappeared.
@kbd{distclean} has the habit of deleting files it shouldn't. Watch out
-for the @file{version.in} update cronjob.
+for the @file{version.in} update @kbd{cronjob}.
-@subheading Copy all the @file{.bz2} files to the ftp directory:
+@smallexample
+$ ( cd gdb/src && cvs -f -q -n update )
+M djunpack.bat
+? gdb-5.1.91.tar
+? proto-toplev
+@dots{} lots of generated files @dots{}
+M gdb/ChangeLog
+M gdb/NEWS
+M gdb/README
+M gdb/version.in
+@dots{} lots of generated files @dots{}
+$
+@end smallexample
-@example
-cp */src/*.bz2 ~ftp/.....
-@end example
+@noindent
+@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 Something about @kbd{gzip}'ing them.
+@subsubheading Create compressed versions of the release
-@subheading Something about web pages?
+@smallexample
+$ cp */src/*.tar .
+$ cp */src/*.bz2 .
+$ ls -F
+dejagnu/ dejagnu-gdb-5.2.tar.bz2 gdb/ gdb-5.2.tar insight/ insight-5.2.tar
+$ for m in gdb insight
+do
+bzip2 -v -9 -c $m-$v.tar > $m-$v.tar.bz2
+gzip -v -9 -c $m-$v.tar > $m-$v.tar.gz
+done
+$
+@end smallexample
-@subheading Something about documentation?
+@noindent
+Note:
-@subheading Cleanup the release tree
+@itemize @bullet
+@item
+A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} is not since,
+in that mode, @code{gzip} does not know the name of the file and, hence,
+can not include it in the compressed file. This is also why the release
+process runs @code{tar} and @code{bzip2} as separate passes.
+@end itemize
+
+@subsection Sanity check the tar ball
-In particular you'll need to:
+Pick a popular machine (Solaris/PPC?) and try the build on that.
+
+@smallexample
+$ bunzip2 < gdb-5.2.tar.bz2 | tar xpf -
+$ cd gdb-5.2
+$ ./configure
+$ make
+@dots{}
+$ ./gdb/gdb ./gdb/gdb
+GNU gdb 5.2
+@dots{}
+(gdb) b main
+Breakpoint 1 at 0x80732bc: file main.c, line 734.
+(gdb) run
+Starting program: /tmp/gdb-5.2/gdb/gdb
+
+Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734
+734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL);
+(gdb) print args
+$1 = @{argc = 136426532, argv = 0x821b7f0@}
+(gdb)
+@end smallexample
+@subsection Make a release candidate available
+
+If this is a release candidate then the only remaining steps are:
+
+@enumerate
+@item
+Commit @file{version.in} and @file{ChangeLog}
+@item
+Tweak @file{version.in} (and @file{ChangeLog} to read
+@var{L}.@var{M}.@var{N}-0000-00-00-cvs so that the version update
+process can restart.
+@item
+Make the release candidate available in
+@uref{ftp://sources.redhat.com/pub/gdb/snapshots/branch}
+@item
+Notify the relevant mailing lists ( @email{gdb@@sources.redhat.com} and
+@email{gdb-testers@@sources.redhat.com} that the candidate is available.
+@end enumerate
+
+@subsection Make a formal release available
+
+(And you thought all that was required was to post an e-mail.)
+
+@subsubheading Install on sware
+
+Copy the new files to both the release and the old release directory:
+
+@smallexample
+$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
+$ cp *.bz2 *.gz ~ftp/pub/gdb/releases
+@end smallexample
+
+@noindent
+Clean up the releases directory so that only the most recent releases
+are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):
+
+@smallexample
+$ cd ~ftp/pub/gdb/releases
+$ rm @dots{}
+@end smallexample
+
+@noindent
+Update the file @file{README} and @file{.message} in the releases
+directory:
+
+@smallexample
+$ vi README
+@dots{}
+$ rm -f .message
+$ ln README .message
+@end smallexample
+
+@subsubheading Update the web pages.
+
+@table @file
+
+@item htdocs/download/ANNOUNCEMENT
+This file, which is posted as the official announcement, includes:
@itemize @bullet
@item
-Commit the changes to @file{ChangeLog} and @file{version.in}
+General announcement
@item
-Tag the repository.
+News. If making an @var{M}.@var{N}.1 release, retain the news from
+earlier @var{M}.@var{N} release.
+@item
+Errata
+@end itemize
+
+@item htdocs/index.html
+@itemx htdocs/news/index.html
+@itemx htdocs/download/index.html
+These files include:
+@itemize @bullet
+@item
+announcement of the most recent release
+@item
+news entry (remember to update both the top level and the news directory).
@end itemize
+These pages also need to be regenerate using @code{index.sh}.
+@item download/onlinedocs/
+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 @code{cron} jobs and then just edit accordingly.
+Something like:
-@section After the release
+@smallexample
+$ ~/ss/update-web-docs \
+ ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
+ $PWD/www \
+ /www/sourceware/htdocs/gdb/download/onlinedocs \
+ gdb
+@end smallexample
+
+@item download/ari/
+Just like the online documentation. Something like:
-Remove any @kbd{OBSOLETE} code.
+@smallexample
+$ /bin/sh ~/ss/update-web-ari \
+ ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
+ $PWD/www \
+ /www/sourceware/htdocs/gdb/download/ari \
+ gdb
+@end smallexample
+@end table
+
+@subsubheading Shadow the pages onto gnu
+
+Something goes here.
+
+
+@subsubheading Install the @value{GDBN} tar ball on GNU
+
+At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in
+@file{~ftp/gnu/gdb}.
+
+@subsubheading Make the @file{ANNOUNCEMENT}
+
+Post the @file{ANNOUNCEMENT} file you created above to:
+
+@itemize @bullet
+@item
+@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
+@item
+@email{info-gnu@@gnu.org, General GNU Announcement list} (but delay it a
+day or so to let things get out)
+@item
+@email{bug-gdb@@gnu.org, GDB Bug Report mailing list}
+@end itemize
+
+@subsection Cleanup
+
+The release is out but you're still not finished.
+
+@subsubheading Commit outstanding changes
+
+In particular you'll need to commit any changes to:
+
+@itemize @bullet
+@item
+@file{gdb/ChangeLog}
+@item
+@file{gdb/version.in}
+@item
+@file{gdb/NEWS}
+@item
+@file{gdb/README}
+@end itemize
+
+@subsubheading 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_2-$d-release )
+@end smallexample
+
+Insight is used since that contains more of the release than
+@value{GDBN} (@code{dejagnu} doesn't get tagged but I think we can live
+with that).
+
+@subsubheading Mention the release on the trunk
+
+Just put something in the @file{ChangeLog} so that the trunk also
+indicates when the release was made.
+
+@subsubheading 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.2.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}.
+
+@subsubheading Merge into trunk
+
+The files committed to the branch may also need changes merged into the
+trunk.
+
+@subsubheading Revise the release schedule
+
+Post a revised release schedule to @email{gdb@@sources.redhat.com, GDB
+Discussion List} with an updated announcement. The schedule can be
+generated by running:
+
+@smallexample
+$ ~/ss/schedule `date +%s` schedule
+@end smallexample
+
+@noindent
+The first parameter is approximate date/time in seconds (from the epoch)
+of the most recent release.
+
+Also update the schedule @code{cronjob}.
+
+@section Post release
+
+Remove any @code{OBSOLETE} code.
@node 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