Build trace file format

The build trace file is a log of your C/C++ build, an unfiltered execution trace, which can be processed by kwinject to generate a build specification. The build trace file is output in the JSON file format. The file contains:

• version and creator information
• the commands started in the build
• the command-line arguments and environment variables
• the current working directory in which the command was running

Root level fields

The top level of the JSON file contains basic information about the trace file, as well as the env object and one or more id objects (or event objects). Each top level object (version, creator, top-level env or id) must go on a single separate line. Version, creator, and env must be listed before the event(s). Below is an example of the root level of a typical JSON build trace file:

{"version":101} 
{"creator":"kwinject, version 10.1.1"}
{"env":{"LIBGL_DRIVERS":"/usr/lib/fglrx/dri:/usr/lib32/dri", "MAKEFLAGS": " --jobserver-fds=3"}}
{"id":26008,"parent_id":-1,"work_dir":"/space/zlib-1.2.8","executable":"/space/gcc-4.9.0/bin/gcc","args":["gcc","-D_LARGEFILE64_SOURCE=1","-DHAVE_HIDDEN","-c","crc32.c"],"env-diff":{"ANT_HOME":"/opt/apache-ant-1.7","COLORTERM":"gnome-terminal","JAVA_HOME":"/opt/sun-jdk-1.6","LANG":"en_US.UTF-8"}}
{"id":26008,"parent_id":-1,"work_dir":"/space/zlib-1.2.8","executable":"/space/gcc-4.9.0/bin/gcc","args":["gcc","-D_LARGEFILE64_SOURCE=1","-DHAVE_HIDDEN","-c","foo.c"],"env-diff":{"ANT_HOME":"/opt/apache-ant-1.7","COLORTERM":"gnome-terminal","JAVA_HOME":"/opt/sun-jdk-1.6","LANG":"en_US.UTF-8"}}
...
{"id":26008,"parent_id":-1,"work_dir":"/space/zlib-1.2.8","executable":"/space/gcc-4.9.0/bin/gcc","args":["gcc","-D_LARGEFILE64_SOURCE=1","-DHAVE_HIDDEN","-c","bar32.c"],"env-diff":{"ANT_HOME":"/opt/apache-ant-1.7","COLORTERM":"gnome-terminal","JAVA_HOME":"/opt/sun-jdk-1.6","LANG":"en_US.UTF-8"}}

The fields are:

Field	Description
version	the version of the build trace file. The version is calculated as a decimal. 101 (the current version) is equivalent to version 1.1. For example, 203 is equivalent to version 2.3.
creator	(optional) a string representing the name of the tool that created the trace file. For example, kwinject, or kwlogparser, or kwwrap.
env	an object containing environment variables. This represents all environment variables on the system, before the first process is executed.
id	one or more id objects used to capture system events. See below for more information.

The id (event) object

The id object contains information about actual system execution events that occur as part of your build. A new id object is created for each process and sub process that occur as part of your build.

The fields are:

Field	Description
id	the unique ID of the event.
parent_id	the ID of event that spawned this event. If not present, the top-level process is assumed to be the parent of this event.
work_dir	current working directory at execution time.
executable	full path to executable (for example, /usr/bin/gcc).
args	an array containing the command line arguments, including argv[0], which is usually the executable field.
env-diff	(optional) an object containing the list of changed environment variables in the current environment. This field contains the difference between the system level environment variables between parent and child process. New variables and changed values of existing variables are represented as is: "name" : "value". Removed variables are represented by null value.