![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
C/C++ Build Management Apex Build Management for C and C++ provides facilities for the definition, management and customization of build environments. In addition to the general facilities for the definition of build environments, Apex Build Management also provides standard models of build environments which can be used with little or no modification. The majority of this chapter will focus on the characteristics of the standard build models.
Note: Build Management for C and C++ is only available with Apex C/C++ and Apex Duo. For more information about these products, contact your Rational sales representative.
Standard Models for C/C++ Build ManagementStandard models for C/C++ build management provide an "out-of-the-box" solution which supports the common build activities of compilation, construction of libraries, and linking of executables. In addition the standard models provide their own methods for customization which are less complex than constructing a build management model from scratch.
The standard build management models provide the following:
- Standard Makefiles
Standard makefiles support commonly needed compilation capabilities such as coding, creation of libraries, and linking executables. These makefiles also support several forms of user customization.
- Automated Management of Standard Makefiles
The management of the standard makefiles is automated to ensure that each view and directory contains the correct makefiles. Automated management of makefile macros is also provided to ensure that macros have the correct values as the contents and characteristics of directories change.
- Predefined and User-defined Build Policies
The semantics of applying a build management operation to a view are defined by the build policy of the view. For example, the build policy defines whether or a not a library will be constructed in a view. The standard makefiles come with support for several different build policies. Users may also define their own build policies.
- Integration with Standard C/C++ Compilers
Variations of the standard models are provided to support integration with the C/C++ compilers that have been developed by different vendors. Currently these models support integration with the Rational Apex C/C++ compiler, and the Sun C++ SPARCompiler version 4.1. In addition a generic model is provided for integration with other C++ compilers.
- Management of Dependency Information
Management of dependency information is provided to control when object files need to be recompiled. The standard models for Apex compilers ensure that dependencies are recomputed automatically whenever source files are recompiled. The standard models for other compilers provide a capability to recompute dependencies either automatically or upon user request.
- Management of Template Repositories
Management of template repository objects is provide to simplify the usage of templates.
- Architectural Enforcement
The standard models provide architectural enforcement which ensures that access to header files does not violate the specified system architecture.
- Support for Linking Ada with C/C++ (Apex Only)
The standard Rational Apex C/C++ models provide support for automatically linking C and C++ code into the closure of an Ada main program.
Basic Concepts
This section presents a brief overview of how the standard C/C++ build management facilities are used to support compilation and other activities.
All build activities occur in views.The specific characteristics of build activities in a view are determined by the view's build key which is specified by a switch of the same name in the view's switch file. The build key is usually derived from the model which was provided when the view was created. The standard models for C/C++ build management are based on standard build keys which contain the following:
- Prototype makefiles which will be propagated into views and their subdirectories.
- Scripts which are invoked from the makefiles in order to run the platform compiler, linker, or other tools.
- Property files which define the build environment, including:
- A description of makefile characteristics.
- The names of macros in the makefiles whose values will be automatically updated by Apex.
- Tables which define how Apex commands are to be translated into make commands.
Views utilizing the standard C/C++ build keys and models are created by the ceate_working and create_release commands and copied by the copy_view command. Generally C/C++ views are created using the default C/C++ model which is available in the session switch APEX_DEFAULT_MODEL. When a view is created with a standard C/C++ model all makefiles and directory structures required by the build system are created.
C/C++ source files are usually created by either the create_c or create_cpp commands. These commands create C/C++ header and source files with initial contents that are based on special prototype files which are located in the directory named by the APEX_PROTOTYPE_DIR environment variable. C/C++ files may also be copied into views by Apex commands or by Unix shell commands. Regardless of how files are created, makefiles and related directory structures are updated appropriately by Apex prior to running any build commands.
C/C++ source files are compiled by running the code command. C/C++ source files may directly include any header file within the same view. Header files in other views may only be included if architectural relationships have been established. Namely the view containing the header file must export the header file and the view containing the include must import the view which exports the header file. Header files may be named either by their simple name (for example,. #include "file.h") or by their subsystem-relative name (for example., #include "subsystem/file.h")
The dependencies between an object file and header files are updated automatically as a side-effect of each compilation. Dependencies may also be updated manually by running the dependencies command.
Entire views may be compiled by running the code command on the view itself. Compiling a view causes all source files in the view to be compiled and in addition creates any required libraries. The creation of libraries is controlled by the build policy associated with the view. Different build policies are defined by the standard build keys to allow libraries to be built with different contents or allow externally constructed libraries to be managed. By default, when libraries are constructed all object files are checked and regenerated if they are obsolete including the object files associated with template instantiations.
Prior to linking a main program, the source file containing the main entry point must be registered as a main program. Registration is automatic when Apex C/C++ compilers are used. Manual registration must be performed when running other compilers. Manual registration is accomplished by running the register_main_program command. Actual linking occurs when the link command is run on the registered main program file. The closure of a main program is the set of object files, libraries and option settings which must be passed to the linker in order to link the main program. The closure of a C/C++ main program is computed by first identifying appropriate views and then querying views to determine the contribution which each view will make to the overall closure. Support is also provided for linking C/C++ code in the closure of Ada main programs.
All Summit/CM operations may be applied to C/C++ files. C/C++ files may be placed under version control. When C/C++ files are created, deleted, or copied between views by Summit/CM operations, all appropriate makefiles and directories are automatically updated.
A number of mechanisms are provided for customization of the standard build operations. The customization operations allow standard operations to be augmented or completely redefined.
Build Management CommandsCommand Overview
Apex provides a rich set of build management commands which can be used to support the normal activities involved in building software systems. These commands cover different phases of build management from initial preparation of source files, to compilation, test and final delivery. In the various predefined build management models some of these commands have predefined meanings while others are provided for user customization.
The full set of build management commands are summarized below. The following sections provide a detailed explanation of the commands.
- PRE-PROCESSING COMMANDS
- COMPILATION COMMANDS
- Parse
Determine syntactic correctness.
- Pretty_Print
Format the contents of the source files.
- Analyze
Determine semantic correctness.
- Dependencies
Determine compilation dependencies.
- Code
- Link
- VERIFICATION AND TEST COMMANDS
- Check_Rules
Check conformance with coding rules.
- Test
- POST-PROCESSING COMMANDS
- Generate
Generate additional objects from source files.
- Deliver
Deliver any executables, libraries or other objects to their final location.
- Finalize
- MANAGEMENT COMMANDS
- Build
Perform a sequence of build operations that are required to "build" the entire view The sequence of build operations is specified by the value of the BUILD_PHASES context switch.
- MAINTENANCE AND SUPPORT COMMANDS
Standard Options
The build commands accept a standard set of options which include:
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falseMain Program Commands
C/C++ source files containing main programs must be registered in order to allow those main programs to be linked and to prevent the object files associated with those main programs from being included in the link of other main programs.
Main program registration occurs automatically when compiling with Apex C/C++ compiler. Therefore, when those compilers are used, the register_main_program and unregister_main_program commands described below need not be used. Whenever non-Apex compilers are used manual main program registration must be performed.
The following commands provide methods to register, unregister and show information about registered main programs. These commands utilize the general mechanisms for source file registration which are discussed later.
Registration Commands
Registered sets provide a general way in which files can be grouped together in order to record some common characteristic of all files in the set. Inclusion in a set or exclusion from a set is one criteria that is used to manage build activities. For example, registered sets are used to keep track of C/C++ source files which contain main programs.
The name of a registered set must be a simple identifier. The file containing the contents of the registered set is stored in the view's Policy directory and has the extension .reg.
Coordination of set membership across views can be accomplished in two ways. Firstly, whenever a new version is propagated by accept_changes between two views, membership in a registered set is also propagated provided that the set exists in the destination view and is not itself controlled. Secondly, a registration file may itself be controlled and propagated between views.
Although arbitrary sets can be created, their use depends on the setting in the C/C++ models. There are two sets defined in the standard C/C++ models:
- main_programs
C/C++ source files in this set may be linked as main programs and the object files in these sets will not be linked into other main programs.
- ignore
C/C++ source files in this set will not be compiled when the enclosing directory is compiled, will not be included in libraries, and will not be linked into main programs.
Compilation (C/C++)
This section presents a detailed description of how compilation is managed by the standard C/C++ models.
Compiler Kinds
The standard models provide support for three different types of compilers. The type of compiler that is being used is identified by the CPP_COMPILER_KIND context switch and should be set to one of the values below:
- apex
Specifies that an Apex C/C++ compiler is being used. This compiler provides support for automatic updates of dependency information and automatic identification of main programs when compilation occurs. This type of compiler also supports local template repositories and the ability to create libraries in views which contain up-to-date template instantiation object files.
- SPARCompiler-4
Specifies that Sun's SPARCompiler version 4.1 is being used. This type of compiler also supports local template repositories and the ability to create libraries in views which contain up-to-date template instantiation object files.
- generic
Specifies that a generic C++ compiler is being used. This type of compiler only provides support for a global template repository.
Compiling C/C++ Files
The standard C/C++ models provide several capabilities for managing compilation of C/C++ source files. These capabilities include:
- Selection of a compiler and a compiler variant.
- A method for controlling compiler options to ensure that all source files in a view are compiled in a consistent manner.
- Management of compiler artifacts such as the object file.
- Management of dependency information which determines when recompilation is required.
- Control over the naming environment that is used for the resolution of names in include directives.
Compiler Selection
Selection of the compiler to use is based on switches in the view and applies to all compilation and linking in the view. The switches which control compiler selection are normally derived from the model associated with the view. The switches include:
- CPP_COMPILER_HOME
Specifies the pathname of the C/C++ compiler that is to be used in the view.
- CPP_COMPILER_VARIANT
Specifies the name of the compiler variant that is to be used for the designated compiler. This is primarily used by Apex compilers to specify a non-default compiler configuration.
- CPP_COMPILER_KIND
Specifies the kind of compiler that is being used invoked. Possible values are:
Compiler Switches
Compiler options are stored in the switch file associated with the view and apply to the compilation of all files within the view. The names of the switches are:
- DEBUGGING
Specifies if debugging information is to be generated.
- OPTIMIZATION_LEVEL
Specifies the level of optimization.
- OPTIMIZATION_OBJECTIVE
Specifies the objective of optimization.
- PROFILING
Specifies whether profiling information is be generated.
- CPP_OPTIONS, CPP_PRE_OPTIONS
Contains additional options that will be passed directly to the C++ compiler.
- C_OPTIONS, C_PRE_OPTIONS
Contains additional options that will be passed directly to the C compiler.
For individual compilations the values of the switches may be overridden on the command line by specifying new values for the -cpp_options or -c_options switches.
Non-Apex Compiler Switches
A number of options are provided to control the behavior or non-Apex compilers:
- DEPENDENCIES
Specifies whether or not dependencies should be updated as part of each compilation.
- SIENNA
Specifies whether or not Sienna should be generated as part of each compilation.
- SIENNA_HOME
Specifies the home directory of the Apex compiler to use for Sienna generation.
- SIENNA_OPTIONS
Specifies options to be passed to the Apex compiler for Sienna generation. This is in addition to the normal compilation options specified by CPP_OPTIONS and C_OPTIONS.
Compilation Artifacts
Compiling source files generates an object file and possibly a number of additional artifact files which are used for debugging, navigation, and dependency management. Compilation artifact files are removed when the clean command is run on the source file.
Compilation Dependencies
Each object file has a number of dependencies. The dependencies include the header files which are referenced by the source file. The dependencies also include other files and switch values which effect the way in which an object file is produced. The full set of dependencies include the following:
- Each object file is dependent on any header files which are included by the source file associated with the object file. Thus, an object file will be considered obsolete if any of the header files it depends on are updated.
- Each object file is dependent on the settings of the CPP_COMPILER_HOME, CPP_COMPILER_VARIANT, and CPP_COMPILER_KIND switches. If either of these switches is changed the object files in the view are considered obsolete.
- Each object file is dependent on the switch values DEBUGGING, OPTIMIZATION_LEVEL, PROFILING, CPP_OPTIONS, CPP_PRE_OPTIONS, CPP_PTREPOSITORY_MODE, CPP_PTREPOSITORY_NAME, C_OPTIONS and C_PRE_OPTIONS which were set in the view's switch file at the time the object file was generated. Thus, an object file will be considered obsolete if any of these switches are changed in the view.
- Each object file is dependent on the makefiles which contain the rules for the generation of the object file. Thus an object file will be considered obsolete if the makefiles are changed.
- Each object file is dependent on the imports for the view containing the object file. Thus, an object file will be considered obsolete if the imports are modified for the view containing the object file.
Resolution of Include Names
Names in include directives are resolved based on the naming environment constructed by build management and by any explicit -I directives set in the compilation options in the switch file. The default behavior provides direct visibility to header files in all imported views provided those header files have been exported. The later section on Name Space Management describes the ways in which the naming environment can be customized.
Template Instantiations
The standard C/C++ models provide two modes for the management of template instantiation repositories. These two modes are global and local.
- Global Repository Mode
In global mode, there is a single repository for each system configuration. Compilation in any view of the configuration uses the global repository and all views in a system configuration should name the same repository in their CPP_PTREPOSITORY_NAME context switch.
- Local Repository Mode
In local mode, each view has its own repository which contains the objects associated with instantiations in that view.
Not all of the compiler kinds supported by the standard models support all of the repository modes. In particular, the generic compiler kind only supports the use of global repositories.
The following context switches are used to manage repositories:
- CPP_PTREPOSITORY_MODE
The mode, either global or local
- CPP_PTREPOSITORY_NAME
The name of the template repository which will be used when the repository mode is global. This switch should normally be used to name a view which has been designated as a template repository by setting its build policy to ptrepository.
- CPP_PTREPOSITORY_ARTIFACT_NAMES
Names repository artifacts that will be removed when cleaning the view.
- CPP_PTREPOSITORY_ARTIFACT_EXTS
Provides extensions for repository artifacts that will be removed when cleaning the view.
Compiling C/C++ Views and Using Build Policies
In the standard C/C++ keys, the build policy of a view defines what happens when a build operation is applied to the entire view. The build policy of a view also defines what the view will contribute when it is involved in linking a main program. For example, the predefined build policy library, specifies that coding a view will cause a library to be created containing the object files in the view. The build policy library also specifies that when the view is in the closure of a main program, the library will be provided as part of the link.
The build policy of a view is specified by the BUILD_POLICY switch in the view's switch file.
Standard Build Policies
The standard C/C++ keys support a number of predefined build policies, including:
- object_files
Specifies that coding a view will create object files but no library. The object files will directly contribute to each link.
- library
Specifies that coding a view will create a library from the object files in the view. The library will be contributed to each link.
- layer_library
Specifies that coding a view will create a library containing object files from the view and each of the directly imported views. The library will be contributed to each link.
- closure_library
Specifies that coding a view will create a library containing object files from the view and all imported views. The library will be contributed to each link.
- mutual_library
Specifies that coding a view will create a library containing object files from the view and each of the mutually imported views. The library will be contributed to each link.
This policy should be used to designate one view in a mutual set to contain a library for the entire set. All other members of the set should have their policy set to mutual_member.
- mutual_member
Specifies that coding a view will cause creation of object files. The view will make no contribution to any linking operation.
- external_library
Specifies that coding the view will have no affect and there is no predefined contribution to a link. This is used when the view contains externally generated libraries.
- ptrepository
Specifies that the view contains a global template repository but no source code. Cleaning such a view will cause the repository to be removed.
- custom_build
Users may also define their own build policies with arbitrary names and semantics. This is discussed in the later section on customization.
Building Libraries
A number of the standard build policies specify that libraries will be constructed when the view is compiled. In general the standard build models are capable of constructing either archive or shared libraries, however shared libraries are not supported for all platforms.
When a build policy specifies that a library is to be constructed there are independent switches which determine whether archived libraries and/or shared libraries are to be built. These switches are called CREATE_ARCHIVED_LIBRARY and CREATED_SHARED_LIBRARY. The default settings in the standard models specify that archive libraries are to be built and shared libraries are not to be built. The name of an archive library is specified by the LIBRARY_NAME context switch and the name of a shared library is specified by the SHARED_LIBRARY_NAME context switch.
Whenever a library is constructed a closure file is also constructed which contains the names of all object files which were included in the library. The closure file has the.closure extension.
There are 5 steps in the construction of either an archive library or a shared library:
- 1 . Code the Closure
If the switch -closure_compilation_policy is set to compile_all and neither -no_closure_compilation nor -use_existing_closure is set, then code all source files whose objects files will be contained in the library. This will include source files in the current view and in other views depending on the setting of the BUILD_POLICY switch.
- 2 . Compute the Library Closure
Compute the set of object files that will be included in the library. If the -use_existing_closure option is set and the closure file for the library exists then use the current contents of the closure file to construct the library. Otherwise, reconstruct the closure file by examining the contents of all views which will contribute to the library.
- 3 . Check Template Instantiations
Template instantiations associated with object files in the library are checked to make sure they are up to date. Instantiation objects which are obsolete will be regenerated. Object files containing instantiation code are included in the library closure file. If a closure file exists and the -use_existing_closure option is set then this step is skipped.
This step will be skipped if the template repository mode is global. Libraries for views with a global template repository mode will not contain any instantiation objects.
- 4 . Check Library Currency
If a library exists then a check is made to see if the library is up to date with respect to the files in the closure file. If the library is up to date then it will not be rebuilt.
- 5 . Generate the Library
Generate the library based on the specified closure. Note that the options -no_closure_compilation and -use_existing_closure can significantly reduce the time to generate libraries when it is known that all source files are already compiled and that the desired contents of the library have not changed from the last time the library was constructed.
Name Space Management
The ability of a C/C++ client file to include a C/C++ header file is determined by the visibility and architectural control characteristics of the views containing both files.
Visibility Control
A reference from a client file to an included header file may only be resolved if the naming environment of the view containing the client file has been configured to provide visibility to the included file through the name that is given in the include directive. Visibility control provides a way to specify a naming environment and have Apex automatically construct the directory structures and makefile macros needed to implement that naming environment. A default naming environment is provided as part of the standard model and customization of the naming environment is provided by the visibility description file.
There are two types of file references in include directives which can be resolved in the naming environments constructed by Apex:
- Immediate References
Immediate references provide immediate access to a header file in either the current view or an imported view. Immediate references in include directives have the form:
#include "simple-name.h"
- Qualified References
Qualified references provide access to included files through relative pathnames. The relative pathnames may name files in the current view or an imported view. Qualified references in include directives have the form:
Include references based on fully-qualified names are not subject to management by Apex.
There are three directories in each view which are constructed by the standard models as part of the management of naming environments:
- Links/Local
Contains symbolic links to each C/C++ file in the view. This directory provides a flattened name space for the view. This directory is usually provided to the compiler as -ILinks/Local in order to provide immediate access to all of the files in the current view.
- Links/Immediate
Contains symbolic links to imported views. These symbolic links are used to provide immediate access to files in imported views. The targets of these links may be any directory in the imported view including the Links/Local directory.
- Links/Imported
Contains symbolic links to imported views. These symbolic links are used to provide qualified access to files in imported view. The targets of these links may be any directory in the imported views including the Links/Local directory.
The directories named above are normally used by C/C++ models in order to control the naming environment of the compiler through the use of the -I directives to the compiler. For example, the include directives -ILinks/Local and -ILinks/Imported provide immediate access to all local files and qualified access to files in imported views. Other tools may also base their name spaces on these links.
Default Visibility Control
The standard model provides both immediate and subsystem-qualified visibility by default to all header files in the current view and in imported views. Immediate visibility allows a header file to be named by its simple name regardless of which view or directory contains the header file. Subsystem-qualified visibility allows a header file to be named by a two-part name composed of the simple subsystem name (without the .ss extension) followed by the simple header file name. For example, the following illustrates the two default visibility modes:
#include "header.h" // immediate #include "subsystem/header.h" // qualified
Visibility Description File
The visibility description file provides a means by which access to header files may be customized for header files in both the current view and in imported views.
Each view may contain a visibility description file which is named Imports/Description.vdf. If a view does not contain a visibility description file then the view is subject to the default visibility control described previously.
A supplier view may also contain a visibility description file which may be used by its clients. This file is named Exports/Description.vdf and is used by all clients of the view in order to determine which type of link should be created for the supplier.
Warning: The contents of Exports/Description.vdf in various views are not tracked by the system and will not cause recomputation of import information when changed unless the
-recompute option is passed to the import command.
A visibility description file contains a series of lines which are either subsystem entries or indirect description entries.
A subsystem entry has the form:
subsystem-name [ target-name [ local-name [local-dir-name] ] ]An indirect description entry has the form:
visibility-description-file-name
Where the fields of both types of entries have the following meaning:
- subsystem-name
The name of the subsystem to which the description line will apply. This name may contain wildcards. This name may also refer to the subsystem of the containing view in order to affect visibility to local files. Finally, the same subsystem may appear in more than one entry with different target-names or local-names.
- target-name
Specifies a directory in the imported view to which visibility is desired with the naming environment of the client. It may name the view itself, by using ".". The actual view name is always derived from the actual imports and must not be explicitly indicated. If the target-name is not provided then "." is used.
- local-name
Specifies the local name by which the import will be known in the naming environment. This name is also subject to keyword replacement in the context of the imported view. For example, "<subsystem:t:r>" specifies that the simple name of the subsystem will be used.
If no local-name is provided (or if the local-name is "." or nil), then the entry requests immediate visibility. Immediate visibility signifies that clients may reference the names in the target by their simple names. For example, the following is an example of a reference to a header file that is enabled by immediate visibility:
#include "foo.h"
If a local-name is provided, then the entry requests qualified visibility. Qualified visibility specifies that clients may reference the names in the target by names that are qualified by the local-name. For example, if a local name of "xxx" was specified then include references would look like:
#include "xxx/bar.h"
A local-name must specify a relative pathname which does not include the special parent directory name "..".
- local-dir-name
The subdirectory of <view>/Links in which the link is created. If not supplied then <view>/Links/Imported is used for qualified entries and <view>/Links/Immediate is used for immediate entries.
In general, the links in <view>/Links/Imported and <view>/Links/Immediate are passed to both the C and C++ compilers as the values of appropriate -I options when compiling source files in the view. If certain values should only be passed to the C or C++ compilers then the ,local-dir-name field may be set to Imported_Cpp, Imported_C, Immediate_Cpp or Immediate_C as appropriate.
- visibility-description-file-name
The name of some other visibility description file whose contents are to be effectively treated as part of the current file. The visibility description file extension .vdf must be specified as part of this file name. This type of entry provides a way to simplify project-wide administration of visibility policies.
Visibility description files may also contain comments which begin with the character "#".
Below is an example of a visibility description file which provides the same visibility as the default visibility.
* Links/Local # immediate * Links/Local <subsystem:t:r> # qualified
The contents of a view's visibility description file are examined whenever the view's imports are recomputed. For each imported view the visibility description file is searched for any entries which are applicable. If one or more entries are found, all of those entries are applied and symbolic links and makefile macros are adjusted accordingly. If no entry is found for an imported view, then the default visibility control is applied to that import.
Local Visibility Switches
As mentioned earlier, by default the Links/Local directory of a view contains symbolic links to all source files in the view. This behavior may be modified by using the following context switches:
- LOCAL_VISIBILITY_INCLUSIONS
Contains the names of additional files for which links will be created in the Links/Local directory. The values of this switch may be a sequence of names, separated by blanks and containing wildcards.
Default value: " "- LOCAL_VISIBILITY_EXCLUSIONS
Contains the names of files for which links will not be created in the Links/Local directory. In particular for a link to be created the file must be named by LOCAL_VISIBILITY_INCLUSIONS and not named by LOCAL_VISIBILITY_EXCLUSIONS. The values of this switch may be a sequence of names, separated by blanks and containing wildcards.
Default value: " "- LOCAL_VISIBILITY_OVERRIDE_DEFAULT
This switch provides a way to override the default policy which creates symbolic links in Links/Local for all header and source files in the view. Setting this switch to true will cause links to be created only for the files specified by the combination of local visibility inclusion and exclusions switches. Setting this switch to false will create links for source and header files and for any additional files named by the local visibility inclusion and exclusions switches.
Default value: false- LOCAL_VISIBILITY_DISABLED
This switch provides a way to disable all local visibility. If set to true then no symbolic links will be created in Links/Local.
Default value: falseArchitectural Control
In addition to being resolved within the naming environment constructed by Apex visibility control, an included file must also satisfy any architectural restrictions. In particular, a client file may only include a supplier file if one of the following is true:
- Both the client file and the supplied file are in the same view.
- The client file is in a view which directly imports the view containing the supplier file. In addition, when the Apex C/C++ compiler is used, the supplier export set which is utilized by the client view must contain the client file.
Linking (C / C++)
Linking C/C++ Main Programs
Linking a C/C++ main program requires that the appropriate object files, libraries, and option settings be identified and passed to the platform linker for processing.
In general, linking a C/C++ program has six steps:
- 1 . The link mode of the main program is identified. The link mode is used to specify whether archive or shared libraries will be linked against.
- 2 . The view closure sequence is computed. This sequence contains all of the views which will contribute to the link in the proper order.
- 3 . The views in the closure sequence are compiled if the -closure_compilation_policy switch is set to compile_all and neither -no_closure_compilation nor -use_existing_closure switches are set.
- 4 . The link contribution of each view is computed. The link contribution of a view contains the object files, libraries, and options which the view contributes to a main program. For views containing libraries, the link mode of the main program determines whether an archive of shared library will be contributed to the link.
- 5 . The main program contribution is computed. The main program contribution consists of the object file for the main program and additional options specific to the main program.
- 6 . The platform linker is invoked to perform the link based on the closure that was constructed from the link contributions of all the views in the closure sequence.
If the program has been previously linked and the -use_existing_closure option is set then the previous closure is used and steps 1 to 5 are skipped.
A successful link produces an executable whose name is the root name of the source file which contained the main program.
Main Program Link Modes
The link mode of a main program determines whether archive or shared libraries will be used when linking a main program. The link mode is specified by the -c_link_mode and -cpp_link_mode options for C and C++ main programs respectively.
- static
Only archive libraries are to be used.
- dynamic
Only shared libraries are to be used.
- dynamic_or_static
Shared libraries should be used if possible, otherwise archive libraries are to be used.
- default
The switch LINK_CONTRIBUTION_DEFAULT_MODE will be examined in each closure view to determine what type of library the view will contribute. The value of this context switch may be either static, dynamic, or dynamic_or_static.
The default settings of switches are such that archived libraries are created and linked against for all build policies which involve libraries.
Computing the View Closure Sequence of a Main Program
The view closure sequence is the sequence of views which will make contributions to the link. The sequence is computed from the imports, an optional configuration specified by the CONFIGURATION switch, and the value of the LINK_CLOSURE_POLICY switch.
Note: The contents of a configuration file should only be those units not already included in the import closure.
For the different values of LINK_CLOSURE_POLICY, the closure sequence is composed of the following:
- imports
The view closure sequence is composed of the full set of imported views. The views are in an order that is determined by the import relationships and link dependencies of the views in the import closure. Link dependencies are based on the setting of the LINK_DEPENDENCIES switch in the view's switch file.
- configuration
The view closure sequence is composed entirely of views referenced by the configuration in the order specified by the configuration.
- update
The view closure sequence is a combination of imported views and views referenced by the configuration. An initial sequence is computed from the imports as if LINK_CLOSURE_POLICY were set to imports. The final sequence is computed by replacing any view in the initial sequence with a corresponding view from the configuration. Views in the configuration for which there is no corresponding view in the original imports, will not be placed in the final sequence.
- combine
The view closure sequence is a combination of imported views and views referenced by the configuration. An initial sequence is computed from the imports as if LINK_CLOSURE_POLICY were set to imports. The final sequence is computed by replacing any view in the initial sequence with a corresponding view from the configuration. Finally, any additional views in the configuration are added to the end of the sequence in the order specified by the configuration.
Computing the Link Contribution for Views in a Closure
The link contribution of a view contains the object files, libraries, and options which the view contributes to the link of a main program. The link contribution is dependent on the link mode of the main program being linked.
The link contribution of a view usually has three parts:
- 1 . The value of the LINK_CONTRIBUTION_PRE_OPTIONS switch (if objects files or an archived library are being contributed) or the value of the LINK_CONTRIBUTION_SHARED_PRE_OPTIONS switch (if a shared library is being contributed).
- 2 . The content of the view which is usually either the object files or the libraries in the view. When archive libraries are specified then the content is the value of the LINK_CONTRIBUTION_LIBRARY context switch. When shared libraries are specified then the content is the value of the LINK_CONTRIBUTION_SHARED_LIBRARY context switch.
- 3 . The value of the LINK_CONTRIBUTION_OPTIONS switch (if objects files or an archived library are being contributed) or the value of the LINK_CONTRIBUTION_SHARED_OPTIONS switch (if a shared library is being contributed).
The content of the view is determined by the setting of the BUILD_POLICY switch in the view.
- object_files
The view content is composed of the object files in the view that correspond to known C/C++ source files which are not registered as main programs.
- library
The view content is composed of the view's library.
- layer_library
The view content is composed of the library in the view which contains object files from the view and its direct imports.
- closure_library
The view content is composed of the library in the view which contains object files from the view and all of its imports.
- mutual_library
The view content is composed of the library in the view which contains object files from the view and its mutual imports.
- mutual_member
The view has no content. Any object files in the view should be included in a library of some other view.
- external_library
The view has no predefined content. This type of view usually contains libraries that were generated externally and placed in the view. The libraries should be named by the LINK_CONTRIBUTION_OPTIONS switch or the LINK_CONTRIBUTION_SHARED_OPTIONS switch.
- custom_build or user-defined value
For example, consider a view whose build switches are as shown below:
BUILD_POLICY: library CREATE_ARCHIVED_LIBRARY: true CREATE_SHARED_LIBRARY: false LIBRARY_NAME: foo.a LINK_CONTRIBUTION_PRE_options LINK_CONTRIBUTION_LIBRARY: <view>/<view'switch(library_name)> LINK_CONTRIBUTION_options
This view would contain an archive library called foo.a and a library closure file called foo.a.closure, but the view would not contain a shared library. Whenever the view is included in the closure of a main program, the view would contribute the archive library foo.a, unless the link mode dynamic was specified, in which case an error would occur.
For another example, consider a view containing an external library libxyz.a which is to be statically linked into any programs that require it. An appropriate setting for entries in this view's switch file would be:
BUILD_POLICY: external_library LINK_CONTRIBUTION_options -L<view> -Bstatic -lxyz
Computing the Main Program Link Contribution
The main program contribution is composed of three parts:
- 1 . The main program's object file.
- 2 . The value of the CPP_LINK_PRE_OPTIONS switch for a C++ program (or C_LINK_PRE_OPTIONS for a C program). The value of this switch will precede the link contributions for all views.
- 3 . The value of the CPP_LINK_OPTIONS switch for a C++ program (or C_LINK_OPTIONS for a C program). The value of this switch will follow the link contributions for all views.
Invoking the Platform Linker
When all contributions have been computed the platform linker is invoked with an argument list that contains the main program contribution and the contributions from all of the views in the closure sequence. The view contributions occur in the order defined by the sequence. The full argument list to the platform linker is saved as part of every link in the file <main>.closure.
Linking Ada Programs Containing C/C++ (Apex Duo only)
Ada programs may be linked with C/C++ in their closure. The view containing the Ada main program must have been enabled for C/C++ linking by the enable_cpp_linking command. When an Ada program is linked against C++, the link occurs in three steps:
- 1 . The Ada pre-linker is run to compute the Ada closure in the usual way.
- 2 . The C/C++ closure is computed and recompiled as if the main program were a C/C++ program. Recompilation of the C/C++ closure can be prevented by setting the -no_cpp_closure_compilation option.
- 3 . The closures are combined (with the Ada closure preceding the C/C++ closure) and then the platform linker is run as if the main program were C/C++.
More information on linking Ada programs containing C/C++ can be found in the Programmer's Guide and the Ada Compiler Reference.
Customization (Build Management)
Apex provides a number of ways in which the standard build management mechanisms can be customized for individual views. Customization capabilities include modifying existing build policies and defining new build policies. Customization of individual object types may also be accomplished by defining the objects and their operations.
Customization is performed by modifying the contents of the following two files:
- Policy/Customization.prop
This file contains settings for various build management properties including the names and definitions of new object types which will be managed in the view.
- Policy/Customization.mk
This file contains the settings for makefile macros and targets which are used to define new build policies, modify existing build policies, and define targets associated with object types defined in Policy/Customization.prop.
Customizing Build Policies
Build Policy Implementation
The build policy for a view defines the actions that occur when a build operation is applied to the view as a whole. The build policy affects the standard build operations, including:
- prepare
- parse
- pretty_print
- dependencies
- analyze
- code
- link
- generate
- check_rules
- test
- deliver
- finalize
- build
- clean
- disassemble
The build policy also effects two queries that are made of views:
- link_contribution.query
This query allows the view to specify what it will contribute to a link. If recompilation is requested as part of making the query then the internal operation query_code_precondition is also executed.
- object_files_content.query
This query allows the view to specify the object files in the view and is used when a library is being constructed that contains the contents of the view.
In the standard keys, whenever a build operation or query is applied to a view, make is invoked in such a way as to build the target "build-policy.operation-or-query". For example, when the code command is run on a view with build policy library, make will eventually be asked to build the target "library.code".
Each build policy must define targets for all of the standard operations and queries. For example, the build policy library, which causes the view to construct a library from all object files in the view and provide the library as the link contribution of the view, has the following targets which implement the policy.
- library.prepare
- library.parse
- library.pretty_print
- library.dependencies
Update the dependencies for all source files in the view.
- library.analyze
- library.code
Compile all source files in the view and then construct a library from the object files which were created.
- library.link
Link all registered main programs in the view.
- library.generate
- library.check_rules
Run the code rule checker on the files in the view (only defined for Apex views).
- library.test
- library.deliver
Deliver artifacts as specified in the DELIVER_OBJECTS and DELIVER_TO_DIRECTORY switches.
- library.finalize
- library.build
Prepare and then code the current view and all imported views.
- library.disassemble
Disassembles object files (only defined for Apex views).
- library.clean
Remove all object files, libraries, and other compiler artifacts in the view.
- library.link_contribution.query
Return the link contribution of the view which will include the name of the library which was constructed in the view.
- library.query_code_precondition
Used in conjunction with library.link_contribution.query This target is used to rebuild the library prior to returning the result of the query.
- library.object_files_content.query
Return the names of object files for all the source files in the view.
Customizing Existing Build Policies
The existing build policies may be customized through the use of trigger macros whose values can be set in the customization makefile Policy/Customization.mk. For each of the standard operations (although not for the standard queries), there are two macros:
- CUSTOM_<operation>_PRECONDITION
This macro allows additional dependencies to be defined for the designated standard operation. If an error occurs during the processing of this dependency then processing of the standard operation will not occur. For example, to customize the standard code operation one could add the following to Customization.mk:
CUSTOM_CODE_PRECONDITION = code_precondition code_precondition: @<precondition-processing>
- CUSTOM_<operation>_ACTION
This macro allows additional actions to be defined for the designated standard operation. The actions specified are executed after standard processing has been done. For example, additional processing for the code operation would be defined by:
Creating New Build Policies
Users may also define their own build policies. The Customization.mk contains the full set of targets necessary to define the build policy custom_build. Users may define the semantics of the custom_build policy by associating actions with targets. When the custom_build policy has been defined, it will be activated in the view by setting the BUILD_POLICY switch to custom_build.
The custom_build policy (and any other user policy) should make free use of the standard targets defined for other policies. For example, if the code operation for custom_build was to perform the same operation as that for the library policy then one could define the following target:
custom_build.code: library.code
Customizing Build Properties for New File Classes
In addition to defining and modifying build policies for entire views it is also possible to define new classes of objects and the commands which will be applied to those objects. For example, it is possible to define a new class of object for YACC files and to define the meaning of build management commands when they are applied to YACC files.
Customization of build properties occurs in the Policy/Customization.prop file.
Defining New Object Classes
New object classes are defined by modifying the Subclasses property in the Policy/Customization.prop file. The format of the file is shown below.
Warning: The syntax of the first line, "{Subclasses:+" implies that the subclass entries in this table will be added to the overall set of subclasses entries. If the "+" was absent then these entries would replace all of the predefined entries .
{Subclasses:+ { {class-name, base-class, comp-state, ext-list, name-list}, ... } Subclasses}
where each field has the following meaning:
- class-name
The name of the new object class which is being defined.
- base-class
The base class of the newly defined class. Usually this will be set to "file".
- comp-state
Currently this field is unused and should be set to the value source.
- ext-list
A list of extensions which can be used for the new class. The list should be comma separated within braces.
- name-list
A list of names which can be used for the new class. The list should be comma separated within braces.
For example, in order to define a new class for YACC files the following could be used:
{Subclasses:+ { {yacc, file, source, { .y }, {} } } Subclasses}
Command Translation Tables
Command translation tables are used to determine the meaning of a particular build command on a particular class of object. The command translation table is a property in the file Policy/Customization.prop. The command translation table can be used to define any shell command which should be executed when the original command is applied to the designated type of object.
The format of a command translation table is shown below.
Warning: Note that the syntax of the first line, "{Command_Translation:+" implies that the translation entries in this table will be added to the overall set of translation entries. If the "+" was absent then these entries would replace all of the predefined entries.
{Command_Translation:+ { {object-class, build-command, "command-string"}, ... } Command_Translation}
The fields in a command translation entry have the following meaning:
- object-class
The class of object to which this command translation will apply. The class may be any recognized predefined or user-defined class.
- build-command
The build command to which the translation will apply for the designated object class. The set of build commands are those listed previously.
- command-string
A string containing Bourne shell commands which will be executed. This string is subject to keyword replacement in the context of the objects to which the original command was applied.
For example, assuming that the makefiles contain suffix rules to generate .c files from .y then the prepare command on YACC objects can be defined as shown below:
{Command_Translation:+ { {yacc, prepare, "cd <dir> ; make <object:t:r>.c, }" } } Command_Translation}
In the example above, the apexsummit command
%apexsummit prepare /source/sub.ss/view.wrk/foo.y
will be translated into the command:
%(cd /source/sub.ss/view.wrk ; make foo.c)
The actual selection and execution of command strings proceeds according to the following steps:
- 1 . The original arguments to the build command are placed in sets. Each set contains objects which have the same class and the same parent directory.
In the example above the set of objects would contain the source file foo.y.
- 2 . For each object set, the command translation table is searched for the command translation for the specified class. If no entry for the specified class is found then the table is searched for an entry for the parent class. If no command translation is found for the original class or any parent class then an error is emitted and no further processing occurs.
- 3 . If a command string is identified then the string undergoes keyword replacement in the context of the set of objects.
In the example, above the keyword <dir> would be replaced the name of the directory containing the set of objects, and the keyword string {<object:t:r>.c, } would be replaced by the name of the object with the parent directory removed and the original extension .y replaced by the new extension .c. Note that the because the keyword <object:t:r> was placed in braces, if the original command was applied to multiple objects in the same directory then all objects in the set would be processed.
- 4 . The resulting string (with keywords replaced) is executed in a Bourne shell subprocess. If the string contains separators of the form "<;;>" then the separate substrings are executed consecutively in separate shells.
Utility Translation Table
Utility actions are invoked when certain events happen to files or directories in specified object classes. The recognized events are:
- post_create
Invoked after the object has been created.
- post_delete
Invoked after the object has been deleted.
- post_maintain
Invoked after the object has been maintained.
- post_set_key
Invoked after the view containing the object has been remodelled.
The utility translation table has the same format as the command translation table:
{Utility_Translation:+ { {object-class, event-name, "command-string"}, ... } Utility_Translation}
The fields in a command translation entry have the following meaning:
- object-class
The class of object to which this command translation will apply. The class may be any recognized OMS class.
- event-name
The name of the event which will cause the command string to be executed.
- command-string
A string containing Bourne shell commands which will be executed. This string is subject to key word replacement in the context of the objects of the designated class to which the original command was applied.
For example, below is a utility translation table containing empty command strings for all of the events defined for YACC files.
{Utility_Translation:+ { { yacc, post_create, ""}, { yacc, post_maintain, ""}, { yacc, post_set_key, ""}, { yacc, post_delete, ""} } Utility_Translation}
Directory Structure
Views that utilize the standard C/C++ models have a directory structure that is illustrated below.
/source/subsystem.ss/view.wrk/ Exports/ Imports/ Links -> ./.Rational/Build_Control/Links Makefile Policy/ Code_Rules.sw Customization.mk Customization.prop Switches ignore.reg main_programs.reg Templates/ foo.C foo.h foo.o lib.a lib.a.closure main.C main.closure main.o .Makefiles.rtnl/ foo.dep main.dep <implementation-objects> .Rational/ Build_Control/ Links/ Immediate/ Imported/ Local/ <implementation-objects> <implementation-objects>
The objects have the following meaning:
- /source/subsystem.ss/view.wrk
The root directory of the view.
- Exports
A directory containing information about the exports of the view.
- Imports
A directory containing information about the imports of the view.
- Links
A symbolic link to a directory which contains links to local and imported files. Usually used to establish visibility during compilation.
- Makefile
The root makefile. This makefile "includes" a number of other makefiles described below.
- Policy
A directory containing policy information for the view including switches, customization makefiles, and registered set information.
- Policy/Code_Rules.sw
A file containing information about which code rules should be checked. Only provided in Apex views.
- Policy/Customization.mk
A makefile that is reserved for user customization of the build process.
- Policy/Customization.prop
A file containing properties which customize the build mechanisms in the view.
- Policy/Switches
A file of switches for the view.
- Policy/ignore.reg
A list of source files that will be ignored during compilation.
- Policy/main_programs.reg
A list of source files containing main programs.
- Template
The template database used by the Apex C++ compiler.
- foo.C
- foo.h
- foo.o
An object file associated with a C++ source file.
- lib.a
An archive library constructed for the view.
- lib.a.closure
The names of the object files that are contained in the library.
- main.C
A C++ source file containing a main program.
- main.closure
The closure file for a main program. This file contains the arguments passed to the linker when the last link was attempted.
- main.o
An object file associated with the main program.
- .Makefiles.rtnl
A directory which contains makefiles associated with the parent source directory.
- .Makefiles.rtnl/foo.dep
A file containing the dependencies of the associated object file. This file is generated automatically when the object file is generated.
- .Makefiles.rtnl/main.dep
A file containing the dependencies for the main program's object file.
- .Rational
A directory containing Apex implementation state.
- .Rational/Build_Control
A directory containing build control state.
- .Rational/Build_Control/Links
A directory containing symbolic links for name resolution.
- .Rational/Build_Control/LinksImmediate
A directory containing symbolic links to imported views which are used for immediate visibility.
- .Rational/Build_Control/Links/Imported
A directory containing symbolic links to imported views.
- .Rational/Build_Control/Links/Local
Context Switches for Build Management
This section presents the context switches associated with C/C++ Build Management. The meaning of these switches in the standard C/C++ models is described.
The default value are used if the switch is not set in the switch file.
General Build Management Switches
- BUILD_KEY: pathname
Specifies the name of the build key of the view and determines all of the build management characteristics of the view. Usually this value is derived from the view's model.
Default value: " "- BUILD_POLICY: policy-name
Specifies the meaning of build operations that are applied to the view. See Standard Build Policies for the standard values. Note, however that user-defined values are also acceptable.
Default value: object_files- BUILD_COMPONENT: component
Specifies the component to be built in the view. The standard makefiles support C/C++, Java or a combination as components. The possible values are:
- cpp
Denotes that only C/C++ components will be built in the view.
- java
Denotes that only Java components will be built in the view.
- java_cpp
Denotes that both Java and C/C++ components will be built in the view.
- BUILD_PHASES: commands
Specifies the set of build commands or "phases" which should be executed when the build command is run in the view. Usually this is used to define the meaning of "build everything" in the view. The value may be any list of commands separated by commas. At run time the value of this string will be executed by the apex_shell interpreter which accepts and expanded form of C shell. The default value will run the prepare command on the current view and all imports and then run the code command on the current view and all imports.
Default value: "apex prepare -imports <view>; apex code -imports <view>"- CPP_COMPILER_HOME pathname
Specifies the pathname to the C/C++ compiler that is to be used in the view
Default value: " "- CPP_COMPILER_VARIANT variant
Specifies the compiler variant that is to be used. This is only used for Apex compilers which have different variants that are specified by alternative compiler configuration files (that is, ".cfg" files) in the CPP_COMPILER_HOME directory. When multiple Apex compiler configuration files exist then this value should be the simple name of the file without a the .cfg extension.
Default value: "default"- CPP_COMPILER_KIND kind
Specifies the kind of compiler that is named by the CPP_COMPILER_HOME switch. The possible values are:
- apex
Denotes the Rational Apex family of compilers.
- SPARCompiler-4
Denotes Sun's SPARCompilers version 4.1 and later.
- generic
- LINK_CLOSURE_POLICY: closure-policy
Specifies the way in which the closure of main programs is to be computed. The possible values are:
- imports
Specifies that the closure is composed of the imports.
- configuration
Specifies that the closure is composed of the designated configuration.
- update
Specifies that the closure is composed the imports with appropriate entries replaced by the values in the configuration.
- combine
Specifies that the closure is composed the imports with appropriate entries replaced by the values in the configuration, and additional entries added.
- CLOSURE_COMPILATION_POLICY: compilation-policy
When building a library or linking a main program, specifies the policy for automatic recompilation of the closure. Possible values are compile_all and compile_none.
Default value: compile_all- CREATE_ARCHIVED_LIBRARY: boolean
Determines whether or not an archived library will be created when a library is specified by the build policy. Note that a library is only created if this option is set and the build policy specifies that a library is to be created
Default value: true- CREATE_SHARED_LIBRARY: boolean
Determines whether or not an archived library will be created when a library is specified by the build policy.
Default value: false- LIBRARY_NAME: simple_name
Specifies the name of the archive library in the view.
Default value: "lib<subsystem:t:r>.a"- SHARED_LIBRARY_NAME: simple_name
Specifies the name of the shared library in the view.
Default value: "lib<subsystem:t:r>.so"- CONFIGURATION: pathname
Specifies the configuration to be used when computing the closure of a main program.
Default value: " "- MAKE_options tokens
Specifies options that are passed to make whenever it is invoked as part of the execution of a command.
Default value: " "C Compilation and Linking Switches
- C_OPTIONS tokens
Options that are passed to the C compiler when a C source file is compiled.
Default value: " "- C_PRE_OPTIONS tokens
Options that are passed to the C compiler when a C source file is compiled
.Default value: " "- C_LINK_OPTIONS tokens
Options that are passed to the linker whenever a C main program is linked.
Default value: " "- C_LINK_PRE_OPTIONS tokens
Options that are passed to the linker whenever a C main program is linked.
Default value: " "- C_LINK_MODE: link-mode
Specifies the link mode for C main programs in the view. The possible values are:
- static
Only archive libraries are to be used.
- dynamic
Only shared libraries are to be used.
- dynamic_or_static
Shared libraries should be used if possible, otherwise archive libraries are to be used.
- default
The switch LINK_CONTRIBUTION_DEFAULT_MODE will be examined in each closure view to determine what type of library the view will contribute. The value of this context switch may be either static, dynamic, or dynamic_or_static.
- DEBUGGING: boolean
Specifies whether or not debugging is enabled in the view.
Default value: false- OPTIMIZATION_LEVEL: number
Specifies the optimization level.
Default value: 0- PROFILING: kind
Specifies whether profiling is enabled. Possible values are prof and gprof.
Default value: " "C++ Compilation and Linking Switches
- CPP_OPTIONS tokens
Options that are passed to the C++ compiler when a C++ source file is compiled.
Default value: " "- CPP_PRE_OPTIONS tokens
Options that are passed to the C++ compiler when a C++ source file is compiled.
Default value: " "- CPP_LINK_OPTIONS tokens
Options that are passed to the linker whenever a C++ main program is linked.
Default value: " "- CPP_LINK_PRE_OPTIONS tokens
Options that are passed to the linker whenever a C++ main program is linked.
Default value: " "- CPP_LINK_MODE: link_mode
Specifies the link mode for C main programs in the view. The possible values are:
- static
Only archive libraries are to be used.
- dynamic
Only shared libraries are to be used.
- dynamic_or_static
Shared libraries should be used if possible, otherwise archive libraries are to be used.
- default
The switch LINK_CONTRIBUTION_DEFAULT_MODE will be examined in each closure view to determine what type of library the view will contribute. The value of this context switch may be either static, dynamic, or dynamic_or_static.
- CPP_PTREPOSITORY_MODE: ptrepository-mode
Specifies the template repository mode for the view. The possible values are:
- local
Used to specify that each view will have its own repository for the objects associated with templates in the view.
- global
Used to specify that each view in a system configuration will use the same repository.
- CPP_PTREPOSITORY_NAME: pathname
Specifies the name of the template repository used by the view when the repository mode is global. Usually this switch should name a view whose build policy has been set to ptrepository and has thereby been designated as a global repository.
Default value: " "- CPP_PTREPOSITORY_ARTIFACT_NAMES: names
The names of artifacts within the view's repository which should removed when the view is cleaned. This value need not be set for either apex or SPARCompiler-4 compiler kinds.
Default value: " "- CPP_PTREPOSITORY_ARTIFACT_EXTS: extensions
The extensions of artifacts within the view's repository which should be removed when the view is cleaned. Values should be a begin with a period and be separated by spaces. This value need not be set for either apex or SPARCompiler-4 compiler kinds.
Default value: " "- DEBUGGING: boolean
Specifies whether or not debugging is enabled in the view
Default value: false- OPTIMIZATION_LEVEL: number
Specifies the optimization level.
Default value: false- PROFILING: kind
Specifies whether profiling is enabled. Possible values are prof and gprof.
Default value: " "Java Compilation and Linking Switches
- JAVA_HOME: pathname
Specifies the pathname to the Java Developers Kit home directory.
Default value: "nil "- JAVAC_OPTIONS tokens
Specifies options which will be passed to the Java compiler.
Default value: ""- JAVA_OPTIONS tokens
Specifies options which will be passed to the Java interpreter.
Default value: " "- JAVA_CLASSPATH: pathname-list
Specifies a list of pathnames separated by colons (":") in which to look for additional Java classes. This need not be set to access classes in other Apex views.
Default value: "nil "Assembly File Switches
- S_OPTIONS string
Options that are passed to the assembler whenever a user assembly (.s) file is processed.
Default value: " "Local Visibility Switches
- LOCAL_VISIBILITY_INCLUSIONS: names
Contains a list of names, possibly containing wildcards, for which additional links will be created in Links/Local unless the object is also named in the corresponding exclusion switch.
Default value: " "- LOCAL_VISIBILITY_EXCLUSIONS: names
Contains a list of names, possibly containing wildcards, for which additional links will be not be created in Links/Local even if the object is named by an expression in corresponding inclusion switch.
Default value: " "- LOCAL_VISIBILITY_OVERRIDE_DEFAULT: boolean
If false then links to objects named by LOCAL_VISIBILITY_INCLUSIONS and LOCAL_VISIBILITY_EXCLUSIONS will be added to the default links in Links/Local. If true then the new links will be added instead of the default links.
Default value: false- LOCAL_VISIBILITY_DISABLED: boolean
If set then no local visibility is set up for objects in the current view. This results in no symbolic links being placed in Links/Local.
Default value: falseLink Contribution Switches
- LINK_CONTRIBUTION_OPTIONS tokens
Options that are included as part of the link contribution of the view for static link modes whenever the view is part of the closure of a main program. These options follow the object file or library contribution of the view.
Default value: " "- LINK_CONTRIBUTION_PRE_OPTIONS tokens
Options that are included as part of the link contribution of the view for static link modes whenever the view is part of the closure of a main program. These options precede the object file or library contribution of the view.
Default value: " "- LINK_CONTRIBUTION_LIBRARY: string
The name of the library that is included in the contribution for static link modes.
Default value: "<view>/<view'switch(library_name)>"- LINK_CONTRIBUTION_SHARED_OPTIONS tokens
Options that are included as part of the link contribution of the view for dynamic link modes whenever the view is part of the closure of a main program. These options follow the object file or library contribution of the view.
Default value: " "- LINK_CONTRIBUTION_SHARED_PRE_OPTIONS tokens
Options that are included as part of the link contribution of the view for dynamic link modes whenever the view is part of the closure of a main program. These options precede the object file or library contribution of the view.
Default value: " "- LINK_CONTRIBUTION_SHARED_LIBRARY: string
The name of the library that is included in the contribution for dynamic link modes.
Default value: "<view>/<view'switch(shared_library_name)>""- LINK_CONTRIBUTION_DEFAULT_MODE: link-mode
The link mode to use when the main program specified that the default for each closure view should be used. There are three link modes:
- static
Only archive libraries are to be used.
- dynamic
Only shared libraries are to be used.
- dynamic_or_static
Shared libraries should be used if possible, otherwise archive libraries are to be used.
- LINK_DEPENDENCIES: subsystem; subsystem; ...
Specifies additional dependencies to be considered during linking. Dependencies are specified as a list of subsystem names separated by semicolons. The subsystems listed are treated as though import relationship existed from the current view to views of the listed subsystems. This allows representation of link dependencies that are not necessarily compilation dependencies (such as between two views that contain different external libraries but no source).
Default value: " "Delivery Switches
- DELIVER_OBJECTS: relative-names
The view relative names of objects that are to be copied as part of the deliver command.
Default value: " "- DELIVER_TO_DIRECTORY: pathname
The directory to which the corresponding objects are to be delivered.
Default value: " "- DELIVER_OBJECTS_[1-9]: relative-names
The view relative names of objects that are to be copied as part of the deliver command.
Default value: " "- DELIVER_TO_DIRECTORY_[1-9]: pathname
The directory to which the corresponding objects are to be delivered.
Default value: " "Non-Apex C/C++ Compilation Switches
These options are provided to control the behavior when non-Apex compilers being used to generate code (i.e., when CPP_COMPILER_KIND is not set to apex),
- DEPENDENCIES: boolean
This switch determines whether or not compilation dependencies files are updated as part of each compilation.
Default value: false- SIENNA: boolean
This switch determines whether or not Sienna will be generated as part of each compilation. Sienna generation is required in order to enable the Apex navigation facilities.
Default value: false- SIENNA_HOME: pathname
This switch provides the pathname to the Apex compiler which is invoked from Sienna generation.
Default value: nil- SIENNA_OPTIONS tokens
This switch contains options which will be passed to the Apex compiler for Sienna generation but which will not be passed to the non-Apex compiler when generation code.
Default value: " "Ada Linking Switches (Apex Duo only)
- ALTERNATE_KEY: pathname
The alternate key in a Ada view that is used to enable linking C/C++ in the closure.
Default value: " "- LINK_CLOSURE_LANGUAGES: Ada | C++
Specifies the languages in the closure. Only needed when the closure contains languages other than that of the main program.
Default value: " "
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |