C++ Source Files and Source Regions

VisualAge C++ uses the four terms listed below to describe user code that is processed in a C++ incremental build. The first three terms describe C++ source files. The last term relates to preprocessed C++ source code that is stored in the codestore.

Primary Sources
Primary sources are source files listed in the configuration file. They can be ordinary source files or header files. During a build, these files are subject to orderless compile.

A primary source file is not the same as a translation unit. In a traditional compiler, each source file is a translation unit, but VisualAge C++ builds from all sources at once. As a result, the one-definition rule of the C++ standard applies to the entire set of sources for a build.

VisualAge C++ applies the conventional rules of internal and external linkage to primary sources. Variables and functions declared with internal linkage are visible only within the primary source file in which they are declared. Variables and functions declared with external linkage are visible to all source files.

Included Sources
Included sources are source files not listed in the configuration file. They are compiled because they are included, either directly or indirectly, in primary files with #include preprocessor directives.

A C++ source file can be named in an #include directive and also be listed in the configuration file. When that happens, the file is treated as a primary source and the #include directive is ignored. You can leave the #include directive in place so that your source files can also be compiled by traditional C++ compilers.

Included sources are treated as if their contents appeared at the inclusion point. For example, the file boundaries have no effect on source region boundaries.

For faster builds and to simplify your source file organization, use primary sources rather than included sources as much as possible. You should convert included sources that are semantically the same in all places where they are included to primary or macro sources.

Macro Sources
Macro sources are primary sources to which the build option macros(global) applies. During a build, they are preprocessed before other sources, and in the order of their appearance in the configuration file. For purposes other than controlling the visibility for macros, macro sources are identical to primary sources.

Use macro sources for files that contain macro definitions that must be visible in other source files. The scope of macros defined in macro sources includes all macro sources listed subsequently in the configuration file and all sources that are not macro sources. If a subsequent macro source undefines a macro with a #undef directive, the scope of that macro ends.

Macros defined in primary sources that are not macro sources are local to the file in which they are defined.

Source Regions
Source regions are not source files. Source regions are stored in the codestore and contain preprocessed tokens. They are the smallest units of preprocessed source that can be recompiled and relinked during an incremental build. Usually a source region contains a representation of a much smaller section of code than a source file. For example, each high level declaration in your code is represented in the codestore in a separate source region. If you change a declaration between builds, only the regions that represent the declaration and regions that depend upon it are rebuilt.

Source regions are considered to be unordered with respect to other source regions. This means that the source code from which one source region is generated can refer to names declared in source code from which other source regions are generated, regardless of the order in which the source files are processed. Within a source region, declarations and statements are ordered using the normal C++ rules of ordering. This means that within a class declaration or within a function body, names must be declared before they are used.



Configuration Files
Codestore
Incremental C++ Builds
One Definition Rule
Macros in C++ Source Files
The Configuration Optimizer


Convert Included Source Files to Primary Source Files
Add or Change Source Files