+If you are adding a new operating system for an existing CPU chip, add a
+@file{config/tm-@var{os}.h} file that describes the operating system
+facilities that are unusual (extra symbol table info; the breakpoint
+instruction needed; etc.). Then write a @file{@var{arch}/tm-@var{os}.h}
+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
+@cindex target vector
+
+The target vector defines the interface between @value{GDBN}'s
+abstract handling of target systems, and the nitty-gritty code that
+actually exercises control over a process or a serial port.
+@value{GDBN} includes some 30-40 different target vectors; however,
+each configuration of @value{GDBN} includes only a few of them.
+
+@section File Targets
+
+Both executables and core files have target vectors.
+
+@section Standard Protocol and Remote Stubs
+
+@value{GDBN}'s file @file{remote.c} talks a serial protocol to code
+that runs in the target system. @value{GDBN} provides several sample
+@dfn{stubs} that can be integrated into target programs or operating
+systems for this purpose; they are named @file{*-stub.c}.
+
+The @value{GDBN} user's manual describes how to put such a stub into
+your target code. What follows is a discussion of integrating the
+SPARC stub into a complicated operating system (rather than a simple
+program), by Stu Grossman, the author of this stub.
+
+The trap handling code in the stub assumes the following upon entry to
+@code{trap_low}:
+
+@enumerate
+@item
+%l1 and %l2 contain pc and npc respectively at the time of the trap;
+
+@item
+traps are disabled;
+
+@item
+you are in the correct trap window.
+@end enumerate
+
+As long as your trap handler can guarantee those conditions, then there
+is no reason why you shouldn't be able to ``share'' traps with the stub.
+The stub has no requirement that it be jumped to directly from the
+hardware trap vector. That is why it calls @code{exceptionHandler()},
+which is provided by the external environment. For instance, this could
+set up the hardware traps to actually execute code which calls the stub
+first, and then transfers to its own trap handler.
+
+For the most point, there probably won't be much of an issue with
+``sharing'' traps, as the traps we use are usually not used by the kernel,
+and often indicate unrecoverable error conditions. Anyway, this is all
+controlled by a table, and is trivial to modify. The most important
+trap for us is for @code{ta 1}. Without that, we can't single step or
+do breakpoints. Everything else is unnecessary for the proper operation
+of the debugger/stub.
+
+From reading the stub, it's probably not obvious how breakpoints work.
+They are simply done by deposit/examine operations from @value{GDBN}.
+
+@section ROM Monitor Interface
+
+@section Custom Protocols
+
+@section Transport Layer
+
+@section Builtin Simulator
+
+
+@node Native Debugging
+
+@chapter Native Debugging
+@cindex native debugging
+
+Several files control @value{GDBN}'s configuration for native support:
+
+@table @file
+@vindex NATDEPFILES
+@item gdb/config/@var{arch}/@var{xyz}.mh
+Specifies Makefile fragments needed by a @emph{native} configuration on
+machine @var{xyz}. In particular, this lists the required
+native-dependent object files, by defining @samp{NATDEPFILES=@dots{}}.
+Also specifies the header file which describes native support on
+@var{xyz}, by defining @samp{NAT_FILE= nm-@var{xyz}.h}. You can also
+define @samp{NAT_CFLAGS}, @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS},
+@samp{NAT_CDEPS}, etc.; see @file{Makefile.in}.
+
+@emph{Maintainer's note: The @file{.mh} suffix is because this file
+originally contained @file{Makefile} fragments for hosting @value{GDBN}
+on machine @var{xyz}. While the file is no longer used for this
+purpose, the @file{.mh} suffix remains. Perhaps someone will
+eventually rename these fragments so that they have a @file{.mn}
+suffix.}
+
+@item gdb/config/@var{arch}/nm-@var{xyz}.h
+(@file{nm.h} is a link to this file, created by @code{configure}). Contains C
+macro definitions describing the native system environment, such as
+child process control and core file support.
+
+@item gdb/@var{xyz}-nat.c
+Contains any miscellaneous C code required for this native support of
+this machine. On some machines it doesn't exist at all.
+@end table
+
+There are some ``generic'' versions of routines that can be used by
+various systems. These can be customized in various ways by macros
+defined in your @file{nm-@var{xyz}.h} file. If these routines work for
+the @var{xyz} host, you can just include the generic file's name (with
+@samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
+
+Otherwise, if your machine needs custom support routines, you will need
+to write routines that perform the same functions as the generic file.
+Put them into @file{@var{xyz}-nat.c}, and put @file{@var{xyz}-nat.o}
+into @code{NATDEPFILES}.
+
+@table @file
+@item inftarg.c
+This contains the @emph{target_ops vector} that supports Unix child
+processes on systems which use ptrace and wait to control the child.
+
+@item procfs.c
+This contains the @emph{target_ops vector} that supports Unix child
+processes on systems which use /proc to control the child.
+
+@item fork-child.c
+This does the low-level grunge that uses Unix system calls to do a ``fork
+and exec'' to start up a child process.
+
+@item infptrace.c
+This is the low level interface to inferior processes for systems using
+the Unix @code{ptrace} call in a vanilla way.
+@end table
+
+@section Native core file Support
+@cindex native core files
+
+@table @file
+@findex fetch_core_registers
+@item core-aout.c::fetch_core_registers()
+Support for reading registers out of a core file. This routine calls
+@code{register_addr()}, see below. Now that BFD is used to read core
+files, virtually all machines should use @code{core-aout.c}, and should
+just provide @code{fetch_core_registers} in @code{@var{xyz}-nat.c} (or
+@code{REGISTER_U_ADDR} in @code{nm-@var{xyz}.h}).
+
+@item core-aout.c::register_addr()
+If your @code{nm-@var{xyz}.h} file defines the macro
+@code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
+set @code{addr} to the offset within the @samp{user} struct of @value{GDBN}
+register number @code{regno}. @code{blockend} is the offset within the
+``upage'' of @code{u.u_ar0}. If @code{REGISTER_U_ADDR} is defined,
+@file{core-aout.c} will define the @code{register_addr()} function and
+use the macro in it. If you do not define @code{REGISTER_U_ADDR}, but
+you are using the standard @code{fetch_core_registers()}, you will need
+to define your own version of @code{register_addr()}, put it into your
+@code{@var{xyz}-nat.c} file, and be sure @code{@var{xyz}-nat.o} is in
+the @code{NATDEPFILES} list. If you have your own
+@code{fetch_core_registers()}, you may not need a separate
+@code{register_addr()}. Many custom @code{fetch_core_registers()}
+implementations simply locate the registers themselves.@refill
+@end table
+
+When making @value{GDBN} run native on a new operating system, to make it
+possible to debug core files, you will need to either write specific
+code for parsing your OS's core files, or customize
+@file{bfd/trad-core.c}. First, use whatever @code{#include} files your
+machine uses to define the struct of registers that is accessible
+(possibly in the u-area) in a core file (rather than
+@file{machine/reg.h}), and an include file that defines whatever header
+exists on a core file (e.g. the u-area or a @code{struct core}). Then
+modify @code{trad_unix_core_file_p} to use these values to set up the
+section information for the data segment, stack segment, any other
+segments in the core file (perhaps shared library contents or control
+information), ``registers'' segment, and if there are two discontiguous
+sets of registers (e.g. integer and float), the ``reg2'' segment. This
+section information basically delimits areas in the core file in a
+standard way, which the section-reading routines in BFD know how to seek
+around in.
+
+Then back in @value{GDBN}, you need a matching routine called
+@code{fetch_core_registers}. If you can use the generic one, it's in
+@file{core-aout.c}; if not, it's in your @file{@var{xyz}-nat.c} file.
+It will be passed a char pointer to the entire ``registers'' segment,
+its length, and a zero; or a char pointer to the entire ``regs2''
+segment, its length, and a 2. The routine should suck out the supplied
+register values and install them into @value{GDBN}'s ``registers'' array.
+
+If your system uses @file{/proc} to control processes, and uses ELF
+format core files, then you may be able to use the same routines for
+reading the registers out of processes and out of core files.
+
+@section ptrace
+
+@section /proc
+
+@section win32
+
+@section shared libraries
+
+@section Native Conditionals
+@cindex native conditionals
+
+When @value{GDBN} is configured and compiled, various macros are
+defined or left undefined, to control compilation when the host and
+target systems are the same. These macros should be defined (or left
+undefined) in @file{nm-@var{system}.h}.
+
+@table @code
+@item ATTACH_DETACH
+@findex ATTACH_DETACH
+If defined, then @value{GDBN} will include support for the @code{attach} and
+@code{detach} commands.
+
+@item CHILD_PREPARE_TO_STORE
+@findex CHILD_PREPARE_TO_STORE
+If the machine stores all registers at once in the child process, then
+define this to ensure that all values are correct. This usually entails
+a read from the child.
+
+[Note that this is incorrectly defined in @file{xm-@var{system}.h} files
+currently.]
+
+@item FETCH_INFERIOR_REGISTERS
+@findex FETCH_INFERIOR_REGISTERS
+Define this if the native-dependent code will provide its own routines
+@code{fetch_inferior_registers} and @code{store_inferior_registers} in
+@file{@var{host}-nat.c}. If this symbol is @emph{not} defined, and
+@file{infptrace.c} is included in this configuration, the default
+routines in @file{infptrace.c} are used for these functions.
+
+@item FILES_INFO_HOOK
+@findex FILES_INFO_HOOK
+(Only defined for Convex.)
+
+@item FP0_REGNUM
+@findex FP0_REGNUM
+This macro is normally defined to be the number of the first floating
+point register, if the machine has such registers. As such, it would
+appear only in target-specific code. However, @file{/proc} support uses this
+to decide whether floats are in use on this target.
+
+@item GET_LONGJMP_TARGET
+@findex GET_LONGJMP_TARGET
+For most machines, this is a target-dependent parameter. On the
+DECstation and the Iris, this is a native-dependent parameter, since
+@file{setjmp.h} is needed to define it.
+
+This macro determines the target PC address that @code{longjmp} will jump to,
+assuming that we have just stopped at a longjmp breakpoint. It takes a
+@code{CORE_ADDR *} as argument, and stores the target PC value through this
+pointer. It examines the current state of the machine as needed.
+
+@item I386_USE_GENERIC_WATCHPOINTS
+An x86-based machine can define this to use the generic x86 watchpoint
+support; see @ref{Algorithms, I386_USE_GENERIC_WATCHPOINTS}.
+
+@item KERNEL_U_ADDR
+@findex KERNEL_U_ADDR
+Define this to the address of the @code{u} structure (the ``user
+struct'', also known as the ``u-page'') in kernel virtual memory. @value{GDBN}
+needs to know this so that it can subtract this address from absolute
+addresses in the upage, that are obtained via ptrace or from core files.
+On systems that don't need this value, set it to zero.
+
+@item KERNEL_U_ADDR_BSD
+@findex KERNEL_U_ADDR_BSD
+Define this to cause @value{GDBN} to determine the address of @code{u} at
+runtime, by using Berkeley-style @code{nlist} on the kernel's image in
+the root directory.
+
+@item KERNEL_U_ADDR_HPUX
+@findex KERNEL_U_ADDR_HPUX
+Define this to cause @value{GDBN} to determine the address of @code{u} at
+runtime, by using HP-style @code{nlist} on the kernel's image in the
+root directory.
+
+@item ONE_PROCESS_WRITETEXT
+@findex ONE_PROCESS_WRITETEXT
+Define this to be able to, when a breakpoint insertion fails, warn the
+user that another process may be running with the same executable.
+
+@item PREPARE_TO_PROCEED (@var{select_it})
+@findex PREPARE_TO_PROCEED
+This (ugly) macro allows a native configuration to customize the way the
+@code{proceed} function in @file{infrun.c} deals with switching between
+threads.
+
+In a multi-threaded task we may select another thread and then continue
+or step. But if the old thread was stopped at a breakpoint, it will
+immediately cause another breakpoint stop without any execution (i.e. it
+will report a breakpoint hit incorrectly). So @value{GDBN} must step over it
+first.
+
+If defined, @code{PREPARE_TO_PROCEED} should check the current thread
+against the thread that reported the most recent event. If a step-over
+is required, it returns TRUE. If @var{select_it} is non-zero, it should
+reselect the old thread.
+
+@item PROC_NAME_FMT
+@findex PROC_NAME_FMT
+Defines the format for the name of a @file{/proc} device. Should be
+defined in @file{nm.h} @emph{only} in order to override the default
+definition in @file{procfs.c}.
+
+@item PTRACE_FP_BUG
+@findex PTRACE_FP_BUG
+See @file{mach386-xdep.c}.
+
+@item PTRACE_ARG3_TYPE
+@findex PTRACE_ARG3_TYPE
+The type of the third argument to the @code{ptrace} system call, if it
+exists and is different from @code{int}.
+
+@item REGISTER_U_ADDR
+@findex REGISTER_U_ADDR
+Defines the offset of the registers in the ``u area''.
+
+@item SHELL_COMMAND_CONCAT
+@findex SHELL_COMMAND_CONCAT
+If defined, is a string to prefix on the shell command used to start the
+inferior.
+
+@item SHELL_FILE
+@findex SHELL_FILE
+If defined, this is the name of the shell to use to run the inferior.
+Defaults to @code{"/bin/sh"}.
+
+@item SOLIB_ADD (@var{filename}, @var{from_tty}, @var{targ}, @var{readsyms})
+@findex SOLIB_ADD
+Define this to expand into an expression that will cause the symbols in
+@var{filename} to be added to @value{GDBN}'s symbol table. If
+@var{readsyms} is zero symbols are not read but any necessary low level
+processing for @var{filename} is still done.
+
+@item SOLIB_CREATE_INFERIOR_HOOK
+@findex SOLIB_CREATE_INFERIOR_HOOK
+Define this to expand into any shared-library-relocation code that you
+want to be run just after the child process has been forked.
+
+@item START_INFERIOR_TRAPS_EXPECTED
+@findex START_INFERIOR_TRAPS_EXPECTED
+When starting an inferior, @value{GDBN} normally expects to trap
+twice; once when
+the shell execs, and once when the program itself execs. If the actual
+number of traps is something other than 2, then define this macro to
+expand into the number expected.
+
+@item SVR4_SHARED_LIBS
+@findex SVR4_SHARED_LIBS
+Define this to indicate that SVR4-style shared libraries are in use.
+
+@item USE_PROC_FS
+@findex USE_PROC_FS
+This determines whether small routines in @file{*-tdep.c}, which
+translate register values between @value{GDBN}'s internal
+representation and the @file{/proc} representation, are compiled.
+
+@item U_REGS_OFFSET
+@findex U_REGS_OFFSET
+This is the offset of the registers in the upage. It need only be
+defined if the generic ptrace register access routines in
+@file{infptrace.c} are being used (that is, @file{infptrace.c} is
+configured in, and @code{FETCH_INFERIOR_REGISTERS} is not defined). If
+the default value from @file{infptrace.c} is good enough, leave it
+undefined.
+
+The default value means that u.u_ar0 @emph{points to} the location of
+the registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means
+that @code{u.u_ar0} @emph{is} the location of the registers.
+
+@item CLEAR_SOLIB
+@findex CLEAR_SOLIB
+See @file{objfiles.c}.
+
+@item DEBUG_PTRACE
+@findex DEBUG_PTRACE
+Define this to debug @code{ptrace} calls.
+@end table
+
+
+@node Support Libraries
+
+@chapter Support Libraries
+
+@section BFD
+@cindex BFD library
+
+BFD provides support for @value{GDBN} in several ways:
+
+@table @emph
+@item identifying executable and core files
+BFD will identify a variety of file types, including a.out, coff, and
+several variants thereof, as well as several kinds of core files.
+
+@item access to sections of files
+BFD parses the file headers to determine the names, virtual addresses,
+sizes, and file locations of all the various named sections in files
+(such as the text section or the data section). @value{GDBN} simply
+calls BFD to read or write section @var{x} at byte offset @var{y} for
+length @var{z}.
+
+@item specialized core file support
+BFD provides routines to determine the failing command name stored in a
+core file, the signal with which the program failed, and whether a core
+file matches (i.e.@: could be a core dump of) a particular executable
+file.
+
+@item locating the symbol information
+@value{GDBN} uses an internal interface of BFD to determine where to find the
+symbol information in an executable file or symbol-file. @value{GDBN} itself
+handles the reading of symbols, since BFD does not ``understand'' debug
+symbols, but @value{GDBN} uses BFD's cached information to find the symbols,
+string table, etc.
+@end table
+
+@section opcodes
+@cindex opcodes library
+
+The opcodes library provides @value{GDBN}'s disassembler. (It's a separate
+library because it's also used in binutils, for @file{objdump}).
+
+@section readline
+
+@section mmalloc
+
+@section libiberty
+
+@section gnu-regex
+@cindex regular expressions library
+
+Regex conditionals.
+
+@table @code
+@item C_ALLOCA
+
+@item NFAILURES
+
+@item RE_NREGS
+
+@item SIGN_EXTEND_CHAR
+
+@item SWITCH_ENUM_BUG
+
+@item SYNTAX_TABLE
+
+@item Sword
+
+@item sparc
+@end table
+
+@section include
+
+@node Coding
+
+@chapter Coding
+
+This chapter covers topics that are lower-level than the major
+algorithms of @value{GDBN}.
+
+@section Cleanups
+@cindex cleanups
+
+Cleanups are a structured way to deal with things that need to be done
+later.
+
+When your code does something (e.g., @code{xmalloc} some memory, or
+@code{open} a file) that needs to be undone later (e.g., @code{xfree}
+the memory or @code{close} the file), it can make a cleanup. The
+cleanup will be done at some future point: when the command is finished
+and control returns to the top level; when an error occurs and the stack
+is unwound; or when your code decides it's time to explicitly perform
+cleanups. Alternatively you can elect to discard the cleanups you
+created.
+
+Syntax:
+
+@table @code
+@item struct cleanup *@var{old_chain};
+Declare a variable which will hold a cleanup chain handle.
+
+@findex make_cleanup
+@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
+Make a cleanup which will cause @var{function} to be called with
+@var{arg} (a @code{char *}) later. The result, @var{old_chain}, is a
+handle that can later be passed to @code{do_cleanups} or
+@code{discard_cleanups}. Unless you are going to call
+@code{do_cleanups} or @code{discard_cleanups}, you can ignore the result
+from @code{make_cleanup}.
+
+@findex do_cleanups
+@item do_cleanups (@var{old_chain});
+Do all cleanups added to the chain since the corresponding
+@code{make_cleanup} call was made.
+
+@findex discard_cleanups
+@item discard_cleanups (@var{old_chain});
+Same as @code{do_cleanups} except that it just removes the cleanups from
+the chain and does not call the specified functions.
+@end table
+
+Cleanups are implemented as a chain. The handle returned by
+@code{make_cleanups} includes the cleanup passed to the call and any
+later cleanups appended to the chain (but not yet discarded or
+performed). E.g.:
+
+@smallexample
+make_cleanup (a, 0);
+@{
+ struct cleanup *old = make_cleanup (b, 0);
+ make_cleanup (c, 0)
+ ...
+ do_cleanups (old);
+@}
+@end smallexample
+
+@noindent
+will call @code{c()} and @code{b()} but will not call @code{a()}. The
+cleanup that calls @code{a()} will remain in the cleanup chain, and will
+be done later unless otherwise discarded.@refill
+
+Your function should explicitly do or discard the cleanups it creates.
+Failing to do this leads to non-deterministic behavior since the caller
+will arbitrarily do or discard your functions cleanups. This need leads
+to two common cleanup styles.
+
+The first style is try/finally. Before it exits, your code-block calls
+@code{do_cleanups} with the old cleanup chain and thus ensures that your
+code-block's cleanups are always performed. For instance, the following
+code-segment avoids a memory leak problem (even when @code{error} is
+called and a forced stack unwind occurs) by ensuring that the
+@code{xfree} will always be called:
+
+@smallexample
+struct cleanup *old = make_cleanup (null_cleanup, 0);
+data = xmalloc (sizeof blah);
+make_cleanup (xfree, data);
+... blah blah ...
+do_cleanups (old);
+@end smallexample
+
+The second style is try/except. Before it exits, your code-block calls
+@code{discard_cleanups} with the old cleanup chain and thus ensures that
+any created cleanups are not performed. For instance, the following
+code segment, ensures that the file will be closed but only if there is
+an error:
+
+@smallexample
+FILE *file = fopen ("afile", "r");
+struct cleanup *old = make_cleanup (close_file, file);
+... blah blah ...
+discard_cleanups (old);
+return file;
+@end smallexample
+
+Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify
+that they ``should not be called when cleanups are not in place''. This
+means that any actions you need to reverse in the case of an error or
+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 Per-architecture module data
+@cindex per-architecture module data
+@cindex multi-arch data
+@cindex data-pointer, per-architecture/per-module
+
+The multi-arch framework includes a mechanism for adding module specific
+per-architecture data-pointers to the @code{struct gdbarch} architecture
+object.
+
+A module registers one or more per-architecture data-pointers using the
+function @code{register_gdbarch_data}:
+
+@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free})
+
+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}.
+
+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.
+
+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.
+
+@end deftypefun
+
+A typical module has @code{init} and @code{free} functions of the form:
+
+@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
+
+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.
+
+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
+
+The per-architecture data-pointer is accessed using the function:
+
+@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
+
+The non-@code{NULL} data-pointer returned by @code{gdbarch_data} should
+be saved in a local variable and then used directly:
+
+@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}.
+
+@value{GDBN} uses the function @code{xfree} to return memory to the
+memory pool. Consistent with ISO-C, this function ignores a request to
+free a @code{NULL} pointer.
+
+@emph{Pragmatics: On some systems @code{free} fails when passed a
+@code{NULL} pointer.}
+
+@value{GDBN} can use the non-portable function @code{alloca} for the
+allocation of small temporary values (such as strings).
+
+@emph{Pragmatics: This function is very non-portable. Some systems
+restrict the memory being allocated to no more than a few kilobytes.}
+
+@value{GDBN} uses the string function @code{xstrdup} and the print
+function @code{xasprintf}.
+
+@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
+functions such as @code{sprintf} are very prone to buffer overflow
+errors.}
+
+
+@subsection Compiler Warnings
+@cindex compiler warnings
+
+With few exceptions, developers should include the configuration option
+@samp{--enable-gdb-build-warnings=,-Werror} when building @value{GDBN}.
+The exceptions are listed in the file @file{gdb/MAINTAINERS}.
+
+This option causes @value{GDBN} (when built using GCC) to be compiled
+with a carefully selected list of compiler warning flags. Any warnings
+from those flags being treated as errors.
+
+The current list of warning flags includes:
+
+@table @samp
+@item -Wimplicit
+Since @value{GDBN} coding standard requires all functions to be declared
+using a prototype, the flag has the side effect of ensuring that
+prototyped functions are always visible with out resorting to
+@samp{-Wstrict-prototypes}.
+
+@item -Wreturn-type
+Such code often appears to work except on instruction set architectures
+that use register windows.
+
+@item -Wcomment
+
+@item -Wtrigraphs
+
+@item -Wformat
+Since @value{GDBN} uses the @code{format printf} attribute on all
+@code{printf} like functions this checks not just @code{printf} calls
+but also calls to functions such as @code{fprintf_unfiltered}.
+
+@item -Wparentheses
+This warning includes uses of the assignment operator within an
+@code{if} statement.
+
+@item -Wpointer-arith
+
+@item -Wuninitialized
+@end table
+
+@emph{Pragmatics: Due to the way that @value{GDBN} is implemented most
+functions have unused parameters. Consequently the warning
+@samp{-Wunused-parameter} is precluded from the list. The macro
+@code{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---
+it is not an error to have @code{ATTRIBUTE_UNUSED} on a parameter that
+is being used. The options @samp{-Wall} and @samp{-Wunused} are also
+precluded because they both include @samp{-Wunused-parameter}.}
+
+@emph{Pragmatics: @value{GDBN} has not simply accepted the warnings
+enabled by @samp{-Wall -Werror -W...}. Instead it is selecting warnings
+when and where their benefits can be demonstrated.}
+
+@subsection Formatting
+
+@cindex source code formatting
+The standard GNU recommendations for formatting must be followed
+strictly.
+
+A function declaration should not have its name in column zero. A
+function definition should have its name in column zero.
+
+@smallexample
+/* Declaration */
+static void foo (void);
+/* Definition */
+void
+foo (void)
+@{
+@}
+@end smallexample
+
+@emph{Pragmatics: This simplifies scripting. Function definitions can
+be found using @samp{^function-name}.}
+
+There must be a space between a function or macro name and the opening
+parenthesis of its argument list (except for macro definitions, as
+required by C). There must not be a space after an open paren/bracket
+or before a close paren/bracket.
+
+While additional whitespace is generally helpful for reading, do not use
+more than one blank line to separate blocks, and avoid adding whitespace
+after the end of a program line (as of 1/99, some 600 lines had
+whitespace after the semicolon). Excess whitespace causes difficulties
+for @code{diff} and @code{patch} utilities.
+
+Pointers are declared using the traditional K&R C style:
+
+@smallexample
+void *foo;
+@end smallexample
+
+@noindent
+and not:
+
+@smallexample
+void * foo;
+void* foo;
+@end smallexample
+
+@subsection Comments
+
+@cindex comment formatting
+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{*}:
+
+@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 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.)
+
+Put a blank line between the block comments preceding function or
+variable definitions, and the definition itself.
+
+In general, put function-body comments on lines by themselves, rather
+than trying to fit them into the 20 characters left at the end of a
+line, since either the comment or the code will inevitably get longer
+than will fit, and then somebody will have to move it anyhow.
+
+@subsection C Usage
+
+@cindex C data types
+Code must not depend on the sizes of C data types, the format of the
+host's floating point numbers, the alignment of anything, or the order
+of evaluation of expressions.
+
+@cindex function usage
+Use functions freely. There are only a handful of compute-bound areas
+in @value{GDBN} that might be affected by the overhead of a function
+call, mainly in symbol reading. Most of @value{GDBN}'s performance is
+limited by the target interface (whether serial line or system call).
+
+However, use functions with moderation. A thousand one-line functions
+are just as hard to understand as a single thousand-line function.
+
+@emph{Macros are bad, M'kay.}
+(But if you have to use a macro, make sure that the macro arguments are
+protected with parentheses.)
+
+@cindex types
+
+Declarations like @samp{struct foo *} should be used in preference to
+declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
+
+
+@subsection Function Prototypes
+@cindex function prototypes
+
+Prototypes must be used when both @emph{declaring} and @emph{defining}
+a function. Prototypes for @value{GDBN} functions must include both the
+argument type and name, with the name matching that used in the actual
+function definition.
+
+All external functions should have a declaration in a header file that
+callers include, except for @code{_initialize_*} functions, which must
+be external so that @file{init.c} construction works, but shouldn't be
+visible to random source files.
+
+Where a source file needs a forward declaration of a static function,
+that declaration must appear in a block near the top of the source file.
+
+
+@subsection Internal Error Recovery
+
+During its execution, @value{GDBN} can encounter two types of errors.
+User errors and internal errors. User errors include not only a user
+entering an incorrect command but also problems arising from corrupt
+object files and system errors when interacting with the target.
+Internal errors include situations where @value{GDBN} has detected, at
+run time, a corrupt or erroneous situation.
+
+When reporting an internal error, @value{GDBN} uses
+@code{internal_error} and @code{gdb_assert}.
+
+@value{GDBN} must not call @code{abort} or @code{assert}.
+
+@emph{Pragmatics: There is no @code{internal_warning} function. Either
+the code detected a user error, recovered from it and issued a
+@code{warning} or the code failed to correctly recover from the user
+error and issued an @code{internal_error}.}
+
+@subsection File Names
+
+Any file used when building the core of @value{GDBN} must be in lower
+case. Any file used when building the core of @value{GDBN} must be 8.3
+unique. These requirements apply to both source and generated files.
+
+@emph{Pragmatics: The core of @value{GDBN} must be buildable on many
+platforms including DJGPP and MacOS/HFS. Every time an unfriendly file
+is introduced to the build process both @file{Makefile.in} and
+@file{configure.in} need to be modified accordingly. Compare the
+convoluted conversion process needed to transform @file{COPYING} into
+@file{copying.c} with the conversion needed to transform
+@file{version.in} into @file{version.c}.}
+
+Any file non 8.3 compliant file (that is not used when building the core
+of @value{GDBN}) must be added to @file{gdb/config/djgpp/fnchange.lst}.
+
+@emph{Pragmatics: This is clearly a compromise.}
+
+When @value{GDBN} has a local version of a system header file (ex
+@file{string.h}) the file name based on the POSIX header prefixed with
+@file{gdb_} (@file{gdb_string.h}).
+
+For other files @samp{-} is used as the separator.
+
+
+@subsection Include Files
+
+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.
+
+An external declaration should only appear in one include file.
+
+An external declaration should never appear in a @code{.c} file.
+Exception: a declaration for the @code{_initialize} function that
+pacifies @option{-Wmissing-declaration}.
+
+A @code{typedef} definition should only appear in one include file.
+
+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.
+
+All @file{.h} files should be wrapped in:
+
+@smallexample
+#ifndef INCLUDE_FILE_NAME_H
+#define INCLUDE_FILE_NAME_H
+header body
+#endif
+@end smallexample
+
+
+@subsection Clean Design and Portable Implementation
+
+@cindex design
+In addition to getting the syntax right, there's the little question of
+semantics. Some things are done in certain ways in @value{GDBN} because long
+experience has shown that the more obvious ways caused various kinds of
+trouble.
+
+@cindex assumptions about targets
+You can't assume the byte order of anything that comes from a target
+(including @var{value}s, object files, and instructions). Such things
+must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in
+@value{GDBN}, or one of the swap routines defined in @file{bfd.h},
+such as @code{bfd_get_32}.
+
+You can't assume that you know what interface is being used to talk to
+the target system. All references to the target must go through the
+current @code{target_ops} vector.
+
+You can't assume that the host and target machines are the same machine
+(except in the ``native'' support modules). In particular, you can't
+assume that the target machine's header files will be available on the
+host machine. Target code must bring along its own header files --
+written from scratch or explicitly donated by their owner, to avoid
+copyright problems.
+
+@cindex portability
+Insertion of new @code{#ifdef}'s will be frowned upon. It's much better
+to write the code portably than to conditionalize it for various
+systems.
+
+@cindex system dependencies
+New @code{#ifdef}'s which test for specific compilers or manufacturers
+or operating systems are unacceptable. All @code{#ifdef}'s should test
+for features. The information about which configurations contain which
+features should be segregated into the configuration files. Experience
+has proven far too often that a feature unique to one particular system
+often creeps into other systems; and that a conditional based on some
+predefined macro for your current system will become worthless over
+time, as new versions of your system come out that behave differently
+with regard to this feature.
+
+Adding code that handles specific architectures, operating systems,
+target interfaces, or hosts, is not acceptable in generic code.
+
+@cindex portable file name handling
+@cindex file names, portability
+One particularly notorious area where system dependencies tend to
+creep in is handling of file names. The mainline @value{GDBN} code
+assumes Posix semantics of file names: absolute file names begin with
+a forward slash @file{/}, slashes are used to separate leading
+directories, case-sensitive file names. These assumptions are not
+necessarily true on non-Posix systems such as MS-Windows. To avoid
+system-dependent code where you need to take apart or construct a file
+name, use the following portable macros:
+
+@table @code
+@findex HAVE_DOS_BASED_FILE_SYSTEM
+@item HAVE_DOS_BASED_FILE_SYSTEM
+This preprocessing symbol is defined to a non-zero value on hosts
+whose filesystems belong to the MS-DOS/MS-Windows family. Use this
+symbol to write conditional code which should only be compiled for
+such hosts.
+
+@findex IS_DIR_SEPARATOR
+@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
+pass.
+
+@findex IS_ABSOLUTE_PATH
+@item IS_ABSOLUTE_PATH (@var{file})
+Evaluates to a non-zero value if @var{file} is an absolute file name.
+For Unix and GNU/Linux hosts, a name which begins with a slash
+@file{/} is absolute. On DOS and Windows, @file{d:/foo} and
+@file{x:\bar} are also absolute file names.
+
+@findex FILENAME_CMP
+@item FILENAME_CMP (@var{f1}, @var{f2})
+Calls a function which compares file names @var{f1} and @var{f2} as
+appropriate for the underlying host filesystem. For Posix systems,
+this simply calls @code{strcmp}; on case-insensitive filesystems it
+will call @code{strcasecmp} instead.
+
+@findex DIRNAME_SEPARATOR
+@item DIRNAME_SEPARATOR
+Evaluates to a character which separates directories in
+@code{PATH}-style lists, typically held in environment variables.
+This character is @samp{:} on Unix, @samp{;} on DOS and Windows.
+
+@findex SLASH_STRING
+@item SLASH_STRING
+This evaluates to a constant string you should use to produce an
+absolute filename from leading directories and the file's basename.
+@code{SLASH_STRING} is @code{"/"} on most systems, but might be
+@code{"\\"} for some Windows-based ports.
+@end table
+
+In addition to using these macros, be sure to use portable library
+functions whenever possible. For example, to extract a directory or a
+basename part from a file name, use the @code{dirname} and
+@code{basename} library functions (available in @code{libiberty} for
+platforms which don't provide them), instead of searching for a slash
+with @code{strrchr}.
+
+Another way to generalize @value{GDBN} along a particular interface is with an
+attribute struct. For example, @value{GDBN} has been generalized to handle
+multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but
+by defining the @code{target_ops} structure and having a current target (as
+well as a stack of targets below it, for memory references). Whenever
+something needs to be done that depends on which remote interface we are
+using, a flag in the current target_ops structure is tested (e.g.,
+@code{target_has_stack}), or a function is called through a pointer in the
+current target_ops structure. In this way, when a new remote interface
+is added, only one module needs to be touched---the one that actually
+implements the new remote interface. Other examples of
+attribute-structs are BFD access to multiple kinds of object file
+formats, or @value{GDBN}'s access to multiple source languages.
+
+Please avoid duplicating code. For example, in @value{GDBN} 3.x all
+the code interfacing between @code{ptrace} and the rest of
+@value{GDBN} was duplicated in @file{*-dep.c}, and so changing
+something was very painful. In @value{GDBN} 4.x, these have all been
+consolidated into @file{infptrace.c}. @file{infptrace.c} can deal
+with variations between systems the same way any system-independent
+file would (hooks, @code{#if defined}, etc.), and machines which are
+radically different don't need to use @file{infptrace.c} at all.
+
+All debugging code must be controllable using the @samp{set debug
+@var{module}} command. Do not use @code{printf} to print trace
+messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use
+@code{#ifdef DEBUG}.
+
+
+@node Porting GDB
+
+@chapter Porting @value{GDBN}
+@cindex porting to new machines
+
+Most of the work in making @value{GDBN} compile on a new machine is in
+specifying the configuration of the machine. This is done in a
+dizzying variety of header files and configuration scripts, which we
+hope to make more sensible soon. Let's say your new host is called an
+@var{xyz} (e.g., @samp{sun4}), and its full three-part configuration
+name is @code{@var{arch}-@var{xvend}-@var{xos}} (e.g.,
+@samp{sparc-sun-sunos4}). In particular:
+
+@itemize @bullet
+@item
+In the top level directory, edit @file{config.sub} and add @var{arch},
+@var{xvend}, and @var{xos} to the lists of supported architectures,
+vendors, and operating systems near the bottom of the file. Also, add
+@var{xyz} as an alias that maps to
+@code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by
+running
+
+@smallexample
+./config.sub @var{xyz}
+@end smallexample
+
+@noindent
+and
+
+@smallexample
+./config.sub @code{@var{arch}-@var{xvend}-@var{xos}}
+@end smallexample
+
+@noindent
+which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}}
+and no error messages.
+
+@noindent
+You need to port BFD, if that hasn't been done already. Porting BFD is
+beyond the scope of this manual.
+
+@item
+To configure @value{GDBN} itself, edit @file{gdb/configure.host} to recognize
+your system and set @code{gdb_host} to @var{xyz}, and (unless your
+desired target is already available) also edit @file{gdb/configure.tgt},
+setting @code{gdb_target} to something appropriate (for instance,
+@var{xyz}).
+
+@emph{Maintainer's note: Work in progress. The file
+@file{gdb/configure.host} originally needed to be modified when either a
+new native target or a new host machine was being added to @value{GDBN}.
+Recent changes have removed this requirement. The file now only needs
+to be modified when adding a new native configuration. This will likely
+changed again in the future.}
+
+@item
+Finally, you'll need to specify and define @value{GDBN}'s host-, native-, and
+target-dependent @file{.h} and @file{.c} files used for your
+configuration.
+@end itemize
+
+@section Configuring @value{GDBN} for Release
+
+@cindex preparing a release
+@cindex making a distribution tarball
+From the top level directory (containing @file{gdb}, @file{bfd},
+@file{libiberty}, and so on):
+
+@smallexample
+make -f Makefile.in gdb.tar.gz
+@end smallexample
+
+@noindent
+This will properly configure, clean, rebuild any files that are
+distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
+and will then make a tarfile. (If the top level directory has already
+been configured, you can just do @code{make gdb.tar.gz} instead.)
+
+This procedure requires:
+
+@itemize @bullet
+
+@item
+symbolic links;
+
+@item
+@code{makeinfo} (texinfo2 level);
+
+@item
+@TeX{};
+
+@item
+@code{dvips};
+
+@item
+@code{yacc} or @code{bison}.
+@end itemize
+
+@noindent
+@dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
+
+@subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
+
+@file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
+which are not yet a default for anything (but we have to start using
+them sometime).
+
+For making paper, the only thing this implies is the right generation of
+@file{texinfo.tex} needs to be included in the distribution.
+
+For making info files, however, rather than duplicating the texinfo2
+distribution, generate @file{gdb-all.texinfo} locally, and include the
+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 Versions and Branches
+
+@subsection Version Identifiers
+
+@value{GDBN}'s version is determined by the file @file{gdb/version.in}.
+
+@value{GDBN}'s mainline uses ISO dates to differentiate between
+versions. The CVS repository uses @var{YYYY}-@var{MM}-@var{DD}-cvs
+while the corresponding snapshot uses @var{YYYYMMDD}.
+
+@value{GDBN}'s release branch uses a slightly more complicated scheme.
+When the branch is first cut, the mainline version identifier is
+prefixed with the @var{major}.@var{minor} from of the previous release
+series but with .90 appended. As draft releases are drawn from the
+branch, the minor minor number (.90) is incremented. Once the first
+release (@var{M}.@var{N}) has been made, the version prefix is updated
+to @var{M}.@var{N}.0.90 (dot zero, dot ninety). Follow on releases have
+an incremented minor minor version number (.0).
+
+Using 5.1 (previous) and 5.2 (current), the example below illustrates a
+typical sequence of version identifiers:
+
+@table @asis
+@item 5.1.1
+final release from previous branch
+@item 2002-03-03-cvs
+main-line the day the branch is cut
+@item 5.1.90-2002-03-03-cvs
+corresponding branch version
+@item 5.1.91
+first draft release candidate
+@item 5.1.91-2002-03-17-cvs
+updated branch version
+@item 5.1.92
+second draft release candidate
+@item 5.1.92-2002-03-31-cvs
+updated branch version
+@item 5.1.93
+final release candidate (see below)
+@item 5.2
+official release
+@item 5.2.0.90-2002-04-07-cvs
+updated CVS branch version
+@item 5.2.1
+second official release
+@end table
+
+Notes:
+
+@itemize @bullet
+@item
+Minor minor minor draft release candidates such as 5.2.0.91 have been
+omitted from the example. Such release candidates are, typically, never
+made.
+@item
+For 5.1.93 the bziped tar ball @file{gdb-5.1.93.tar.bz2} is just the
+official @file{gdb-5.2.tar} renamed and compressed.
+@end itemize
+
+To avoid version conflicts, vendors are expected to modify the file
+@file{gdb/version.in} to include a vendor unique alphabetic identifier
+(an official @value{GDBN} release never uses alphabetic characters in
+its version identifer).
+
+Since @value{GDBN} does not make minor minor minor releases (e.g.,
+5.1.0.1) the conflict between that and a minor minor draft release
+identifier (e.g., 5.1.0.90) is avoided.
+
+
+@subsection Branches
+
+@value{GDBN} draws a release series (5.2, 5.2.1, @dots{}) from a single
+release branch (gdb_5_2-branch). Since minor minor minor releases
+(5.1.0.1) are not made, the need to branch the release branch is avoided
+(it also turns out that the effort required for such a a branch and
+release is significantly greater than the effort needed to create a new
+release from the head of the release branch).
+
+Releases 5.0 and 5.1 used branch and release tags of the form:
+
+@smallexample
+gdb_N_M-YYYY-MM-DD-branchpoint
+gdb_N_M-YYYY-MM-DD-branch
+gdb_M_N-YYYY-MM-DD-release
+@end smallexample
+
+Release 5.2 is trialing the branch and release tags:
+
+@smallexample
+gdb_N_M-YYYY-MM-DD-branchpoint
+gdb_N_M-branch
+gdb_M_N-YYYY-MM-DD-release
+@end smallexample
+
+@emph{Pragmatics: The branchpoint and release tags need to identify when
+a branch and release are made. The branch tag, denoting the head of the
+branch, does not have this criteria.}
+
+
+@section Branch Commit Policy
+
+The branch commit policy is pretty slack. @value{GDBN} releases 5.0,
+5.1 and 5.2 all used the below:
+
+@itemize @bullet
+@item
+The @file{gdb/MAINTAINERS} file still holds.
+@item
+Don't fix something on the branch unless/until it is also fixed in the
+trunk. If this isn't possible, mentioning it in the @file{gdb/PROBLEMS}
+file is better than committing a hack.
+@item
+When considering a patch for the branch, suggested criteria include:
+Does it fix a build? Does it fix the sequence @kbd{break main; run}
+when debugging a static binary?
+@item
+The further a change is from the core of @value{GDBN}, the less likely
+the change will worry anyone (e.g., target specific code).
+@item
+Only post a proposal to change the core of @value{GDBN} after you've
+sent individual bribes to all the people listed in the
+@file{MAINTAINERS} file @t{;-)}
+@end itemize
+
+@emph{Pragmatics: Provided updates are restricted to non-core
+functionality there is little chance that a broken change will be fatal.
+This means that changes such as adding a new architectures or (within
+reason) support for a new host are considered acceptable.}
+
+
+@section Obsoleting code
+
+Before anything else, poke the other developers (and around the source
+code) to see if there is anything that can be removed from @value{GDBN}
+(an old target, an unused file).
+
+Obsolete code is identified by adding an @code{OBSOLETE} prefix to every
+line. Doing this means that it is easy to identify something that has
+been obsoleted when greping through the sources.
+
+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
+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 or so.
+@item
+Post the proposal on @email{gdb-announce@@sources.redhat.com, the GDB
+Announcement mailing list}.
+@item
+Wait a week or so.
+@item
+Go through and edit all relevant files and lines so that they are
+prefixed with the word @code{OBSOLETE}.
+@item
+Wait until the next GDB version, containing this obsolete code, has been
+released.
+@item
+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}
+
+People always forget. Send a post reminding them but also if you know
+something interesting happened add it yourself. The @code{schedule}
+script will mention this in its e-mail.
+
+@subheading Review @file{gdb/README}
+
+Grab one of the nightly snapshots and then walk through the
+@file{gdb/README} looking for anything that can be improved. The
+@code{schedule} script will mention this in its e-mail.
+
+@subheading Refresh any imported files.
+
+A number of files are taken from external repositories. They include:
+
+@itemize @bullet
+@item
+@file{texinfo/texinfo.tex}
+@item
+@file{config.guess} et.@: al.@: (see the top-level @file{MAINTAINERS}
+file)
+@item
+@file{etc/standards.texi}, @file{etc/make-stds.texi}
+@end itemize
+
+@subheading Check the ARI
+
+@uref{http://sources.redhat.com/gdb/ari,,A.R.I.} is an @code{awk} script
+(Awk Regression Index ;-) that checks for a number of errors and coding
+conventions. The checks include things like using @code{malloc} instead
+of @code{xmalloc} and file naming problems. There shouldn't be any
+regressions.
+
+@subsection Review the bug data base
+
+Close anything obviously fixed.
+
+@subsection Check all cross targets build
+
+The targets are listed in @file{gdb/MAINTAINERS}.
+
+
+@section Cut the Branch
+
+@subheading Create the branch
+
+@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 smallexample
+
+@itemize @bullet
+@item
+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
+Insight (which includes GDB) and dejagnu are all tagged at the same time
+@item
+@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 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
+
+The process of creating and then making available a release is broken
+down into a number of stages. The first part addresses the technical
+process of creating a releasable tar ball. The later stages address the
+process of releasing that tar ball.
+
+When making a release candidate just the first section is needed.
+
+@subsection Create a release candidate
+
+The objective at this stage is to create a set of tar balls that can be
+made available as a formal release (or as a less formal release
+candidate).
+
+@subsubheading Freeze the branch
+
+Send out an e-mail notifying everyone that the branch is frozen to
+@email{gdb-patches@@sources.redhat.com}.
+
+@subsubheading Establish a few defaults.
+
+@smallexample
+$ b=gdb_5_2-branch
+$ v=5.2
+$ t=/sourceware/snapshot-tmp/gdbadmin-tmp
+$ echo $t/$b/$v
+/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
+$ mkdir -p $t/$b/$v
+$ cd $t/$b/$v
+$ pwd
+/sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_2-branch/5.2
+$ which autoconf
+/home/gdbadmin/bin/autoconf
+$
+@end smallexample
+
+@noindent
+Notes:
+
+@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
+
+@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 smallexample
+
+@noindent
+Note:
+
+@itemize @bullet
+@item
+The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't
+any confusion between what is written here and what your local
+@code{cvs} really does.
+@end itemize
+
+@subsubheading Update relevant files.
+
+@table @file
+
+@item gdb/NEWS
+
+Major releases get their comments added as part of the mainline. Minor
+releases should probably mention any significant bugs that were fixed.
+
+Don't forget to include the @file{ChangeLog} entry.
+
+@smallexample
+$ emacs gdb/src/gdb/NEWS
+...
+c-x 4 a
+...
+c-x c-s c-x c-c
+$ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS
+$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
+@end smallexample
+
+@item gdb/README
+
+You'll need to update:
+
+@itemize @bullet
+@item
+the version
+@item
+the update date
+@item
+who did it
+@end itemize
+
+@smallexample
+$ emacs gdb/src/gdb/README
+...
+c-x 4 a
+...
+c-x c-s c-x c-c
+$ cp gdb/src/gdb/README insight/src/gdb/README
+$ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
+@end smallexample
+
+@emph{Maintainer note: Hopefully the @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.}
+
+@item gdb/version.in
+
+@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 smallexample
+
+@item dejagnu/src/dejagnu/configure.in
+
+Dejagnu is more complicated. The version number is a parameter to
+@code{AM_INIT_AUTOMAKE}. Tweak it to read something like gdb-5.1.91.
+
+Don't forget to re-generate @file{configure}.
+
+Don't forget to include a @file{ChangeLog} entry.
+
+@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
+
+@end table
+
+@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 )
+done
+$ ( m=dejagnu; cd $m/src && gmake -f Makefile.in $m.tar.bz2 )
+@end smallexample
+
+@subsubheading Check the source files
+
+You're looking for files that have mysteriously disappeared.
+@kbd{distclean} has the habit of deleting files it shouldn't. Watch out
+for the @file{version.in} update @kbd{cronjob}.
+
+@smallexample
+$ ( cd gdb/src && cvs -f -q -n update )
+M djunpack.bat
+? gdb-5.1.91.tar
+? proto-toplev
+@dots{} lots of generated files @dots{}
+M gdb/ChangeLog
+M gdb/NEWS
+M gdb/README
+M gdb/version.in
+@dots{} lots of generated files @dots{}
+$
+@end smallexample
+
+@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.}
+
+@subsubheading Create compressed versions of the release
+
+@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
+
+@subsection Sanity check the tar ball
+
+Pick a popular machine (Solaris/PPC?) and try the build on that.
+
+@smallexample
+$ bunzip2 < gdb-5.2.tar.bz2 | tar xpf -
+$ cd gdb-5.2
+$ ./configure
+$ make
+@dots{}
+$ ./gdb/gdb ./gdb/gdb
+GNU gdb 5.2
+@dots{}
+(gdb) b main
+Breakpoint 1 at 0x80732bc: file main.c, line 734.
+(gdb) run
+Starting program: /tmp/gdb-5.2/gdb/gdb
+
+Breakpoint 1, main (argc=1, argv=0xbffff8b4) at main.c:734
+734 catch_errors (captured_main, &args, "", RETURN_MASK_ALL);
+(gdb) print args
+$1 = @{argc = 136426532, argv = 0x821b7f0@}
+(gdb)
+@end smallexample
+
+@subsection Make a release candidate available
+
+If this is a release candidate then the only remaining steps are:
+
+@enumerate
+@item
+Commit @file{version.in} and @file{ChangeLog}
+@item
+Tweak @file{version.in} (and @file{ChangeLog} to read
+@var{L}.@var{M}.@var{N}-0000-00-00-cvs so that the version update
+process can restart.
+@item
+Make the release candidate available in
+@uref{ftp://sources.redhat.com/pub/gdb/snapshots/branch}
+@item
+Notify the relevant mailing lists ( @email{gdb@@sources.redhat.com} and
+@email{gdb-testers@@sources.redhat.com} that the candidate is available.
+@end enumerate
+
+@subsection Make a formal release available
+
+(And you thought all that was required was to post an e-mail.)
+
+@subsubheading Install on sware
+
+Copy the new files to both the release and the old release directory:
+
+@smallexample
+$ cp *.bz2 *.gz ~ftp/pub/gdb/old-releases/
+$ cp *.bz2 *.gz ~ftp/pub/gdb/releases
+@end smallexample
+
+@noindent
+Clean up the releases directory so that only the most recent releases
+are available (e.g. keep 5.2 and 5.2.1 but remove 5.1):
+
+@smallexample
+$ cd ~ftp/pub/gdb/releases
+$ rm @dots{}
+@end smallexample
+
+@noindent
+Update the file @file{README} and @file{.message} in the releases
+directory:
+
+@smallexample
+$ vi README
+@dots{}
+$ rm -f .message
+$ ln README .message
+@end smallexample
+
+@subsubheading Update the web pages.
+
+@table @file
+
+@item htdocs/download/ANNOUNCEMENT
+This file, which is posted as the official announcement, includes:
+@itemize @bullet
+@item
+General announcement
+@item
+News. If making an @var{M}.@var{N}.1 release, retain the news from
+earlier @var{M}.@var{N} release.
+@item
+Errata
+@end itemize
+
+@item htdocs/index.html
+@itemx htdocs/news/index.html
+@itemx htdocs/download/index.html
+These files include:
+@itemize @bullet
+@item
+announcement of the most recent release
+@item
+news entry (remember to update both the top level and the news directory).
+@end itemize
+These pages also need to be regenerate using @code{index.sh}.
+
+@item download/onlinedocs/
+You need to find the magic command that is used to generate the online
+docs from the @file{.tar.bz2}. The best way is to look in the output
+from one of the nightly @code{cron} jobs and then just edit accordingly.
+Something like:
+
+@smallexample
+$ ~/ss/update-web-docs \
+ ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
+ $PWD/www \
+ /www/sourceware/htdocs/gdb/download/onlinedocs \
+ gdb
+@end smallexample
+
+@item download/ari/
+Just like the online documentation. Something like:
+
+@smallexample
+$ /bin/sh ~/ss/update-web-ari \
+ ~ftp/pub/gdb/releases/gdb-5.2.tar.bz2 \
+ $PWD/www \
+ /www/sourceware/htdocs/gdb/download/ari \
+ gdb
+@end smallexample
+
+@end table
+
+@subsubheading Shadow the pages onto gnu
+
+Something goes here.
+
+
+@subsubheading Install the @value{GDBN} tar ball on GNU
+
+At the time of writing, the GNU machine was @kbd{gnudist.gnu.org} in
+@file{~ftp/gnu/gdb}.
+
+@subsubheading Make the @file{ANNOUNCEMENT}
+
+Post the @file{ANNOUNCEMENT} file you created above to:
+
+@itemize @bullet
+@item
+@email{gdb-announce@@sources.redhat.com, GDB Announcement mailing list}
+@item
+@email{info-gnu@@gnu.org, General GNU Announcement list} (but delay it a
+day or so to let things get out)
+@item
+@email{bug-gdb@@gnu.org, GDB Bug Report mailing list}
+@end itemize
+
+@subsection Cleanup
+
+The release is out but you're still not finished.
+
+@subsubheading Commit outstanding changes
+
+In particular you'll need to commit any changes to:
+
+@itemize @bullet
+@item
+@file{gdb/ChangeLog}
+@item
+@file{gdb/version.in}
+@item
+@file{gdb/NEWS}
+@item
+@file{gdb/README}
+@end itemize
+
+@subsubheading Tag the release
+
+Something like:
+
+@smallexample
+$ d=`date -u +%Y-%m-%d`
+$ echo $d
+2002-01-24
+$ ( cd insight/src/gdb && cvs -f -q update )
+$ ( cd insight/src && cvs -f -q tag gdb_5_2-$d-release )
+@end smallexample
+
+Insight is used since that contains more of the release than
+@value{GDBN} (@code{dejagnu} doesn't get tagged but I think we can live
+with that).
+
+@subsubheading Mention the release on the trunk
+
+Just put something in the @file{ChangeLog} so that the trunk also
+indicates when the release was made.
+
+@subsubheading Restart @file{gdb/version.in}
+
+If @file{gdb/version.in} does not contain an ISO date such as
+@kbd{2002-01-24} then the daily @code{cronjob} won't update it. Having
+committed all the release changes it can be set to
+@file{5.2.0_0000-00-00-cvs} which will restart things (yes the @kbd{_}
+is important - it affects the snapshot process).
+
+Don't forget the @file{ChangeLog}.
+
+@subsubheading Merge into trunk
+
+The files committed to the branch may also need changes merged into the
+trunk.
+
+@subsubheading Revise the release schedule
+
+Post a revised release schedule to @email{gdb@@sources.redhat.com, GDB
+Discussion List} with an updated announcement. The schedule can be
+generated by running:
+
+@smallexample
+$ ~/ss/schedule `date +%s` schedule
+@end smallexample
+
+@noindent
+The first parameter is approximate date/time in seconds (from the epoch)
+of the most recent release.
+
+Also update the schedule @code{cronjob}.
+
+@section Post release
+
+Remove any @code{OBSOLETE} code.
+
+@node Testsuite
+
+@chapter Testsuite
+@cindex test suite
+
+The testsuite is an important component of the @value{GDBN} package.
+While it is always worthwhile to encourage user testing, in practice
+this is rarely sufficient; users typically use only a small subset of
+the available commands, and it has proven all too common for a change
+to cause a significant regression that went unnoticed for some time.
+
+The @value{GDBN} testsuite uses the DejaGNU testing framework.
+DejaGNU is built using @code{Tcl} and @code{expect}. The tests
+themselves are calls to various @code{Tcl} procs; the framework runs all the
+procs and summarizes the passes and fails.
+
+@section Using the Testsuite
+
+@cindex running the test suite
+To run the testsuite, simply go to the @value{GDBN} object directory (or to the
+testsuite's objdir) and type @code{make check}. This just sets up some
+environment variables and invokes DejaGNU's @code{runtest} script. While
+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:
+
+@smallexample
+ === gdb Summary ===
+
+# of expected passes 6016
+# of unexpected failures 58
+# of unexpected successes 5
+# of expected failures 183
+# of unresolved testcases 3
+# of untested testcases 5
+@end smallexample
+
+The ideal test run consists of expected passes only; however, reality
+conspires to keep us from this ideal. Unexpected failures indicate
+real problems, whether in @value{GDBN} or in the testsuite. Expected
+failures are still failures, but ones which have been decided are too
+hard to deal with at the time; for instance, a test case might work
+everywhere except on AIX, and there is no prospect of the AIX case
+being fixed in the near future. Expected failures should not be added
+lightly, since you may be masking serious bugs in @value{GDBN}.
+Unexpected successes are expected fails that are passing for some
+reason, while unresolved and untested cases often indicate some minor
+catastrophe, such as the compiler being unable to deal with a test
+program.
+
+When making any significant change to @value{GDBN}, you should run the
+testsuite before and after the change, to confirm that there are no
+regressions. Note that truly complete testing would require that you
+run the testsuite with all supported configurations and a variety of
+compilers; however this is more than really necessary. In many cases
+testing with a single configuration is sufficient. Other useful
+options are to test one big-endian (Sparc) and one little-endian (x86)
+host, a cross config with a builtin simulator (powerpc-eabi,
+mips-elf), or a 64-bit host (Alpha).
+
+If you add new functionality to @value{GDBN}, please consider adding
+tests for it as well; this way future @value{GDBN} hackers can detect
+and fix their changes that break the functionality you added.
+Similarly, if you fix a bug that was not previously reported as a test
+failure, please add a test case for it. Some cases are extremely
+difficult to test, such as code that handles host OS failures or bugs
+in particular versions of compilers, and it's OK not to try to write
+tests for all of those.
+
+@section Testsuite Organization
+
+@cindex test suite organization
+The testsuite is entirely contained in @file{gdb/testsuite}. While the
+testsuite includes some makefiles and configury, these are very minimal,
+and used for little besides cleaning up, since the tests themselves
+handle the compilation of the programs that @value{GDBN} will run. The file
+@file{testsuite/lib/gdb.exp} contains common utility procs useful for
+all @value{GDBN} tests, while the directory @file{testsuite/config} contains
+configuration-specific files, typically used for special-purpose
+definitions of procs like @code{gdb_load} and @code{gdb_start}.
+
+The tests themselves are to be found in @file{testsuite/gdb.*} and
+subdirectories of those. The names of the test files must always end
+with @file{.exp}. DejaGNU collects the test files by wildcarding
+in the test directories, so both subdirectories and individual files
+get chosen and run in alphabetical order.
+
+The following table lists the main types of subdirectories and what they
+are for. Since DejaGNU finds test files no matter where they are
+located, and since each test file sets up its own compilation and
+execution environment, this organization is simply for convenience and
+intelligibility.
+
+@table @file
+@item gdb.base
+This is the base testsuite. The tests in it should apply to all
+configurations of @value{GDBN} (but generic native-only tests may live here).
+The test programs should be in the subset of C that is valid K&R,
+ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance
+for prototypes).
+
+@item gdb.@var{lang}
+Language-specific tests for any language @var{lang} besides C. Examples are
+@file{gdb.c++} and @file{gdb.java}.
+
+@item gdb.@var{platform}
+Non-portable tests. The tests are specific to a specific configuration
+(host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for
+HP-UX.
+
+@item gdb.@var{compiler}
+Tests specific to a particular compiler. As of this writing (June
+1999), there aren't currently any groups of tests in this category that
+couldn't just as sensibly be made platform-specific, but one could
+imagine a @file{gdb.gcc}, for tests of @value{GDBN}'s handling of GCC
+extensions.
+
+@item gdb.@var{subsystem}
+Tests that exercise a specific @value{GDBN} subsystem in more depth. For
+instance, @file{gdb.disasm} exercises various disassemblers, while
+@file{gdb.stabs} tests pathways through the stabs symbol reader.
+@end table
+
+@section Writing Tests
+@cindex writing tests
+
+In many areas, the @value{GDBN} tests are already quite comprehensive; you
+should be able to copy existing tests to handle new cases.
+
+You should try to use @code{gdb_test} whenever possible, since it
+includes cases to handle all the unexpected errors that might happen.
+However, it doesn't cost anything to add new test procedures; for
+instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that
+calls @code{gdb_test} multiple times.
+
+Only use @code{send_gdb} and @code{gdb_expect} when absolutely
+necessary, such as when @value{GDBN} has several valid responses to a command.
+
+The source language programs do @emph{not} need to be in a consistent
+style. Since @value{GDBN} is used to debug programs written in many different
+styles, it's worth having a mix of styles in the testsuite; for
+instance, some @value{GDBN} bugs involving the display of source lines would
+never manifest themselves if the programs used GNU coding style
+uniformly.
+
+@node Hints
+
+@chapter Hints
+
+Check the @file{README} file, it often has useful information that does not
+appear anywhere else in the directory.
+
+@menu
+* Getting Started:: Getting started working on @value{GDBN}
+* Debugging GDB:: Debugging @value{GDBN} with itself
+@end menu
+
+@node Getting Started,,, Hints
+
+@section Getting Started
+
+@value{GDBN} is a large and complicated program, and if you first starting to
+work on it, it can be hard to know where to start. Fortunately, if you
+know how to go about it, there are ways to figure out what is going on.
+
+This manual, the @value{GDBN} Internals manual, has information which applies
+generally to many parts of @value{GDBN}.
+
+Information about particular functions or data structures are located in
+comments with those functions or data structures. If you run across a
+function or a global variable which does not have a comment correctly
+explaining what is does, this can be thought of as a bug in @value{GDBN}; feel
+free to submit a bug report, with a suggested comment if you can figure
+out what the comment should say. If you find a comment which is
+actually wrong, be especially sure to report that.
+
+Comments explaining the function of macros defined in host, target, or
+native dependent files can be in several places. Sometimes they are
+repeated every place the macro is defined. Sometimes they are where the
+macro is used. Sometimes there is a header file which supplies a
+default definition of the macro, and the comment is there. This manual
+also documents all the available macros.
+@c (@pxref{Host Conditionals}, @pxref{Target
+@c Conditionals}, @pxref{Native Conditionals}, and @pxref{Obsolete
+@c Conditionals})
+
+Start with the header files. Once you have some idea of how
+@value{GDBN}'s internal symbol tables are stored (see @file{symtab.h},
+@file{gdbtypes.h}), you will find it much easier to understand the
+code which uses and creates those symbol tables.
+
+You may wish to process the information you are getting somehow, to
+enhance your understanding of it. Summarize it, translate it to another
+language, add some (perhaps trivial or non-useful) feature to @value{GDBN}, use
+the code to predict what a test case would do and write the test case
+and verify your prediction, etc. If you are reading code and your eyes
+are starting to glaze over, this is a sign you need to use a more active
+approach.
+
+Once you have a part of @value{GDBN} to start with, you can find more
+specifically the part you are looking for by stepping through each
+function with the @code{next} command. Do not use @code{step} or you
+will quickly get distracted; when the function you are stepping through
+calls another function try only to get a big-picture understanding
+(perhaps using the comment at the beginning of the function being
+called) of what it does. This way you can identify which of the
+functions being called by the function you are stepping through is the
+one which you are interested in. You may need to examine the data
+structures generated at each stage, with reference to the comments in
+the header files explaining what the data structures are supposed to
+look like.
+
+Of course, this same technique can be used if you are just reading the
+code, rather than actually stepping through it. The same general
+principle applies---when the code you are looking at calls something
+else, just try to understand generally what the code being called does,
+rather than worrying about all its details.
+
+@cindex command implementation
+A good place to start when tracking down some particular area is with
+a command which invokes that feature. Suppose you want to know how
+single-stepping works. As a @value{GDBN} user, you know that the
+@code{step} command invokes single-stepping. The command is invoked
+via command tables (see @file{command.h}); by convention the function
+which actually performs the command is formed by taking the name of
+the command and adding @samp{_command}, or in the case of an
+@code{info} subcommand, @samp{_info}. For example, the @code{step}
+command invokes the @code{step_command} function and the @code{info
+display} command invokes @code{display_info}. When this convention is
+not followed, you might have to use @code{grep} or @kbd{M-x
+tags-search} in emacs, or run @value{GDBN} on itself and set a
+breakpoint in @code{execute_command}.
+
+@cindex @code{bug-gdb} mailing list
+If all of the above fail, it may be appropriate to ask for information
+on @code{bug-gdb}. But @emph{never} post a generic question like ``I was
+wondering if anyone could give me some tips about understanding
+@value{GDBN}''---if we had some magic secret we would put it in this manual.
+Suggestions for improving the manual are always welcome, of course.
+
+@node Debugging GDB,,,Hints
+
+@section Debugging @value{GDBN} with itself
+@cindex debugging @value{GDBN}
+
+If @value{GDBN} is limping on your machine, this is the preferred way to get it
+fully functional. Be warned that in some ancient Unix systems, like
+Ultrix 4.2, a program can't be running in one process while it is being
+debugged in another. Rather than typing the command @kbd{@w{./gdb
+./gdb}}, which works on Suns and such, you can copy @file{gdb} to
+@file{gdb2} and then type @kbd{@w{./gdb ./gdb2}}.
+
+When you run @value{GDBN} in the @value{GDBN} source directory, it will read a
+@file{.gdbinit} file that sets up some simple things to make debugging
+gdb easier. The @code{info} command, when executed without a subcommand
+in a @value{GDBN} being debugged by gdb, will pop you back up to the top level
+gdb. See @file{.gdbinit} for details.
+
+If you use emacs, you will probably want to do a @code{make TAGS} after
+you configure your distribution; this will put the machine dependent
+routines for your local machine where they will be accessed first by
+@kbd{M-.}
+
+Also, make sure that you've either compiled @value{GDBN} with your local cc, or
+have run @code{fixincludes} if you are compiling with gcc.
+
+@section Submitting Patches
+
+@cindex submitting patches
+Thanks for thinking of offering your changes back to the community of
+@value{GDBN} users. In general we like to get well designed enhancements.
+Thanks also for checking in advance about the best way to transfer the
+changes.
+
+The @value{GDBN} maintainers will only install ``cleanly designed'' patches.
+This manual summarizes what we believe to be clean design for @value{GDBN}.
+
+If the maintainers don't have time to put the patch in when it arrives,
+or if there is any question about a patch, it goes into a large queue
+with everyone else's patches and bug reports.
+
+@cindex legal papers for code contributions
+The legal issue is that to incorporate substantial changes requires a
+copyright assignment from you and/or your employer, granting ownership
+of the changes to the Free Software Foundation. You can get the
+standard documents for doing this by sending mail to @code{gnu@@gnu.org}
+and asking for it. We recommend that people write in "All programs
+owned by the Free Software Foundation" as "NAME OF PROGRAM", so that
+changes in many programs (not just @value{GDBN}, but GAS, Emacs, GCC,
+etc) can be
+contributed with only one piece of legalese pushed through the
+bureaucracy and filed with the FSF. We can't start merging changes until
+this paperwork is received by the FSF (their rules, which we follow
+since we maintain it for them).
+
+Technically, the easiest way to receive changes is to receive each
+feature as a small context diff or unidiff, suitable for @code{patch}.
+Each message sent to me should include the changes to C code and
+header files for a single feature, plus @file{ChangeLog} entries for
+each directory where files were modified, and diffs for any changes
+needed to the manuals (@file{gdb/doc/gdb.texinfo} or
+@file{gdb/doc/gdbint.texinfo}). If there are a lot of changes for a
+single feature, they can be split down into multiple messages.
+
+In this way, if we read and like the feature, we can add it to the
+sources with a single patch command, do some testing, and check it in.
+If you leave out the @file{ChangeLog}, we have to write one. If you leave
+out the doc, we have to puzzle out what needs documenting. Etc., etc.
+
+The reason to send each change in a separate message is that we will not
+install some of the changes. They'll be returned to you with questions
+or comments. If we're doing our job correctly, the message back to you
+will say what you have to fix in order to make the change acceptable.
+The reason to have separate messages for separate features is so that
+the acceptable changes can be installed while one or more changes are
+being reworked. If multiple features are sent in a single message, we
+tend to not put in the effort to sort out the acceptable changes from
+the unacceptable, so none of the features get installed until all are
+acceptable.
+
+If this sounds painful or authoritarian, well, it is. But we get a lot
+of bug reports and a lot of patches, and many of them don't get
+installed because we don't have the time to finish the job that the bug
+reporter or the contributor could have done. Patches that arrive
+complete, working, and well designed, tend to get installed on the day
+they arrive. The others go into a queue and get installed as time
+permits, which, since the maintainers have many demands to meet, may not
+be for quite some time.
+
+Please send patches directly to
+@email{gdb-patches@@sources.redhat.com, the @value{GDBN} maintainers}.
+
+@section Obsolete Conditionals
+@cindex obsolete code
+
+Fragments of old code in @value{GDBN} sometimes reference or set the following
+configuration macros. They should not be used by new code, and old uses
+should be removed as those parts of the debugger are otherwise touched.
+
+@table @code
+@item STACK_END_ADDR
+This macro used to define where the end of the stack appeared, for use
+in interpreting core file formats that don't record this address in the
+core file itself. This information is now configured in BFD, and @value{GDBN}
+gets the info portably from there. The values in @value{GDBN}'s configuration
+files should be moved into BFD configuration files (if needed there),
+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!
+
+@end table
+
+@include fdl.texi
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+