X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdbint.texinfo;h=433844aa004f0abf7e428275a611b429393af10e;hb=db034ac5129e86e2dfccebe047f0ee50fd933ec9;hp=672851a25750d3f5b628e586cc5a84f526d57e4d;hpb=937f164bdad49a45c2608a7f48ca93ee9b35b12b;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 672851a257..433844aa00 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -50,7 +50,7 @@ Software Foundation raise funds for GNU development.'' @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 @@ -239,9 +239,9 @@ and called functions. 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 @@ -453,7 +453,7 @@ Insert or remove a hardware watchpoint starting at @var{addr}, for 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 */ @@ -461,7 +461,7 @@ defined by @file{breakpoint.h} as follows: 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. @@ -722,6 +722,14 @@ the main command list, and should be used for those commands. The usual 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 @@ -863,7 +871,7 @@ maximum of five levels. The overall structure of the table output code is something like this: -@example +@smallexample ui_out_table_begin ui_out_table_header @dots{} @@ -874,7 +882,7 @@ The overall structure of the table output code is something like this: 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: @@ -946,7 +954,7 @@ be signaled. 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, "..."); @@ -1139,7 +1147,7 @@ produce a table. The original code was: -@example +@smallexample if (!found_a_breakpoint++) @{ annotate_breakpoints_headers (); @@ -1162,11 +1170,11 @@ The original code was: annotate_breakpoints_table (); @} -@end example +@end smallexample Here's the new version: -@example +@smallexample nr_printable_breakpoints = @dots{}; if (addressprint) @@ -1203,13 +1211,13 @@ Here's the new version: 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); @@ -1224,11 +1232,11 @@ in the above example. The original code was: 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); @@ -1244,44 +1252,44 @@ This is the new version: 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 (" "); else printf_filtered ("library \"%s\" ", b->dll_pathname); -@end example +@end smallexample It became: -@example +@smallexample annotate_field (5); if (b->dll_pathname == NULL) @{ @@ -1294,21 +1302,21 @@ It became: 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) @{ @@ -1316,20 +1324,20 @@ It became: 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) @{ @@ -1337,22 +1345,22 @@ It became: 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 @@ -1826,7 +1834,7 @@ The file @file{mdebugread.c} implements reading for this format. 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 @@ -1904,7 +1912,7 @@ parsers that define a bunch of global names, the following lines @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 @@ -1921,7 +1929,7 @@ various parsers from defining the same global names: #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 @@ -2312,6 +2320,135 @@ The target architecture object is implemented as the C structure @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. @@ -2487,17 +2624,19 @@ C@t{++} reference type. @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. @@ -2505,6 +2644,10 @@ In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in 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: @@ -2589,6 +2732,85 @@ their @var{reg} and @var{type} arguments in different orders. @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 @@ -2834,6 +3056,12 @@ otherwise, we should leave it alone. The function @code{default_coerce_float_to_double} provides this behavior; it is the default value, for compatibility with older configurations. +@item 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 @@ -2918,8 +3146,8 @@ Deprecated in favor of @code{PRINT_FLOAT_INFO}. 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 @@ -2935,12 +3163,6 @@ See @file{stack.c}. @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 @@ -3050,15 +3272,6 @@ pointer. It examines the current state of the machine as needed. 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 @@ -3105,11 +3318,6 @@ The epilogue of a function is defined as the part of a function where the stack frame of the function already has been destroyed up to the final `return from function call' instruction. -@item IN_SIGTRAMP (@var{pc}, @var{name}) -@findex IN_SIGTRAMP -Define this to return non-zero if the given @var{pc} and/or @var{name} -indicates that the current function is a @code{sigtramp}. - @item SIGTRAMP_START (@var{pc}) @findex SIGTRAMP_START @itemx SIGTRAMP_END (@var{pc}) @@ -3191,34 +3399,43 @@ address the pointer refers to. @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 @@ -3308,6 +3525,18 @@ them. @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 @@ -3325,11 +3554,6 @@ This should only need to be defined if @code{TARGET_READ_PC} and @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 @@ -3405,9 +3629,9 @@ for parameters/results have been allocated on the stack. 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 @@ -3425,12 +3649,6 @@ of a branch or jump. 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 @@ -3547,18 +3765,15 @@ Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. @findex TARGET_WRITE_SP @itemx TARGET_READ_FP @findex TARGET_READ_FP -@itemx TARGET_WRITE_FP -@findex TARGET_WRITE_FP @findex read_pc @findex write_pc @findex read_sp @findex write_sp @findex read_fp -@findex write_fp These change the behavior of @code{read_pc}, @code{write_pc}, -@code{read_sp}, @code{write_sp}, @code{read_fp} and @code{write_fp}. -For most targets, these may be left undefined. @value{GDBN} will call the read -and write register functions with the relevant @code{_REGNUM} argument. +@code{read_sp}, @code{write_sp} and @code{read_fp}. For most targets, +these may be left undefined. @value{GDBN} will call the read and write +register functions with the relevant @code{_REGNUM} argument. These macros are useful when a target keeps one of these registers in a hard to get at place; for example, part in a segment register and part @@ -3597,6 +3812,12 @@ being considered is known to have been compiled by GCC; this is helpful 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 @@ -3680,6 +3901,168 @@ that just @code{#include}s @file{tm-@var{arch}.h} and @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 @@ -4185,7 +4568,7 @@ Cleanups are implemented as a chain. The handle returned by 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); @@ -4193,7 +4576,7 @@ make_cleanup (a, 0); ... do_cleanups (old); @} -@end example +@end smallexample @noindent will call @code{c()} and @code{b()} but will not call @code{a()}. The @@ -4212,13 +4595,13 @@ code-segment avoids a memory leak problem (even when @code{error} is called and a forced stack unwind occurs) by ensuring that the @code{xfree} will always be called: -@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 @@ -4226,13 +4609,13 @@ any created cleanups are not performed. For instance, the following code segment, ensures that the file will be closed but only if there is an error: -@example +@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 @@ -4241,66 +4624,204 @@ interruption must be on the cleanup chain before you call these 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}. @@ -4389,7 +4910,7 @@ strictly. 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 */ @@ -4397,7 +4918,7 @@ void foo (void) @{ @} -@end example +@end smallexample @emph{Pragmatics: This simplifies scripting. Function definitions can be found using @samp{^function-name}.} @@ -4415,17 +4936,17 @@ for @code{diff} and @code{patch} utilities. 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 @@ -4435,13 +4956,13 @@ The standard GNU requirements on comments must be followed strictly. 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.) @@ -4544,26 +5065,37 @@ For other files @samp{-} is used as the separator. @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 @@ -4631,7 +5163,7 @@ symbol to write conditional code which should only be compiled for 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 @@ -4723,16 +5255,16 @@ vendors, and operating systems near the bottom of the file. Also, add @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}} @@ -4769,9 +5301,9 @@ configuration. 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 @@ -4817,83 +5349,207 @@ files @file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will split the document into one overall file and five or so included files. + @node Releasing GDB @chapter Releasing @value{GDBN} @cindex making a new release of gdb -@section 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. @@ -4903,114 +5559,250 @@ 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 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 @@ -5018,13 +5810,22 @@ 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 @@ -5032,192 +5833,278 @@ 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 @@ -5230,36 +6117,58 @@ In particular you'll need to commit the changes to: @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. @@ -5290,7 +6199,7 @@ the testsuite is running, you'll get mentions of which test file is in use, 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 @@ -5299,7 +6208,7 @@ finished, you'll get a summary that looks like this: # 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 @@ -5615,16 +6524,6 @@ and deleted from all of @value{GDBN}'s config files. 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