espressif/binutils-gdb
1
0
Fork 0
mirror of https://github.com/espressif/binutils-gdb.git synced 2025-06-20 18:08:24 +08:00
Code Issues Packages Projects Releases Wiki Activity

* gdbint.texinfo (Misc Guidelines): Renamed from Coding.

Browse Source 
All references updated.  Correct sections marked as subsections.
	(Coding Standards): New chapter.  Move the coding standard related
	subsections here.  Add section on Python coding standards.
This commit is contained in:
Doug Evans
2010-10-20 22:53:36 +00:00
parent 78c62ceee3
commit a0e0ffdffa
2 changed files with 247 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
gdb/doc/ChangeLog
View File

@ -1,3 +1,10 @@
2010-10-20 Doug Evans <dje@google.com>
* gdbint.texinfo (Misc Guidelines): Renamed from Coding.
All references updated. Correct sections marked as subsections.
(Coding Standards): New chapter. Move the coding standard related
subsections here. Add section on Python coding standards.
2010-10-13 Doug Evans <dje@google.com> 2010-10-13 Doug Evans <dje@google.com>
* gdb.texinfo (Python): Add "Python modules". * gdb.texinfo (Python): Add "Python modules".

456
gdb/doc/gdbint.texinfo
View File

@ -83,7 +83,8 @@ as the mechanisms that adapt @value{GDBN} to specific hosts and targets.
* Target Vector Definition:: * Target Vector Definition::
* Native Debugging:: * Native Debugging::
* Support Libraries:: * Support Libraries::
* Coding:: * Coding Standards::
* Misc Guidelines::
* Porting GDB:: * Porting GDB::
* Versions and Branches:: * Versions and Branches::
* Start of New Year Procedure:: * Start of New Year Procedure::
@ -1322,9 +1323,9 @@ be signaled.
@deftypefun {struct cleanup *} make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) @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 This function first opens the tuple and then establishes a cleanup
(@pxref{Coding, Cleanups}) to close the tuple. It provides a convenient (@pxref{Misc Guidelines, Cleanups}) to close the tuple.
and correct implementation of the non-portable@footnote{The function It provides a convenient and correct implementation of the
cast is not portable ISO C.} code sequence: non-portable@footnote{The function cast is not portable ISO C.} code sequence:
@smallexample @smallexample
struct cleanup *old_cleanup; struct cleanup *old_cleanup;
ui_out_tuple_begin (uiout, "..."); ui_out_tuple_begin (uiout, "...");
@ -1349,7 +1350,8 @@ be signaled.
@deftypefun {struct cleanup *} make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id}) @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 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. that will close the list.
@end deftypefun @end deftypefun
@ -5756,9 +5758,235 @@ Binary search the array.
@section include @section include
@node Coding @node Coding Standards
@chapter Coding @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.
@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 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 This chapter covers topics that are lower-level than the major
algorithms of @value{GDBN}. algorithms of @value{GDBN}.
@ -5995,28 +6223,7 @@ 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 @value{GDBN} Coding Standards @section Memory Management
@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}, @value{GDBN} does not use the functions @code{malloc}, @code{realloc},
@code{calloc}, @code{free} and @code{asprintf}. @code{calloc}, @code{free} and @code{asprintf}.
@ -6054,7 +6261,7 @@ functions such as @code{sprintf} are very prone to buffer overflow
errors.} errors.}
@subsection Compiler Warnings @section Compiler Warnings
@cindex compiler warnings @cindex compiler warnings
With few exceptions, developers should avoid the configuration option With few exceptions, developers should avoid the configuration option
@ -6109,124 +6316,7 @@ currently too noisy to enable with @samp{-Werror}.
@end table @end table
@subsection Formatting @section Internal Error Recovery
@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. During its execution, @value{GDBN} can encounter two types of errors.
User errors and internal errors. User errors include not only a user User errors and internal errors. User errors include not only a user
@ -6245,76 +6335,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 @code{warning} or the code failed to correctly recover from the user
error and issued an @code{internal_error}.} error and issued an @code{internal_error}.}
@subsection Command Names @section Command Names
GDB U/I commands are written @samp{foo-bar}, not @samp{foo_bar}. GDB U/I commands are written @samp{foo-bar}, not @samp{foo_bar}.
@subsection File Names @section Clean Design and Portable Implementation
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
@subsection Clean Design and Portable Implementation
@cindex design @cindex 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
@ -6448,7 +6473,6 @@ All debugging code must be controllable using the @samp{set debug
messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use messages. Use @code{fprintf_unfiltered(gdb_stdlog, ...}. Do not use
@code{#ifdef DEBUG}. @code{#ifdef DEBUG}.
@node Porting GDB @node Porting GDB
@chapter Porting @value{GDBN} @chapter Porting @value{GDBN}