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
option. This page collects the documentation related to the explain feature.
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