.\" Copyright (C) 1992, Digital Equipment Corporation
.\" All rights reserved.
.\" See the file COPYRIGHT for a full description.
.\"
.\" Last modified on Tue Oct 13 16:39:21 PDT 1992 by muller
.\"      modified on Tue Sep 22 08:36:57 PDT 1992 by mhb
.nh
.TH M3MAKE 1
.SH NAME
m3make \- Modula-3 make

.\"------------------------------------------------------------------------
.SH SYNTAX
.B m3make 
options target ...

.\"------------------------------------------------------------------------
.SH DESCRIPTION

.PP
.B m3make
is a slightly enhanced version of plain 
.BR make (1).
The primary benefit of
.B m3make
is that the operational description found in most makefiles is
replaced by a more declarative one.
The result is that
.B m3makefiles
are smaller, simpler, and more portable.
.PP
.B m3make
is essentially a combination of 
.BR cpp (1)
and
.BR make (1);
don't be afraid, the interface to the combination is usually simpler
than that of
.BR make (1). 
When started, 
.B m3make
looks for a file named
.I m3makefile
in the current directory.  This file describes what goes
into a particular piece of the system, but not how to construct it.
The operational aspects of the system are confined to templates that
are configured when SRC Modula-3 is installed.
The language recognized by
.B m3make
is described below.
.PP
To process an
.BR m3makefile ,
just type 
.BR m3make.
.PP
By default,
.B m3make
defines the following targets for all makefiles:
.TP
.B all
constructs this package's program or library
.TP
.B install
installs the result in a public directory
.TP
.B clean
deletes all derived files
.PP
The default target is
.BR all .
.PP
If you want additional things done with these targets, you can extend
them with make's double-colon rules.  For example, suppose that
the file
.B lex.yy.c
is a derived file that you want to be able to
.BR scratch ,
add the following to your
.BR m3makefile :
.IP
.B clean:: ; /bin/rm -f lex.yy.c
.PP
Note the two colons after the target name.  They are the standard
.B make
notation for extending an existing target.
In
.BR m3makefile s
you should always use double colons.
See the
.BR make (1)
man page for the gory details.
.PP
.B m3makefiles
follow the C convention for comments; that is, they are
enclosed by
.BR /* and */ .
A comment can cross line boundaries.
.PP
Note that the full power of make is available in
.B m3make
since the last step of
.B m3make
is to invoke
.BR make .
Most m3makefiles don't need this extra generality.
.PP
If you have trouble with
.BR m3make ,
it may help to examine the actual input to
.BR make .
The final file created by
.B m3make
and passed to
.B make
is named
.BR .makefile .

.\"------------------------------------------------------------------------
.SH OPTIONS

The following options are interpreted by
.BR m3make :

.TP
.B -d " dir"
Change the current directory to 
.I dir
before doing anything.

.TP
.BI -f " file"
Use
.I file 
instead of
.I m3makefile
as the name of the m3makefile

.TP
.BI -D sym
This option is passed unchanged to the cpp preprocessor.

.TP
.BI -U sym
This option is passed unchanged to the cpp preprocessor.

.TP
.BI -R " dir"
Use 
.I dir
for the root of the packages, instead of /proj/m3/pkg.

.TP
.BI -T " file"
Use
.I file
as the template, instead of the standard one.

.PP
The other options are passed unchanged to 
.BR make .


.\"------------------------------------------------------------------------
.SH MODULA-3 PACKAGES

.PP
SRC Modula-3 is distributed as a set of packages.
A
.I package
is a directory of files including an
.BR m3makefile ,
.BR README ,
.BR COPYRIGHT ,
and usually a collection of Modula-3 source files.  Packages are located
in a fixed location in the file system that is determined at configuration
time (e.g. /proj/m3/pkg). There are three primary types of packages:
.IR source ,
.IR program ,
and
.IR library .
A source package contains a collection
of Modula-3 sources, it builds nothing.
A program package constructs a single executable program (an
.B a.out
file) by compiling and linking the contents of a set of source packages.
Similarly, a library package constructs a single library (a
.B .a
file) from a set of source packages.
.PP
The m3makefile for a source package simply lists the pieces of source
that are to be included in programs or libraries that name this package.
.PP
The
.B m3makefile
for a program package names the sources needed to build the program.
It contains a single
.B program()
or
.B Program()
invocation (described below).
.PP
The
.B m3makefile
for a library package names the sources to be included in the library.
It contains a single
.B library()
or
.B Library()
invocation (described below).
.PP
Note that like in a program, all the imports of a library must be satisfied.
If an m3makefile builds a library
.B libA.a
and any of the objects in that library
import interfaces from another library
.BR libB.a ,
then
.B import_lib(B)
must be specified in that
.BR m3makefile .
.PP
When SRC Modula-3 is configured and installed several public
repositories are identified.
There is a repository of the sources of shared interfaces
and generics.
In this man page we refer to it as the
.B /pub
directory.
There is a repository of the shared libraries (the
.B /lib
directory).
There is a repository of the shared executable programs (the
.B /bin
directory).

.\"------------------------------------------------------------------------
.SH PREDEFINED MACROS

.PP
The following macros are predefined by
.BR m3make .
Most
.B m3makefiles
are simply lists of invocations of these macros.
Note that source files are named relative to the
.B m3makefile
that mentions them.
.TP
.BI BinExport( X )
export source file
.I X
to
.BR /bin .
.TP
.BI BindExport( X )
export derived file
.I X
to
.BR /bin .
.TP
.BI bundle( m )
The module
.B m
is to be built as a bundle of the files specified by the calls to the
.I resource 
and 
.I resource_named
macros.
.TP
.BI c_source( X )
the file
.I X.c
contains a C module, include it in the compilation.
.TP
.BI generic_interface( X )
the file
.I X.ig
contains a generic interface.
.TP
.BI Generic_interface( X )
like
.BR generic_interface ,
but also exports
.I X.ig
to
.BR /pub .
.TP
.BI generic_implementation( X )
the file
.I X.mg
contains a generic module.
.TP
.BI Generic_implementation( X )
like
.BR generic_implementation ,
but also exports
.I X.mg
to
.BR /pub .
.TP
.BI generic_module( X )
the files
.I X.ig
and
.I X.mg
contain a generic interface and its generic implementation.
.TP
.BI Generic_module( X )
like
.BR generic_module ,
but also exports
.I X.ig
and
.I X.mg
to
.BR /pub .
.TP
.BI h_source( X )
the file
.I X.h
contains a C include file.
Add the directory containing
.I X.h
to the default search path.
.TP
.BI H_source( X )
like
.BR h_source ,
but also exports
.I X.h
to
.BR /pub .

.TP
.BI import_lib( X )
include
.BI \-l X
in the final link command.
.TP
.BI import_obj( X )
include
.I X
in the final link command.
.TP
.BI interface( X )
the file
.I X.i3
contains an interface.
Add the directory containing
.I X.i3
to the default search path.
.TP
.BI Interface( X )
like
.BR interface ,
but also exports
.I X.i3
to
.BR /pub .
.TP
.BI implementation( X )
the file
.I X.m3
contains a module.
.TP
.B just_compile
compile the named sources, but don't produce a final program or library.
.TP
.BI library( X )
constructs a library named
.BI lib X \.a
and its link info file
.BI lib X \.ax
from the given sources.
.TP
.BI Library( X )
like
.BR library ,
but also exports
.BI lib X \.a
and
.BI lib X \.ax
to
.BR /lib .
.TP
.BI LibExport( X )
export source file
.I X
to
.BR /lib .
.TP
.BI LibdExport( X )
export derived file
.I X
to
.BR /lib .
.TP
.BI manPage( name , sec )
format man page
.IR name.sec .
.TP
.BI ManPage( name , sec )
like
.BR manPage ,
but also exports the man page to section
.I sec
of the public man page repository.
.TP
.BI ManExport( X , s )
export source file
.I X.s
to section
.I s
of the man pages.
.TP
.BI MandExport( X , s )
export derived file
.I X.s
to section
.I s
of the man pages.
.TP
.BI module( X )
the files
.I X.i3
and
.I X.m3
contain an interface and its implementation.
Add the directory containing
.I X.i3
to the default search path.
.TP
.BI Module( X )
like
.BR module ,
but also exports
.I X.i3
to
.BR /pub .
Add the directory containing
.I X.i3
to the default search path.
.TP
.BI noweb( f,r,d )
The file
.I f
is a 
.B noweb
source file.  The file
.I d
is a Modula-3 source file (including its extension) which should be
created by extracting from the root
.I r
in the noweb file.

.TP
.BI Noweb( f,r,d )
Similar to 
.BR noweb ,
but also exports the file
.I d
to
.BR /pub.

.TP
.BI package( P )
include the sources named in package
.IR P .
This is equivalent to
.BI source_dir( X/P )
where
.I X
is the predefined location of your Modula-3 packages.
.TP
.BI pgm_source( X )
the file
.I X
contains compilable source (e.g.
.BR .ic ,
.BR .mc ,
.B .is
or
.B .ms
files).
.TP
.BI program( X )
constructs an executable program named
.I X
from the given sources.
.TP
.BI Program( X )
like
.IR program ,
but also exports
.I X
to
.BR /bin .
.TP
.BI PubExport( X )
export file
.I X
to
.BR /pub .
.TP
.BI resource( file )
Shorthand for
.I resource(file,file)
.TP
.BI resource_named( rd,file )
.I file
is a resource file.  It will be accessible via the reader
.I rd
if a bundle is built.
.TP
.BI s_source( X )
the file
.I X.s
contains an assembly module.
.TP
.BI source( X )
the file 
.I X
contains non-compilable source.
.TP
.BI source_dir( D )
recursively include the sources named in the m3makefile in directory
.IR D .
The current system can only handle one level of
.BR source_dir .

.\"------------------------------------------------------------------------
.SH MAKE VARIABLES

.PP
In addition to the entries above, a program or library package may
define any of the following
.B make
variables:
.TP
.B M3
the Modula-3 compiler to use (default
.BR m3 ).
.TP
.B M3FLAGS
the primary compilation flags (default
.BR "-w1 -make -why" ).
.TP
.B M3OPT
the optional debugging and optimization flags (default
.BR \-g ).
.TP
.B M3DEFPATH
the search path argument for imported interfaces (default empty).
Note that when setting this variable you must include the
.B \-D
part of the argument.
For example,
.br
.BR "M3DEFPATH\ =\ -D../mypub:../yourpub" .
.TP
.B M3LIBPATH
the search path argument for imported libraries (default empty).
Note that when setting this variable you must include the
.B \-L
part of the argument.
For example,
.br
.BR "M3LIBPATH\ =\ -L../mylib:../yourlib" .
.PP
See the
.BR m3 (1)
man page for full details on the flags it recognizes.

.\"------------------------------------------------------------------------
.SH INCREMENTAL LINKING

.PP
To use the compiler's incremental linking and dynamic loading facitily
to get smaller programs and faster linking,
partition the components of your program into
the
.I TIP
and the 
.IR ICEBERG .
The TIP is the small part of your program that you want to modify.
The ICEBERG is the large fixed piece which you import from someone else.
Use
.B \#ifdef
to partition your
.BR m3makefile .
For example:
.na

         #ifdef TIP
         implementation (main)
         #endif

         #ifdef ICEBERG
         import_lib (m3i)
         import_lib (m3X11R4)
         #endif

         program (my_pgm)
.fi
.PP
Note that the
.B program
line is not included in the
.BR \#ifdef s.
Any other lines (e.g.
.B M3OPT=...
or
.BR M3DEFPATH=... )
that apply to all pieces should also be outside the
.BR \#ifdef s.
.PP
Next, type
.B "m3make -DICEBERG"
to build the ICEBERG.
Then, type
.B "m3make -DTIP"
to build the TIP.  This is the step that you
repeat during your edit-compile-link-run-crash-s<cratch head-debug cycle.
.PP
You will find a bunch of new files:
.TP
.B my_pgm.b
the bulk of the ICEBERG.
.TP
.B my_pgm.bx
the Modula-3 link information for the ICEBERG.
.TP
.B my_pgm.by
the ICEBERG's symbol table.
.TP
.B my_pgm.ov
the bulk of the TIP.
.TP
.B my_pgm
a two-line shell script that runs the program.
.PP
If you type
.B m3make
with no arguments, the full stand-alone program
will be built just as it would before you added the
.BR \#ifdef s.
Remember to remove the shell script first,
otherwise
.B m3make
will decide that everything's up-to-date.
.PP
Note, the shell script uses local file names for the ICEBERG and TIP.
Without rewriting it, you cannot run your program from a directory
other than the one where you built it.
.PP
Do not ship the ICEBERG and TIP version of your program to the public
.B /bin
directory.  They will not work there.

.\"------------------------------------------------------------------------
.SH MACHINE DEPENDENCIES

.PP
Generally, each version of a machine-dependent program or library is
described by a separate
.B m3makefile
that references the particular
source packages needed for that version.  Machine-dependencies may
also be encoded with cpp
.BR #if 's
and
.BR #ifdef 's.
For example, the piece of the base library's
.B m3makefile
that includes the random number generator looks like this:
.na

         package(random/generic)
         #ifdef TARGET_VAX
         package(random/VAX)
         #endif
         #ifdef TARGET_DS3100
         package(random/IEEE-le)
         #endif
         #ifdef TARGET_SPARC
         package(random/IEEE-be)
         #endif
.fi

.\"------------------------------------------------------------------------
.SH EXAMPLES

.PP
The following packages should be good starting
points for writing your own m3makefiles:
.TP
text\ \ \ \ \ \ \ 
the source package that implements
.BR TEXT s.
.TP
calculator
a small, simple FormsVBT program.
.TP
sx\ \ \ \ \ \ \ \ 
a small, self-contained library package.
.TP
libm3
a larger library package that imports several source packages.
.TP
ui/apps
a custom makefile to build several test programs.
.TP
compiler
a large program (the compiler itself).

.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR m3 (1),
.BR make (1),
.BR cpp (1).

.SH AUTHOR OF OBJECT
     Bill Kalsow

.SH AUTHOR OF DOCUMENTATION
     Bill Kalsow