2.3 Using the Generated VMS Build File

This section describes the options you can use to control the build process using the generated VMS build file

The VMS 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 VMS build file is executed with the "@ " 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 lowercase on the command line), and the lower case letters are optional. Most options can be abbreviated.

The primary options are:

• COMPile: Compiles some or all 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 if 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 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).

Some primaries, such as STD, ALL, and SYStem, are combinations of other primaries. The secondary options apply in these cases as well. 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, give the secondary option NORMal. It is rarely 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 passed to the compiler ( only "/debug" is passed to the VMS MACRO assembler).
  
  
• 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 passed 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 passed to the linker.
  
  
• MAPALL: Creates a full link map file. The option "/full" is passed 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. Valid 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. But the capability exists 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 how to obtain a full compile listing with cross-reference from a pair of modules:

@prog.bld comp listall,listxref "module1.c module2.f".