@c GPI.DOC, version 1.0 for GNU Pascal 2.0 (corresponding to GCC 2.7.2.1)
@c 26. July 1996, Peter Gerwinski <peter.gerwinski@uni-essen.de>
@c last modified: 4. Aug. 1996

@node GPI files
@chapter GPI files -- GNU Pascal Interfaces

This file documents the mechanism how information is transferred
from the exporting Modules and Units to the Program, Module or
Unit which imports (uses) the information.

The GPI mechanism is not (yet :-) as stable as it should be.  
If you encounter problems with your Modules or Units, please do 
the following:

@itemize @bullet
@item
To work around, include the module interface (or the whole
Unit) via a preprocessor directive #include "myfile.pas" or
(*$i MyFile *) into the source of the main program, *prior* to
the "Program foo" headline.  Do not use #include or $i in a 
Module using another Module; use them in the main program, 
instead -- and in the correct order.

@item
To help the problem being solved, please report the bug in
the following way:

@itemize @bullet
@item
Construct the *smallest possible* combination of Modules
(Units) and Programs which still produces the error.

@item
Send the bug report and your (small!) example programs via 
e-mail to Peter Gerwinski <peter.gerwinski@@uni-esen.de>.
@end itemize

@item
To solve the problem by yourself (requires experience with
`C'), get the source of the GNU Pascal Compiler (GPC) from 
ftp://kampi.hut.fi/jtv/gnu-pascal, make sure that you can 
compile it on your system and go on reading.
@end itemize


@section The GPI mechanism

A GPI file contains a precompiled GNU Pascal Interface.  ``Precompiled''
means in this context that the Interface already has been
parsed (i.e the front-end has done its work), but that no assembler
output has been produced yet.

The GPI file format is an implementation-dependent (but not @emph{too}
implementation-dependent ;-) file format for storing GNU Pascal 
Interfaces to be exported---Extended Pascal and PXSC module 
interfaces as well as interface parts of Borland Pascal Units 
compiled with GNU Pascal.

To see what information is stored in or loaded from a GPI file, run 
GPC with an additional command-line option @code{--debug-gpi}.  Then, GPC 
will write a human-readable version of what is being stored/loaded 
to stderr.

While parsing an Interface, GPC stores the names of exported objects
in tree lists---in gpc-parse.y, the bison (yacc) source of GPC's parser,
search for @code{handle_autoexport}.  At the end of the Interface, everything
is stored in one or more GPI files.  This is called in gpc-parse.y---search 
for @code{create_gpi_files ()}.

Everything else is done in gpc-module.c.  Here you can find the source
of create_gpi_files () which documents the file format:  First, a header 
of 33 bytes containing the string @code{GNU Pascal Module/Unit Interface\n}
is stored, then the name of the primary source file of the module as a
string, then the name of the exported interface as a tree node (see
below), after that all exported names in the order as they were stored
while parsing.

The names and the objects (i.e. constants, data types, variables and
functions) they refer to are internally represented as so-called
@emph{tree nodes} as defined in the files tree.h and tree.def from the GCC
source (i.e. the source of the GNU C compiler).  The names are stored 
as @code{IDENTIFIER_NODE}s, their meanings as @code{IDENTIFIER_GLOBAL_VALUE}s 
of these nodes.  The main problem when storing tree nodes is that they 
form a complicated tree in memory with a lot of circular references
making it hard to decide which information must be stored and which 
mustn't.

The functions load_tree and store_tree are intended to load/store
a tree node in a GPI file.

Each tree node has a @code{TREE_CODE} indicating what kind of information
it contains.  Each different tree node must be stored in a different
way.  See the source of @code{load_tree} and @code{store_tree} for details.

Most tree nodes contain pointers to other tree nodes; therefore
@code{load_tree} and @code{store_tree} are recursive functions.  
The @code{--debug-gpi} debugging informations contains the recursion 
level in parantheses, e.g. @code{loaded (2):} means that the loaded 
information was requested by a pointer contained in a tree node 
requested by a pointer contained in a tree node representing an 
exported symbol.

Since this recursion can be circular (think of a record containing
a pointer to a record of the same type), we must resolve references
to tree nodes which already have been loaded.  For this reason, and 
for saving disk space, I have introduced a @code{gpi_contents} list
containing pointers to all nodes so far loaded from / stored in the
GPI file under consideration.  When storing a node which already is
in the gpi_contents list, a (normally invalid) @code{TREE_CODE} of 255 
@samp{(0xFF)} followed by the (int) index of the node in the 
@code{gpi_contents} list is stored instead.  Like this, the reference 
uses 1 byte plus the size of an int (normally 4) in the GPI file.  
In the debugging information, this method of storing/loading is 
indicated as @code{via gpi_contents}.

There are some special tree_nodes (e.g. @code{integer_type_node} or
@code{NULL_TREE}) which are used very often.  I have assigned (normally 
invalid) unique @code{TREE_CODES} for them, so they can be stored in a 
single byte.

That's it.  Now you should be able to ``read'' GPI files using GPC's
@code{--debug-gpi} option.  If you encounter a case where the loaded 
information differs too much from the stored information, you 
have found a bug---congratulations!  What ``too much'' means, depends
on the object being stored in / loaded from the GPI file.  Remind
that the order things are loaded from a GPI file is the @emph{reversed}
order things are stored when considering @emph{different} recursion levels,
but the @emph{same} order when considering ths @emph{same} recursion level.
