X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdbint.texinfo;h=267a6eb22eff241fb2a06c714071d007b9cedaa2;hb=86b498803658eb5e7ed3eb1a8131051e5e31e0e6;hp=0255c028aa9aab81cb29163ca6be32d9c739224e;hpb=da082f17971d56d64eb9f525f0f546baa3400d6a;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 0255c028aa..267a6eb22e 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -1,20 +1,21 @@ \input texinfo @c -*- texinfo -*- @setfilename gdbint.info @include gdb-cfg.texi +@settitle @value{GDBN} Internals +@setchapternewpage off @dircategory Software development @direntry * Gdb-Internals: (gdbint). The GNU debugger's internals. @end direntry @copying -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, -2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009 -Free Software Foundation, Inc. +Copyright @copyright{} 1990-1994, 1996, 1998-2006, 2008-2012 Free +Software Foundation, Inc. Contributed by Cygnus Solutions. Written by John Gilmore. Second Edition by Stan Shebs. Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or +under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU @@ -27,8 +28,6 @@ This file documents the internals of the GNU debugger @value{GDBN}. @insertcopying @end ifnottex -@setchapternewpage off -@settitle @value{GDBN} Internals @syncodeindex fn cp @syncodeindex vr cp @@ -83,7 +82,8 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets. * Target Vector Definition:: * Native Debugging:: * Support Libraries:: -* Coding:: +* Coding Standards:: +* Misc Guidelines:: * Porting GDB:: * Versions and Branches:: * Start of New Year Procedure:: @@ -781,11 +781,6 @@ inferior after a watchpoint has been hit. This is usually set when watchpoints trigger at the instruction following an interesting read or write. -@findex CANNOT_STEP_HW_WATCHPOINTS -@item CANNOT_STEP_HW_WATCHPOINTS -If this is defined to a non-zero value, @value{GDBN} will remove all -watchpoints before stepping the inferior. - @findex STOPPED_BY_WATCHPOINT @item STOPPED_BY_WATCHPOINT (@var{wait_status}) Return non-zero if stopped by a watchpoint. @var{wait_status} is of @@ -1327,9 +1322,9 @@ be signaled. @deftypefun {struct cleanup *} make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) This function first opens the tuple and then establishes a cleanup -(@pxref{Coding, Cleanups}) to close the tuple. It provides a convenient -and correct implementation of the non-portable@footnote{The function -cast is not portable ISO C.} code sequence: +(@pxref{Misc Guidelines, Cleanups}) to close the tuple. +It provides a convenient and correct implementation of the +non-portable@footnote{The function cast is not portable ISO C.} code sequence: @smallexample struct cleanup *old_cleanup; ui_out_tuple_begin (uiout, "..."); @@ -1354,7 +1349,8 @@ be signaled. @deftypefun {struct cleanup *} make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function -opens a list and then establishes cleanup (@pxref{Coding, Cleanups}) +opens a list and then establishes cleanup +(@pxref{Misc Guidelines, Cleanups}) that will close the list. @end deftypefun @@ -2294,6 +2290,12 @@ and all the psymbols themselves are allocated in a pair of large arrays on an obstack, so there is little to be gained by trying to free them unless you want to do a lot more work. +Whether or not psymtabs are created depends on the objfile's symbol +reader. The core of @value{GDBN} hides the details of partial symbols +and partial symbol tables behind a set of function pointers known as +the @dfn{quick symbol functions}. These are documented in +@file{symfile.h}. + @section Types @unnumberedsubsec Fundamental Types (e.g., @code{FT_VOID}, @code{FT_BOOLEAN}). @@ -2783,19 +2785,6 @@ Define this if @code{lseek (n)} does not necessarily move to byte number @code{n} in the file. This is only used when reading source files. It is normally faster to define @code{CRLF_SOURCE_FILES} when possible. -@item NORETURN -If defined, this should be one or more tokens, such as @code{volatile}, -that can be used in both the declaration and definition of functions to -indicate that they never return. The default is already set correctly -if compiling with GCC. This will almost never need to be defined. - -@item ATTR_NORETURN -If defined, this should be one or more tokens, such as -@code{__attribute__ ((noreturn))}, that can be used in the declarations -of functions to indicate that they never return. The default is already -set correctly if compiling with GCC. This will almost never need to be -defined. - @item lint Define this to help placate @code{lint} in some situations. @@ -3617,7 +3606,7 @@ register should be printed. Define a custom version of this function for fuller control over how the registers are displayed. The access should be for the specified architecture, @var{gdbarch}, -with output to the the file specified by the User Interface +with output to the file specified by the User Interface Independent Output file handle, @var{file} (@pxref{UI-Independent Output, , UI-Independent Output---the @code{ui_out} Functions}). @@ -4927,11 +4916,6 @@ number of that register. Use this function to convert stab register @var{stab_regnr} into @value{GDBN} regnum. If not defined, no conversion will be done. -@item SYMBOL_RELOADING_DEFAULT -@findex SYMBOL_RELOADING_DEFAULT -The default value of the ``symbol-reloading'' variable. (Never defined in -current sources.) - @item TARGET_CHAR_BIT @findex TARGET_CHAR_BIT Number of bits in a char; defaults to 8. @@ -5768,9 +5752,277 @@ Binary search the array. @section include -@node Coding +@node Coding Standards + +@chapter Coding Standards +@cindex coding standards + +@section @value{GDBN} C 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. -@chapter Coding +@subsection Formatting + +@cindex source code formatting +The standard GNU recommendations for formatting must be followed +strictly. Any @value{GDBN}-specific deviation from GNU +recomendations is described below. + +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 + +In addition, whitespace around casts and unary operators should follow +the following guidelines: + +@multitable @columnfractions .2 .2 .8 +@item Use... @tab ...instead of @tab + +@item @code{!x} +@tab @code{! x} +@item @code{~x} +@tab @code{~ x} +@item @code{-x} +@tab @code{- x} +@tab (unary minus) +@item @code{(foo) x} +@tab @code{(foo)x} +@tab (cast) +@item @code{*x} +@tab @code{* x} +@tab (pointer dereference) +@end multitable + +Any two or more lines in code should be wrapped in braces, even if +they are comments, as they look like separate statements: + +@smallexample +if (i) + @{ + /* Return success. */ + return 0; + @} +@end smallexample + +@noindent +and not: + +@smallexample +if (i) + /* Return success. */ + return 0; +@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 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}). These headers should be relatively +independent: they should use only macros defined by @file{configure}, +the compiler, or the host; they should include only system headers; they +should refer only to system types. They may be shared between multiple +programs, e.g.@: @value{GDBN} and @sc{gdbserver}. + +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 + +@section @value{GDBN} Python Coding Standards + +@value{GDBN} follows the published @code{Python} coding standards in +@uref{http://www.python.org/dev/peps/pep-0008/, @code{PEP008}}. + +In addition, the guidelines in the +@uref{http://google-styleguide.googlecode.com/svn/trunk/pyguide.html, +Google Python Style Guide} are also followed where they do not +conflict with @code{PEP008}. + +@subsection @value{GDBN}-specific exceptions + +There are a few exceptions to the published standards. +They exist mainly for consistency with the @code{C} standards. + +@c It is expected that there are a few more exceptions, +@c so we use itemize here. + +@itemize @bullet + +@item +Use @code{FIXME} instead of @code{TODO}. + +@end itemize + +@node Misc Guidelines + +@chapter Misc Guidelines This chapter covers topics that are lower-level than the major algorithms of @value{GDBN}. @@ -6007,28 +6259,7 @@ 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 +@section Memory Management @value{GDBN} does not use the functions @code{malloc}, @code{realloc}, @code{calloc}, @code{free} and @code{asprintf}. @@ -6066,7 +6297,7 @@ functions such as @code{sprintf} are very prone to buffer overflow errors.} -@subsection Compiler Warnings +@section Compiler Warnings @cindex compiler warnings With few exceptions, developers should avoid the configuration option @@ -6121,124 +6352,7 @@ currently too noisy to enable with @samp{-Werror}. @end table -@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 +@section 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 @@ -6257,72 +6371,11 @@ 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 +@section Command 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. +GDB U/I commands are written @samp{foo-bar}, not @samp{foo_bar}. -@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}). These headers should be relatively -independent: they should use only macros defined by @file{configure}, -the compiler, or the host; they should include only system headers; they -should refer only to system types. They may be shared between multiple -programs, e.g.@: @value{GDBN} and @sc{gdbserver}. - -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 +@section Clean Design and Portable Implementation @cindex design In addition to getting the syntax right, there's the little question of @@ -6456,7 +6509,6 @@ All debugging code must be controllable using the @samp{set debug messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use @code{#ifdef DEBUG}. - @node Porting GDB @chapter Porting @value{GDBN} @@ -6752,15 +6804,18 @@ Update the copyright year in the startup message Update the copyright year in: @itemize @bullet -@item file @file{top.c}, function @code{print_gdb_version} -@item file @file{gdbserver/server.c}, function @code{gdbserver_version} -@item file @file{gdbserver/gdbreplay.c}, function @code{gdbreplay_version} + @item + file @file{top.c}, function @code{print_gdb_version} + @item + file @file{gdbserver/server.c}, function @code{gdbserver_version} + @item + file @file{gdbserver/gdbreplay.c}, function @code{gdbreplay_version} @end itemize @item -Add the new year in the copyright notices of all source and documentation -files. This can be done semi-automatically by running the @code{copyright.sh} -script. This script requires Emacs 22 or later to be installed. +Run the @file{copyright.py} Python script to add the new year in the copyright +notices of most source files. This script has been tested with Python +2.6 and 2.7. @end itemize @@ -7570,6 +7625,14 @@ will give a result of ``UNRESOLVED'', like this: UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host. @end smallexample +@section Testsuite Parameters + +Several variables exist to modify the behavior of the testsuite. + +@itemize @bullet + +@item @code{TRANSCRIPT} + Sometimes it is convenient to get a transcript of the commands which the testsuite sends to @value{GDBN}. For example, if @value{GDBN} crashes during testing, a transcript can be used to more easily @@ -7591,6 +7654,103 @@ make check RUNTESTFLAGS=TRANSCRIPT=y Note that the transcript is not always complete. In particular, tests of completion can yield partial command lines. +@item @code{GDB} + +Sometimes one wishes to test a different @value{GDBN} than the one in the build +directory. For example, one may wish to run the testsuite on +@file{/usr/bin/gdb}. + +@smallexample +make check RUNTESTFLAGS=GDB=/usr/bin/gdb +@end smallexample + +@item @code{GDBSERVER} + +When testing a different @value{GDBN}, it is often useful to also test a +different gdbserver. + +@smallexample +make check RUNTESTFLAGS="GDB=/usr/bin/gdb GDBSERVER=/usr/bin/gdbserver" +@end smallexample + +@item @code{INTERNAL_GDBFLAGS} + +When running the testsuite normally one doesn't want whatever is in +@file{~/.gdbinit} to interfere with the tests, therefore the test harness +passes @option{-nx} to @value{GDBN}. One also doesn't want any windowed +version of @value{GDBN}, e.g., @samp{gdb -tui}, to run. +This is achieved via @code{INTERNAL_GDBFLAGS}. + +@smallexample +set INTERNAL_GDBFLAGS "-nw -nx" +@end smallexample + +This is all well and good, except when testing an installed @value{GDBN} +that has been configured with @option{--with-system-gdbinit}. Here one +does not want @file{~/.gdbinit} loaded but one may want the system +@file{.gdbinit} file loaded. This can be achieved by pointing @code{$HOME} +at a directory without a @file{.gdbinit} and by overriding +@code{INTERNAL_GDBFLAGS} and removing @option{-nx}. + +@smallexample +cd testsuite +HOME=`pwd` runtest \ + GDB=/usr/bin/gdb \ + GDBSERVER=/usr/bin/gdbserver \ + INTERNAL_GDBFLAGS=-nw +@end smallexample + +@end itemize + +There are two ways to run the testsuite and pass additional parameters +to DejaGnu. The first is with @kbd{make check} and specifying the +makefile variable @samp{RUNTESTFLAGS}. + +@smallexample +make check RUNTESTFLAGS=TRANSCRIPT=y +@end smallexample + +The second is to cd to the @file{testsuite} directory and invoke the DejaGnu +@command{runtest} command directly. + +@smallexample +cd testsuite +make site.exp +runtest TRANSCRIPT=y +@end smallexample + +@section Testsuite Configuration +@cindex Testsuite Configuration + +It is possible to adjust the behavior of the testsuite by defining +the global variables listed below, either in a @file{site.exp} file, +or in a board file. + +@itemize @bullet + +@item @code{gdb_test_timeout} + +Defining this variable changes the default timeout duration used during +communication with @value{GDBN}. More specifically, the global variable +used during testing is @code{timeout}, but this variable gets reset to +@code{gdb_test_timeout} at the beginning of each testcase, making sure +that any local change to @code{timeout} in a testcase does not affect +subsequent testcases. + +This global variable comes in handy when the debugger is slower than +normal due to the testing environment, triggering unexpected @code{TIMEOUT} +test failures. Examples include when testing on a remote machine, or +against a system where communications are slow. + +If not specifically defined, this variable gets automatically defined +to the same value as @code{timeout} during the testsuite initialization. +The default value of the timeout is defined in the file +@file{gdb/testsuite/config/unix.exp} that is part of the @value{GDBN} +test suite@footnote{If you are using a board file, it could override +the test-suite default; search the board file for "timeout".}. + +@end itemize + @section Testsuite Organization @cindex test suite organization @@ -7674,6 +7834,96 @@ instance, some @value{GDBN} bugs involving the display of source lines would never manifest themselves if the programs used GNU coding style uniformly. +Some testcase results need more detailed explanation: + +@table @code +@item KFAIL +Known problem of @value{GDBN} itself. You must specify the @value{GDBN} bug +report number like in these sample tests: +@smallexample +kfail "gdb/13392" "continue to marker 2" +@end smallexample +or +@smallexample +setup_kfail gdb/13392 "*-*-*" +kfail "continue to marker 2" +@end smallexample + +@item XFAIL +Known problem of environment. This typically includes @value{NGCC} but it +includes also many other system components which cannot be fixed in the +@value{GDBN} project. Sample test with sanity check not knowing the specific +cause of the problem: +@smallexample +# On x86_64 it is commonly about 4MB. +if @{$stub_size > 25000000@} @{ + xfail "stub size $stub_size is too large" + return +@} +@end smallexample + +You should provide bug report number for the failing component of the +environment, if such bug report is available: +@smallexample +if @{[test_compiler_info @{gcc-[0-3]-*@}] + || [test_compiler_info @{gcc-4-[0-5]-*@}]@} @{ + setup_xfail "gcc/46955" *-*-* +@} +gdb_test "python print ttype.template_argument(2)" "&C::c" +@end smallexample +@end table + +@section Board settings +In @value{GDBN} testsuite, the tests can be configured or customized in the board +file by means of @dfn{Board Settings}. Each setting should be consulted by +test cases that depend on the corresponding feature. + +Here are the supported board settings: + +@table @code + +@item gdb,cannot_call_functions +The board does not support inferior call, that is, invoking inferior functions +in @value{GDBN}. +@item gdb,can_reverse +The board supports reverse execution. +@item gdb,no_hardware_watchpoints +The board does not support hardware watchpoints. +@item gdb,nofileio +@value{GDBN} is unable to intercept target file operations in remote and perform +them on the host. +@item gdb,noinferiorio +The board is unable to provide I/O capability to the inferior. +@c @item gdb,noresults +@c NEED DOCUMENT. +@item gdb,nosignals +The board does not support signals. +@item gdb,skip_huge_test +Skip time-consuming tests on the board with slow connection. +@item gdb,skip_float_tests +Skip tests related to float points on target board. +@item gdb,use_precord +The board supports process record. +@item gdb_server_prog +The location of GDBserver. If GDBserver somewhere other than its default +location is used in test, specify the location of GDBserver in this variable. +The location is a file name of GDBserver that can be either absolute or +relative to testsuite subdirectory in build directory. +@item in_proc_agent +The location of in-process agent. If in-process agent other than its default +location is used in test, specify the location of in-process agent in +this variable. The location is a file name of in-process agent that can be +either absolute or relative to testsuite subdirectory in build directory. +@item noargs +@value{GDBN} does not support argument passing for inferior. +@item no_long_long +The board does not support type @code{long long}. +@c @item use_cygmon +@c NEED DOCUMENT. +@item use_gdb_stub +The tests are running with gdb stub. +@end table + @node Hints @chapter Hints @@ -7686,7 +7936,7 @@ appear anywhere else in the directory. * Debugging GDB:: Debugging @value{GDBN} with itself @end menu -@node Getting Started,,, Hints +@node Getting Started @section Getting Started @@ -7769,7 +8019,7 @@ 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 +@node Debugging GDB @section Debugging @value{GDBN} with itself @cindex debugging @value{GDBN} @@ -7877,9 +8127,10 @@ information about the architecture. The test results are stored in log files in the directory the script was called from. @include observer.texi -@raisesections + +@node GNU Free Documentation License +@appendix GNU Free Documentation License @include fdl.texi -@lowersections @node Index @unnumbered Index