Previous: Valid vimake Commands Up: vimake Next: Using the Generated Unix Makefile
Using the Generated VMS Build File
The generated VMS build file is quite powerful. This section describes the
options you can use to control the build process.
The build files will look different depending on whether you are building
a PROGRAM, SUBROUTINE, or PROCEDURE, and what languages you use. All
options are described below. Some may not apply, depending on what you
are building.
The build file is executed via the standard `` @'' command. The build
file can have three arguments. The first is the primary option, the second is
the secondary option list, and the third is a module list. All three
parameters are optional. In the lists below, the capitalized letters are
required (although they may be in lower case on the command line), and the
lower case letters are optional. So, most options can be abbreviated.
The primary options are:
- COMPile: Compiles all or a few source code modules. Valid for PROGRAM
and SUBROUTINE only.
- DOC: Builds the documentation files for the unit. Currently, the
only supported type of documentation file is a TAE error message file,
although other types will be added. Valid for PROGRAM, SUBROUTINE, and
PROCEDURE.
- LINK: Links the program. Valid for PROGRAM only.
- INSTall: Installs modules in the object library. Valid for SUBROUTINE
only.
- STD: Builds a private version (``standard'') of the unit in the current
directory. It is the default of no primary option is given. It is valid for
PROGRAM, SUBROUTINE, and PROCEDURE. For PROGRAM, it is equivalent to the
COMPile and LINK steps together. For SUBROUTINE, it is equivalent to the
COMPile and INSTall-LOCAL steps together. For PROCEDURE, it is essentially a
no-op.
- ALL: Builds a private version of the unit in the current directory,
including documentation. It is valid for PROGRAM, SUBROUTINE, and PROCEDURE.
For PROGRAM, it is equivalent to the COMPile, DOC, and LINK steps together.
For SUBROUTINE, it is equivalent to the COMPile, DOC, and INSTall-LOCAL steps
together. For PROCEDURE, it performs the DOC step.
- SYStem: Performs a system build of the unit. This option should only
be used by Configuration Management to build the VICAR system. It is valid
for PROGRAM, SUBROUTINE, and PROCEDURE. For PROGRAM, it is equivalent to
COMPile, DOC, LINK, CLEAN-OBJ, and CLEAN-SRC. For SUBROUTINE, it is equivalent
to COMPile, DOC, INSTall-SYSTEM, CLEAN-OBJ, and CLEAN-SRC. For PROCEDURE, it
is equivalent to DOC and CLEAN-SRC.
- CLEAN: Deletes and/or purges files that are used during the build
but are not needed during program execution. It is valid for PROGRAM,
SUBROUTINE, and PROCEDURE.
The default primary option is STD, which may be omitted. If so, then the
secondary option list becomes the first argument to the BLD file, and the
module list becomes the second argument.
The secondary option list is a list of options, separated by commas and with
no blanks, that modify how the primary options are performed. They are
associated with a primary option, so the corresponding primary must be given
for the secondary to take effect (unless the primary is the default STD).
Note that some primaries, such as STD, ALL, and SYStem, are actually a
combination of several other primaries. The secondary options apply in
these cases as well. So, for example, the secondaries for COMPile and LINK
may be given for STD.
There is one secondary that does not need a primary:
- NORMal: Used only as a placeholder if no secondary options are needed
but the module list is. If you need to use the module list, but have no
secondary options, you must give the secondary option NORMal. It should
rarely be used.
The secondary options for the COMPile primary option are:
- DEBug: Compiles the source code for use with the debugger. The options
`` /debug/noopt'' are given to the compiler (only `` /debug'' is
given to Macro).
- PROfile: Compiles the source code for use with PCA, the Performance
and Coverage Analyzer. The option `` /debug'' is given to the compiler.
- LISt: Generates a list file. The option `` /list'' is given to the
compiler.
- LISTALL: Generates a full list. The option `` /show=all'' is
given to the compiler. LISTALL implies LIST, so you need not give both.
- LISTXREF: Generates a cross reference listing. The option
`` /cross_ref'' is given to the compiler. LISTXREF implies LIST, so
you need not give both.
- LINT: Runs the lint syntax checker for C. This option is not
currently implemented.
The secondary options for the LINK primary option are:
- DEBug: Links the code for use with the debugger. The option
`` /debug'' is given to the linker.
- PROfile: Links the code for use with PCA, the Performance and Coverage
Analyzer. The option `` /debug=sys$library:pca$obj.obj'' is given to
the linker.
- MAP: Creates a link map file. The option `` /map'' is given to the
linker.
- MAPALL: Creates a full link map file. The option `` /full'' is
given to the linker. MAPALL implies MAP, so you need not give both.
- MAPXREF: Includes a cross reference listing in the map file. The option
`` /cross_ref'' is given to the linker. MAPXREF implies MAP, so you
need not give both.
The secondary options for the INSTall primary option are:
- LOCAL: Installs the object code in the local (private) library. This
is the default. The name of the library may be specified with the
LOCAL_LIBRARY macro in the imakefile.
- SYSTEM: Installs the object code in the VICAR system library. This
option may only be used by Configuration Management.
The secondary options for the CLEAN primary option are:
- OBJ: Deletes object and list files. For PROGRAMs, it purges the
executable. This is the default. It is valid only for PROGRAM and SUBROUTINE.
- SRC: Deletes the source code, imakefile, and BLD files. Be very careful
with this option! It is intended mainly for system builds, where the source
code can be deleted after the build because it is maintained in the COM file.
If you are modifying code and do not have an up-to-date COM file, then do
not use the CLEAN-SRC option.
The secondary options for the DOC primary option are:
- MSG: Builds the TAE error message file. If no secondary options for
DOC are given, then all documentation is built. If a secondary option is
present, then only the types given in the secondaries are built.
The last parameter to the BLD file is the module list. It is a list of modules
to compile or clean. Normally, the entire application is built at once, so
this is not often used. However, the capability is there to build only some
of the code. This is useful if you are modifying one module of a large
program. Once everything is compiled, you need only compile the module
you are changing. The names given in the module list must match exactly
with the names in the MODULE_LIST macro in the imakefile. If you want to
give more than one module name, then separate them with spaces and enclose
the whole list in double quotes.
Some examples may prove helpful. The first example merely compiles a version
of the program into the local directory:
@prog.bld
The next example is the same, except the documentation (if present) is built
as well:
@prog.bld all
This example shows building the program for use in the debugger. Note how
the secondary option is first because STD was defaulted:
@prog.bld debug
The next example shows recompiling a single module out of a large application,
and then relinking it with the debugger. A link map is created. The other
modules must have already been compiled:
@prog.bld comp deb module.c
@prog.bld link deb,map
The last example shows shows how to obtain a full compile listing with
cross-reference from a pair of modules:
@prog.bld comp listall,listxref "module1.c module2.f"