sourcebuild.texi

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

@node Documentation
@subsection Building Documentation

The main GCC documentation is in the form of manuals in Texinfo
format.  These are installed in Info format; DVI versions may be
generated by @samp{make dvi}, PDF versions by @samp{make pdf}, and
HTML versions by @command{make html}.  In addition, some man pages are
generated from the Texinfo manuals, there are some other text files
with miscellaneous documentation, and runtime libraries have their own
documentation outside the @file{gcc} directory.  FIXME: document the
documentation for runtime libraries somewhere.

@menu
* Texinfo Manuals::      GCC manuals in Texinfo format.
* Man Page Generation::  Generating man pages from Texinfo manuals.
* Miscellaneous Docs::   Miscellaneous text files with documentation.
@end menu

@node Texinfo Manuals
@subsubsection Texinfo Manuals

The manuals for GCC as a whole, and the C and C++ front ends, are in
files @file{doc/*.texi}.  Other front ends have their own manuals in
files @file{@var{language}/*.texi}.  Common files
@file{doc/include/*.texi} are provided which may be included in
multiple manuals; the following files are in @file{doc/include}:

@table @file
@item fdl.texi
The GNU Free Documentation License.
@item funding.texi
The section ``Funding Free Software''.
@item gcc-common.texi
Common definitions for manuals.
@item gpl.texi
@itemx gpl_v3.texi
The GNU General Public License.
@item texinfo.tex
A copy of @file{texinfo.tex} known to work with the GCC manuals.
@end table

DVI-formatted manuals are generated by @samp{make dvi}, which uses
@command{texi2dvi} (via the Makefile macro @code{$(TEXI2DVI)}).  
PDF-formatted manuals are generated by @samp{make pdf}, which uses
@command{texi2pdf} (via the Makefile macro @code{$(TEXI2PDF)}).  HTML
formatted manuals are generated by @command{make html}.  Info
manuals are generated by @samp{make info} (which is run as part of
a bootstrap); this generates the manuals in the source directory,
using @command{makeinfo} via the Makefile macro @code{$(MAKEINFO)},
and they are included in release distributions.

Manuals are also provided on the GCC web site, in both HTML and
PostScript forms.  This is done via the script
@file{maintainer-scripts/update_web_docs}.  Each manual to be
provided online must be listed in the definition of @code{MANUALS} in
that file; a file @file{@var{name}.texi} must only appear once in the
source tree, and the output manual must have the same name as the
source file.  (However, other Texinfo files, included in manuals but
not themselves the root files of manuals, may have names that appear
more than once in the source tree.)  The manual file
@file{@var{name}.texi} should only include other files in its own
directory or in @file{doc/include}.  HTML manuals will be generated by
@samp{makeinfo --html}, PostScript manuals by @command{texi2dvi}
and @command{dvips}, and PDF manuals by @command{texi2pdf}.
All Texinfo files that are parts of manuals must
be checked into SVN, even if they are generated files, for the
generation of online manuals to work.

The installation manual, @file{doc/install.texi}, is also provided on
the GCC web site.  The HTML version is generated by the script
@file{doc/install.texi2html}.

@node Man Page Generation
@subsubsection Man Page Generation

Because of user demand, in addition to full Texinfo manuals, man pages
are provided which contain extracts from those manuals.  These man
pages are generated from the Texinfo manuals using
@file{contrib/texi2pod.pl} and @command{pod2man}.  (The man page for
@command{g++}, @file{cp/g++.1}, just contains a @samp{.so} reference
to @file{gcc.1}, but all the other man pages are generated from
Texinfo manuals.)

Because many systems may not have the necessary tools installed to
generate the man pages, they are only generated if the
@file{configure} script detects that recent enough tools are
installed, and the Makefiles allow generating man pages to fail
without aborting the build.  Man pages are also included in release
distributions.  They are generated in the source directory.

Magic comments in Texinfo files starting @samp{@@c man} control what
parts of a Texinfo file go into a man page.  Only a subset of Texinfo
is supported by @file{texi2pod.pl}, and it may be necessary to add
support for more Texinfo features to this script when generating new
man pages.  To improve the man page output, some special Texinfo
macros are provided in @file{doc/include/gcc-common.texi} which
@file{texi2pod.pl} understands:

@table @code
@item @@gcctabopt
Use in the form @samp{@@table @@gcctabopt} for tables of options,
where for printed output the effect of @samp{@@code} is better than
that of @samp{@@option} but for man page output a different effect is
wanted.
@item @@gccoptlist
Use for summary lists of options in manuals.
@item @@gol
Use at the end of each line inside @samp{@@gccoptlist}.  This is
necessary to avoid problems with differences in how the
@samp{@@gccoptlist} macro is handled by different Texinfo formatters.
@end table

FIXME: describe the @file{texi2pod.pl} input language and magic
comments in more detail.

@node Miscellaneous Docs
@subsubsection Miscellaneous Documentation

In addition to the formal documentation that is installed by GCC,
there are several other text files with miscellaneous documentation:

@table @file
@item ABOUT-GCC-NLS
Notes on GCC's Native Language Support.  FIXME: this should be part of
this manual rather than a separate file.
@item ABOUT-NLS
Notes on the Free Translation Project.
@item COPYING
The GNU General Public License.
@item COPYING.LIB
The GNU Lesser General Public License.
@item *ChangeLog*
@itemx */ChangeLog*
Change log files for various parts of GCC@.
@item LANGUAGES
Details of a few changes to the GCC front-end interface.  FIXME: the
information in this file should be part of general documentation of
the front-end interface in this manual.
@item ONEWS
Information about new features in old versions of GCC@.  (For recent
versions, the information is on the GCC web site.)
@item README.Portability
Information about portability issues when writing code in GCC@.  FIXME:
why isn't this part of this manual or of the GCC Coding Conventions?
@end table

FIXME: document such files in subdirectories, at least @file{config},
@file{cp}, @file{objc}, @file{testsuite}.

@node Front End
@subsection Anatomy of a Language Front End

A front end for a language in GCC has the following parts:

@itemize @bullet
@item
A directory @file{@var{language}} under @file{gcc} containing source
files for that front end.  @xref{Front End Directory, , The Front End
@file{@var{language}} Directory}, for details.
@item
A mention of the language in the list of supported languages in
@file{gcc/doc/install.texi}.
@item
A mention of the name under which the language's runtime library is
recognized by @option{--enable-shared=@var{package}} in the
documentation of that option in @file{gcc/doc/install.texi}.
@item
A mention of any special prerequisites for building the front end in
the documentation of prerequisites in @file{gcc/doc/install.texi}.
@item
Details of contributors to that front end in
@file{gcc/doc/contrib.texi}.  If the details are in that front end's
own manual then there should be a link to that manual's list in
@file{contrib.texi}.
@item
Information about support for that language in
@file{gcc/doc/frontends.texi}.
@item
Information about standards for that language, and the front end's
support for them, in @file{gcc/doc/standards.texi}.  This may be a
link to such information in the front end's own manual.
@item
Details of source file suffixes for that language and @option{-x
@var{lang}} options supported, in @file{gcc/doc/invoke.texi}.
@item
Entries in @code{default_compilers} in @file{gcc.c} for source file
suffixes for that language.
@item
Preferably testsuites, which may be under @file{gcc/testsuite} or
runtime library directories.  FIXME: document somewhere how to write
testsuite harnesses.
@item
Probably a runtime library for the language, outside the @file{gcc}
directory.  FIXME: document this further.
@item
Details of the directories of any runtime libraries in
@file{gcc/doc/sourcebuild.texi}.
@end itemize

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

@itemize @bullet
@item
At least one Bugzilla component for bugs in that front end and runtime
libraries.  This category needs to be mentioned in
@file{gcc/gccbug.in}, as well as being added to the Bugzilla database.
@item
Normally, one or more maintainers of that front end listed in
@file{MAINTAINERS}.
@item
Mentions on the GCC web site in @file{index.html} and
@file{frontends.html}, with any relevant links on
@file{readings.html}.  (Front ends that are not an official part of
GCC may also be listed on @file{frontends.html}, with relevant links.)
@item
A news item on @file{index.html}, and possibly an announcement on the
@email{gcc-announce@@gcc.gnu.org} mailing list.
@item
The front end's manuals should be mentioned in
@file{maintainer-scripts/update_web_docs} (@pxref{Texinfo Manuals})
and the online manuals should be linked to from
@file{onlinedocs/index.html}.
@item
Any old releases or CVS repositories of the front end, before its
inclusion in GCC, should be made available on the GCC FTP site
@uref{ftp://gcc.gnu.org/pub/gcc/old-releases/}.
@item
The release and snapshot script @file{maintainer-scripts/gcc_release}
should be updated to generate appropriate tarballs for this front end.
The associated @file{maintainer-scripts/snapshot-README} and
@file{maintainer-scripts/snapshot-index.html} files should be updated
to list the tarballs and diffs for this front end.
@item
If this front end includes its own version files that include the
current date, @file{maintainer-scripts/update_version} should be
updated accordingly.
@end itemize

@menu
* Front End Directory::  The front end @file{@var{language}} directory.
* Front End Config::     The front end @file{config-lang.in} file.
@end menu

@node Front End Directory
@subsubsection The Front End @file{@var{language}} Directory

A front end @file{@var{language}} directory contains the source files
of that front end (but not of any runtime libraries, which should be
outside the @file{gcc} directory).  This includes documentation, and
possibly some subsidiary programs build alongside the front end.
Certain files are special and other parts of the compiler depend on
their names:

@table @file
@item config-lang.in
This file is required in all language subdirectories.  @xref{Front End
Config, , The Front End @file{config-lang.in} File}, for details of
its contents
@item Make-lang.in
This file is required in all language subdirectories.  It contains
targets @code{@var{lang}.@var{hook}} (where @code{@var{lang}} is the
setting of @code{language} in @file{config-lang.in}) for the following
values of @code{@var{hook}}, and any other Makefile rules required to
build those targets (which may if necessary use other Makefiles
specified in @code{outputs} in @file{config-lang.in}, although this is
deprecated).  It also adds any testsuite targets that can use the
standard rule in @file{gcc/Makefile.in} to the variable
@code{lang_checks}.

@table @code
@itemx all.cross
@itemx start.encap
@itemx rest.encap
FIXME: exactly what goes in each of these targets?
@item tags
Build an @command{etags} @file{TAGS} file in the language subdirectory
in the source tree.
@item info
Build info documentation for the front end, in the build directory.
This target is only called by @samp{make bootstrap} if a suitable
version of @command{makeinfo} is available, so does not need to check
for this, and should fail if an error occurs.
@item dvi
Build DVI documentation for the front end, in the build directory.
This should be done using @code{$(TEXI2DVI)}, with appropriate
@option{-I} arguments pointing to directories of included files.
@item pdf
Build PDF documentation for the front end, in the build directory.
This should be done using @code{$(TEXI2PDF)}, with appropriate
@option{-I} arguments pointing to directories of included files.
@item html
Build HTML documentation for the front end, in the build directory.
@item man
Build generated man pages for the front end from Texinfo manuals
(@pxref{Man Page Generation}), in the build directory.  This target
is only called if the necessary tools are available, but should ignore
errors so as not to stop the build if errors occur; man pages are
optional and the tools involved may be installed in a broken way.
@item install-common
Install everything that is part of the front end, apart from the
compiler executables listed in @code{compilers} in
@file{config-lang.in}.
@item install-info
Install info documentation for the front end, if it is present in the
source directory.  This target should have dependencies on info files
that should be installed.