@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001
+Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001, 2002
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
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
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.
place to add commands is in the @code{_initialize_@var{xyz}} routines at
the ends of most source files.
+@findex add_setshow_cmd
+@findex add_setshow_cmd_full
+To add paired @samp{set} and @samp{show} commands, use
+@code{add_setshow_cmd} or @code{add_setshow_cmd_full}. The former is
+a slightly simpler interface which is useful when you don't need to
+further modify the new command structures, while the latter returns
+the new command structures for manipulation.
+
@cindex deprecating commands
@findex deprecate_cmd
Before removing commands from the command set it is a good idea to
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:
This function first opens the tuple and then establishes a cleanup
(@pxref{Coding, Cleanups}) to close the tuple. It provides a convenient
and correct implementation of the non-portable@footnote{The function
-cast is not portable ISO-C.} code sequence:
+cast is not portable ISO C.} code sequence:
@smallexample
struct cleanup *old_cleanup;
ui_out_tuple_begin (uiout, "...");
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
DWARF 1 is a debugging format that was originally designed to be
used with ELF in SVR4 systems.
-@c CHILL_PRODUCER
+@c OBSOLETE CHILL_PRODUCER
@c GCC_PRODUCER
@c GPLUS_PRODUCER
@c LCC_PRODUCER
@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
@code{struct gdbarch *}. The structure, and its methods, are generated
using the Bourne shell script @file{gdbarch.sh}.
+@section Operating System ABI Variant Handling
+@cindex OS ABI variants
+
+@value{GDBN} provides a mechanism for handling variations in OS
+ABIs. An OS ABI variant may have influence over any number of
+variables in the target architecture definition. There are two major
+components in the OS ABI mechanism: sniffers and handlers.
+
+A @dfn{sniffer} examines a file matching a BFD architecture/flavour pair
+(the architecture may be wildcarded) in an attempt to determine the
+OS ABI of that file. Sniffers with a wildcarded architecture are considered
+to be @dfn{generic}, while sniffers for a specific architecture are
+considered to be @dfn{specific}. A match from a specific sniffer
+overrides a match from a generic sniffer. Multiple sniffers for an
+architecture/flavour may exist, in order to differentiate between two
+different operating systems which use the same basic file format. The
+OS ABI framework provides a generic sniffer for ELF-format files which
+examines the @code{EI_OSABI} field of the ELF header, as well as note
+sections known to be used by several operating systems.
+
+@cindex fine-tuning @code{gdbarch} structure
+A @dfn{handler} is used to fine-tune the @code{gdbarch} structure for the
+selected OS ABI. There may be only one handler for a given OS ABI
+for each BFD architecture.
+
+The following OS ABI variants are defined in @file{osabi.h}:
+
+@table @code
+
+@findex GDB_OSABI_UNKNOWN
+@item GDB_OSABI_UNKNOWN
+The ABI of the inferior is unknown. The default @code{gdbarch}
+settings for the architecture will be used.
+
+@findex GDB_OSABI_SVR4
+@item GDB_OSABI_SVR4
+UNIX System V Release 4
+
+@findex GDB_OSABI_HURD
+@item GDB_OSABI_HURD
+GNU using the Hurd kernel
+
+@findex GDB_OSABI_SOLARIS
+@item GDB_OSABI_SOLARIS
+Sun Solaris
+
+@findex GDB_OSABI_OSF1
+@item GDB_OSABI_OSF1
+OSF/1, including Digital UNIX and Compaq Tru64 UNIX
+
+@findex GDB_OSABI_LINUX
+@item GDB_OSABI_LINUX
+GNU using the Linux kernel
+
+@findex GDB_OSABI_FREEBSD_AOUT
+@item GDB_OSABI_FREEBSD_AOUT
+FreeBSD using the a.out executable format
+
+@findex GDB_OSABI_FREEBSD_ELF
+@item GDB_OSABI_FREEBSD_ELF
+FreeBSD using the ELF executable format
+
+@findex GDB_OSABI_NETBSD_AOUT
+@item GDB_OSABI_NETBSD_AOUT
+NetBSD using the a.out executable format
+
+@findex GDB_OSABI_NETBSD_ELF
+@item GDB_OSABI_NETBSD_ELF
+NetBSD using the ELF executable format
+
+@findex GDB_OSABI_WINCE
+@item GDB_OSABI_WINCE
+Windows CE
+
+@findex GDB_OSABI_GO32
+@item GDB_OSABI_GO32
+DJGPP
+
+@findex GDB_OSABI_NETWARE
+@item GDB_OSABI_NETWARE
+Novell NetWare
+
+@findex GDB_OSABI_ARM_EABI_V1
+@item GDB_OSABI_ARM_EABI_V1
+ARM Embedded ABI version 1
+
+@findex GDB_OSABI_ARM_EABI_V2
+@item GDB_OSABI_ARM_EABI_V2
+ARM Embedded ABI version 2
+
+@findex GDB_OSABI_ARM_APCS
+@item GDB_OSABI_ARM_APCS
+Generic ARM Procedure Call Standard
+
+@end table
+
+Here are the functions that make up the OS ABI framework:
+
+@deftypefun const char *gdbarch_osabi_name (enum gdb_osabi @var{osabi})
+Return the name of the OS ABI corresponding to @var{osabi}.
+@end deftypefun
+
+@deftypefun void gdbarch_register_osabi (enum bfd_architecture @var{arch}, enum gdb_osabi @var{osabi}, void (*@var{init_osabi})(struct gdbarch_info @var{info}, struct gdbarch *@var{gdbarch}))
+Register the OS ABI handler specified by @var{init_osabi} for the
+architecture/OS ABI pair specified by @var{arch} and @var{osabi}.
+@end deftypefun
+
+@deftypefun void gdbarch_register_osabi_sniffer (enum bfd_architecture @var{arch}, enum bfd_flavour @var{flavour}, enum gdb_osabi (*@var{sniffer})(bfd *@var{abfd}))
+Register the OS ABI file sniffer specified by @var{sniffer} for the
+BFD architecture/flavour pair specified by @var{arch} and @var{flavour}.
+If @var{arch} is @code{bfd_arch_unknown}, the sniffer is considered to
+be generic, and is allowed to examine @var{flavour}-flavoured files for
+any architecture.
+@end deftypefun
+
+@deftypefun enum gdb_osabi gdbarch_lookup_osabi (bfd *@var{abfd})
+Examine the file described by @var{abfd} to determine its OS ABI.
+The value @code{GDB_OSABI_UNKNOWN} is returned if the OS ABI cannot
+be determined.
+@end deftypefun
+
+@deftypefun void gdbarch_init_osabi (struct gdbarch info @var{info}, struct gdbarch *@var{gdbarch}, enum gdb_osabi @var{osabi})
+Invoke the OS ABI handler corresponding to @var{osabi} to fine-tune the
+@code{gdbarch} structure specified by @var{gdbarch}. If a handler
+corresponding to @var{osabi} has not been registered for @var{gdbarch}'s
+architecture, a warning will be issued and the debugging session will continue
+with the defaults already established for @var{gdbarch}.
+@end deftypefun
+
@section Registers and Memory
@value{GDBN}'s model of the target machine is rather simple.
@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
@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
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
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
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
@findex NPC_REGNUM
The number of the ``next program counter'' register, if defined.
-@item NNPC_REGNUM
-@findex NNPC_REGNUM
-The number of the ``next next program counter'' register, if defined.
-Currently, this is only defined for the Motorola 88K.
-
@item PARM_BOUNDARY
@findex PARM_BOUNDARY
If non-zero, round arguments to a boundary of this many bits before
Define this to convert sdb register numbers into @value{GDBN} regnums. If not
defined, no conversion will be done.
-@item SHIFT_INST_REGS
-@findex SHIFT_INST_REGS
-(Only used for m88k targets.)
+@c OBSOLETE @item SHIFT_INST_REGS
+@c OBSOLETE @findex SHIFT_INST_REGS
+@c OBSOLETE (Only used for m88k targets.)
@item SKIP_PERMANENT_BREAKPOINT
@findex SKIP_PERMANENT_BREAKPOINT
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
@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
@file{config/tm-@var{os}.h}.
+@section Converting an existing Target Architecture to Multi-arch
+@cindex converting targets to multi-arch
+
+This section describes the current accepted best practice for converting
+an existing target architecture to the multi-arch framework.
+
+The process consists of generating, testing, posting and committing a
+sequence of patches. Each patch must contain a single change, for
+instance:
+
+@itemize @bullet
+
+@item
+Directly convert a group of functions into macros (the conversion does
+not change the behavior of any of the functions).
+
+@item
+Replace a non-multi-arch with a multi-arch mechanism (e.g.,
+@code{FRAME_INFO}).
+
+@item
+Enable multi-arch level one.
+
+@item
+Delete one or more files.
+
+@end itemize
+
+@noindent
+There isn't a size limit on a patch, however, a developer is strongly
+encouraged to keep the patch size down.
+
+Since each patch is well defined, and since each change has been tested
+and shows no regressions, the patches are considered @emph{fairly}
+obvious. Such patches, when submitted by developers listed in the
+@file{MAINTAINERS} file, do not need approval. Occasional steps in the
+process may be more complicated and less clear. The developer is
+expected to use their judgment and is encouraged to seek advice as
+needed.
+
+@subsection Preparation
+
+The first step is to establish control. Build (with @option{-Werror}
+enabled) and test the target so that there is a baseline against which
+the debugger can be compared.
+
+At no stage can the test results regress or @value{GDBN} stop compiling
+with @option{-Werror}.
+
+@subsection Add the multi-arch initialization code
+
+The objective of this step is to establish the basic multi-arch
+framework. It involves
+
+@itemize @bullet
+
+@item
+The addition of a @code{@var{arch}_gdbarch_init} function@footnote{The
+above is from the original example and uses K&R C. @value{GDBN}
+has since converted to ISO C but lets ignore that.} that creates
+the architecture:
+@smallexample
+static struct gdbarch *
+d10v_gdbarch_init (info, arches)
+ struct gdbarch_info info;
+ struct gdbarch_list *arches;
+@{
+ struct gdbarch *gdbarch;
+ /* there is only one d10v architecture */
+ if (arches != NULL)
+ return arches->gdbarch;
+ gdbarch = gdbarch_alloc (&info, NULL);
+ return gdbarch;
+@}
+@end smallexample
+@noindent
+@emph{}
+
+@item
+A per-architecture dump function to print any architecture specific
+information:
+@smallexample
+static void
+mips_dump_tdep (struct gdbarch *current_gdbarch,
+ struct ui_file *file)
+@{
+ @dots{} code to print architecture specific info @dots{}
+@}
+@end smallexample
+
+@item
+A change to @code{_initialize_@var{arch}_tdep} to register this new
+architecture:
+@smallexample
+void
+_initialize_mips_tdep (void)
+@{
+ gdbarch_register (bfd_arch_mips, mips_gdbarch_init,
+ mips_dump_tdep);
+@end smallexample
+
+@item
+Add the macro @code{GDB_MULTI_ARCH}, defined as 0 (zero), to the file@*
+@file{config/@var{arch}/tm-@var{arch}.h}.
+
+@end itemize
+
+@subsection Update multi-arch incompatible mechanisms
+
+Some mechanisms do not work with multi-arch. They include:
+
+@table @code
+@item EXTRA_FRAME_INFO
+Delete.
+@item FRAME_FIND_SAVED_REGS
+Replaced with @code{FRAME_INIT_SAVED_REGS}
+@end table
+
+@noindent
+At this stage you could also consider converting the macros into
+functions.
+
+@subsection Prepare for multi-arch level to one
+
+Temporally set @code{GDB_MULTI_ARCH} to @code{GDB_MULTI_ARCH_PARTIAL}
+and then build and start @value{GDBN} (the change should not be
+committed). @value{GDBN} may not build, and once built, it may die with
+an internal error listing the architecture methods that must be
+provided.
+
+Fix any build problems (patch(es)).
+
+Convert all the architecture methods listed, which are only macros, into
+functions (patch(es)).
+
+Update @code{@var{arch}_gdbarch_init} to set all the missing
+architecture methods and wrap the corresponding macros in @code{#if
+!GDB_MULTI_ARCH} (patch(es)).
+
+@subsection Set multi-arch level one
+
+Change the value of @code{GDB_MULTI_ARCH} to GDB_MULTI_ARCH_PARTIAL (a
+single patch).
+
+Any problems with throwing ``the switch'' should have been fixed
+already.
+
+@subsection Convert remaining macros
+
+Suggest converting macros into functions (and setting the corresponding
+architecture method) in small batches.
+
+@subsection Set multi-arch level to two
+
+This should go smoothly.
+
+@subsection Delete the TM file
+
+The @file{tm-@var{arch}.h} can be deleted. @file{@var{arch}.mt} and
+@file{configure.in} updated.
+
+
@node Target Vector Definition
@chapter Target Vector Definition
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
functions, since they might never return to your code (they
@samp{longjmp} instead).
-@section Wrapping Output Lines
-@cindex line wrap in output
+@section Per-architecture module data
+@cindex per-architecture module data
+@cindex multi-arch data
+@cindex data-pointer, per-architecture/per-module
-@findex wrap_here
-Output that goes through @code{printf_filtered} or @code{fputs_filtered}
-or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
-added in places that would be good breaking points. The utility
-routines will take care of actually wrapping if the line width is
-exceeded.
+The multi-arch framework includes a mechanism for adding module specific
+per-architecture data-pointers to the @code{struct gdbarch} architecture
+object.
-The argument to @code{wrap_here} is an indentation string which is
-printed @emph{only} if the line breaks there. This argument is saved
-away and used later. It must remain valid until the next call to
-@code{wrap_here} or until a newline has been printed through the
-@code{*_filtered} functions. Don't pass in a local variable and then
-return!
+A module registers one or more per-architecture data-pointers using the
+function @code{register_gdbarch_data}:
-It is usually best to call @code{wrap_here} after printing a comma or
-space. If you call it before printing a space, make sure that your
-indentation properly accounts for the leading space that will print if
-the line wraps there.
+@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free})
-Any function or set of functions that produce filtered output must
-finish by printing a newline, to flush the wrap buffer, before switching
-to unfiltered (@code{printf}) output. Symbol reading routines that
-print warnings are a good example.
+The @var{init} function is used to obtain an initial value for a
+per-architecture data-pointer. The function is called, after the
+architecture has been created, when the data-pointer is still
+uninitialized (@code{NULL}) and its value has been requested via a call
+to @code{gdbarch_data}. A data-pointer can also be initialize
+explicitly using @code{set_gdbarch_data}.
-@section @value{GDBN} Coding Standards
-@cindex coding standards
+The @var{free} function is called when a data-pointer needs to be
+destroyed. This occurs when either the corresponding @code{struct
+gdbarch} object is being destroyed or when @code{set_gdbarch_data} is
+overriding a non-@code{NULL} data-pointer value.
-@value{GDBN} follows the GNU coding standards, as described in
-@file{etc/standards.texi}. This file is also available for anonymous
-FTP from GNU archive sites. @value{GDBN} takes a strict interpretation
-of the standard; in general, when the GNU standard recommends a practice
-but does not require it, @value{GDBN} requires it.
+The function @code{register_gdbarch_data} returns a @code{struct
+gdbarch_data} that is used to identify the data-pointer that was added
+to the module.
-@value{GDBN} follows an additional set of coding standards specific to
-@value{GDBN}, as described in the following sections.
+@end deftypefun
+A typical module has @code{init} and @code{free} functions of the form:
-@subsection ISO-C
+@smallexample
+static struct gdbarch_data *nozel_handle;
+static void *
+nozel_init (struct gdbarch *gdbarch)
+@{
+ struct nozel *data = XMALLOC (struct nozel);
+ @dots{}
+ return data;
+@}
+@dots{}
+static void
+nozel_free (struct gdbarch *gdbarch, void *data)
+@{
+ xfree (data);
+@}
+@end smallexample
-@value{GDBN} assumes an ISO-C compliant compiler.
+Since uninitialized (@code{NULL}) data-pointers are initialized
+on-demand, an @code{init} function is free to call other modules that
+use data-pointers. Those modules data-pointers will be initialized as
+needed. Care should be taken to ensure that the @code{init} call graph
+does not contain cycles.
-@value{GDBN} does not assume an ISO-C or POSIX compliant C library.
+The data-pointer is registered with the call:
+@smallexample
+void
+_initialize_nozel (void)
+@{
+ nozel_handle = register_gdbarch_data (nozel_init, nozel_free);
+@dots{}
+@end smallexample
-@subsection Memory Management
+The per-architecture data-pointer is accessed using the function:
-@value{GDBN} does not use the functions @code{malloc}, @code{realloc},
-@code{calloc}, @code{free} and @code{asprintf}.
+@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle})
+Given the architecture @var{arch} and module data handle
+@var{data_handle} (returned by @code{register_gdbarch_data}, this
+function returns the current value of the per-architecture data-pointer.
+@end deftypefun
-@value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and
-@code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@:
-these functions do not return when the memory pool is empty. Instead,
-they unwind the stack using cleanups. These functions return
-@code{NULL} when requested to allocate a chunk of memory of size zero.
+The non-@code{NULL} data-pointer returned by @code{gdbarch_data} should
+be saved in a local variable and then used directly:
-@emph{Pragmatics: By using these functions, the need to check every
-memory allocation is removed. These functions provide portable
+@smallexample
+int
+nozel_total (struct gdbarch *gdbarch)
+@{
+ int total;
+ struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
+ @dots{}
+ return total;
+@}
+@end smallexample
+
+It is also possible to directly initialize the data-pointer using:
+
+@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer})
+Update the data-pointer corresponding to @var{handle} with the value of
+@var{pointer}. If the previous data-pointer value is non-NULL, then it
+is freed using data-pointers @var{free} function.
+@end deftypefun
+
+This function is used by modules that require a mechanism for explicitly
+setting the per-architecture data-pointer during architecture creation:
+
+@smallexample
+/* Called during architecture creation. */
+extern void
+set_gdbarch_nozel (struct gdbarch *gdbarch,
+ int total)
+@{
+ struct nozel *data = XMALLOC (struct nozel);
+ @dots{}
+ set_gdbarch_data (gdbarch, nozel_handle, nozel);
+@}
+@end smallexample
+
+@smallexample
+/* Default, called when nozel not set by set_gdbarch_nozel(). */
+static void *
+nozel_init (struct gdbarch *gdbarch)
+@{
+ struct nozel *default_nozel = XMALLOC (struc nozel);
+ @dots{}
+ return default_nozel;
+@}
+@end smallexample
+
+@smallexample
+void
+_initialize_nozel (void)
+@{
+ nozel_handle = register_gdbarch_data (nozel_init, NULL);
+ @dots{}
+@end smallexample
+
+@noindent
+Note that an @code{init} function still needs to be registered. It is
+used to initialize the data-pointer when the architecture creation phase
+fail to set an initial value.
+
+
+@section Wrapping Output Lines
+@cindex line wrap in output
+
+@findex wrap_here
+Output that goes through @code{printf_filtered} or @code{fputs_filtered}
+or @code{fputs_demangled} needs only to have calls to @code{wrap_here}
+added in places that would be good breaking points. The utility
+routines will take care of actually wrapping if the line width is
+exceeded.
+
+The argument to @code{wrap_here} is an indentation string which is
+printed @emph{only} if the line breaks there. This argument is saved
+away and used later. It must remain valid until the next call to
+@code{wrap_here} or until a newline has been printed through the
+@code{*_filtered} functions. Don't pass in a local variable and then
+return!
+
+It is usually best to call @code{wrap_here} after printing a comma or
+space. If you call it before printing a space, make sure that your
+indentation properly accounts for the leading space that will print if
+the line wraps there.
+
+Any function or set of functions that produce filtered output must
+finish by printing a newline, to flush the wrap buffer, before switching
+to unfiltered (@code{printf}) output. Symbol reading routines that
+print warnings are a good example.
+
+@section @value{GDBN} Coding Standards
+@cindex coding standards
+
+@value{GDBN} follows the GNU coding standards, as described in
+@file{etc/standards.texi}. This file is also available for anonymous
+FTP from GNU archive sites. @value{GDBN} takes a strict interpretation
+of the standard; in general, when the GNU standard recommends a practice
+but does not require it, @value{GDBN} requires it.
+
+@value{GDBN} follows an additional set of coding standards specific to
+@value{GDBN}, as described in the following sections.
+
+
+@subsection ISO C
+
+@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant
+compiler.
+
+@value{GDBN} does not assume an ISO C or POSIX compliant C library.
+
+
+@subsection Memory Management
+
+@value{GDBN} does not use the functions @code{malloc}, @code{realloc},
+@code{calloc}, @code{free} and @code{asprintf}.
+
+@value{GDBN} uses the functions @code{xmalloc}, @code{xrealloc} and
+@code{xcalloc} when allocating memory. Unlike @code{malloc} et.al.@:
+these functions do not return when the memory pool is empty. Instead,
+they unwind the stack using cleanups. These functions return
+@code{NULL} when requested to allocate a chunk of memory of size zero.
+
+@emph{Pragmatics: By using these functions, the need to check every
+memory allocation is removed. These functions provide portable
behavior.}
@value{GDBN} does not use the function @code{free}.
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.)
@subsection Include Files
-All @file{.c} files should include @file{defs.h} first.
+A @file{.c} file should include @file{defs.h} first.
+
+A @file{.c} file should directly include the @code{.h} file of every
+declaration and/or definition it directly refers to. It cannot rely on
+indirect inclusion.
+
+A @file{.h} file should directly include the @code{.h} file of every
+declaration and/or definition it directly refers to. It cannot rely on
+indirect inclusion. Exception: The file @file{defs.h} does not need to
+be directly included.
-All @file{.c} files should explicitly include the headers for any
-declarations they refer to. They should not rely on files being
-included indirectly.
+An external declaration should only appear in one include file.
-With the exception of the global definitions supplied by @file{defs.h},
-a header file should explicitly include the header declaring any
-@code{typedefs} et.al.@: it refers to.
+An external declaration should never appear in a @code{.c} file.
+Exception: a declaration for the @code{_initialize} function that
+pacifies @option{-Wmissing-declaration}.
-@code{extern} declarations should never appear in @code{.c} files.
+A @code{typedef} definition should only appear in one include file.
-All include files should be wrapped in:
+An opaque @code{struct} declaration can appear in multiple @file{.h}
+files. Where possible, a @file{.h} file should use an opaque
+@code{struct} declaration instead of an include.
-@example
+All @file{.h} files should be wrapped in:
+
+@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}}
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 Obsolete any code
+@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
-Before anything else, poke the other developers (and around the source
-code) to see there is anything that can be removed from @value{GDBN} (an
-old target, an unused file).
+Notes:
-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.
+@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.
-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.
+
+@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
-announce the change on @email{gdb@@sources.redhat.com, GDB mailing list}
+The @file{gdb/MAINTAINERS} file still holds.
@item
-wait a week or so
+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
-announce the change on @email{gdb-announce@@sources.redhat.com, GDB
-Announcement mailing list}
+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
-wait a week or so
+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
-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}.
+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{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.}
+@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 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.
+@section Obsoleting code
-@subheading Organize and announce the schedule.
+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).
-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.
+Obsolete code is identified by adding an @code{OBSOLETE} prefix to every
+line. Doing this means that it is easy to identify something that has
+been obsoleted when greping through the sources.
-@itemize @bullet
+The process is done in stages --- this is mainly to ensure that the
+wider @value{GDBN} community has a reasonable opportunity to respond.
+Remember, everything on the Internet takes a week.
+
+@enumerate
@item
-announce it
+Post the proposal on @email{gdb@@sources.redhat.com, the GDB mailing
+list} Creating a bug report to track the task's state, is also highly
+recommended.
@item
-wait a week
+Wait a week or so.
@item
-announce branch date
+Post the proposal on @email{gdb-announce@@sources.redhat.com, the GDB
+Announcement mailing list}.
@item
-wait a week
+Wait a week or so.
@item
-Cut the branch
+Go through and edit all relevant files and lines so that they are
+prefixed with the word @code{OBSOLETE}.
@item
-wait a week
+Wait until the next GDB version, containing this obsolete code, has been
+released.
@item
-start enjoying all the fun
-@end itemize
+Remove the obsolete code.
+@end enumerate
+
+@noindent
+@emph{Maintainer note: While removing old code is regrettable it is
+hopefully better for @value{GDBN}'s long term development. 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}
-As an aside, the branch tag name is probably regrettable vis:
-@example
-gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}
-@end example
+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.
@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 Prompt for @file{gdb/NEWS}
+@subheading Check the ARI
-People always forget. Send a post reminding them but also if you know
-something interesting happened add it your self.
+@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.
-@subheading Review @file{gdb/README}
+@subsection Review the bug data base
-Grab one of the nightly snapshots and then walk through the
-@file{gdb/README} looking for anything that can be improved.
+Close anything obviously fixed.
-@subheading Check the ARI
+@subsection Check all cross targets build
-ARI is an @code{awk} script (Awk Regression Indicator?) 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.
+The targets are listed in @file{gdb/MAINTAINERS}.
-@section Cut the branch
-@subheading The dirty work
+@section Cut the Branch
-I think something like the below was used:
+@subheading Create the branch
-@example
-$ 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
+@smallexample
+$ u=5.1
+$ v=5.2
+$ V=`echo $v | sed 's/\./_/g'`
+$ D=`date -u +%Y-%m-%d`
+$ echo $u $V $D
+5.1 5_2 2002-03-03
+$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
+-D $D-gmt gdb_$V-$D-branchpoint insight+dejagnu
+cvs -f -d :ext:sources.redhat.com:/cvs/src rtag
+-D 2002-03-03-gmt gdb_5_2-2002-03-03-branchpoint insight+dejagnu
+$ ^echo ^^
+...
+$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
+-b -r gdb_$V-$D-branchpoint gdb_$V-branch insight+dejagnu
+cvs -f -d :ext:sources.redhat.com:/cvs/src rtag \
+-b -r gdb_5_2-2002-03-03-branchpoint gdb_5_2-branch insight+dejagnu
+$ ^echo ^^
+...
$
-@end example
+@end smallexample
@itemize @bullet
@item
-the @kbd{-D YYYY-MM-DD-gmt} forces the branch to an exact date/time.
+by using @kbd{-D YYYY-MM-DD-gmt} the branch is forced to an exact
+date/time.
+@item
+the trunk is first taged so that the branch point can easily be found
@item
-the trunk is first tagged so that the branch point can easily be found
+Insight (which includes GDB) and dejagnu are all tagged at the same time
@item
-Insight (which includes GDB) and dejagnu are tagged at the same time
+@file{version.in} gets bumped to avoid version number conflicts
+@item
+the reading of @file{.cvsrc} is disabled using @file{-f}
+@end itemize
+
+@subheading Update @file{version.in}
+
+@smallexample
+$ u=5.1
+$ v=5.2
+$ V=`echo $v | sed 's/\./_/g'`
+$ echo $u $v$V
+5.1 5_2
+$ cd /tmp
+$ echo cvs -f -d :ext:sources.redhat.com:/cvs/src co \
+-r gdb_$V-branch src/gdb/version.in
+cvs -f -d :ext:sources.redhat.com:/cvs/src co
+ -r gdb_5_2-branch src/gdb/version.in
+$ ^echo ^^
+U src/gdb/version.in
+$ cd src/gdb
+$ echo $u.90-0000-00-00-cvs > version.in
+$ cat version.in
+5.1.90-0000-00-00-cvs
+$ cvs -f commit version.in
+@end smallexample
+
+@itemize @bullet
+@item
+@file{0000-00-00} is used as a date to pump prime the version.in update
+mechanism
+@item
+@file{.90} and the previous branch version are used as fairly arbitrary
+initial branch version number
@end itemize
-@subheading Post the branch info
@subheading Update the web and news pages
+Something?
+
@subheading Tweak cron to track the new branch
+The file @file{gdbadmin/cron/crontab} contains gdbadmin's cron table.
+This file needs to be updated so that:
+
+@itemize @bullet
+@item
+a daily timestamp is added to the file @file{version.in}
+@item
+the new branch is included in the snapshot process
+@end itemize
+
+@noindent
+See the file @file{gdbadmin/cron/README} for how to install the updated
+cron table.
+
+The file @file{gdbadmin/ss/README} should also be reviewed to reflect
+any changes. That file is copied to both the branch/ and current/
+snapshot directories.
+
+
+@subheading Update the NEWS and README files
+
+The @file{NEWS} file needs to be updated so that on the branch it refers
+to @emph{changes in the current release} while on the trunk it also
+refers to @emph{changes since the current release}.
+
+The @file{README} file needs to be updated so that it refers to the
+current release.
+
+@subheading Post the branch info
+
+Send an announcement to the mailing lists:
+
+@itemize @bullet
+@item
+@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
+@item
+@email{gdb@@sources.redhat.com, GDB Discsussion mailing list} and
+@email{gdb-testers@@sources.redhat.com, GDB Discsussion mailing list}
+@end itemize
+
+@emph{Pragmatics: The branch creation is sent to the announce list to
+ensure that people people not subscribed to the higher volume discussion
+list are alerted.}
+
+The announcement should include:
+
+@itemize @bullet
+@item
+the branch tag
+@item
+how to check out the branch using CVS
+@item
+the date/number of weeks until the release
+@item
+the branch commit policy
+still holds.
+@end itemize
+
@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.
+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).
-@subheading Establish a few defaults.
+@subsubheading Freeze the branch
-@example
-$ b=gdb_5_1-2001-07-29-branch
-$ v=5.1.1
+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_1-2001-07-29-branch/5.1.1
+/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 the
-version taken from the binutils snapshot directory. It is most likely
-that your system's installed version (@file{/usr/bin}?) is probably
-correct.
+@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, which can be
+found at @uref{ftp://sources.redhat.com/pub/binutils/}. It is very
+unlikely that a system installed version of @code{autoconf} (e.g.,
+@file{/usr/bin/autoconf}) is correct.
+@end itemize
-@example
+@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
-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.
+@subsubheading Update relevant files.
-@subheading Update relevant files.
+@table @file
-@subsubheading @file{gdb/NEWS}
+@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 update the ChangeLog.
+Don't forget to include the @file{ChangeLog} entry.
-@example
+@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 example
+@end smallexample
+
+@item gdb/README
-@subsubheading @file{gdb/README}
+You'll need to update:
-You'll need to update: the version, the update date, and who did it.
+@itemize @bullet
+@item
+the version
+@item
+the update date
+@item
+who did it
+@end itemize
-@example
+@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 example
+@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: 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.}
-@subsubheading @file{gdb/version.in}
+@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 to version ...
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 example
+@end smallexample
-@subsubheading @file{dejagnu/src/dejagnu/configure.in}
+@item 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}.
+@code{AM_INIT_AUTOMAKE}. Tweak it to read something like gdb-5.1.91.
-Re-generate configure.
+Don't forget to re-generate @file{configure}.
-Add a ChangeLog.
+Don't forget to include a @file{ChangeLog} entry.
-@subheading Do the dirty work
+@smallexample
+$ emacs dejagnu/src/dejagnu/configure.in
+...
+c-x 4 a
+...
+c-x c-s c-x c-c
+$ ( cd dejagnu/src/dejagnu && autoconf )
+@end smallexample
-This is identical to the process used when creating the daily snapshot.
+@end table
-@example
-$ for m in gdb insight dejagnu
+@subsubheading Do the dirty work
+
+This is identical to the process used to create the daily snapshot.
+
+@smallexample
+$ for m in gdb insight
do
-( cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+( cd $m/src && gmake -f Makefile.in $m.tar )
done
-@end example
+$ ( m=dejagnu; cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+@end smallexample
-@subheading Check the source files
+@subsubheading Check the source files
-You're looking for files that have mysteriously disappeared as the
+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 @kbd{cronjob}.
-@example
+@smallexample
$ ( cd gdb/src && cvs -f -q -n update )
M djunpack.bat
+? gdb-5.1.91.tar
? proto-toplev
-? gdb-5.1.1.tar.bz2
+@dots{} lots of generated files @dots{}
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
+@dots{} lots of generated files @dots{}
$
-@end example
+@end smallexample
+@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 Re-pack the release with @code{gzip}
+@subsubheading Create compressed versions of the release
-@example
-$ cp */*/*.bz2 .
-$ bunzip2 -k -v *.bz2
-$ gzip -9 -v *.tar
-@end example
+@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
+
+@noindent
+Note:
+
+@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
-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.
+@subsection Sanity check the tar ball
-@emph{Maintainer note: The release process could be changed to create
-@file{.tar} rather than @file{.tar.bz2} files.}
+Pick a popular machine (Solaris/PPC?) and try the build on that.
-@section Check the release
+@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
-Grab the @file{gdb.tar.bz2}, copy it to your local machine and then try
-a simple build using it.
+@subsection Make a release candidate available
-If this is a pre-release just copy the @file{.bz2} files to the snapshot
-directory and skip the remaining steps.
+If this is a release candidate then the only remaining steps are:
-If it is a final release, also make it available under a bogus name so
-that others can download and check it.
+@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
-@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.}
+@subsection Make a formal release available
-@section Release the tar ball
+(And you thought all that was required was to post an e-mail.)
-This is where, unfortunately, the notes just get vague.
+@subsubheading Install on sware
-@subheading Install on sware
+Copy the new files to both the release and the old release directory:
-@example
+@smallexample
+$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
$ cp *.bz2 *.gz ~ftp/pub/gdb/releases
-@end example
+@end smallexample
-@subheading Create and update the web pages.
+@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):
-Try the following:
+@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
-create the directory @file{htdocs/@var{version}} (e.g., @file{htdocs/5.1.1}
+General announcement
@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.
+News. If making an @var{M}.@var{N}.1 release, retain the news from
+earlier @var{M}.@var{N} release.
@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}
+Errata
+@end itemize
+
+@item htdocs/index.html
+@itemx htdocs/news/index.html
+@itemx htdocs/download/index.html
+These files include:
+@itemize @bullet
@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}.
+announcement of the most recent release
@item
-grep the @file{htdocs} tree for references to the previous release
-version (@file{htdocs/download/index.html})
+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}.
-@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
-
+@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 cronjobs and then just edit accordingly.
+from one of the nightly @code{cron} jobs and then just edit accordingly.
Something like:
-@example
+@smallexample
$ ~/ss/update-web-docs \
- ~ftp/pub/gdb/releases/gdb-5.1.1.tar.bz2 \
+ ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
$PWD/www \
- /www/sourceware/htdocs/gdb/5.1.1/onlinedocs \
+ /www/sourceware/htdocs/gdb/download/onlinedocs \
gdb
-@end example
+@end smallexample
+
+@item download/ari/
+Just like the online documentation. Something like:
+
+@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
-@subheading Something about @file{ANNOUNCEMENT}
+At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in
+@file{~ftp/gnu/gdb}.
+
+@subsubheading Make the @file{ANNOUNCEMENT}
-Send the @file{ANNOUNCEMENT} file you created above to:
+Post 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).
+@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
-@subheading Install it on GNU
+@subsection Cleanup
-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
+The release is out but you're still not finished.
-@subheading Commit outstanding changes
+@subsubheading Commit outstanding changes
-In particular you'll need to commit the changes to:
+In particular you'll need to commit any changes to:
@itemize @bullet
@item
@file{gdb/README}
@end itemize
-@subheading Tag the release
+@subsubheading Tag the release
Something like:
-@example
+@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 example
+$ ( 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
-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.).
+Just put something in the @file{ChangeLog} so that the trunk also
+indicates when the release was made.
-@subheading Restart @file{gdb/version.in}
+@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.1.0_0000-00-00-cvs} which will restart things (yes the @kbd{_}
+@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}.
-@subheading Merge into trunk
+@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.
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
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
projects / deliverable / binutils-gdb.git / blobdiff