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

@node AutoMake
@chapter GNU Pascal's AutoMake facility

This file documents a feature of GPC which makes it superfluos
to use `make' (and to write a Makefile) in most cases.

(For those who know Borland Pascal:  @samp{bpc -m foo}  (``make'') is now 
@samp{gpc --automake foo.pas.})

When you invoke GPC with the command line option @code{--automake}, it
checks whether the Modules/Units your program uses must be
recompiled.  If so, it recursively calls @code{GPC -c} to compile them.
Furthermore, the names of user-written object files are 
automatically passed to the linker.  This means that you can
compile (and link) your program with a line like

@smallexample
  gpc --automake foo.pas
@end smallexample

even if @code{foo} is a large project with a lot of Modules/Units and
include files.  (Yes, when you have modified an include file, GPC
recognizes which Modules/Units must be recompiled!)

If you want to pass command line options to such second-level
compiles, specify them with the --automake option:

@smallexample
  gpc --automake="-g -O6 -D TERMCAP" foo.pas
@end smallexample

Don't forget the quotes if the string contains blanks.  When you omit
this specification, top level command line options are @emph{not}
automatically passed through.


@section The AutoMake mechanism---how it works

When a Program/Module/Unit imports (uses) an Interface, GPC
searches for the GPI file (see GPI.DOC) derived from the name
of the Interface.

Case 1:  A GPI file was found.

Each GPI file contains the name of the primary source file
(normally a @code{.pas} or @code{.p} file) of the Module/Unit, and the
names of all interfaces imported.  GPC reads this information 
and invokes itself with a command like

@smallexample
  gpc foo.pas -M -o foo.d
@end smallexample

This means: preprocess the file, and write down the name of
the object file and those of all its source files in @code{foo.d}.
GPC reads @code{foo.d} and looks if the object file exists and if
the source was modified since the creation of the object file
and the gpi file.  If so, GPC calls itself again to compile
the primary source file.  When everything is done, the .d
file is removed.  If there was no need to recompile, all
interfaces imported by the Module/Unit are processed in the
same way as this one.

Case 2:  No GPI file was found.

In this case, GPC derives the name of the source file from
that of the Interface by trying first @code{interface.p}, then
@code{interface.pas}.  This will almost always work with Borland
Pascal Units, almost never with Extended Pascal Modules.  With
Extended Pascal, compile the Module once manually in order to
produce a GPI file.

All this is done by the function @code{gpi_open ()} which uses some
auxiliary functions such as @code{module_must_be_recompiled ()} and
@code{compile_module ()}.

Each time an object file is compiled or recognized as being
up-to-date, its name is stored in a temporary file with the 
same base name as all the other temporary files used by GPC 
but the extension .gpc.  When the top-level gpc is invoked 
(which calls gpc1 later on), it passes the name of this 
temporary file as an additional command line parameter to
gpc1.  After compilation has been completed, the top-level 
gpc reads the temporary file and adds the new object files 
to the arguments passed to the linker.

The additional command (@code{--amtmpfile}; not to be specified
by the user!) is passed to child GPC processes, so all compiles
use the same temporary file.

The source for this is merely in @code{gpc-module.c}, but there are
also some hacks in @code{gcc.c}, additional command line options in
@code{gpc-options.h} and @code{gpc-decl.c}, and @code{gpc-defs.h} is 
adapted to support new functions and global variables.
