Build specification file format
From current
Contents |
Note: It is possible to concatenate multiple build specification files, but a build specification can only have one version line.
Format of the build specification file for C/C++ projects
The Klocwork build specification for C/C++ projects, called kwinject.out by default, is a text file in semicolon-separated format.
The first field is a tag to identify the type of line. The possible tags are as follows:
| Tag | Description |
| version | build specification format version |
| compile | used to track compiler execution |
| link | used to track linker/librarian execution, that is, how executables/libraries are created |
| config | user compiler configuration |
version line
The version line is used to define the build specification format version. It must be the first line in the build specification. Only one version line may appear in a build specification.
Example version line:
version;104
The three-digit integer is used to encode the version. The first (left-most) digit encodes the major version ("1" in above example); the last two digits encode the minor version ("04" in above example, resulting in the "1.4" full version code).
Version 1.4 or later indicates that the build specification was generated using a source encoding of UTF-8, allowing multibyte characters (for example, Japanese). To ensure that kwbuildproject processes the build specification with UTF-8 encoding, the version must be version;104 or later.
compile line
Compile lines are used to track compiler execution.
Example compile line:
compile;/tmp/zlib-1.2.2;/usr/bin/gcc;/tmp/zlib-1.2.2/example.o;example.c;-DUSE_MMAP
The fields are:
| Field | Description |
| "compile" tag | tag for compilation lines |
| work directory | current working directory at linker execution time (/tmp/zlib-1.2.2 in the above example) |
| compiler | full path to user compiler executable (for example, /usr/bin/gcc) |
| output file | name of the "native" object file (for example, /tmp/zlib-1.2.2/example.o) |
| source file | name of the source file (for example, example.c) |
| compiler flags | extra compiler options, separated by semi-colon; generally a list of include directories and macro definitions (for example, -DUSE_MMAP) |
link lines
Link lines are used to track linker execution, that is, how executables/libraries are created.
Example link line:
link;/tmp/zlib-1.2.2;/tmp/zlib-1.2.2/example;/tmp/zlib-1.2.2/example.o;/tmp/zlib-1.2.2/libz.a
The fields are:
| Field | Description |
| "link" tag | tag for link lines |
| work directory | current working directory at compiler execution time (/tmp/zlib-1.2.2 in the above example) |
| output file | name of the executable or library (for example, /tmp/zlib-1.2.2/example) |
| object files | semi-colon-separated list of object files and/or libraries linked into executable/library (for example, /tmp/zlib-1.2.2/example.o;/tmp/zlib-1.2.2/libz.a) |
config line
The config line is used to record the list of defines and include directories implicitly used by the native compiler. This line is optional, but in order to obtain an accurate analysis, system defines and includes must be specified.
Example config line (truncated):
config;/usr/bin/gcc;-e;gnu;-DGNUC=3;...;-J/usr/include;...
The fields are:
| Field | Description |
| "config" tag | tag for config lines |
| compiler | path to compiler (for example, /usr/bin/gcc) |
| flags | a list of semicolon-separated compilation options to be passed to the Klocwork compiler. The listed flags will be automatically added to every compile command line using the same compiler. |
Format of the build specification file for Java projects
The Klocwork build specification for Java projects, called kwinject.out by default, is a semicolon-separated text file containing the following information about the Java source files in your Klocwork project:
- the classpath and Java version for the javac invocation, identified in jconfig lines
- the source Java files that were compiled, identified in jcompile lines
As shown in the following sample file, this information is repeated for each javac execution:
version;105
jconfig;COMPILE_UNIT_1;-classpath;C:\Program Files\Java\jdk1.5.0_06\jre\lib\rt.jar;-source;1.4
jcompile;COMPILE_UNIT_1;D:\Klocwork\sources\jcolor\src\com\klocwork\util\jcolor\ColorConsolePrintStream.java
jcompile;COMPILE_UNIT_1;D:\Klocwork\sources\jcolor\src\com\klocwork\util\jcolor\NativeColorConsolePrintStream.java jconfig;COMPILE_UNIT_2;-classpath;D:\khlov\Klocwork\class\junit.jar;
D:\khlov\Klocwork\class\colt.jar;D:\khlov\Klocwork\class\log4j.jar;
D:\khlov\Klocwork\class\easymock.jar;D:\khlov\Klocwork\sources\kwutils\test_classes;
D:\khlov\Klocwork\sources\kwutils\classes;C:\Program Files\Java\jdk1.5.0_06\jre\lib\rt.jar;D:\khlov\Klocwork\class\typed.jar;
D:\khlov\Klocwork\class\jdom.jar;D:\khlov\Klocwork\class\jcolor.jar;-source;1.4
jcompile;COMPILE_UNIT_2;D:\khlov\Klocwork\sources\kwutils\src\com\klocwork\util\CommandLineParser.java
jcompile;COMPILE_UNIT_2;D:\khlov\Klocwork\sources\kwutils\src\com\klocwork\util\DebugOptions.java
jclass;COMPILE_UNIT_2;D:\khlov\Klocwork\sources\kwutils\classes\com\klocwork\util\classes
The example shows two javac executions, identified by the two jconfig lines.
The first field of each line is a tag to identify the type of line. The possible tags are as follows:
| Tag | Description |
| version | build specification format version |
| jconfig | used to define Java compiler options, such as Java version and classpath |
| jcompile | used to specify compiled source files |
version line
The version line is used to define the build specification format version. It must be the first line in the build specification. Only one version line may appear in a build specification.
Example version line:
version;105
Version 1.4 or later indicates that the build specification was generated using a source encoding of UTF-8, allowing multibyte characters (for example, Japanese). To ensure that kwbuildproject processes the build specification with UTF-8 encoding, the version must be version;104 or later.
jconfig line
The jconfig line is used to identify Java compiler options -- the Java version and classpath. Every javac unit name referred to in the build specification must be described in a jconfig line. Each javac unit name referred to in the build specification must be described in a jconfig line only once.
Example jconfig line:
jconfig;COMPILE_UNIT_1;-classpath;C:\Program Files\Java\jdk1.5.0_06\jre\lib\rt.jar;-source;1.5
The fields are:
| Field | Description |
| jconfig tag | tag for jconfig lines |
| compilation unit | Java compilation unit name (for example, COMPILE_UNIT_1 in the sample file) |
| options | a list of separated compiler options listing the source version and classpath (for example, -classpath%3BC:\Program Files\Java\jdk1.5.0_06\jre\lib\rt.jar%3B-source%3B1.4) The options are separated by "%3B". In a build specification, the %3B characters replace the following separators: colon ":" for Unix, or semicolon ";" for Windows. |
jcompile line
Each jcompile line is used to describe a source file of the compilation unit identified in the preceding jconfig line.
Example jcompile line:
jcompile;COMPILE_UNIT_1;D:\Klocwork\sources\jcolor\src\com\klocwork\util\jcolor\ColorConsolePrintStream.java
The fields are:
| Field | Description |
| jcompile tag | tag for jcompile lines |
| compilation unit | Java compilation unit name (for example, COMPILE_UNIT_1 in the sample file) |
| source file | full path name of the source file (for example, D:\Klocwork\sources\jcolor\src\com\klocwork\util\ jcolor\ColorConsolePrintStream.java) |
Format of the build specification file for .jsp files
The Klocwork build specification for .jsp files is a semi-colon-separated text file generated by kwwebappscan containing the following information:
- optional application server settings, identified in jspconfig lines
- the web applications to analyze, identified in jspcompile lines
This information is repeated for each web application in the project. For example:
version;105
jspconfig;config1;appserver.name=tomcat_6_0;appserver.location=d:\test\tomcat_6.0.14
jspcompile;config1;D:\test\webgoat.war.unpacked
The first field of each line is a tag to identify the type of line. The possible tags are as follows:
| Tag | Description |
| version | build specification format version |
| jspconfig | optional application server settings |
| jspcompile | the web applications to analyze |
version line
The version line is used to define the build specification format version. It must be the first line in the build specification. Only one version line may appear in a build specification.
Example version line:
version;105
Version 1.4 or later indicates that the build specification was generated using a source encoding of UTF-8, allowing multibyte characters (for example, Japanese). To ensure that kwbuildproject processes the build specification with UTF-8 encoding, the version must be version;104 or later.
jspconfig line
The jspconfig line is used to identify a non-default application server. If no application server was specified in the kwwebappscan command line, the jspconfig line will look like this:
jspconfig;config1
Example jspconfig line where a non-default application server was specified in the kwwebappscan command line:
jspconfig;config1;appserver.name=tomcat_6_0;appserver.location=d:\test\tomcat_6.0.14
The fields are:
| Field | Description |
| jspconfig tag | tag for jspconfig lines |
| configuration | name assigned to this configuration |
| options | application server settings (name and location) |
jspcompile line
Each jspcompile line is used to point to one web application.
Example jspcompile line:
jspcompile;config1;D:\test\webgoat.war.unpacked
The fields are:
| Field | Description |
| jspcompile tag | tag for jspcompile lines |
| configuration | name assigned to this configuration |
| web application | path to web application |
Format of the build specification file for C# projects
The Klocwork build specification for C# projects, named <input-file>.out by default, is a text file in semicolon-separated format.
The build specification is divided into compilation units, each containing a "cscompile" and "csconfig" line. Each of these compilation units has a unique identifier of the form CS<number>, for example, CS1, CS2, etc.
The first field is a tag to identify the type of line. The possible tags are as follows:
| Tag | Description |
| version | build specification format version |
| csconfig | user compiler configuration |
| cscompile | used to track compiler execution |
version line
The version line is used to define the build specification format version. It must be the first line in the build specification. Only one version line may appear in a build specification.
Example version line:
version;105
The three-digit integer is used to encode the version. The first (left-most) digit encodes the major version ("1" in above example); the last two digits encode the minor version ("05" in above example, resulting in the "1.5" full version code).
csconfig line
The csconfig line is used to record the configuration used by the native compiler.
Example csconfig line (truncated):
csconfig;CS2;D:\WBFSManager\trunk\libwbfsNET;/define:DEBUG,TRACE;/reference:C:\Windows\Microsoft.NET\Framework\v2.0.50727\System.dll,...C:\Windows\Microsoft.NET\Framework\v2.0.50727\System.Xml.dll
The fields are:
| Field | Description |
| "csconfig" tag | tag for config lines |
| compilation ID | unique identifier for the compilation unit, used to bind a csconfig line with a cscompile line (for example, CS2) |
| source project directory | path to the directory containing the C# project (for example, D:\WBFSManager\trunk\libwbfsNET) |
| compiler options | a list of semicolon-separated options for the Klocwork Truepath™ C# analysis engine (for example, /define:DEBUG,TRACE) |
cscompile line
cscompile lines are used to track compiler execution.
Example cscompile line:
cscompile;CS2;bin\Debug\libwbfsNET.dll;WbfsIntermWrapper.cs;Properties\AssemblyInfo.cs
The fields are:
| Field | Description |
| "cscompile" tag | tag for compilation lines |
| compilation ID | unique identifier for the compilation unit, used to bind a csconfig line with a cscompile line (for example, CS2) |
| DLL or exe | path to DLL or executable (bin\Debug\libwbfsNET.dll in the above example) |
| source files | semicolon-separated list of source files in the project (for example, WbfsIntermWrapper.cs;Properties\AssemblyInfo.cs) |