Creating and Using Build Specification Files

If it is difficult to modify your build process to create a new build configuration, then you may need to create a build specification instead.

A build specification file is a summary that details how your application is built. In particular, it summarizes the steps needed to perform static security analysis and specifies the files to process and the compilation options to use. It also describes the pseudo object modules that must be linked to generate the analysis results and the librarian invocations that are needed to combine those pseudo object modules into static link libraries.

The Intel® Compiler provides utility programs to create and execute build specifications. Invoke any of these utilities with the -help switch to get a usage message or with the -version switch to identify the version.

Creating a Build Specification File

There are several ways to create a build specification. They are described here in order of convenience.

• Run your normal (debug) build under the injection utility

  The injection utility launches your build command as a child process, intercepts process creations, and generates a build specification file. Each time it sees an invocation of the compiler, librarian, or linker, it captures the command options and adds a corresponding command to the build specification file. Run the utility, as shown in the following:

  inspxe-inject -save-spec <output build spec> -- <build command>

  For example:

  inspxe-inject -save-spec buildapp_sca.spec -- make debug

  The injection utility automatically recognizes the following four compilers: the Intel® C++ compiler, the Intel® Fortran compiler, the Microsoft Visual C++* compiler, and the GNU* C++ compiler. The injection utility will not operate correctly if your build procedure invokes a compiler, librarian, or linker on another computer.

  Note

  If your build procedure compiles or links files that are not part of your application, the resulting build specification file will also analyze those files. If you cannot avoid compiling unrelated source files during your build, edit the build specification file with a text editor to eliminate the unwanted compilation and link steps.

• Modify your build procedure to "wrap" each compilation, librarian, and linker step, then execute the modified build

  You can modify your build program or script to invoke the compiler, librarian, or linker indirectly using the wrapper utility. The wrapper utility appends a single action to the build specification file that corresponds to a command. It then executes the specified command (unless the -no-run switch is supplied). At every point where your build program or script invokes the compiler, librarian, or linker, run the utility, as shown in the following:

  inspxe-wrap -save-spec <output build spec> [-no-run] -- <command>

  For example:

  inspxe-wrap -save-spec buildapp_sca.spec -- icl $(CFLAGS) file1.c

  Note

  If your build procedure compiles or links files that are not part of your application, you should not wrap these actions. Wrapping would include these actions in the build specification, which is undesirable.

  Note

  The actions created by your instrumented build will be appended to the previous contents of the build specification. Therefore, before you execute your modified build, you should delete the output build specification file.

Dealing with Multiple Projects, Multiple Configurations, and Shared Code

Your development team may use a master build script that builds several projects or several configurations of the same project. For example, a build script might compile and link the debug and release versions of several different applications.

Running a build script like this under the injection utility (or after instrumentation with the wrap utility) will generate a single build specification that, when executed, scans everything that was built. This is inconvenient because it does not allow you to scan one project by itself. Also, it may not be useful to scan more than one configuration of the same program, as all configurations of the same project generally contain the same defects.

If your master build script supports the capability to build only a single configuration of a single project, then you should use this to create a separate build specification file for each project. This still gives you the ability to scan individual projects; you can then write a script that scans all the projects.

Sometimes common source files or libraries are built into multiple projects. In these cases, there is often considerable overlap in analysis results. That is, defects in shared files tend to appear in every project that uses that file. It is possible that a defect in a common file will be detected in some project contexts and not in others. To cover this possibility, you may want to analyze the results for that file in every project. You will need to decide if the additional coverage is worth the effort.

It may want to choose one primary project where the analysis results for a shared file will be investigated. (For a library, the natural choice is the analysis results for the library itself.) For extra coverage, you can compare the results of analyzing the primary project with the results of investigating another project to see if any new problems in the shared file were discovered.

Using the Build Specification File

Once you have created a build specification, you can use it to perform static security analysis. Remember to update your build specification each time a file is added or removed from the project or when compilation options change. Otherwise, full analysis of your entire application will not occur.

To perform static security analysis from a build specification, use the following command line utility.

inspxe-runsc -spec-file <build spec> [<options>]

<options> represents additional options to be passed to the compilation (and link) steps.

Build Specification Utility Options

Option	Result
-?, -h, -help	Describes command line options
-d-i=id -disable-id=id	Disables warning with specified id
-e-i=id , -enable-id=id	Enables warning with specified id
-l=(1 | 2 | 3), -level=(1 | 2 | 3)	Specifies level of static security analysis (default = 3)
-l-d=dir, -log-dir=dir	Specifies directory where information is logged
-no-return-app-exitcode	Sets the return code based on success of the tool, not the underlying result (default for inspxe-inject)
-o-i=file, -option-file=file	Specifies the file containing command line options
-q, -quiet	Suppresses non-essential messages
-r=dir, -result-dir=dir	Specifies the directory where analysis results are created (inspxe-runsc only)
-return-app-exitcode	Sets the return code based on success of underlying operation, not the tool (default for inspxe-wrap and inspxe-runsc)
-s-s=file, -save-spec=file	Specifies the file containing build specification (inspxe-wrap and inspxe-inject only). The wrap utility appends to this file; the injection utility overwrites this file.
-t-d=dir, -tmp-dir=dir	Specifies the directory where temporary files are created
-v, -verbose	Prints additional information
-V, -version	Displays the version number of the utility

A user error in usage, such as an invalid command line option, causes a return code of 1. An error in the tool itself causes a return code of 2. In addition, the following rules apply:

• inspxe-wrap returns the return code of the wrapped command
• inspxe-runsc returns 0 if the analysis results are complete and 4 if an error occurred that prevented complete analysis
• inspxe-inject returns 0

Adding the -return-app-exitcode to the inspxe-inject command line causes the inspxe-inject utility to return the return code of the observed build command. This is recommended if the build command return code is a reliable indicator of whether the actions recorded in the build specification are complete and correct.

If no options are specified, the option to enable level 3 static security analysis is added by default.

Copyright © 1996-2011, Intel Corporation. All rights reserved.