* gdbint.texinfo: Expand on GDB's coding standards,
specify the use of arg names with prototypes.
This commit is contained in:
parent
d951f9e4f9
commit
18b1e896d4
|
@ -1,3 +1,8 @@
|
||||||
|
Mon Jan 4 18:29:18 1999 Stan Shebs <shebs@andros.cygnus.com>
|
||||||
|
|
||||||
|
* gdbint.texinfo: Expand on GDB's coding standards,
|
||||||
|
specify the use of arg names with prototypes.
|
||||||
|
|
||||||
1998-12-14 J.T. Conklin <jtc@redbacknetworks.com>
|
1998-12-14 J.T. Conklin <jtc@redbacknetworks.com>
|
||||||
|
|
||||||
* gdb.texinfo: Fix tipo.
|
* gdb.texinfo: Fix tipo.
|
||||||
|
|
|
@ -12,7 +12,7 @@ END-INFO-DIR-ENTRY
|
||||||
@ifinfo
|
@ifinfo
|
||||||
This file documents the internals of the GNU debugger GDB.
|
This file documents the internals of the GNU debugger GDB.
|
||||||
|
|
||||||
Copyright 1990, 91, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
|
Copyright 1990-1999 Free Software Foundation, Inc.
|
||||||
Contributed by Cygnus Solutions. Written by John Gilmore.
|
Contributed by Cygnus Solutions. Written by John Gilmore.
|
||||||
Second Edition by Stan Shebs.
|
Second Edition by Stan Shebs.
|
||||||
|
|
||||||
|
@ -55,7 +55,7 @@ regarded as a program in the language TeX).
|
||||||
@end tex
|
@end tex
|
||||||
|
|
||||||
@vskip 0pt plus 1filll
|
@vskip 0pt plus 1filll
|
||||||
Copyright @copyright{} 1990, 91, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
|
Copyright @copyright{} 1990-1999 Free Software Foundation, Inc.
|
||||||
|
|
||||||
Permission is granted to make and distribute verbatim copies of
|
Permission is granted to make and distribute verbatim copies of
|
||||||
this manual provided the copyright notice and this permission notice
|
this manual provided the copyright notice and this permission notice
|
||||||
|
@ -1562,9 +1562,15 @@ where @var{valbuf} is the address of the value to be stored.
|
||||||
The default value of the `symbol-reloading' variable. (Never defined in
|
The default value of the `symbol-reloading' variable. (Never defined in
|
||||||
current sources.)
|
current sources.)
|
||||||
|
|
||||||
@item TARGET_BYTE_ORDER
|
@item TARGET_BYTE_ORDER_DEFAULT
|
||||||
The ordering of bytes in the target. This must be defined to be either
|
The ordering of bytes in the target. This must be either
|
||||||
@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}.
|
@code{BIG_ENDIAN} or @code{LITTLE_ENDIAN}. This macro replaces
|
||||||
|
@var{TARGET_BYTE_ORDER} which is deprecated.
|
||||||
|
|
||||||
|
@item TARGET_BYTE_ORDER_SELECTABLE_P
|
||||||
|
Non-zero if the target has both @code{BIG_ENDIAN} and
|
||||||
|
@code{LITTLE_ENDIAN} variants. This macro replaces
|
||||||
|
@var{TARGET_BYTE_ORDER_SELECTABLE} which is deprecated.
|
||||||
|
|
||||||
@item TARGET_CHAR_BIT
|
@item TARGET_CHAR_BIT
|
||||||
Number of bits in a char; defaults to 8.
|
Number of bits in a char; defaults to 8.
|
||||||
|
@ -2185,22 +2191,96 @@ finish by printing a newline, to flush the wrap buffer, before switching
|
||||||
to unfiltered (``@code{printf}'') output. Symbol reading routines that
|
to unfiltered (``@code{printf}'') output. Symbol reading routines that
|
||||||
print warnings are a good example.
|
print warnings are a good example.
|
||||||
|
|
||||||
@section Coding Style
|
@section GDB Coding Standards
|
||||||
|
|
||||||
GDB follows the GNU coding standards, as described in
|
GDB follows the GNU coding standards, as described in
|
||||||
@file{etc/standards.texi}. This file is also available for anonymous
|
@file{etc/standards.texi}. This file is also available for anonymous
|
||||||
FTP from GNU archive sites. There are some additional considerations
|
FTP from GNU archive sites. GDB takes a strict interpretation of the
|
||||||
for GDB maintainers that reflect the unique environment and style of GDB
|
standard; in general, when the GNU standard recommends a practice but
|
||||||
maintenance. If you follow these guidelines, GDB will be more
|
does not require it, GDB requires it.
|
||||||
consistent and easier to maintain.
|
|
||||||
|
|
||||||
GDB's policy on the use of prototypes is that prototypes are used to
|
GDB follows an additional set of coding standards specific to GDB,
|
||||||
@emph{declare} functions but never to @emph{define} them. Simple macros
|
as described in the following sections.
|
||||||
are used in the declarations, so that a non-ANSI compiler can compile
|
|
||||||
GDB without trouble. The simple macro calls are used like this:
|
You can configure with @samp{--enable-build-warnings} to get GCC to
|
||||||
|
check on a number of these rules. GDB sources ought not to engender any
|
||||||
|
complaints, unless they are caused by bogus host systems. (The exact
|
||||||
|
set of enabled warnings is currently @samp{-Wall -Wpointer-arith
|
||||||
|
-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations}.
|
||||||
|
|
||||||
|
@subsection Formatting
|
||||||
|
|
||||||
|
The standard GNU recommendations for formatting must be followed
|
||||||
|
strictly.
|
||||||
|
|
||||||
|
Note that while in a definition, the function's name must be in column
|
||||||
|
zero, in a function declaration, the name must be on the same line as
|
||||||
|
the return type.
|
||||||
|
|
||||||
|
In addition, 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 diff and
|
||||||
|
patch.
|
||||||
|
|
||||||
|
@subsection Comments
|
||||||
|
|
||||||
|
The standard GNU requirements on comments must be followed strictly.
|
||||||
|
|
||||||
|
Block comments must appear in the following form, with no `/*'- or
|
||||||
|
'*/'-only lines, and no leading `*':
|
||||||
|
|
||||||
@example @code
|
@example @code
|
||||||
extern int memory_remove_breakpoint PARAMS ((CORE_ADDR, char *));
|
/* 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 GDB should read more commands. */
|
||||||
|
@end example
|
||||||
|
|
||||||
|
(Note that this format is encouraged by Emacs; tabbing for a multi-line
|
||||||
|
comment works correctly, and 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
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Use functions freely. There are only a handful of compute-bound areas
|
||||||
|
in GDB that might be affected by the overhead of a function call, mainly
|
||||||
|
in symbol reading. Most of GDB'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 one thousand-line function.
|
||||||
|
|
||||||
|
@subsection Function Prototypes
|
||||||
|
|
||||||
|
Prototypes must be used to @emph{declare} functions but never to
|
||||||
|
@emph{define} them. Prototypes for GDB functions must include both the
|
||||||
|
argument type and name, with the name matching that used in the actual
|
||||||
|
function definition.
|
||||||
|
|
||||||
|
For the sake of compatibility with pre-ANSI compilers, define prototypes
|
||||||
|
with the @code{PARAMS} macro:
|
||||||
|
|
||||||
|
@example @code
|
||||||
|
extern int memory_remove_breakpoint PARAMS ((CORE_ADDR addr,
|
||||||
|
char *contents_cache));
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
Note the double parentheses around the parameter types. This allows an
|
Note the double parentheses around the parameter types. This allows an
|
||||||
|
@ -2209,22 +2289,21 @@ C preprocessor. When the function has no parameters, it should be
|
||||||
described like:
|
described like:
|
||||||
|
|
||||||
@example @code
|
@example @code
|
||||||
void noprocess PARAMS ((void));
|
extern void noprocess PARAMS ((void));
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
The @code{PARAMS} macro expands to its argument in ANSI C, or to a
|
The @code{PARAMS} macro expands to its argument in ANSI C, or to a
|
||||||
simple @code{()} in traditional C.
|
simple @code{()} in traditional C.
|
||||||
|
|
||||||
All external functions should have a @code{PARAMS} declaration in a
|
All external functions should have a @code{PARAMS} declaration in a
|
||||||
header file that callers include. All static functions should have such
|
header file that callers include, except for @code{_initialize_*}
|
||||||
a declaration near the top of their source file.
|
functions, which must be external so that @file{init.c} construction
|
||||||
|
works, but shouldn't be visible to random source files.
|
||||||
|
|
||||||
We don't have a gcc option that will properly check that these rules
|
All static functions must be declared in a block near the top of the
|
||||||
have been followed, but it's GDB policy, and we periodically check it
|
source file.
|
||||||
using the tools available (plus manual labor), and clean up any
|
|
||||||
remnants.
|
|
||||||
|
|
||||||
@section Clean Design
|
@subsection Clean Design
|
||||||
|
|
||||||
In addition to getting the syntax right, there's the little question of
|
In addition to getting the syntax right, there's the little question of
|
||||||
semantics. Some things are done in certain ways in GDB because long
|
semantics. Some things are done in certain ways in GDB because long
|
||||||
|
@ -2327,11 +2406,6 @@ any system-independent file would (hooks, #if defined, etc.), and
|
||||||
machines which are radically different don't need to use infptrace.c at
|
machines which are radically different don't need to use infptrace.c at
|
||||||
all.
|
all.
|
||||||
|
|
||||||
@emph{Do} write code that doesn't 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. In short, follow good
|
|
||||||
programming practices for writing portable C code.
|
|
||||||
|
|
||||||
|
|
||||||
@node Porting GDB
|
@node Porting GDB
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue