4.2.2 Compilation, Libraries and Programs

Building rules are used to create objects, libraries and programs from particular sources. For source files include dependences are automatically generated. The use of system and project definitions in source and include files is checked and stored as additional dependence information. If any of these values is modified the associated compiled objects are deleted to avoid any possible impacts due to incompatible versions. This is very useful, if some part of the code is only conditionally compiled. All definitions and flags are used from

1. the target rule if available,
2. the Local in the local module if available,
3. the Subtree in the local or parent modules if available,
4. the project defines and flags,
5. the project defines and flags of dependent sub-projects,
6. the system defines of the configuration,
7. the version defined in the host/queue definition file (see Section 8.5),
8. the default version.

This mechanism allows to override any flag or definition. Care must be taken, if project or system define is overridden because this may generate incompatible versions of code.

All targets generate automatically so called position independent code if the object file is included into a shared library. This is an requirement of same operating system and building a shared library from object files built with position dependent code will fail. If the object is not included in a shared library position dependent code is generated because this is faster on some systems, but never slower. Using the project save information a change from an archive to a shared library version can be detected and associated objects can be deleted and rebuilt without user interaction.

If an object file generated by any compilation rule is required outside the own project, it must be installed using Install-Target. For libraries and programs this is the default, but may be overridden to avoid unnecessary installation.

Local This rule defines additional flags and Cpp preprocessor definitions for all rules used in this module, respectively this directory.

All keys are optional and associated to the rules as given in Table 4.2.

  
Tabelle 4.2: Flags/Defines associated to rules used by Local/Subtree

There are no definitions for libraries since they are only a collection of object files. The flags and defines may be used in user defined extension rules too if they are subclassed from the corresponding file class (see Section 8.3).

Subtree This rule is identical to Local with the exception, that all definitions are automatically inherited to subdirectories instead of being local only. This rule should be used mainly in the top directory of a project. A Local overrides any value of a Subtree.

Include-Target This rule is used to export include files from one directory either project wide or to parent projects. If the include files are exported from the project they are automatically copied to a global project dependent include directory during creation of an installation. For this rule, no symbolicName is defined.

The key include gives a list of the files for inclusion either by name or symbolicName. This key can be omitted, if the key wildcard is used with a pattern string (see Table A.2). In this case all include files matching the file expression are marked as include files. If the key project is used, the include files are not exported and must not be used outside, but have project wide scope.

The key area forces to copy the include files in the given subdirectory during installation. This is important if the include files are included with a path element.

CC-Target This rule uses the C compiler to create objects from the given source file.

The key source holds a list of files either by symbolicName or explicit string name. It is not allowed to use one source file for multiple compilation within the same directory. The key wildcard replaces the key source and defines all files matching the file pattern expression as source for compilation.

The key flags and defines override any other flags and definitions for this rule.

The boolean key example defines this file as a programming example. This automatically installs the source files in a global directory during project installation.

The resulting object files are associated to the symbolicName. If the file extension of the source file is not compatible with the file extensions supported by the compiler, a temporary C source file is generated which includes the real source file. This is needed if automatically generated code is used as source because within VMake these files have an additional ``a'' in their file extension, e.g., ``ac'' instead of ``c''. In addition since VMake uses a typed file information, only real source files can be used as source files, e.g., no object files or libraries. This is detected during scan of the description file vmfile.mk.

C++-Target This rule is similar to CC-Target, but uses the C++ compiler for compilation.

Care should be taken when using include files designed for C because some commonly used names are reserved in C++ like new or class. In addition all C include files should have the correct

and

framing around C function prototypes. In the project ViennaBasesSystem (see Appendix A) the macros

are defined respectively to avoid all these preprocessor conditionals in the include file ``machine.h''. These macros are defined for the C compiler as empty comments and for the C++ compiler as the corresponding framing code.

Fortran-Target This rule can be used for any kind of FORTRAN compilation, either with or without applying the Cpp preprocessor to the source files prior to compilation with a 77 or 90 compiler.

The distinction between this different compilations are done by boolean keys f77, f90, and cpp. The default is to use the 77 compiler without Cpp preprocessing which is identical to the key f77.

All keys are similar to CC-Target, but the key defines is only used in combination with the key cpp, which means, that the FORTRAN source files are preprocessed using the Cpp. The main advantage of using Cpp is compiler independent file inclusion and use of conditional FORTRAN statements (e.g., for opening files). If only a 90 compiler is available for a certain configuration, 77 files are also compiled with this compiler (backward compatibility)[Lan93, Buc94].

Pascal-Target This rule allows to compile source files with a PASCAL compiler.

All keys are similar to CC-Target, but the key defines is only used in combination with the key cpp, which means, that the PASCAL source files are preprocessed using the Cpp. The main advantage of using Cpp is compiler independent file inclusion and use of conditional PASCAL statements (e.g., for opening files).

Library-Target This rule allows to combine object files created by any of the compilation rules to an object library.

The key libname is the name of the library independent of the operating system. A prefix and a file extension will be added, e.g., a string ``vbs'' would imply a library ``libvbs.a'' for UNIX for an archive version and ``LIBVBS.OLB'' for VMS.

The key archive is the default and forces an archive library whereelse the key shared generates a shared library, if supported for the configuration. For shared libraries so called position independent code is needed. This requirement is already checked during object file creation by the compilation targets. The implied library name is in this case ``libvbs-sh'' with an operating system dependent file extension.

The key project specifies that this library is private to the current project and should not be exported to parent projects. This means that the library is not installed globally if the project is installed.

The key depends is used to obtain dependence information about libraries which are needed by the object included in the library. This allows VMake to build a full library list for programs even if only the top libraries are given in the Program-Target. For a shared library this flag may be very important because some operating systems do not allow unresolved external references during generation of shared libraries (e.g., AIX from IBM) or may result in faster program startup. The generated library is associated to the symbolicName. These dependences are also used to determine the correct linker command during program generation.

Program-Target This rule is used to generate a program from objects and libraries. The `main' function of the program must be in an object file. The correct linker is automatically selected since VMake has full language information from the objects and libraries.

The key progname is the name of the executable without extension. The platform specific file extension is automatically added by VMake.

The key objects gives a list of compiled object files used for the program and the key libraries for the libraries. Only the first-level required libraries must be given, since VMake knows library dependences defined by the Library-Target and includes automatically all required libraries.

The boolean key example marks the resulting program as an example for installation. With the key project installation can be omitted. The key flags is used to override any program linking flags.

The generated program associated to the symbolic name can be used for execution from within VMake to generate data files or to run selftests. The output can be examined by the Check-Target (see Check-Target).

VLisp-Program This rule is a special case of the Program-Target to generate a new VLisp interpreter. The correct initialization code for the generated binding code of the Tool Abstraction Concept (see Section 6.2) from C and C++ to VLisp by Create-TAC-Interface (see Create-TAC-Interface) is added automatically to the executable.

The key objects must include the symbolicName VLisp-Main-Object for the main routine of the VLisp interpreter. The key libraries must specify at least the symbolicName VLisp-Library for the VLisp interpreter library. Additional libraries may be required for the functionality bound by Tool Abstraction Concept.

Compile-Lisp This rule is used to compile LISP source files to byte code recognized by the VLisp interpreter (see Appendix B). Compiled LISP code is executed faster and uses less memory space. Byte compiled LISP code is configuration independent and can be shared between all configurations without problems. The generated code cannot be included into libraries and programs, but can be executed by any VLisp interpreter generated with VLisp-Program (see VLisp-Program).

The key source is used to specify the VLisp source files. The key can be omitted, if the key wildcard is used with a file pattern expression to include LISP source files. Compiled LISP files are automatically copied to a global directory during installation. The default installation may be overridden installing the compiled LISP files explicitly with Install-Target (see Install-Target) for grouping LISP code together.