Re: Structuring the manual for a language front end.

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

On Tue, 5 Jun 2001, Tim Josling wrote:

> Does anyone have any suggestions on how to structure a manual for
> a front end to gcc? In particular in the case of 'treelang' which
> is a sample/demo language for the edification of new compiler
> developers.

There are several related manual design issues here:

* For the user manual for a front end, the GNU Coding Standards discuss
how to structure manual, inclusing how to provide both tutorial and
reference information.  The nature of treelang is that it is fairly
atypical here, in that you need to document the language rather than
presuming people know the language and documenting differences in GCC's
version.

* For the internals manual for a front end (which may be part of the same 
manual), if there is one, describe the overall structure of the front end, 
how a program passes through it, what is in what source files, which 
functions do what, etc..

* For the manual on writing front ends - which is what I was mainly
thinking of - we need to provide comprehensive documentation on the front
end interface, which is also approachable for people wanting to learn how
to write front ends (so, for example, someone doing a research project
compiler for a specialised language finds it reasonably straightforward to
write a GCC front end as an alternative to going via generated C code).  
A possible outline for what should go in this manual - which may be part
of the main manual or a general internals manual - is below.  As part of
writing such a manual (which should use the existing documentation in
c-tree.texi, and other such manuals in existence if the assignment issues
can be resolved), the opportunity should be taken to clean up the front 
end interface.  I've probably missed some things that should go in a front 
end interface manual, and the order may need to change.  This manual needs 
to include plenty of references to examples - both in treelang, designed 
as an example, and to the other front ends.

Introduction.  Existing front ends, in-tree and out of tree.

Languages for which GCC's internal representation is designed.  Why to
write GCC front ends for even very different languages (e.g. the
Mercury front end, or front ends developed as research projects);
advantages versus going via C.

The GCC build system for front ends.  What goes in config-lang.in.
What goes in Make-lang.in.  (Subdirectory Makefile.in as a deprecated
interface.)

The GCC build system for runtime libraries, including multilibs and
cross-compilation.  What needs to go where when adding a runtime
library.

How to fit testsuites, both compiler and runtime library, into the GCC
testsuite system.

The C-level interface for front ends.  (Clean up the interface in the
process of documenting it, rather than just documenting the present ad
hoc system.)

Headers a front end provides (lang-options.h, lang-specs.h).

Hooks provided by a front end.  Interface with toplev.c.  Option
parsing.  Variables a front end needs to provide.

How and when to use Bison and Flex, versus hand-written parsers and
lexers, in front ends.  Use of gperf.

Function at a time mode as the preferred alternative for a new front
end.  Option to use trees internally, or another internal
representation that is converted to trees only after all the syntax
and semantic checking has been done.

The tree format.  How trees are converted to RTL; handling of
language-specific tree codes.

Documentation of basic tree structures and functions to manipulate
them.

Documentation of all tree codes, functions and accessor macros (as in
c-tree.texi).  Use of constant folding.

Optimizations on trees (e.g. inlining in C++) versus on RTL.

The diagnostics interface.  Functions for warnings/errors/..., and
when to use which of them.  Adding language-specific format codes.
Working with i18n.

The garbage collection interface.  Memory management.  When to use
alloca(), when to use obstacks.

Portability.  What front ends can presume (e.g. that they are compiled
by GCC) and what they can't (e.g. modern libc features).  Use of
libiberty.  General data structures in libiberty and GCC: using them
versus rolling your own yet another hash table.  Special
considerations for programs run on the build system (until we have a
build libiberty); Canadian crosses.

Special considerations for front ends written in their own non-C
language (e.g. Ada).

Documenting your front end.  Texinfo manuals; generating output from
them.  Putting output on the gcc.gnu.org website: onlinedocs and
update_web_docs.  texi2html versus makeinfo --html.  Generating
manpages with texi2pod.pl.  --help and --version.

Places where the rest of GCC should be changed when integrating a
front end into the main distribution.  See e.g.
http://gcc.gnu.org/ml/gcc/2001-05/msg01181.html

-- 
Joseph S. Myers
jsm28@cam.ac.uk