UVMBLD: Creating Make Files

Author: Peter Kasper

Contents:
Description: What UVMBLD does.
Example 1: Updating directories of include files.
Example 2: Updating object libraries.
Example 3: Maintaining release versions.
See the Table of Contents for more information.

The standard UNIX method of updating target files such as archive libraries or executables is to create a "make file" for each target and use the make command to update the target from the various source files on which it depends. The difficulty with this process is the maintenance of the make files, especially when the number of dependencies is changing with time. The "uvmbld" command described below is designed to simplify this process by automatically generating a make file from a list of UVM library elements satisfying a specified pattern or group.

UCM version v5_1

Description

This Perl script creates a make file called "Makefile" which can be used to update a directory containing derivatives of UVM library elements matching the element specification. The command assumes that each element will be mapped into a target file with the same name but not necessarily the same file type or extension. The command has the form:-

uvmbld [library/][file] [-i initialize] [-d directory]
  [-e extension] [-r rule] [-f finalize] [-n tag] [-F]

The libraries and elements referenced by library/file follow the same conventions as used in the UVM commands. All libraries found in the directory tree(s) indicated will be searched for elements matching file unless the -F flag is set, in which case only the top-level libraries will be referenced. If omitted "library" defaults to the value found in $HOME/UVM_DEFAULT and "file" defaults to "*".

Uvmbld uses the files "initialize", "finalize", "rule" and any dependency files, "library/UVM/name.type", associated with each element matching the "file" specification (see under CHECKIN), to create the file "Makefile", which is constructed as follows:-

Contents of the file "initialize", if it exists ...
TGT = directory
UVM = library
Target entry for first UVM element matching "file"
:
Target entry for last UVM element matching "file"
ALL : Dependency list ...
Contents of the file "finalize", if it exists ...

The dependency list for ALL consists of a list of all the files matching the file specification, "file". This is the target one should specify when using the make or gmake command to update all the target entries. A rule for updating this target can be specified with the file "finalize".

Each target entry in "Makefile" has the following structure:-

$(TGT)/name.extension : $(UVM)/name.type,v \
Contents of the file "library/UVM/name.type", if it exists ...
Contents of the file "rule", if it exists ...

If the target file type, "extension", is not specified, it is derived from the UVM element type as shown below:-

$(TGT)/name.type : $(UVM)/name.type,v \
Contents of the file "library/UVM/name.type", if it exists ...
Contents of the file "rule", if it exists ...

If the file target directory is not specified, it defaults to the current working directory.
If the file "rule" is not specified, it defaults to a simple check-out of the latest revision of the element into the specified directory. Thus the target entry becomes:-

$(TGT)/name.type : $(UVM)/name.type,v \
Contents of the file "library/UVM/name.type", if it exists ...
<TAB>co -f $(TGT)/name.type $(UVM)/name.type,v

Note that if the -r option is omitted then the -e option must also be omitted since the co command assumes a specific relationship between the RCS file name and the working file name shown above.

If the -i option is specified the target entries will be preceded by the make commands in the file "initialize". This can be for defining various make variables such as vpath.

If the -f option is specified the contents of the file "finalize" will be added to the end of the make file. The file can be used to add a rule to the final target as well as adding any implicit rule definitions to the make file.

If the -n option is specified then the selected elements must not only match the file specification but must also contain a revision that has been tagged with "tag". This option also affects the default rule in that the revision tagged with "tag" is the one that will be checked out.

UCM version v5_1

Example 1: Updating Include File Directories

The following commands will update directories containing include files from source files in three UVM libraries, source/libA, source/libB, and source/libC :-

   uvmbld "source/libA/*.inc" -d includes/libA -i vpath
   gmake -k ALL
   uvmbld "source/libB/*.inc" -d includes/libB -i vpath
   gmake -k ALL
   uvmbld "source/libC/*.inc" -d includes/libC -i vpath
   gmake -k ALL

Assuming the default version of CHECKIN is used and the file "vpath" contains:-

   VPATH = includes/ $(wildcard includes/*/)

then the resulting make file will update an include file even when a nested include include file is changed, provided all the nested include files are in the same library as the referencing file. This is extremely useful when creating make files to update source code using the include files. The limitation that the nested include must reside in the same library can be avoided by keeping all extracted include files in a single directory, regardless which UVM library they come from:-

   uvmbld "source/*.inc" -d includes -i vpath
   gmake -k ALL

where the file "vpath" now contains:-

   VPATH = includes/

One limitation with this method is that the include file names would be required to be unique, regardless of where the source is kept.

UCM version v5_1

Example 2: Updating an Object Library

In this example we create a make file to update an object (or archive) library of FORTRAN routines derived from all the .cdf files in a single UVM library. The technique employed here is somewhat different than what is usually done. In particular neither the resulting archive library nor any of the intermediate files used to build it, are targets in the resulting make file. Instead we keep track of the updates separately for each source file using a directory of empty time stamp files. This has the advantage that the update of each source file can proceed independently of any of the other source files. Hence a compile error in one subroutine will not affect the updates of other subroutines.

   uvmbld "libA/*.cdf" -d times/libA -e -i vpath -r build
   gmake -i CLEAN
   gmake -k target=objects/libA.a ALL

The file "vpath" contains :-

   VPATH = includes/ $(wildcard includes/*/)
   target = CLEAN:
   <TAB>  chmod +w *.cdf
   <TAB>  rm *.cdf
   <TAB>  rm *.f
   <TAB>  rm *.o

The rule file "build" contains :-

   <TAB>  co $<
   <TAB>  kpp $(@F)cdf $(@F)f -d IRIX -i $(VPATH)
   <TAB>  f77 -c $(@F)f
   <TAB>  ar r $(target) $(@F)o
   <TAB>  touch $@

In this example the target files have names of the form, times/file, and hence $(@F) can be used throughout the rule file. Note the way the -e option was used to force an empty extension. Note also how the make variable, target, is used to pass the name of the archive library to gmake and how the VPATH variable is used in the kpp command.

UCM version v5_1

Example 3: Maintaining Release Versions

The following commands can be used to maintain release versions of an include file directory and an object library.

   uvmbld "libA/*.inc" -d includes/libA -i vpath -n release
   gmake -k ALL
   uvmbld "libA/*.cdf" -d times/libA -e -i vpath -r build -n release
   gmake -i CLEAN
   gmake -k target=objects/libA.a ALL

where the file "vpath" contains :-

   VPATH = includes/ $(wildcard includes/*/)
   target = CLEAN:
   <TAB>  chmod +w *.cdf
   <TAB>  rm *.cdf
   <TAB>  rm *.f
   <TAB>  rm *.o

and the rule file "build" contains :-

   <TAB>  co -r release $<
   <TAB>  kpp $(@F)cdf $(@F)f -d IRIX -i $(VPATH)
   <TAB>  f77 -c $(@F)f
   <TAB>  ar r $(target) $(@F)o
   <TAB>  touch $@

In this example, changing a source element, will still cause the archive library to be rebuilt, but the resulting file will be the same as the original unless the tag "Rel" is moved to a different revision. This can be done simply using the "uvma tag" command described previously. For example, the following commands will cause the module "file" to be updated in the archive library above:-

   uvma tag libA/file.cdf -n release
   touch libA/file.cdf,v

Note that the touch command is only necessary if the element has not been replaced since the last update or if it was not previously tagged.