home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1993 #2
/
Image.iso
/
clipper
/
automa.zip
/
AUTOMAKE.DOC
< prev
next >
Wrap
Text File
|
1993-07-06
|
23KB
|
946 lines
AUTOMAKE v1.30
Makefile Maintenance Utility
Copyright (c) 1993 Roy Olsen. All Rights Reserved.
- i -
Terms of Use
You are free to use, copy and distribute AUTOMAKE as
long as no fee is charged and this documentation file
and the sample definition files accompany each copy.
AUTOMAKE is provided "as is" without any warranty,
expressed or implied, including but not limited to
fitness for a particular purpose.
Questions and suggestions for enhancements are welcome.
Contact: Roy Olsen via Compuserve User ID 75040,527.
- ii -
Table of Contents
Why Use AUTOMAKE? . . . . . . . . . . . . . . . . . . . . . . 1
How AUTOMAKE Works . . . . . . . . . . . . . . . . . . . . . 2
AUTOMAKE Definition Files . . . . . . . . . . . . . . . . . . 3
Clipper Inference Rule . . . . . . . . . . . . . . . . . 3
Special AUTOMAKE Macros . . . . . . . . . . . . . . . . 4
AUTOMAKE Macro . . . . . . . . . . . . . . . . . . . . . 5
Application Component Macros . . . . . . . . . . . . . . 6
PRGS Macros . . . . . . . . . . . . . . . . . . . . 6
Switch Macro Suffixes . . . . . . . . . . . . . . . 6
LIBS Macros . . . . . . . . . . . . . . . . . . . . 8
MODS Macros . . . . . . . . . . . . . . . . . . . . 8
CLP Macro . . . . . . . . . . . . . . . . . . . . . . . 8
APPFILES Macro . . . . . . . . . . . . . . . . . . . . . 9
APPLIST Macro . . . . . . . . . . . . . . . . . . . . . 9
#compile rules Directive . . . . . . . . . . . . . . . . 10
Linker Dependency Rule . . . . . . . . . . . . . . . . . 10
Sample Files . . . . . . . . . . . . . . . . . . . . . . 10
Running AUTOMAKE . . . . . . . . . . . . . . . . . . . . . . 11
Building Test and Final .EXE's . . . . . . . . . . . . . 12
- iii -
Why Use AUTOMAKE?
AUTOMAKE automates the task of creating and maintaining RMAKE and
linker script files for Clipper applications. It provides a
method to specify all the components of an application, and the
details of compiling and linking them, in a single place.
Normally to set up make and linker script files you must perform
a number of steps for each module (.PRG file):
add a dependency rule for creating the object file,
<module.obj>: <module.prg>
add the module to the .EXE dependency rule,
<app.exe>: <app.obj> <module.obj>
and insert a command into the linker script file.
FILE <module>
AUTOMAKE simplifies this process so each module is entered only
once. To use it, you create a definition file using RMAKE
commands that AUTOMAKE uses as a template for the make file. The
definition file contains only the basic information needed to
compile and link an application. The files needed to make an
application can be defined like this:
PRGS = <app> <module> <another_module>
LIBS = NanFor
Once the definition file is created, run AUTOMAKE to build the
RMAKE and linker script files; and optionally build a list of
files for archiving the application.
Then, to create or rebuild the application .EXE type:
RMAKE <application>
and RMAKE will compile and link any files that don't exist or
need to be updated.
AUTOMAKE greatly simplifies using RMAKE to build Clipper
applications. It automatically creates RMAKE and linker script
files to your specifications, supporting a wide range of compile
and link scenarios without imposing a specific style or approach.
- 1 -
How AUTOMAKE Works
When you run AUTOMAKE it reads a definition file for an
application, along with make files from RMAKE #include
directives. It creates a make file from the definition file;
inserting the dependency rules and macro definitions needed to
use it with RMAKE. It also writes one or more link script files
containing the FILE, LIB and MODULE commands needed to link the
application. Finally, AUTOMAKE creates a list of file names that
you can use to archive the application.
- 2 -
AUTOMAKE Definition Files
Definition files use the same syntax as RMAKE. Generally each
line in the definition file is copied verbatim to the RMAKE file.
The definition file header (all comment lines before the first
non-comment line) is discarded and a new header is created for
the RMAKE file. All other comment lines are copied. Lines that
are continued with a backslash are recognized as a single
command.
Each line in the definition file is copied to the RMAKE file by
AUTOMAKE. When it encounters the special AUTOMAKE directive
"#compile rules", it's replaced with dependency rules for Clipper
programs. If this directive is not found AUTOMAKE puts the
dependency rules at the bottom of the make file.
AUTOMAKE reads the macros it needs to create dependency rules and
converts any nested macro to its literal value. If any macros
AUTOMAKE needs are not defined in the definition file or an
INCLUDE'd make file, it looks for a DOS environment variable
having the same name. Macros that cannot be found are replaced
with the empty string.
Clipper Inference Rule
----------------------
RMAKE uses an inference rule for dependencies that don't have
shell lines. So if the make file contains:
.prg.obj:
Clipper $< /m
MyApp.obj: MyApp.prg
RMAKE acts as if the dependency was:
MyApp.obj: MyApp.prg
Clipper Myapp.prg /m
If a ".prg.obj:" inference rule is not defined in the definition
file or an INCLUDE'd make file, AUTOMAKE uses the default
inference rule and puts it at the top of the RMAKE file. The
default Clipper inference rule is:
.prg.obj:
set CLIPPERCMD=$(CLP)
Clipper $<
AUTOMAKE also uses the Clipper inference rule to create shell
lines for dependency rules of modules defined using a switch
macro suffix on the macro name. (See: Switch Macro Suffixes.)
- 3 -
Special AUTOMAKE Macros
-----------------------
These macros have special meanings to AUTOMAKE:
AUTOMAKE - configures how AUTOMAKE operates
PRGS - Clipper programs
LIBS - object library files
MODS - modules from object libraries that must occupy a
specific position in the linker script or when multiple
libraries contain modules with the same name
CLP - contains compiler switches used by the Clipper
inference rule
APPFILES - specifies a list of applications files (Note:
this macro is NOT copied to the RMAKE file)
APPLIST - (Optional) name of file containing application
list
The following macros are created by AUTOMAKE. They begin with a
leading underscore to avoid conflicts with commonly used macro
names:
_ALL - name of recompile trigger file
_OBJ - list of .OBJ files
_ROOT or _OVL - name of file containing linker script
commands (also can be _ROOTxxx or _OVLxxx)
- 4 -
AUTOMAKE Macro
--------------
A macro named AUTOMAKE is used to specify AUTOMAKE options. The
options that can be specified are:
_ALL - causes AUTOMAKE to create a recompile trigger file,
assign its name to the macro _ALL and make each .OBJ
file dependant on $(_ALL). If the timestamp is updated
on this file, running RMAKE will recompile all Clipper
programs.
For example, if the AUTOMAKE macro is defined like:
AUTOMAKE = _ALL
then AUTOMAKE produces:
_ALL = <application>.ALL
MyApp.obj: MyApp.prg $(_ALL)
_OBJS - causes AUTOMAKE to create the macro _OBJS containing
a list of .OBJ files to use in the linker dependency
rule like:
$(EXE): $(_OBJS)
For example, if the AUTOMAKE macro is defined like:
AUTOMAKE = _ALL _OBJ
then AUTOMAKE produces:
_OBJS = MyApp.obj Mod1.obj Mod2.obj
- 5 -
Application Component Macros
----------------------------
The PRGS, LIBS and MODS macros are where the modules that make up
an application are specified. When you create these macros, use
only root file names. Do not specify the file path or extension.
These macros names can have a suffix that indicates which section
of the linker script to put these modules. The suffix can be
_ROOT or _OVL, or a modified form of either like _ROOTA or _OVL1
(you can specify up to ten linker script sections). Each section
is placed in a separate file having .LN0 to .LN9 as its extension
and the file name is assigned to a macro with the same name as
the suffix. If no suffix is specified, then _ROOT is used.
PRGS Macros -
These macros specify Clipper programs. A dependency rule
and linker script FILE command is created for each macro
element. For example, if the definition file contains:
PRGS = MyApp
the AUTOMAKE creates a dependency rule in the make file:
MyApp.obj: MyApp.prg
and a command in the linker script file:
FILE MyApp
Optionally, if _OBJS is an element of the AUTOMAKE macro,
then after the dependency rules AUTOMAKE puts:
_OBJS = MyApp.obj
Switch Macro Suffixes -
PRGS macro names can contain an additional suffix specifying
an alternate compiler switch macro to use for these
programs. The name of this macro is the suffix minus its
leading underscore. This capability is useful, for
instance, when Clipper 5 and generic Xbase programs are
combined. AUTOMAKE creates explicit shell lines for these
programs using the Clipper inference rule shell lines. All
occurrences of $(CLP) are replaced with the compiler switch
macro name.
- 6 -
Switch Macro Suffixes (continued) -
When the definition file contains:
CLP = /m /n /w
XBASE = /a /m
PRGS_XBASE = OldMod1 OldMod2
and the Clipper inference rule is:
.prg.obj:
set CLIPPERCMD=$(CLP)
Clipper $<
AUTOMAKE creates dependency rules for _XBASE programs like:
OldMod1.obj: OldMod1.prg
set CLIPPERCMD=$(XBASE)
Clipper $<
When a PRGS macro name contains a section suffix along with
a switch macro suffix, the section suffix should come first
in the macro name:
PRGS_OVL_XBASE = OldMod1 OldMod2
- 7 -
LIBS Macros -
AUTOMAKE puts a LIB command in the linker script file for
each element of these macros. For example:
LIBS = NanFor DbfMdx
causes AUTOMAKE to add this to the linker file assigned to
the _ROOT macro:
LIB NanFor
LIB DbfMdx
An example that puts a library in the overlay is:
LIBS_OVL = Extend
which causes AUTOMAKE to add this to the linker file
assigned to the _OVL macro:
LIB Extend
MODS Macros -
For each element of these macros AUTOMAKE puts a MODULE in
the linker script file:
MODS_OVL = AmPm
results in this being added to the linker file assigned to
the _OVL macro:
MODULE AmPm
Additionally a MODULE...FROM command for Blinker can be
generated by specifying the source library followed by the
module name in parenthesis:
MODS = Clipper(FError)
results in:
MODULE Ferror FROM Clipper
CLP Macro
---------
The CLP macro containing the standard Clipper compiler switches
must exist and be used by the Clipper inference rule if any
dependency rules are generated using an alternate switch macro.
(For more information see: Switch Macro Suffixes.)
- 8 -
APPFILES Macro
--------------
If this macro is defined, AUTOMAKE generates a list of
application files with one file per line. The file list is for
archiving the source, header and make files for an application
(using PKZIP, for instance). The appropriate MAKEPATH[.<ext>]
macro is used to search for each file and the directory is added
to the file name. If the file is in the current directory or
cannot be found on the path, then the file name is listed with no
directory.
In order to add extensions to the elements of a macro, AUTOMAKE
supports macro expressions using the macro append operator: ">".
To use it add a comma after the macro name, then the ">" followed
by the extension to be appended. Assuming the following macro
definitions:
PRGS = MyApp Mod1 Mod2
LIBS = NanFor
makepath[.lib] = $(LIB)
APPFILES = $(PRGS,>.prg) $(LIBS,>.lib)
and the DOS environment variable:
LIB=C:\CLIPPER\LIB
then AUTOMAKE generates a file list containing:
MyApp.prg
Mod1.prg
Mod2.prg
C:\CLIPPER\LIB\NanFor.lib
Note: because it can contain macro expressions which are not
supported by RMAKE, the APPFILES macro is not copied to the .RMK
file.
APPLIST Macro
-------------
This macro specifies the file to use for the list generated from
the APPFILES macro. If this macro is not defined the name
"FILES.LST" is used.
- 9 -
#compile rules Directive
------------------------
This special AUTOMAKE directive is used in the definition file to
specify where to put the dependency rules. AUTOMAKE removes it
and inserts the dependency rules for Clipper programs in its
place. If it's not found AUTOMAKE puts the dependency rules at
the bottom of the make file. However, in order for RMAKE to work
properly the Clipper dependency rules must precede the linker
dependency rule.
Linker Dependency Rule
----------------------
Place a linker dependency rule at the bottom of the definition
file (after the "#compile rules" directive). A simple and
generic example is:
$(EXE).exe: $(_OBJS)
RTLink @$(_ROOT)
See Building Test and Final .EXE's for a complex example.
Sample Files
------------
Several sample files accompany AUTOMAKE and provide additional
examples:
BASIC.DEF - simple definition file
APP.DEF - definition file using an INCLUDE'd make file
COMMON.RMK - RMAKE file containing commands used in common
by multiple applications (used by APP.DEF)
BLINKER.DEF - definition uses BLINKER to link, has explicit
overlay area, provides test and final compile/link and
has AUTOMAKE create a file list for the application
TEST.RMK & FINAL.RMK - Blinker scripts for test and final
linking
VERS.BAT - batch file for saving PKZIP archives
- 10 -
Running AUTOMAKE
Once a definition file is created for an application, run
AUTOMAKE using the syntax:
AUTOMAKE <definition_file>[.DEF]
AUTOMAKE forms the names of the make, linker script and trigger
files using the root of the definition file name with different
extensions. It creates:
- an RMAKE command file with an .RMK extension
- one or more linker script files with .LN<n> extensions
- optionally, a recompile trigger file with an .ALL
extension
If you include a directory with the definition file name, the
above files are created in that directory.
If you type:
AUTOMAKE MYAPP
it reads the definition file MYAPP.DEF and creates MYAPP.RMK,
MYAPP.LN0 and MYAPP.ALL.
To build the application .EXE type:
RMAKE MYAPP
- 11 -
Building Test and Final .EXE's
------------------------------
When developing an application you probably want to include
information for the Clipper debugger during testing, then rebuild
the .EXE for production use after the application is tested. The
following approach allows either to be built from the make file.
1) Have AUTOMAKE create a recompile trigger file. Put the
following line at the top of the definition file:
AUTOMAKE = _ALL
2) Create a conditional compiler switch definition. Also,
define the "ALL" macro for the final rebuild:
CLP = /a /m /n
#ifdef FINAL
ALL = Y
CLP := $(CLP) /l
#else
CLP := $(CLP) /b /p
#endif
3) Update the timestamp on the .ALL file if "ALL" is
defined:
#ifdef ALL
#! echo > $(_ALL)
#endif
After you do this and run AUTOMAKE, this command compiles for
testing:
RMAKE <app>
this command recompiles without debugging information:
RMAKE <app> /DFINAL
and this command recompiles with debugging information:
RMAKE <app> /DALL
- 12 -
You may also want different linker script commands for test and
final linking. This can be accomplished by conditionally
INCLUDE'ing the appropriate linker script:
#ifdef FINAL
#include Final.rmk
#else
#include Test.rmk
#endif
where "TEST.RMK" contains something like:
$(EXE).exe: $(_OBJS)
echo BLINKER INCREMENTAL PAD 256> $(SCRIPT)
echo OUTPUT $(EXE)>> $(SCRIPT)
echo BEGINAREA>> $(SCRIPT)
echo @$(_OVL)>> $(SCRIPT)
echo ENDAREA>> $(SCRIPT)
echo @$(_ROOT)>> $(SCRIPT)
Blinker @$(SCRIPT)
and "FINAL.RMK" contains something like:
$(EXE).exe: $(_OBJS)
echo BLINKER INCREMENTAL OFF> $(SCRIPT)
echo OUTPUT $(EXE)>> $(SCRIPT)
echo @$(_OVL)>> $(SCRIPT)
echo @$(_ROOT)>> $(SCRIPT)
Blinker @$(SCRIPT)
- 13 -
