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.
The overall structure of the table output code is something like this:
-@example
+@smallexample
ui_out_table_begin
ui_out_table_header
@dots{}
ui_out_tuple_end
@dots{}
ui_out_table_end
-@end example
+@end smallexample
Here is the description of table-, tuple- and list-related @code{ui_out}
functions:
The original code was:
-@example
+@smallexample
if (!found_a_breakpoint++)
@{
annotate_breakpoints_headers ();
annotate_breakpoints_table ();
@}
-@end example
+@end smallexample
Here's the new version:
-@example
+@smallexample
nr_printable_breakpoints = @dots{};
if (addressprint)
ui_out_table_body (uiout);
if (nr_printable_breakpoints > 0)
annotate_breakpoints_table ();
-@end example
+@end smallexample
This example, from the @code{print_one_breakpoint} function, shows how
to produce the actual data for the table whose structure was defined
in the above example. The original code was:
-@example
+@smallexample
annotate_record ();
annotate_field (0);
printf_filtered ("%-3d ", b->number);
annotate_field (3);
printf_filtered ("%-3c ", bpenables[(int)b->enable]);
@dots{}
-@end example
+@end smallexample
This is the new version:
-@example
+@smallexample
annotate_record ();
ui_out_tuple_begin (uiout, "bkpt");
annotate_field (0);
annotate_field (3);
ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]);
@dots{}
-@end example
+@end smallexample
This example, also from @code{print_one_breakpoint}, shows how to
produce a complicated output field using the @code{print_expression}
functions which requires a stream to be passed. It also shows how to
automate stream destruction with cleanups. The original code was:
-@example
+@smallexample
annotate_field (5);
print_expression (b->exp, gdb_stdout);
-@end example
+@end smallexample
The new version is:
-@example
+@smallexample
struct ui_stream *stb = ui_out_stream_new (uiout);
struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb);
...
annotate_field (5);
print_expression (b->exp, stb->stream);
ui_out_field_stream (uiout, "what", local_stream);
-@end example
+@end smallexample
This example, also from @code{print_one_breakpoint}, shows how to use
@code{ui_out_text} and @code{ui_out_field_string}. The original code
was:
-@example
+@smallexample
annotate_field (5);
if (b->dll_pathname == NULL)
printf_filtered ("<any library> ");
else
printf_filtered ("library \"%s\" ", b->dll_pathname);
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (5);
if (b->dll_pathname == NULL)
@{
ui_out_field_string (uiout, "what", b->dll_pathname);
ui_out_text (uiout, "\" ");
@}
-@end example
+@end smallexample
The following example from @code{print_one_breakpoint} shows how to
use @code{ui_out_field_int} and @code{ui_out_spaces}. The original
code was:
-@example
+@smallexample
annotate_field (5);
if (b->forked_inferior_pid != 0)
printf_filtered ("process %d ", b->forked_inferior_pid);
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (5);
if (b->forked_inferior_pid != 0)
@{
ui_out_field_int (uiout, "what", b->forked_inferior_pid);
ui_out_spaces (uiout, 1);
@}
-@end example
+@end smallexample
Here's an example of using @code{ui_out_field_string}. The original
code was:
-@example
+@smallexample
annotate_field (5);
if (b->exec_pathname != NULL)
printf_filtered ("program \"%s\" ", b->exec_pathname);
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (5);
if (b->exec_pathname != NULL)
@{
ui_out_field_string (uiout, "what", b->exec_pathname);
ui_out_text (uiout, "\" ");
@}
-@end example
+@end smallexample
Finally, here's an example of printing an address. The original code:
-@example
+@smallexample
annotate_field (4);
printf_filtered ("%s ",
local_hex_string_custom ((unsigned long) b->address, "08l"));
-@end example
+@end smallexample
It became:
-@example
+@smallexample
annotate_field (4);
ui_out_field_core_addr (uiout, "Address", b->address);
-@end example
+@end smallexample
@section Console Printing
@strong{must} be included at the top of the YACC parser, to prevent the
various parsers from defining the same global names:
-@example
+@smallexample
#define yyparse @var{lang}_parse
#define yylex @var{lang}_lex
#define yyerror @var{lang}_error
#define yyexca @var{lang}_exca
#define yyerrflag @var{lang}_errflag
#define yynerrs @var{lang}_nerrs
-@end example
+@end smallexample
At the bottom of your parser, define a @code{struct language_defn} and
initialize it with the right values for your language. Define an
@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.}
+section below are likely to be made obsolete. For instance, instead of
+having different raw and virtual register sizes, an architecture can
+define pseudo-registers that map onto the raw registers.
+
+See the @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.
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_RAW_SIZE (@var{reg})
@findex REGISTER_RAW_SIZE
-Return the raw size of @var{reg}.
+Return the raw size of @var{reg}; defaults to the size of the register's
+virtual type.
@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
@item REGISTER_VIRTUAL_SIZE (@var{reg})
@findex REGISTER_VIRTUAL_SIZE
-Return the virtual size of @var{reg}.
+Return the virtual size of @var{reg}; defaults to the size of the
+register's virtual type.
@xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
@item REGISTER_VIRTUAL_TYPE (@var{reg})
@findex PC_IN_CALL_DUMMY
See @file{inferior.h}.
+@item PC_IN_SIGTRAMP (@var{pc}, @var{name})
+@findex PC_IN_SIGTRAMP
+@cindex sigtramp
+The @dfn{sigtramp} is a routine that the kernel calls (which then calls
+the signal handler). On most machines it is a library routine that is
+linked into the executable.
+
+This function, given a program counter value in @var{pc} and the
+(possibly NULL) name of the function in which that @var{pc} resides,
+returns nonzero if the @var{pc} and/or @var{name} show that we are in
+sigtramp.
+
@item PC_LOAD_SEGMENT
@findex PC_LOAD_SEGMENT
If defined, print information about the load segment for the program
A C expression that returns the address of the ``real'' code beyond the
function entry prologue found at @var{pc}.
-@item SKIP_PROLOGUE_FRAMELESS_P
-@findex SKIP_PROLOGUE_FRAMELESS_P
-A C expression that should behave similarly, but that can stop as soon
-as the function is known to have a frame. If not defined,
-@code{SKIP_PROLOGUE} will be used instead.
-
@item SKIP_TRAMPOLINE_CODE (@var{pc})
@findex SKIP_TRAMPOLINE_CODE
If the target machine has trampoline code that sits between callers and
@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
later cleanups appended to the chain (but not yet discarded or
performed). E.g.:
-@example
+@smallexample
make_cleanup (a, 0);
@{
struct cleanup *old = make_cleanup (b, 0);
...
do_cleanups (old);
@}
-@end example
+@end smallexample
@noindent
will call @code{c()} and @code{b()} but will not call @code{a()}. The
called and a forced stack unwind occurs) by ensuring that the
@code{xfree} will always be called:
-@example
+@smallexample
struct cleanup *old = make_cleanup (null_cleanup, 0);
data = xmalloc (sizeof blah);
make_cleanup (xfree, data);
... blah blah ...
do_cleanups (old);
-@end example
+@end smallexample
The second style is try/except. Before it exits, your code-block calls
@code{discard_cleanups} with the old cleanup chain and thus ensures that
code segment, ensures that the file will be closed but only if there is
an error:
-@example
+@smallexample
FILE *file = fopen ("afile", "r");
struct cleanup *old = make_cleanup (close_file, file);
... blah blah ...
discard_cleanups (old);
return file;
-@end example
+@end smallexample
Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
that they ``should not be called when cleanups are not in place''. This
A function declaration should not have its name in column zero. A
function definition should have its name in column zero.
-@example
+@smallexample
/* Declaration */
static void foo (void);
/* Definition */
foo (void)
@{
@}
-@end example
+@end smallexample
@emph{Pragmatics: This simplifies scripting. Function definitions can
be found using @samp{^function-name}.}
Pointers are declared using the traditional K&R C style:
-@example
+@smallexample
void *foo;
-@end example
+@end smallexample
@noindent
and not:
-@example
+@smallexample
void * foo;
void* foo;
-@end example
+@end smallexample
@subsection Comments
Block comments must appear in the following form, with no @code{/*}- or
@code{*/}-only lines, and no leading @code{*}:
-@example
+@smallexample
/* Wait for control to return from inferior to debugger. If inferior
gets a signal, we may decide to start it up again instead of
returning. That is why there is a loop in this function. When
this function actually returns it means the inferior should be left
stopped and @value{GDBN} should read more commands. */
-@end example
+@end smallexample
(Note that this format is encouraged by Emacs; tabbing for a multi-line
comment works correctly, and @kbd{M-q} fills the block consistently.)
All include files should be wrapped in:
-@example
+@smallexample
#ifndef INCLUDE_FILE_NAME_H
#define INCLUDE_FILE_NAME_H
header body
#endif
-@end example
+@end smallexample
@subsection Clean Design and Portable Implementation
such hosts.
@findex IS_DIR_SEPARATOR
-@item IS_DIR_SEPARATOR (@var{c}
+@item IS_DIR_SEPARATOR (@var{c})
Evaluates to a non-zero value if @var{c} is a directory separator
character. On Unix and GNU/Linux systems, only a slash @file{/} is
such a character, but on Windows, both @file{/} and @file{\} will
@code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
running
-@example
+@smallexample
./config.sub @var{xyz}
-@end example
+@end smallexample
@noindent
and
-@example
+@smallexample
./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
-@end example
+@end smallexample
@noindent
which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
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
Releases 5.0 and 5.1 used branch and release tags of the form:
-@example
+@smallexample
gdb_N_M-YYYY-MM-DD-branchpoint
gdb_N_M-YYYY-MM-DD-branch
gdb_M_N-YYYY-MM-DD-release
-@end example
+@end smallexample
Release 5.2 is trialing the branch and release tags:
-@example
+@smallexample
gdb_N_M-YYYY-MM-DD-branchpoint
gdb_N_M-branch
gdb_M_N-YYYY-MM-DD-release
-@end example
+@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
@item
Don't fix something on the branch unless/until it is also fixed in the
trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS}
-file is better than committing a hack
+file is better than committing a hack.
@item
When considering a patch for the branch, suggested criteria include:
Does it fix a build? Does it fix the sequence @kbd{break main; run}
@section Obsolete any code
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).
+code) to see if there is anything that can be removed from @value{GDBN}
+(an old target, an unused file).
Obsolete code is identified by adding an @code{OBSOLETE} prefix to every
line. Doing this means that it is easy to identify obsolete code when
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
+
+@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
building. If you can't get the problem fixed, document it in the
@file{gdb/PROBLEMS} file.
-@subheading Organize and announce the schedule.
+@subheading Prompt for @file{gdb/NEWS}
-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.
+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.
-@itemize @bullet
-@item
-announce it
-@item
-wait a week
-@item
-announce branch date
-@item
-wait a week
-@item
-Cut the branch
-@item
-wait a week
-@item
-start enjoying all the fun
-@end itemize
+@subheading Review @file{gdb/README}
-As an aside, the branch tag name is probably regrettable vis:
-@example
-gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@}
-@end example
+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 Check the ARI
-@subheading Prompt for @file{gdb/NEWS}
+@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.
-People always forget. Send a post reminding them but also if you know
-something interesting happened add it your self.
+@subsection Review the bug data base
-@subheading Review @file{gdb/README}
+Close anything obviously fixed.
-Grab one of the nightly snapshots and then walk through the
-@file{gdb/README} looking for anything that can be improved.
+@subsection Check all cross targets build
-@subheading Check the ARI
+The targets are listed in @file{gdb/MAINTAINERS}.
-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.
@section Cut the branch
I think something like the below was used:
-@example
+@smallexample
$ d=`date -u +%Y-%m-%d`
$ echo $d
2002-01-24
$ cvs -f -d /cvs/src rtag -b -r gdb_V_V-$d-branchpoint \
gdb_5_1-$d-branch insight+dejagnu
$
-@end example
+@end smallexample
@itemize @bullet
@item
@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
-@subheading Establish a few defaults.
+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).
-@example
-$ b=gdb_5_1-2001-07-29-branch
-$ v=5.1.1
+@subsubheading Freeze the branch
+
+Send out an e-mail notifying everyone that the branch is frozen to
+@email{gdb-patches@@sources.redhat.com}.
+
+@subsubheading Establish a few defaults.
+
+@smallexample
+$ b=gdb_5_2-branch
+$ v=5.2
$ t=/sourceware/snapshot-tmp/gdbadmin-tmp
$ echo $t/$b/$v
+/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
$ mkdir -p $t/$b/$v
$ cd $t/$b/$v
$ pwd
-/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_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. 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
-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.
+@noindent
+Note:
-@subheading Update relevant files.
+@itemize @bullet
+@item
+The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't
+any confusion between what is written here and what your local
+@code{cvs} really does.
+@end itemize
+
+@subsubheading Update relevant files.
+
+@table @file
-@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
-@subsubheading @file{gdb/README}
+@item gdb/README
-You'll need to update: the version, the update date, and who did it.
+You'll need to update:
+
+@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
-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.
+@noindent
+Note:
-@emph{Maintainer note: The release process could be changed to create
-@file{.tar} rather than @file{.tar.bz2} files.}
+@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
-@section Check the release
+@subsection Sanity check the tar ball
-Grab the @file{gdb.tar.bz2}, copy it to your local machine and then try
-a simple build using it.
+Pick a popular machine (Solaris/PPC?) and try the build on that.
-If this is a pre-release just copy the @file{.bz2} files to the snapshot
-directory and skip the remaining steps.
+@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
-If it is a final release, also make it available under a bogus name so
-that others can download and check it.
+@subsection Make a release candidate available
-@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.}
+If this is a release candidate then the only remaining steps are:
-@section Release the tar ball
+@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
-This is where, unfortunately, the notes just get vague.
+@subsection Make a formal release available
-@subheading Install on sware
+(And you thought all that was required was to post an e-mail.)
-@example
+@subsubheading Install on sware
+
+Copy the new files to both the release and the old release directory:
+
+@smallexample
+$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
$ cp *.bz2 *.gz ~ftp/pub/gdb/releases
-@end example
+@end smallexample
+
+@noindent
+Clean up the releases directory so that only the most recent releases
+are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):
+
+@smallexample
+$ cd ~ftp/pub/gdb/releases
+$ rm @dots{}
+@end smallexample
+
+@noindent
+Update the file @file{README} and @file{.message} in the releases
+directory:
-@subheading Create and update the web pages.
+@smallexample
+$ vi README
+@dots{}
+$ rm -f .message
+$ ln README .message
+@end smallexample
-Try the following:
+@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}
-@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.
+General announcement
@item
-copy the @file{NEWS} from the distro into the
-@file{htdocs/@var{version}} directory, trim down to just the most recent
-news items
+News. If making an @var{M}.@var{N}.1 release, retain the news from
+earlier @var{M}.@var{N} release.
@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
+
+At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in
+@file{~ftp/gnu/gdb}.
-@subheading Something about @file{ANNOUNCEMENT}
+@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
-
-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).
+@subsection Cleanup
-@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).
-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.).
+@subsubheading Mention the release on the trunk
-@subheading Restart @file{gdb/version.in}
+Just put something in the @file{ChangeLog} so that the trunk also
+indicates when the release was made.
+
+@subsubheading Restart @file{gdb/version.in}
If @file{gdb/version.in} does not contain an ISO date such as
@kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having
committed all the release changes it can be set to
-@file{5.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