TOM makefiles

The TOM makefiles is a collection of makefiles that enable easy building and rebuilding of TOM program units, library units, and dynamically loadable units. When using the TOM makefiles, you do not need to be concerned with the details of compilation or using a praticular system.

The following files constitute the TOM makefiles.

GNUmakefile.app
Build a program into which dynamic loading is possible.
GNUmakefile.bin
Build a program into which dynamic loading is not necessarily possible. It depends on the operating system being used whether GNUmakefile.app and GNUmakefile.bin actualy create different executables (on NeXTSTEP, for instance, they do not differ).
GNUmakefile.lib
Build a library unit.
GNUmakefile.load
Build a unit which is to be dynamically loaded.
GNUmakefile.top
Build only subprojects.
GNUmakefile.common
The heart of the TOM makefiles. The others are just front-ends to this file.

This is what a minimal, example GNUmakefile looks like:

UNIT=	 hello
TOM_SRC= Hello

tom_prefix=	/usr/local/tom
include	$(tom_prefix)/GNUmakefile.bin
To start with the last line, we see the GNUmakefile.bin being included. This means the GNUmakefile is for a program. The UNIT is called hello; this will also be the name of the resulting program. This simple program contains only one TOM source file, Hello.t. Note that the extension is not specified.

Important macros

The following macro's are mandatory except whence using the GNUmakefile.top.
UNIT
The name of the unit being built. It depends on the actual makefile being used whether the unit will be built as a library, application, etc.

TOM_SRC
The names of the TOM source files in this unit, without extension. (All TOM source files have `t' as their extension.)

USES_UNITS
The names of the units depended upon by the UNIT. These units will appear in the uses clause of the unit file. If unspecified, USES_UNITS defaults to tom.

LINK_UNITS
The names of the units to be linked with the UNIT to produce the final result. For bin and app targets, this must include the tom unit, and every unit specified in the USES_UNITS. For load targets, this should include everything not already in the app into which loading is performed.

If unspecified, the LINK_UNITS are set equal to the USES_UNITS for bin and app targets, and set to NONE for load targets. NONE (case is important) means that the result will be linked against no other units.

More macros

UNIT_PATH
Specify directories (white-space separated) in which to search for TOM units. These are added to the default directory $(tom_prefix). When looking for a unit u, for each directory dir in the path, the directory dir/u is checked for containing the unit u. The first match will be used.

For example, if your project /home/me/src/myapp uses the units tom, too, and the one calld mylib in /home/me/src/mylib, the UNIT_PATH would be .., and USES_UNITS would include mylib. Note that the makefiles use the fact that a unit can reside in a subdirectory of the same name, in a directory somewhere along the UNIT_PATH. This is especially handy when using a lot of units, each residing in a subdirectory of a specific top-level directory.

SUBPROJECTS
The names of directories to be visited by make after the project in this directory is built, cleaned, etc. This macro usually is the only one used in a directory employing the GNUmakefile.top.

C_SRC
The names of any auxiliary C source files, without the extension. For example, the C unit has a file called glue.c which contains code that interfaces the TOM Math class with the C math library. Consequently, the GNUmakefile of the C unit specifies:
C_SRC=	glue
Actually, the extension does not matter, since for every word mysrc only the replacement mysrc.o is used in the makefiles. The makefiles however only contain the rule to create $(GENDIR)/%.o for every C source file %.c.

GP_SRC
Names of any sources to gp, which Generates Parsers for TOM. As usual, these names exclude any extension (which must be `tp').

EXTRA_OBJ
Any extra object files to be linked with the unit.

Secondary macros

TOMC
Name of the TOM compiler. This defaults to tomc, i.e. the compiler must reside in the user's path.
TOMR
Name of the TOM resolver. This defaults to tomr,
GI
Name of the interface generator. Default value is gi,
TM
Name of Meta TOM, the documentation extractor. Default value is tm.

Targets

all
Build what is to be built.
clean
Remove targets and intermediate files.
gendoc
Extract the documentation from the TOM sources.
docclean
Remove the generated documentation.

Secondary GNUmakefiles

The TOM makefiles employ a file named GNUmakefile.link to list extra objects and libraries needed by the unit being built. The GNUmakefile.link is created by running $(TOMMAKEFILES_DIR)/genlinkfile. This is a shell script that tries to locate all unit files in the $(LINK_UNITS) along the $(UNIT_PATH) and the corresponding .la (libtool archive) files. When a unit is found but the archive isn't, the name of a library directory is constructed in such a way that the TOM standard units are also properly found in their installed place.

genlinkfile emits, for each unit found, lines that add to the following macros:

UNIT_OBJS
Directives (-l and -L) to have the linker link with the unit's library archive.
UNIT_DEPS
Files that the unit being built depends upon, suitable for use as a makefile dependency.

In addition, each unit can be accompanied by a GNUmakefile.unit; if this is the case, that makefile is included by the GNUmakefile.link. These GNUmakefile.unit files can add command line arguments to the linking phase of the unit being built:

UF_PRE_LIBS
UF_POST_LIBS
Linker arguments; UF_PRE_LIBS will precede all units' UF_POST_LIBS. This is, for example, used by a library that provides an abstraction of X11 and that uses AC_PATH_XTRA from autoconf AC_PATH_EXTRA sets X_PRE_LIBS, X_LIBS, and X_EXTRA_LIBS, and the library's GNUmakefile.unit.in will look like this:
UF_PRE_LIBS+= @X_PRE_LIBS@
UF_POST_LIBS+= @X_LIBS@ @X_EXTRA_LIBS@ -lX11

Visit TOM on the WWW at http://www.gerbil.org/tom/.
Pieter Schoenmakers <tiggr@gerbil.org>
$Id: makefiles.html,v 1.7 1999/11/11 21:16:28 tiggr Exp $