Appendix C. Using the Compiler Monitor

The imagix-cc-monitor utility monitors non-system processes and records compiler invocations. By running it as you compile your code, you can generate a logfile to use in the Extract from Build Log approach of loading your code into Imagix 4D.

imagix-cc-monitor is a command line executable. Your installation of Imagix 4D contains both a Windows version and a Linux version of the executable, in the ../imagix/bin directory.

If you are compiling your code on a different machine from where you are running Imagix 4D, copy the appropriate executable over to the compile machine, and run it there. Then bring the resultant logfile back to where you are running Imagix 4D, and use it to load in your source code. If imagix-cc-monitor and Imagix 4D are run on different machines and especially if they are under different operating systems, it is likely that you will need to adjust paths using the Directory Mapping substitution, as described in the Extract from Build Log instructions.

Invoking imagix-cc-monitor

The imagix-cc-monitor utility needs to be invoked with at least the -cc option and the name of the compiler executable (compiler_name) to watch for.
imagix-cc-monitor -cc compiler_name

Permissions are an issue in running the utility. In order to monitor the compile processes, imagix-cc-monitor should be run as the same user that is running the compile. Running the utility as administrator or root is another possibility, but less preferable because the utility then spends time monitoring system processes that are not relevant.


-cc compiler_name   Specify compiler(s) to watch for

Multiple compiler names can be watched for, by specifying an additional -cc compiler_name option for each compiler name. So if your software build invoked three compilers, gcc, g++ and cl, the invocation command would look something like:

imagix-cc-monitor -cc gcc.exe -cc g++.exe -cc cl.exe -log c:\test\buildlog

-log output_file   Specify a logfile for recording compiler invocations

Each compiler invocation identified during the current run will be recorded in output_file. If output_file existed previously, it will be overwritten. If the -log option is not specified, compiler invocation data will be written to stdout, where it can be redirected into a file.

-cmdfileflag flag   Specify the command file identifier

Certain compilers support the use of command files for extending the arguments passed in. For example, with the Microsoft Visual C++ compiler, the token @c:\some\path\filename.tmp in the compiler invocation causes the command file c:\some\path\filename.tmp to be read and its contents to be appended to the other arguments in the invocation.

imagix-cc-monitor supports this compiler feature by reading the same command file and recording its contents. In the example above, the flag would be "@", which is also the default value if -cmdfileflag is not specified.

Duration options
When you invoke imagix-cc-monitor, it starts to sample compiler activity, eventually timing out after no activity has occurred for a specified period. In most environments, the default duration settings for the monitor are appropriate and the options can be omitted. However, there can be exceptions.

For example, if you have a particularly fast machine, information about specific files being compiled may come and go between sample points, resulting in the files not being recorded in the logfile. To avoid this, you would specify a shorter sample interval.

Another exception could occur if your build contains time-consuming activities where something other than compiles occur, leaving long gaps between the compile commands. Changing the run_count would prevent the monitor from prematurely timing out.

If necessary, you can change the durations through the following options.

-initialwaitdelay_countSpecify how many cycles to wait for compiler activity to begin
-runforrun_countSpecify how many cycles to monitor compiler activity
-intervalinterval_msecSpecify the sample interval (length of each cycle)

The -initialwait and -runfor settings are integer counts (with default values of -1 and -200 respectively). These combine with the -interval setting (default is 100) to form a duration:

delay_msec = delay_count * interval_msec
run_msec = run_count * interval_msec

The meaning of these durations depend on whether they are positive or negative:

<0<0wait indefinitely for first activity, then stop after no activity in abs(run_msec). this is the default
<0>=0wait indefinitely for first activity, then count down run_msec
>=0<0count down delay_msec, then stop after no activity in abs(run_msec)
>=0>=0count down delay_msec + run_msec

Linux Alternatives

Under Linux, the imagix-cc-monitor utility collects information about the compiler invocations by monitoring the contents of /proc/pid. The length of the process data recorded in /proc/pid is limited; in many default Linux configurations, invocations are truncated after 2000 characters. So if the compiler invocations that you're capturing are long, the logfiles generated by imagix-cc-monitor may lack critical data. In case this is an issue in your environment, two scripts provided in the Imagix 4D distribution support alternative approaches.

Both scripts use the same general approach. They temporarily take the place of your compiler, and record the invocation commands that are passed to them. imagix-cc-subst stops there. imagix-cc-wrapper, after recording the command, then passes the command on to whatever you have temporarily renamed your compiler.

More detail can be found within the scripts themselves, which are located in the ../imagix/bin directory.