Alcatel-Lucent nmake Product Builder

Explain Information

Historically nmake has supported the explain option to report reasons certain actions are taken during a build. The nmake 12 release introduced a new feature to capture the explain data to provide enhanced build diagnostics. This feature allows explain information to be retrieved from state files or structured build logs, even without enabling the explain option. This page collects the documentation related to the explain feature.

References

• Capture of Triggered Target Explain Data - nmake 12 release notes detailing the explain data in nmake state files and structured build logs and how to access it.
• Variable Edit Operators - nmake 12 release notes detailing the variable edit operators used for accessing and formatting explain data.
• Captured Explain Data - Newsletter article showing how to dump explain data from a state file and use of the related variable edit operators.

explain.map

The explain data is stored in the state file and structured build logs in a compact coded form to save space and allow simple processing of the data. The coded data consists of one or more fields separated by spaces where the first field is an integer message code and the remaining fields are parameters for the specific message. The following example shows message 6 with a string parameter and two time stamp parameters.

6 include/hello.h 1301517547 1301348565

The file nmake_install_root/lib/make/explain.map contains a mapping of the message codes to message strings. Each line of the explain.map file contains two fields separated by a tab. The first field is the message number and second field the message string. The message string uses "%s" and "%t" to represent the coded message parameters, "%s" is a string parameter and "%t" a time stamp which is represented as the number of seconds from epoch in the coded data as shown above.

Here is the explain.map file from the nmake 12 release:

0	v1
1	%s action changed [#1]
2	%s action changed [#2]
3	%s action changed [#3]
4	%s action changed [#4]
5	%s [%t] binds to a different file
6	%s [%t] has changed [%t]
7	%s [%t] has changed in view %s
8	%s [%t] has no previous state
9	joint metarule target %s changed
10	%s view %s must be in view %s
11	%s inconsistent with view %s
12	%s named attributes changed
13	%s prerequisite %s added or re-ordered
14	%s prerequisite %s deleted or re-ordered
15	%s alias has changed to %s
16	state variable %s changed to '%s' from '%s'
17	state variable %s initialized to '%s'

Using the explain.map we can see the coded data, "6 include/hello.h 1301517547 1301348565" maps to the string, "%s [%t] has changed [%t]". The coded parameters are plugged into "%s" and "%t" in the order they appear. nmake formats the message as follows:

include/hello.h [Mar 30 16:39:07 2011] has changed [Mar 28 17:42:45 2011]

Message 0 in explain.map is reserved for the version of the map file, the above shows version 1 of the file. The version will change only when new messages are added, not necessarily with each new nmake release. The explain.map versions are upward compatible so scripts processing explain data may use later versions of the file. Starting with nmake 13 structured build logs specify the explain.map version used for generating the log in the emapver element.