2.4 Using the Generated UNIX makefile

Since most VICAR programmers may not be familiar with make, this Section briefly describes how to use it. For more details on using make, see the documentation for it.

A makefile describes the dependencies between parts of an application and how to build those parts to create the output program. Dependencies are simply the files that are needed to build a piece of the program. For example, the executable depends on all the object files and the link libraries it needs. Each object file depends on its corresponding source file, and the include files that it uses. A link library depends on the object files that make it up.

Source code may depend on a preprocessor, such as lex or yacc, or may come from a source code management system. All these dependencies can be tracked by make. make is designed to figure out what needs to be built based on what has changed, and to build only changed files. So, if you modify only one source module, make checks the modification dates, realizes only one module has changed, and recompiles only that module.

The vimake-generated makefile takes advantage of many of these features. It does not allow specifying which include files are used by which source files, but since VICAR applications are typically small, this should not cause a problem, but just require a few extra compiles. Full automatic dependency checking may be added to the makefile in the future.

By default, make looks for several filenames for the makefile, including " makefile" and " makefile". The generated makefile is always named " file.make" where file is the name of the application. Pass the " -f" option to make to specify the name of the makefile.

If you are developing a program, you may rename the file "makefile" (or create a symbolic link) so make will find it automatically. This precludes having more than one application in the same directory, so it should not be done all the time.

To run make, use the following syntax:

 make -f file. make targets

where "file" is the name of the application and "targets" is an optional list of targets to build (described below).

make operates through the use of targets. A target is the final result of the make. A target could be an object file name, in which case that file would be compiled. It could be the executable name, in which case all the compiles and links necessary to create the executable are performed. There are special targets, such as "all" or "clean.src", that cause other actions to be performed. More than one target may be given on the same command, separated by spaces.

The targets available depend on whether you are building a PROGRAM, SUBROUTINE, or PROCEDURE, and on how complex the build is. The allowed targets are listed below. Not all targets will be available in all generated makefiles.

There are fewer options on the UNIX makefile than there are on the VMS BLD file. This is largely due to the fact that make takes care of a lot of the details for you. You generally don't need to specify compiling a single module, or only doing the link, because make will determine what needs to be done and do it for you.

• std: Builds a private version (" standard ") of the unit in the current directory. It is the default target if none is given. It is valid for PROGRAM, SUBROUTINE, and PROCEDURE. For type SUBROUTINE, the modules are installed in the local link library (see library.local).
  
  
• all: Builds a private version of the unit in the current directory, including the documentation. It is valid for PROGRAM, SUBROUTINE, and PROCEDURE. For type SUBROUTINE, the modules are installed in the local link library (see library.local).
  
  
• debug: Builds a debuggable version of the unit ("-g" option to the compiler). This target is only available on machines with conditional macros in make, such as a Sun. On machines without conditional macros, debug is not a valid target. To build the program for debugging on these machines, set the DEBUG flag in the imakefile, and re-run vimake. When available, the debug target is valid for PROGRAM and SUBROUTINE.
  
  
• profile: Builds a version of the unit for use with the profiler (" -pg" option to the compiler). This target is only available on machines with conditional macros in make, such as a Sun. On machines without conditional macros, profile is not a valid target. To build the program for use with the profiler on these machines, set the PROFILE flag in the imakefile, and re-run vimake. When available, the profile target is valid for PROGRAM and SUBROUTINE.
  
  
• system: Performs a system build of the unit. This target should only be used by Configuration Management to build the VICAR system. It is valid for PROGRAM, SUBROUTIN E, and PROCEDURE. The system target performs a clean.src operation, which will delete the source code (since it just came from the COMfile, it's not needed any more).
  
  
• compile: Compiles all the source code, but does not link or install the objects in a library. It is valid for PROGRAM and SUBROUTINE.
  
  
• Object module name: The name of an object module (with ".o" extension) may be given to compile only one module. This is valid for PROGRAM and SUBROUTINE. Specifying an object module name is not particularly useful, since make already determines which modules need to be compiled. This option will rarely be used.
  
  
• Executable name: The name of the program itself may be used as a target, for type PROGRAM only. It is equivalent to the target "std".
  
  
• library.local: Installs the object code in the local (private) library. The name of the library may be specified with the LOCAL_LIBRARY macro in the imakefile. The modules are compiled if needed first. This target is valid for SUBROUTINE only.
  
  
• library. system: Installs the object code in the VICAR system library. This option may only be used by Configuration Management. The modules are compiled if needed first. This target is valid for SUBROUTINE only.
  
  
• clean.obj: Deletes all object code for this unit. Valid for PROGRAM and SUBROUTINE.
  
  
• clean.src: Deletes the source code, imakefile, and makefiles. It is intended mainly for system builds, where the source code can be deleted after the build because it is maintained in the COMfile. If you are modifying code and do not have an up-to-date COM file, then do not use the clean.src target.
  
  
• doc: Builds all the documentation files for the unit. Currently, the only supported type of documentation file is a TAE error messagefile, although other types will be added. Valid for PROGRAM, SUBROUTINE, and PROCEDURE.
  
  
• doc.errmsg: Builds the TAE error message file.

Some examples may prove helpful. The first example compiles a version of the program into the local directory:

 make -f prog.make 

The next example is the same, except the documentation (if present) is built as well:

make -f prog.make all 

This example shows building the program for use in the debugger, for systems that support the "debug" target:

make -f prog make debug 

The last example shows how to delete the object modules after a build. This is not recommended during most program development, because it forces all the modules to be recompiled every time:

 make -f prog.make clean.obj