sourcebuild.texi

理解和实践操作系统的一本好书

@item install-man
Install man pages for the front end.  This target should ignore
errors.
@item srcextra
Copies its dependencies into the source directory.  This generally should
be used for generated files such as Bison output files which are not
present in CVS, but should be included in any release tarballs.  This
target will be executed during a bootstrap if
@samp{--enable-generated-files-in-srcdir} was specified as a
@file{configure} option.
@item srcinfo
@itemx srcman
Copies its dependencies into the source directory.  These targets will be
executed during a bootstrap if @samp{--enable-generated-files-in-srcdir}
was specified as a @file{configure} option.
@item uninstall
Uninstall files installed by installing the compiler.  This is
currently documented not to be supported, so the hook need not do
anything.
@item mostlyclean
@itemx clean
@itemx distclean
@itemx maintainer-clean
The language parts of the standard GNU
@samp{*clean} targets.  @xref{Standard Targets, , Standard Targets for
Users, standards, GNU Coding Standards}, for details of the standard
targets.  For GCC, @code{maintainer-clean} should delete
all generated files in the source directory that are not checked into
CVS, but should not delete anything checked into CVS@.
@end table

@item lang.opt
This file registers the set of switches that the front end accepts on
the command line, and their @option{--help} text.  @xref{Options}.
@item lang-specs.h
This file provides entries for @code{default_compilers} in
@file{gcc.c} which override the default of giving an error that a
compiler for that language is not installed.
@item @var{language}-tree.def
This file, which need not exist, defines any language-specific tree
codes.
@end table

@node Front End Config
@subsubsection The Front End @file{config-lang.in} File

Each language subdirectory contains a @file{config-lang.in} file.  In
addition the main directory contains @file{c-config-lang.in}, which
contains limited information for the C language.  This file is a shell
script that may define some variables describing the language:

@table @code
@item language
This definition must be present, and gives the name of the language
for some purposes such as arguments to @option{--enable-languages}.
@item lang_requires
If defined, this variable lists (space-separated) language front ends
other than C that this front end requires to be enabled (with the
names given being their @code{language} settings).  For example, the
Java front end depends on the C++ front end, so sets
@samp{lang_requires=c++}.
@item subdir_requires
If defined, this variable lists (space-separated) front end directories
other than C that this front end requires to be present.  For example,
the Objective-C++ front end uses source files from the C++ and
Objective-C front ends, so sets @samp{subdir_requires="cp objc"}.
@item target_libs
If defined, this variable lists (space-separated) targets in the top
level @file{Makefile} to build the runtime libraries for this
language, such as @code{target-libobjc}.
@item lang_dirs
If defined, this variable lists (space-separated) top level
directories (parallel to @file{gcc}), apart from the runtime libraries,
that should not be configured if this front end is not built.
@item build_by_default
If defined to @samp{no}, this language front end is not built unless
enabled in a @option{--enable-languages} argument.  Otherwise, front
ends are built by default, subject to any special logic in
@file{configure.ac} (as is present to disable the Ada front end if the
Ada compiler is not already installed).
@item boot_language
If defined to @samp{yes}, this front end is built in stage 1 of the
bootstrap.  This is only relevant to front ends written in their own
languages.
@item compilers
If defined, a space-separated list of compiler executables that will
be run by the driver.  The names here will each end
with @samp{\$(exeext)}.
@item outputs
If defined, a space-separated list of files that should be generated
by @file{configure} substituting values in them.  This mechanism can
be used to create a file @file{@var{language}/Makefile} from
@file{@var{language}/Makefile.in}, but this is deprecated, building
everything from the single @file{gcc/Makefile} is preferred.
@item gtfiles
If defined, a space-separated list of files that should be scanned by
gengtype.c to generate the garbage collection tables and routines for
this language.  This excludes the files that are common to all front
ends.  @xref{Type Information}.

@end table

@node Back End
@subsection Anatomy of a Target Back End

A back end for a target architecture in GCC has the following parts:

@itemize @bullet
@item
A directory @file{@var{machine}} under @file{gcc/config}, containing a
machine description @file{@var{machine}.md} file (@pxref{Machine Desc,
, Machine Descriptions}), header files @file{@var{machine}.h} and
@file{@var{machine}-protos.h} and a source file @file{@var{machine}.c}
(@pxref{Target Macros, , Target Description Macros and Functions}),
possibly a target Makefile fragment @file{t-@var{machine}}
(@pxref{Target Fragment, , The Target Makefile Fragment}), and maybe
some other files.  The names of these files may be changed from the
defaults given by explicit specifications in @file{config.gcc}.
@item
If necessary, a file @file{@var{machine}-modes.def} in the
@file{@var{machine}} directory, containing additional machine modes to
represent condition codes.  @xref{Condition Code}, for further details.
@item
An optional @file{@var{machine}.opt} file in the @file{@var{machine}}
directory, containing a list of target-specific options.  You can also
add other option files using the @code{extra_options} variable in
@file{config.gcc}.  @xref{Options}.
@item
Entries in @file{config.gcc} (@pxref{System Config, , The
@file{config.gcc} File}) for the systems with this target
architecture.
@item
Documentation in @file{gcc/doc/invoke.texi} for any command-line
options supported by this target (@pxref{Run-time Target, , Run-time
Target Specification}).  This means both entries in the summary table
of options and details of the individual options.
@item
Documentation in @file{gcc/doc/extend.texi} for any target-specific
attributes supported (@pxref{Target Attributes, , Defining
target-specific uses of @code{__attribute__}}), including where the
same attribute is already supported on some targets, which are
enumerated in the manual.
@item
Documentation in @file{gcc/doc/extend.texi} for any target-specific
pragmas supported.
@item
Documentation in @file{gcc/doc/extend.texi} of any target-specific
built-in functions supported.
@item
Documentation in @file{gcc/doc/extend.texi} of any target-specific
format checking styles supported.
@item
Documentation in @file{gcc/doc/md.texi} of any target-specific
constraint letters (@pxref{Machine Constraints, , Constraints for
Particular Machines}).
@item
A note in @file{gcc/doc/contrib.texi} under the person or people who
contributed the target support.
@item
Entries in @file{gcc/doc/install.texi} for all target triplets
supported with this target architecture, giving details of any special
notes about installation for this target, or saying that there are no
special notes if there are none.
@item
Possibly other support outside the @file{gcc} directory for runtime
libraries.  FIXME: reference docs for this.  The libstdc++ porting
manual needs to be installed as info for this to work, or to be a
chapter of this manual.
@end itemize

If the back end is added to the official GCC source repository, the
following are also necessary:

@itemize @bullet
@item
An entry for the target architecture in @file{readings.html} on the
GCC web site, with any relevant links.
@item
Details of the properties of the back end and target architecture in
@file{backends.html} on the GCC web site.
@item
A news item about the contribution of support for that target
architecture, in @file{index.html} on the GCC web site.
@item
Normally, one or more maintainers of that target listed in
@file{MAINTAINERS}.  Some existing architectures may be unmaintained,
but it would be unusual to add support for a target that does not have
a maintainer when support is added.
@end itemize

@node Testsuites
@section Testsuites

GCC contains several testsuites to help maintain compiler quality.
Most of the runtime libraries and language front ends in GCC have
testsuites.  Currently only the C language testsuites are documented
here; FIXME: document the others.

@menu
* Test Idioms::     Idioms used in testsuite code.
* Test Directives:: Directives used within DejaGnu tests.
* Ada Tests::       The Ada language testsuites.
* C Tests::         The C language testsuites.
* libgcj Tests::    The Java library testsuites.
* gcov Testing::    Support for testing gcov.
* profopt Testing:: Support for testing profile-directed optimizations.
* compat Testing::  Support for testing binary compatibility.
@end menu

@node Test Idioms
@subsection Idioms Used in Testsuite Code

In general, C testcases have a trailing @file{-@var{n}.c}, starting
with @file{-1.c}, in case other testcases with similar names are added
later.  If the test is a test of some well-defined feature, it should
have a name referring to that feature such as
@file{@var{feature}-1.c}.  If it does not test a well-defined feature
but just happens to exercise a bug somewhere in the compiler, and a
bug report has been filed for this bug in the GCC bug database,
@file{pr@var{bug-number}-1.c} is the appropriate form of name.
Otherwise (for miscellaneous bugs not filed in the GCC bug database),
and previously more generally, test cases are named after the date on
which they were added.  This allows people to tell at a glance whether
a test failure is because of a recently found bug that has not yet
been fixed, or whether it may be a regression, but does not give any
other information about the bug or where discussion of it may be
found.  Some other language testsuites follow similar conventions.

In the @file{gcc.dg} testsuite, it is often necessary to test that an
error is indeed a hard error and not just a warning---for example,
where it is a constraint violation in the C standard, which must
become an error with @option{-pedantic-errors}.  The following idiom,
where the first line shown is line @var{line} of the file and the line
that generates the error, is used for this:

@smallexample
/* @{ dg-bogus "warning" "warning in place of error" @} */
/* @{ dg-error "@var{regexp}" "@var{message}" @{ target *-*-* @} @var{line} @} */
@end smallexample

It may be necessary to check that an expression is an integer constant
expression and has a certain value.  To check that @code{@var{E}} has
value @code{@var{V}}, an idiom similar to the following is used:

@smallexample
char x[((E) == (V) ? 1 : -1)];
@end smallexample

In @file{gcc.dg} tests, @code{__typeof__} is sometimes used to make
assertions about the types of expressions.  See, for example,
@file{gcc.dg/c99-condexpr-1.c}.  The more subtle uses depend on the
exact rules for the types of conditional expressions in the C
standard; see, for example, @file{gcc.dg/c99-intconst-1.c}.

It is useful to be able to test that optimizations are being made
properly.  This cannot be done in all cases, but it can be done where
the optimization will lead to code being optimized away (for example,
where flow analysis or alias analysis should show that certain code
cannot be called) or to functions not being called because they have
been expanded as built-in functions.  Such tests go in
@file{gcc.c-torture/execute}.  Where code should be optimized away, a
call to a nonexistent function such as @code{link_failure ()} may be
inserted; a definition

@smallexample
#ifndef __OPTIMIZE__
void
link_failure (void)
@{
  abort ();
@}
#endif
@end smallexample

@noindent
will also be needed so that linking still succeeds when the test is
run without optimization.  When all calls to a built-in function
should have been optimized and no calls to the non-built-in version of
the function should remain, that function may be defined as
@code{static} to call @code{abort ()} (although redeclaring a function
as static may not work on all targets).

All testcases must be portable.  Target-specific testcases must have
appropriate code to avoid causing failures on unsupported systems;
unfortunately, the mechanisms for this differ by directory.

FIXME: discuss non-C testsuites here.

@node Test Directives
@subsection Directives used within DejaGnu tests

Test directives appear within comments in a test source file and begin
with @code{dg-}.  Some of these are defined within DejaGnu and others
are local to the GCC testsuite.

The order in which test directives appear in a test can be important:
directives local to GCC sometimes override information used by the
DejaGnu directives, which know nothing about the GCC directives, so the
DejaGnu directives must precede GCC directives.

Several test directives include selectors which are usually preceded by
the keyword @code{target} or @code{xfail}.  A selector is: one or more
target triplets, possibly including wildcard characters; a single
effective-target keyword; or a logical expression.  Depending on the
context, the selector specifies whether a test is skipped and reported
as unsupported or is expected to fail.  Use @samp{*-*-*} to match any
target.