Most readers of this information will already be familiar with the notion of a precompiled header. With traditional
precompiled headers, a single header is designated as one to be precompiled. In PC-lint, such a file was one that was
expected to be #include’d in the source module. In PC-lint Plus, an existing precompiled header is processed as a
prefix header and is loaded before each module that follows the pch option designating the PCH header, regardless
of whether that module explicitly #includes the header or not. PC-lint Plus’s precompiled headers act as a sort of
"on disk caching" of a previously compiled header file. Information is loaded into memory as needed, reducing
processing time.
Two types of precompiled headers exist; those precompiled for C modules have the extension "lcph’ while those
precompiled for C++ modules have the extension "lpph". For example, if a header’s name is "a.h" and it is being
precompiled for a C module, the resultant file will be "a.lcph". If a specific header is marked for precompilation and
a precompiled version does not already exist, PC-lint Plus will precompile that header at the start of examining a
module, saving it to a file with the relevant extension. PC-lint Plus will create a C or C++ version of the precompiled
header only if necessary to process the next module. Otherwise, the file will be opened and read in as
needed.
Note: if you #include the file from which a precompiled header is created, you are advised to follow what is
typically considered good programming practice and make sure that header contains a standard include
guard.
To designate that a header is to be precompiled use the option:
-pch( header-name )
The header-name should be the name of a file that can be found via the traditional include process, such as by
examining -i options.
If you want to use a precompiled header for some modules and not for others, you can disable the use of a precompiled header with the option:
-pch()
For example, to use header "a.h" as a precompiled header for the first three modules of your project and not the fourth, the arguments passed to PC-lint Plus should look something like this:
-pch(a.h) module1.c // creates `a.lcph` if needed module2.cpp // creates `a.lpph` if needed module3.c // `a.lcph` already exists; load as needed -pch() module4.c // neither create nor use any precompiled header
You can also specify multiple precompiled headers per project, though only one per module. You do so by passing another -pch(header-name) styled option to PC-lint Plus after the previous module name and before the next. If we alter our example above to use a precompiled header for "b.h" in the fourth module of the project, the argument list would look something like this:
-pch(a.h) module1.c // creates `a.lcph` if needed module2.cpp // creates `a.lpph` if needed module3.c // `a.lcph` already exists; load as needed -pch(b.h) module4.c // creates `b.lcph` if needed
To designate that a header is to be precompiled use the option:
-pch( header-name)
The header-name should be that name used between angle brackets or between quotes on the #include line. In
particular, if the name on the #include line is not a full path name do not use a full path name in the
option.
Normally a precompiled header is the first header encountered in each of the modules that include it. Occasionally it
is not, because the -header() option forcefully (if silently) includes a header just prior to the start of each module.
Also, it just might be desirable to include a header prior to the one declared to be the precompiled header. So earlier
headers are permitted. But if a precompiled header does follow an include sequence, it must follow
that same include sequence in every module in which it is included. Otherwise a diagnostic will be
issued.
The sequence of events that takes place when a precompiled header is included can be monitored by using a variant of the verbosity option that contains or implies the letter ’f’. Given the option sequence:
-pch(x.h) -vf
we would expect to see, at the first time x.h is included, the verbosity line:
Including file x.h (bypass)
As indicated above, x.h becomes, of necessity, a file to be bypassed in subsequent modules. After fully processing x.h and all of its includes we will see the line:
Outputting to file x.lph
The extension "lph" stands for "lint precompiled header". The name of the file containing the precompiled output is
formed by appending this extension onto the root of the file named in the pch option.
In subsequent modules you will see the verbosity line:
Bypassing x.h
in place of a line that would normally show an include of this header.
If the program were to be linted subsequently with the same options, then instead of seeing a verbosity line indicating that x.h were included and x.lph were written we would see:
Absorbing file x.lph
reflective of the fact that x.lph contains binary information representative of the information in x.h.
The .lph file is not automatically regenerated when the original header (or any of its sub headers) is modified. If it is important that it must be done automatically then you will need a make facility or its equivalent. An entry in the make file could be as simple as:
x.lph: x.h ... del x.lph
In words, an x.lph is composed of x.h plus any of its included header files and is ’manufactured’ by a deletion of x.lph. If this confuses the make facility then you might try something like:
request.lph: x.h ... del x.lph touch request.lph
Here you need to create a file called "request.lph" whose content is the minimal necessary for make to consider it a file. Whenever any of a collection of headers is modified, x.lph is deleted and the date of the request.lph is updated.
Lint comment options residing in headers are not currently preserved in the generated precompiled headers. Options, such as suppressions, appearing within headers that are used as precompiled headers (or included by such headers) should therefore be moved out of the header to achieve the desired effect (parameterized suppression options are particularly useful here).