Alcatel-Lucent nmake Product Builder

Release Notes -- Alcatel-Lucent nmake 12

July 2010
[Table of Contents] [Previous Section] [Next Section]

2. New Features and Significant Enhancements

2.1 Capture of Triggered Target Explain Data

This new feature provides enhanced build diagnostics by capturing the reason each target is triggered for an update. "Explain" data is recorded in the state files and structured build logs to provide reasons describing why certain actions were taken during the build as seen in output when using the explain (-e) option. Explanations can be retrieved after a build is complete whether or not the explain option was used and are associated with the triggered target to give more meaning than the standard explain option. Accessing the explain data for a completed build provides useful diagnostics, such as determining the cause of unexpected rebuilds, without manually tracing dependencies or reproducing the build which can be time consuming and error prone.

The feature is controlled by the new explainlog option. By default the option is enabled and explain data is recorded in the state file. Use the --noexplainlog form to disable the feature and exclude the data from the state file. Note that disabling the feature does not affect the structured build logs nor the new variable edit operators (see New Variable Edit Operators to Access Explain Data), it only affects the state files.

State Files

To dump the explain information from a state file use the list (-l) and explain (-e) options and specify the state file with the file (-f) option. In the following example a header file changed causing the object and executable to be updated.

$ nmake -lef Makefile.ms

/* Explain */

hello :
  include/hello.h [Jun 10 10:58:36 2010] has changed [Jun 10 10:42:23 2010]

hello.o :
  include/hello.h [Jun 10 10:58:36 2010] has changed [Jun 10 10:42:23 2010]

Structured Build Logs

Explain data is captured by default in structured build logs created using the xmakelog command. Capture of explain data is controlled by the makelog_format variable. See the Structured Build Logs Overview for more information about the handling of explain data in structured build logs. HTML build logs generated from the structured logs by buildlog2html include the reason in the target's attribute table. The following figure shows the above hello.o target in the HTML log.

Notes

1. Only one reason per target is recorded in the state file. In cases where multiple prerequisites changed or a target is triggered multiple times only one explanation is saved in the state file for the target.
2. The structured build log collects explain data at target trigger time, so for targets triggering multiple times it may capture a different reason for each trigger event.
3. The initial build may contain explanations that are not meaningful since there was no previous state information and everything is built. The explanations are most useful for incremental builds.
4. A build with everything up-to-date such that nothing is rebuilt will have no explain data in the state file.
5. Explain data is presented in a compact, fielded format to preserve space and allow easy extraction of data. The file lib/make/explain.map is included in the nmake distribution to show the mapping of numeric codes to the corresponding message and parameter fields, where %s indicates a string field and %t a time stamp field.
6. In some cases a target may be updated with no corresponding explain data. We are working to identify and correct these issues.

2.2 New Variable Edit Operators to Access Explain Data

Three new variable edit operators are available to access and format explain data during a build.

The following simple example shows the output from the three edit operators. In this example a header was touched causing the target to update. Notice the :F=%(explain)S operator formats the coded string from :T=QEU.

$ cat Makefile
CC = gcc
TARGETS = hello
.SOURCE.h : include
hello :: hello.c

.DONE : .MAKE
        print :T=QE          - $(TARGETS:T=QE)
        print :T=QEU         - $(TARGETS:T=QEU)
        print :F=%(explain)S - $(TARGETS:T=QEU:F=%(explain)S)

$ nmake
+ gcc -O -Iinclude -I- -c hello.c
+ gcc -O -o hello hello.o
:T=QE          - include/hello.h [Jun 11 14:07:13 2010] has changed [Jun 11 14:06:04 2010]
:T=QEU         - "6 include/hello.h 1276279633 1276279564"
:F=%(explain)S - include/hello.h [Jun 11 14:07:13 2010] has changed [Jun 11 14:06:04 2010]

The next example shows how to use for-loops to access each field of the unformatted explain data from multiple targets. Note that the file lib/make/explain.map in the nmake distribution can be used to map the first field code number to the corresponding message.

$ cat Makefile                 
CC = gcc
TARGETS = hello aloha
.SOURCE.h : include
:ALL:
hello :: hello.c
aloha :: aloha.c

.DONE : .MAKE
        local msg field
        for msg $(TARGETS:T=QEU)
                print msg: $(msg)
                for field $(msg)
                        print fld: $(field)
                end
        end


$ nmake
+ gcc -O -Iinclude -I- -c hello.c
+ gcc -O -o hello hello.o
+ gcc -O -I- -c aloha.c
+ gcc -O -o aloha aloha.o
msg: 6 include/hello.h 1276281965 1276281904
fld: 6
fld: include/hello.h
fld: 1276281965
fld: 1276281904
msg: 6 aloha.c 1276281965 1276281904
fld: 6
fld: aloha.c
fld: 1276281965
fld: 1276281904

2.3 Long --name Style Options

Long command line options are now supported. Long options use the existing option names preceded by -- (dash dash) and take the form --[no]name[=value], where name is the option name, value is an additional parameter used by some options, and no negates the option. The table below shows the long form of some of the more common options. For a full list of options see the nmake(1) man page or Reference Manual.

2.4 New --version Command Line Option

The --version command line option is now supported to print the version string and exit. There is no short option form.

$ nmake --version
Alcatel-Lucent (Bell Labs) nmake 12 06/09/2010

[Table of Contents] [Previous Section] [Next Section]