\input texinfo @c -*- texinfo -*-
@setfilename gdbint.info
@include gdb-cfg.texi
-@dircategory Programming & development tools.
+@dircategory Software development
@direntry
* Gdb-Internals: (gdbint). The GNU debugger's internals.
@end direntry
* Support Libraries::
* Coding::
* Porting GDB::
+* Versions and Branches::
* Releasing GDB::
* Testsuite::
* Hints::
watched expression(s) after each instruction. The rest of this
section is mostly irrelevant for software watchpoints.
+When the inferior stops, @value{GDBN} tries to establish, among other
+possible reasons, whether it stopped due to a watchpoint being hit.
+For a data-write watchpoint, it does so by evaluating, for each
+watchpoint, the expression whose value is being watched, and testing
+whether the watched value has changed. For data-read and data-access
+watchpoints, @value{GDBN} needs the target to supply a primitive that
+returns the address of the data that was accessed or read (see the
+description of @code{target_stopped_data_address} below): if this
+primitive returns a valid address, @value{GDBN} infers that a
+watchpoint triggered if it watches an expression whose evaluation uses
+that address.
+
@value{GDBN} uses several macros and primitives to support hardware
watchpoints:
fall-back, in case @code{TARGET_REGION_OK_FOR_HW_WATCHPOINT} is not
defined.
-@findex TARGET_DISABLE_HW_WATCHPOINTS
-@item TARGET_DISABLE_HW_WATCHPOINTS (@var{pid})
-Disables watchpoints in the process identified by @var{pid}. This is
-used, e.g., on HP-UX which provides operations to disable and enable
-the page-level memory protection that implements hardware watchpoints
-on that platform.
-
-@findex TARGET_ENABLE_HW_WATCHPOINTS
-@item TARGET_ENABLE_HW_WATCHPOINTS (@var{pid})
-Enables watchpoints in the process identified by @var{pid}. This is
-used, e.g., on HP-UX which provides operations to disable and enable
-the page-level memory protection that implements hardware watchpoints
-on that platform.
-
+@cindex insert or remove hardware watchpoint
@findex target_insert_watchpoint
@findex target_remove_watchpoint
@item target_insert_watchpoint (@var{addr}, @var{len}, @var{type})
two macros can use them for their internal purposes.
@findex target_stopped_data_address
-@item target_stopped_data_address ()
-If the inferior has some watchpoint that triggered, return the address
-associated with that watchpoint. Otherwise, return zero.
+@item target_stopped_data_address (@var{addr_p})
+If the inferior has some watchpoint that triggered, place the address
+associated with the watchpoint at the location pointed to by
+@var{addr_p} and return non-zero. Otherwise, return zero. Note that
+this primitive is used by @value{GDBN} only on targets that support
+data-read or data-access type watchpoints, so targets that have
+support only for data-write watchpoints need not implement these
+primitives.
@findex HAVE_STEPPABLE_WATCHPOINT
@item HAVE_STEPPABLE_WATCHPOINT
@item STOPPED_BY_WATCHPOINT (@var{wait_status})
Return non-zero if stopped by a watchpoint. @var{wait_status} is of
the type @code{struct target_waitstatus}, defined by @file{target.h}.
+Normally, this macro is defined to invoke the function pointed to by
+the @code{to_stopped_by_watchpoint} member of the structure (of the
+type @code{target_ops}, defined on @file{target.h}) that describes the
+target-specific operations; @code{to_stopped_by_watchpoint} ignores
+the @var{wait_status} argument.
+
+@value{GDBN} does not require the non-zero value returned by
+@code{STOPPED_BY_WATCHPOINT} to be 100% correct, so if a target cannot
+determine for sure whether the inferior stopped due to a watchpoint,
+it could return non-zero ``just in case''.
@end table
@subsection x86 Watchpoints
processors.
@findex i386_stopped_data_address
-@item i386_stopped_data_address (void)
-The macros @code{STOPPED_BY_WATCHPOINT} and
-@code{target_stopped_data_address} are set to call this function. The
-argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This
+@item i386_stopped_data_address (@var{addr_p})
+The target function
+@code{target_stopped_data_address} is set to call this function.
+This
function examines the breakpoint condition bits in the DR6 Debug
Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
macro, and returns the address associated with the first bit that is
set in DR6.
+@findex i386_stopped_by_watchpoint
+@item i386_stopped_by_watchpoint (void)
+The macro @code{STOPPED_BY_WATCHPOINT}
+is set to call this function. The
+argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored. This
+function examines the breakpoint condition bits in the DR6 Debug
+Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
+macro, and returns true if any bit is set. Otherwise, false is
+returned.
+
@findex i386_insert_watchpoint
@findex i386_remove_watchpoint
@item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type})
@item i386_stopped_by_hwbp (void)
This function returns non-zero if the inferior has some watchpoint or
hardware breakpoint that triggered. It works like
-@code{i386_stopped_data_address}, except that it doesn't return the
+@code{i386_stopped_data_address}, except that it doesn't record the
address whose watchpoint triggered.
@findex i386_cleanup_dregs
@smallexample
annotate_field (4);
printf_filtered ("%s ",
- local_hex_string_custom ((unsigned long) b->address, "08l"));
+ hex_string_custom ((unsigned long) b->address, 8));
@end smallexample
It became:
@item NO_STD_REGS
This macro is deprecated.
-@item NO_SYS_FILE
-Define this if your system does not have a @code{<sys/file.h>}.
-
@item SIGWINCH_HANDLER
If your host defines @code{SIGWINCH}, you can define this to be the name
of a function to be called if @code{SIGWINCH} is received.
@cindex terminal device
The name of the generic TTY device, defaults to @code{"/dev/tty"}.
-@item FCLOSE_PROVIDED
-Define this if the system declares @code{fclose} in the headers included
-in @code{defs.h}. This isn't needed unless your compiler is unusually
-anal.
-
@item FOPEN_RB
Define this if binary files are opened the same way as text files.
-@item GETENV_PROVIDED
-Define this if the system declares @code{getenv} in its headers included
-in @code{defs.h}. This isn't needed unless your compiler is unusually
-anal.
-
@item HAVE_MMAP
@findex mmap
In some cases, use the system call @code{mmap} for reading symbol
This is the signal for stopping @value{GDBN}. Defaults to
@code{SIGTSTP}. (Only redefined for the Convex.)
-@item USE_O_NOCTTY
-Define this if the interior's tty should be opened with the @code{O_NOCTTY}
-flag. (FIXME: This should be a native-only flag, but @file{inflow.c} is
-always linked in.)
-
@item USG
Means that System V (prior to SVR4) include files are in use. (FIXME:
This symbol is abused in @file{infrun.c}, @file{regex.c}, and
status words, and other special registers. If this is not defined,
@value{GDBN} will assume that all registers may be written.
-@item DO_DEFERRED_STORES
-@itemx CLEAR_DEFERRED_STORES
-@findex CLEAR_DEFERRED_STORES
-@findex DO_DEFERRED_STORES
-Define this to execute any deferred stores of registers into the inferior,
-and to cancel any deferred stores.
-
-Currently only implemented correctly for native Sparc configurations?
-
@item int CONVERT_REGISTER_P(@var{regnum})
@findex CONVERT_REGISTER_P
Return non-zero if register @var{regnum} can represent data values in a
@code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
function's epilogue.
-@item FUNCTION_START_OFFSET
-@findex FUNCTION_START_OFFSET
+@item DEPRECATED_FUNCTION_START_OFFSET
+@findex DEPRECATED_FUNCTION_START_OFFSET
An integer, giving the offset in bytes from a function's address (as
used in the values of symbols, function pointers, etc.), and the
function's first genuine instruction.
This is zero on almost all machines: the function's address is usually
-the address of its first instruction. However, on the VAX, for example,
-each function starts with two bytes containing a bitmask indicating
-which registers to save upon entry to the function. The VAX @code{call}
-instructions check this value, and save the appropriate registers
-automatically. Thus, since the offset from the function's address to
-its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would
-be 2 on the VAX.
+the address of its first instruction. However, on the VAX, for
+example, each function starts with two bytes containing a bitmask
+indicating which registers to save upon entry to the function. The
+VAX @code{call} instructions check this value, and save the
+appropriate registers automatically. Thus, since the offset from the
+function's address to its first instruction is two bytes,
+@code{DEPRECATED_FUNCTION_START_OFFSET} would be 2 on the VAX.
@item GCC_COMPILED_FLAG_SYMBOL
@itemx GCC2_COMPILED_FLAG_SYMBOL
Return the appropriate register set for a core file section with name
@var{sect_name} and size @var{sect_size}.
-
-@item RETURN_VALUE_ON_STACK(@var{type})
-@findex RETURN_VALUE_ON_STACK
-@cindex returning structures by value
-@cindex structures, returning by value
-
-Return non-zero if values of type TYPE are returned on the stack, using
-the ``struct convention'' (i.e., the caller provides a pointer to a
-buffer in which the callee should store the return value). This
-controls how the @samp{finish} command finds a function's return value,
-and whether an inferior function call reserves space on the stack for
-the return value.
-
-The full logic @value{GDBN} uses here is kind of odd.
-
-@itemize @bullet
-@item
-If the type being returned by value is not a structure, union, or array,
-and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
-concludes the value is not returned using the struct convention.
-
-@item
-Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
-If that returns non-zero, @value{GDBN} assumes the struct convention is
-in use.
-@end itemize
-
-In other words, to indicate that a given type is returned by value using
-the struct convention, that type must be either a struct, union, array,
-or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
-that @code{USE_STRUCT_CONVENTION} likes.
-
-Note that, in C and C@t{++}, arrays are never returned by value. In those
-languages, these predicates will always see a pointer type, never an
-array type. All the references above to arrays being returned by value
-apply only to other languages.
-
@item SOFTWARE_SINGLE_STEP_P()
@findex SOFTWARE_SINGLE_STEP_P
Define this as 1 if the target does not have a hardware single-step
them.
@end itemize
-@item PCC_SOL_BROKEN
-@findex PCC_SOL_BROKEN
-(Used only in the Convex target.)
-
@item PC_LOAD_SEGMENT
@findex PC_LOAD_SEGMENT
If defined, print information about the load segment for the program
If defined, used by @code{frame_pop} to remove a stack frame. This
method has been superseeded by generic code.
-@item push_dummy_call (@var{gdbarch}, @var{func_addr}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
+@item push_dummy_call (@var{gdbarch}, @var{function}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
@findex push_dummy_call
@findex DEPRECATED_PUSH_ARGUMENTS.
@anchor{push_dummy_call} Define this to push the dummy frame's call to
@var{nargs}, the code should push @var{struct_addr} (when
@var{struct_return}), and the return address (@var{bp_addr}).
+@var{function} is a pointer to a @code{struct value}; on architectures that use
+function descriptors, this contains the function descriptor value.
+
Returns the updated top-of-stack pointer.
This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}.
This method replaces @code{CALL_DUMMY_LOCATION},
@code{DEPRECATED_REGISTER_SIZE}.
-@item DEPRECATED_REGISTER_BYTES
-@findex DEPRECATED_REGISTER_BYTES
-The total amount of space needed to store @value{GDBN}'s copy of the
-machine's register state.
-
-This is no longer needed. @value{GDBN} instead computes the size of the
-register buffer at run-time.
-
@item REGISTER_NAME(@var{i})
@findex REGISTER_NAME
Return the name of register @var{i} as a string. May return @code{NULL}
This method has been deprecated in favour of @code{gdbarch_return_value}
(@pxref{gdbarch_return_value}).
-@item SUN_FIXED_LBRAC_BUG
-@findex SUN_FIXED_LBRAC_BUG
-(Used only for Sun-3 and Sun-4 targets.)
-
@item SYMBOL_RELOADING_DEFAULT
@findex SYMBOL_RELOADING_DEFAULT
The default value of the ``symbol-reloading'' variable. (Never defined in
@findex read_sp
@findex read_fp
@anchor{TARGET_READ_SP} These change the behavior of @code{read_pc},
-@code{write_pc}, @code{read_sp} and @code{deprecated_read_fp}. For most
-targets, these may be left undefined. @value{GDBN} will call the read
-and write register functions with the relevant @code{_REGNUM} argument.
+@code{write_pc}, and @code{read_sp}. For most targets, these may be
+left undefined. @value{GDBN} will call the read and write register
+functions with the relevant @code{_REGNUM} argument.
These macros are useful when a target keeps one of these registers in a
hard to get at place; for example, part in a segment register and part
previously saved using @code{SAVE_DUMMY_FRAME_TOS}.
@xref{SAVE_DUMMY_FRAME_TOS}.
-@item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
-@findex USE_STRUCT_CONVENTION
+@item DEPRECATED_USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
+@findex DEPRECATED_USE_STRUCT_CONVENTION
If defined, this must be an expression that is nonzero if a value of the
given @var{type} being returned from a function must have space
allocated for it on the stack. @var{gcc_p} is true if the function
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
@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
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
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
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
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}.
+function @code{xstrprintf}.
@emph{Pragmatics: @code{asprintf} and @code{strdup} can fail. Print
functions such as @code{sprintf} are very prone to buffer overflow
configuration.
@end itemize
-@node Releasing GDB
-
-@chapter Releasing @value{GDBN}
-@cindex making a new release of gdb
+@node Versions and Branches
+@chapter Versions and Branches
-@section Versions and Branches
+@section Versions
-@subsection Version Identifiers
+@value{GDBN}'s version is determined by the file
+@file{gdb/version.in} and takes one of the following forms:
-@value{GDBN}'s version is determined by the file @file{gdb/version.in}.
+@table @asis
+@item @var{major}.@var{minor}
+@itemx @var{major}.@var{minor}.@var{patchlevel}
+an official release (e.g., 6.2 or 6.2.1)
+@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}
+a snapshot taken at @var{YYYY}-@var{MM}-@var{DD}-gmt (e.g.,
+6.1.50.20020302, 6.1.90.20020304, or 6.1.0.20020308)
+@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD}-cvs
+a @sc{cvs} check out drawn on @var{YYYY}-@var{MM}-@var{DD} (e.g.,
+6.1.50.20020302-cvs, 6.1.90.20020304-cvs, or 6.1.0.20020308-cvs)
+@item @var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD} (@var{vendor})
+a vendor specific release of @value{GDBN}, that while based on@*
+@var{major}.@var{minor}.@var{patchlevel}.@var{YYYY}@var{MM}@var{DD},
+may include additional changes
+@end table
-@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 mainline uses the @var{major} and @var{minor} version
+numbers from the most recent release branch, with a @var{patchlevel}
+of 50. At the time each new release branch is created, the mainline's
+@var{major} and @var{minor} version numbers are updated.
-@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).
+@value{GDBN}'s release branch is similar. When the branch is cut, the
+@var{patchlevel} is changed from 50 to 90. As draft releases are
+drawn from the branch, the @var{patchlevel} is incremented. Once the
+first release (@var{major}.@var{minor}) has been made, the
+@var{patchlevel} is set to 0 and updates have an incremented
+@var{patchlevel}.
-Using 5.1 (previous) and 5.2 (current), the example below illustrates a
-typical sequence of version identifiers:
+For snapshots, and @sc{cvs} check outs, it is also possible to
+identify the @sc{cvs} origin:
@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
+@item @var{major}.@var{minor}.50.@var{YYYY}@var{MM}@var{DD}
+drawn from the @sc{head} of mainline @sc{cvs} (e.g., 6.1.50.20020302)
+@item @var{major}.@var{minor}.90.@var{YYYY}@var{MM}@var{DD}
+@itemx @var{major}.@var{minor}.91.@var{YYYY}@var{MM}@var{DD} @dots{}
+drawn from a release branch prior to the release (e.g.,
+6.1.90.20020304)
+@item @var{major}.@var{minor}.0.@var{YYYY}@var{MM}@var{DD}
+@itemx @var{major}.@var{minor}.1.@var{YYYY}@var{MM}@var{DD} @dots{}
+drawn from a release branch after the release (e.g., 6.2.0.20020308)
@end table
-Notes:
+If the previous @value{GDBN} version is 6.1 and the current version is
+6.2, then, substituting 6 for @var{major} and 1 or 2 for @var{minor},
+here's an illustration of a typical sequence:
-@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
+@smallexample
+ <HEAD>
+ |
+6.1.50.20020302-cvs
+ |
+ +--------------------------.
+ | <gdb_6_2-branch>
+ | |
+6.2.50.20020303-cvs 6.1.90 (draft #1)
+ | |
+6.2.50.20020304-cvs 6.1.90.20020304-cvs
+ | |
+6.2.50.20020305-cvs 6.1.91 (draft #2)
+ | |
+6.2.50.20020306-cvs 6.1.91.20020306-cvs
+ | |
+6.2.50.20020307-cvs 6.2 (release)
+ | |
+6.2.50.20020308-cvs 6.2.0.20020308-cvs
+ | |
+6.2.50.20020309-cvs 6.2.1 (update)
+ | |
+6.2.50.20020310-cvs <branch closed>
+ |
+6.2.50.20020311-cvs
+ |
+ +--------------------------.
+ | <gdb_6_3-branch>
+ | |
+6.3.50.20020312-cvs 6.2.90 (draft #1)
+ | |
+@end smallexample
+
+@section Release Branches
+@cindex Release Branches
+
+@value{GDBN} draws a release series (6.2, 6.2.1, @dots{}) from a
+single release branch, and identifies that branch using the @sc{cvs}
+branch tags:
+
+@smallexample
+gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-branchpoint
+gdb_@var{major}_@var{minor}-branch
+gdb_@var{major}_@var{minor}-@var{YYYY}@var{MM}@var{DD}-release
+@end smallexample
+
+@emph{Pragmatics: To help identify the date at which a branch or
+release is made, both the branchpoint and release tags include the
+date that they are cut (@var{YYYY}@var{MM}@var{DD}) in the tag. The
+branch tag, denoting the head of the branch, does not need this.}
+
+@section Vendor Branches
+@cindex vendor branches
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).
+its version identifer). E.g., @samp{6.2widgit2}, or @samp{6.2 (Widgit
+Inc Patch 2)}.
+
+@section Experimental Branches
+@cindex experimental branches
+
+@subsection Guidelines
+
+@value{GDBN} permits the creation of branches, cut from the @sc{cvs}
+repository, for experimental development. Branches make it possible
+for developers to share preliminary work, and maintainers to examine
+significant new developments.
+
+The following are a set of guidelines for creating such branches:
+
+@table @emph
+
+@item a branch has an owner
+The owner can set further policy for a branch, but may not change the
+ground rules. In particular, they can set a policy for commits (be it
+adding more reviewers or deciding who can commit).
-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.
+@item all commits are posted
+All changes committed to a branch shall also be posted to
+@email{gdb-patches@@sources.redhat.com, the @value{GDBN} patches
+mailing list}. While commentary on such changes are encouraged, people
+should remember that the changes only apply to a branch.
+@item all commits are covered by an assignment
+This ensures that all changes belong to the Free Software Foundation,
+and avoids the possibility that the branch may become contaminated.
-@subsection Branches
+@item a branch is focused
+A focused branch has a single objective or goal, and does not contain
+unnecessary or irrelevant changes. Cleanups, where identified, being
+be pushed into the mainline as soon as possible.
-@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).
+@item a branch tracks mainline
+This keeps the level of divergence under control. It also keeps the
+pressure on developers to push cleanups and other stuff into the
+mainline.
-Releases 5.0 and 5.1 used branch and release tags of the form:
+@item a branch shall contain the entire @value{GDBN} module
+The @value{GDBN} module @code{gdb} should be specified when creating a
+branch (branches of individual files should be avoided). @xref{Tags}.
+@item a branch shall be branded using @file{version.in}
+The file @file{gdb/version.in} shall be modified so that it identifies
+the branch @var{owner} and branch @var{name}, e.g.,
+@samp{6.2.50.20030303_owner_name} or @samp{6.2 (Owner Name)}.
+
+@end table
+
+@subsection Tags
+@anchor{Tags}
+
+To simplify the identification of @value{GDBN} branches, the following
+branch tagging convention is strongly recommended:
+
+@table @code
+
+@item @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
+@itemx @var{owner}_@var{name}-@var{YYYYMMDD}-branch
+The branch point and corresponding branch tag. @var{YYYYMMDD} is the
+date that the branch was created. A branch is created using the
+sequence: @anchor{experimental branch tags}
@smallexample
-gdb_N_M-YYYY-MM-DD-branchpoint
-gdb_N_M-YYYY-MM-DD-branch
-gdb_M_N-YYYY-MM-DD-release
+cvs rtag @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint gdb
+cvs rtag -b -r @var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint \
+ @var{owner}_@var{name}-@var{YYYYMMDD}-branch gdb
@end smallexample
-Release 5.2 is trialing the branch and release tags:
-
+@item @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
+The tagged point, on the mainline, that was used when merging the branch
+on @var{yyyymmdd}. To merge in all changes since the branch was cut,
+use a command sequence like:
@smallexample
-gdb_N_M-YYYY-MM-DD-branchpoint
-gdb_N_M-branch
-gdb_M_N-YYYY-MM-DD-release
+cvs rtag @var{owner}_@var{name}-@var{yyyymmdd}-mergepoint gdb
+cvs update \
+ -j@var{owner}_@var{name}-@var{YYYYMMDD}-branchpoint
+ -j@var{owner}_@var{name}-@var{yyyymmdd}-mergepoint
@end smallexample
+@noindent
+Similar sequences can be used to just merge in changes since the last
+merge.
+
+@end table
-@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.}
+@noindent
+For further information on @sc{cvs}, see
+@uref{http://www.gnu.org/software/cvs/, Concurrent Versions System}.
+
+@node Releasing GDB
+@chapter Releasing @value{GDBN}
+@cindex making a new release of gdb
@section Branch Commit Policy
in particular versions of compilers, and it's OK not to try to write
tests for all of those.
+DejaGNU supports separate build, host, and target machines. However,
+some @value{GDBN} test scripts do not work if the build machine and
+the host machine are not the same. In such an environment, these scripts
+will give a result of ``UNRESOLVED'', like this:
+
+@smallexample
+UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
+@end smallexample
+
@section Testsuite Organization
@cindex test suite organization
projects / deliverable / binutils-gdb.git / blobdiff