Support for structured build logs has been refined and extended making the feature more robust. The enhancements include the following:
--infoflag. For example, the generic can be specified as:
makelog_formatmechanism has been enhanced to allow easier addition of user-defined target attributes. Attributes can access information at Makefile level (such as
$(<)) and shell level (such as
xmakelogwill produce an XML log file ready for processing with buildlog2html. The
makelog_formatvariable need not be defined.
For more details see the xmakelog(1) man page.
A new experimental command called buildlog2html is included in the nmake package. The command takes a structured build log output by xmakelog and creates browsable HTML build log to provide enhanced visualization, navigation, summarization, and analysis. The HTML build log provides the following:
To get started first run a build using xmakelog instead of nmake
or nmakelog. Use the xmakelog
--info flag to set
name:value pairs to record and display additional information in the logs.
Any number of user-defined
--info arguments may be provided.
If 'build' is defined it is used as the build id in the HTML log, if it is
not defined then a reasonable default is used.
$ xmakelog --info project:MYPROJ --info build:20090619 --info generic:proj1.0 \ > makelog.txt $ ls -l makelog* -rw-r--r-- 1 richb richb 60 Jun 19 13:41 makelog.txt -rw-r--r-- 1 richb richb 1941 Jun 19 13:41 makelog.xml
The buildlog2html command can now be used to generate the HTML log.
The command has two forms, the first sets up a build log directory and
copies the XML and text logs to the directory. The second form runs the
transformation and generates the HTML. This allows the transformation step
to be run on a different machine, for example a web server instead of the
build machine. The transformation requires Java 1.5 or greater in the PATH.
neato commands from the
graphiz package are picked up in the PATH they will be used to create
graphical views. Graphiz version 2.18 is known to work.
For details on usage see the
buildlog2html(1) man page.
To set up the new build log directory use the
-x flag to
suppress the transformation so it can be run later, possibly on another
machine. Specify the log root directory with the
This directory will contain a subdirectory for each build log and should be
accessible by your web server. If the
-d flag is provided
it sets the name of the build log directory created under the log root.
-d is not provided then a default is used, however including
-d gives an optimization by skipping the need to run a Java
application to parse the XML to determine the default and also allows this
step to run on a machine that may not have Java 1.5 or greater available.
$ buildlog2html -x -b /www/bldlogs -d bld20090619 + cp -p makelog.xml /www/bldlogs/bld20090619/buildlog.xml + cp -p makelog.txt /www/bldlogs/bld20090619/buildlog.txt + cp -p /tools/nmake/sparc5/11/lib/builddata/buildlog.css /www/bldlogs/buildlog.css + cp -p /tools/nmake/sparc5/11/lib/builddata/icon.gif /www/bldlogs/icon.gif
Now the HTML can be generated. If running on another machine then go to
the build log root directory that was specified above with the
flag. Then run buildlog2html with the build log directory to process
on the command line. Multiple directories can be specified to bring them
all up to date. A top-level index.html is created in the current directory
that provides links to all the build logs under the directory. The index is
updated when new build log directories are added and processed. After the
transformation completes load the top index.html in your web browser.
$ cd /www/bldlogs $ buildlog2html bld20090619 + java -cp /tools/nmake/sparc5/11/lib/builddata/saxon9.jar net.sf.saxon.Transfor m -s:bld20090619/buildlog.xml -xsl:/tools/nmake/sparc5/11/lib/builddata/buildlog .xsl -t logname=bld20090619 Saxon 126.96.36.199J from Saxonica Java version 1.5.0 Stylesheet compilation time: 9235 milliseconds Processing file:/home/richb/mrs/090016/bld20090619/buildlog.xml ... [ output deleted ] ... $ ls -l *.html -rw-r--r-- 1 richb richb 2101 Jun 19 14:37 index.html $ ls -l bld20090619/ total 120 -rw-r--r-- 1 richb richb 8175 Jun 19 14:25 build_summary.html -rw-r--r-- 1 richb richb 3440 Jun 19 14:25 build_summary.xml -rw-r--r-- 1 richb richb 60 Jun 19 13:41 buildlog.txt -rw-r--r-- 1 richb richb 1941 Jun 19 13:41 buildlog.xml -rw-r--r-- 1 richb richb 334 Jun 19 14:25 graph1.dot -rw-r--r-- 1 richb richb 1894 Jun 19 14:25 graph1.html -rw-r--r-- 1 richb richb 214 Jun 19 14:25 graph1.map -rw-r--r-- 1 richb richb 1952 Jun 19 14:25 graph1.png -rw-r--r-- 1 richb richb 925 Jun 19 14:25 graph1_expanded.dot -rw-r--r-- 1 richb richb 2190 Jun 19 14:25 graph1_expanded.html -rw-r--r-- 1 richb richb 483 Jun 19 14:25 graph1_expanded.map -rw-r--r-- 1 richb richb 3936 Jun 19 14:25 graph1_expanded.png -rw-r--r-- 1 richb richb 334 Jun 19 14:25 graph2.dot -rw-r--r-- 1 richb richb 1895 Jun 19 14:25 graph2.html -rw-r--r-- 1 richb richb 215 Jun 19 14:25 graph2.map -rw-r--r-- 1 richb richb 2223 Jun 19 14:25 graph2.png -rw-r--r-- 1 richb richb 925 Jun 19 14:25 graph2_expanded.dot -rw-r--r-- 1 richb richb 2193 Jun 19 14:25 graph2_expanded.html -rw-r--r-- 1 richb richb 486 Jun 19 14:25 graph2_expanded.map -rw-r--r-- 1 richb richb 4646 Jun 19 14:25 graph2_expanded.png -rw-r--r-- 1 richb richb 1810 Jun 19 14:25 index.html -rw-r--r-- 1 richb richb 1810 Jun 19 14:25 list.html -rw-r--r-- 1 richb richb 2125 Jun 19 14:25 list_expanded.html -rw-r--r-- 1 richb richb 4443 Jun 19 14:25 makefile_1.html -rw-r--r-- 1 richb richb 6575 Jun 19 14:25 makefile_1_1.html -rw-r--r-- 1 richb richb 2828 Jun 19 14:25 table.html -rw-r--r-- 1 richb richb 3763 Jun 19 14:25 table_expanded.html
The results of example transformations are shown in the screenshots below. They were generated from typical recursive builds consisting of 15 Makefiles and 458 leaf (non-recursive) targets. Build errors, shown in red, were deliberately included to show how they are handled. Click any of the screenshots below to jump to the full example.
[ Note 2010-07-31: See the Build Log page for more recent examples and documentation. ]
The following enhancements were made to the
operator when making a shared library without disabling the library
.slfile name. The
.no, .to and
.oofiles and links have been eliminated.
.sllink is removed it will be relinked in the next build update. Previously the links would not be regenerated in an incremental build.
.oldappended to the file name. This is consistent with other installed targets. Previously they were renamed with
preservevariables are now respected to modify the install behavior of shared libraries where they were previously ignored.
clobber=1will not save the
preservecan be used back up old files to an
preservebase rules variable is now null. It was previously set to a pattern to match versioned shared libraries for ETXTBSY backup. However the versioned libraries had a custom install action that didn't use the variable so it had no affect. The change will keep the behavior consistent and not interfere with user defined values.
The time format output from the
operator now supports a time zone format that compiles with conventions
defined by the World Wide Web Consortium. This is useful for XML element
attributes containing date and time information for processing with other
tools that support the same conventions.
The following format fields are affected:
Previously %z was documented as the time zone type but the field did not function properly and expanded null. Time zone type has been fixed and moved to the %q field. The new %z and %:z fields return the time zone offset in hours and minutes and are consistent with other date commands.
A new command called astutil is included in the nmake package. astutil provides an interface to various libast routines to make features available outside of nmake. Currently it supports the date formatting features to provide a generic date command and a new xsdate command to format the date and time as an XML Schema datatype. Other features may be added later. The xsdate output is used to provide timing information for the new XML build log format.
The first argument to astutil is the internal command to execute. The currently supported commands are date and xsdate. Usage is as follows.
$ astutil --help Usage: astutil --help|command [opts] Interface to miscellaneous libast routines. --help display this help text. Valid commands: xsdate [-s|-S] [-z|-Z] [dateTime|date|time] dateTime current date/time formatted as an XML Schema dateTime (default). date current date formatted as an XML Schema date. time current time formatted as an XML Schema time. -z include time zone. -Z remove time zone. -s include fractions of a second. -S remove fractions of a second. date [+FORMAT] current time in specified format.
The xsdate command outputs the current date and time formatted as an XML Schema datatype. To run the xsdate command run astutil xsdate. By default the date followed by the time (with fractional seconds) and time zone offset are output.
$ astutil xsdate 2009-06-18T15:08:05.243420056-04:00
To print only the date or time specify the
$ astutil xsdate date 2009-06-18 $ astutil xsdate time 15:14:20
-z option adds the time zone if it isn't output by
-Z (upper case) removes the time zone.
-s to add fractional seconds and
-S (upper case) to remove fractional seconds.
$ astutil xsdate 2009-06-18T15:21:49.296742333-04:00 $ astutil xsdate -S 2009-06-18T15:21:53-04:00 $ astutil xsdate -S -Z 2009-06-18T15:22:07 $ astutil xsdate time 15:22:41 $ astutil xsdate -s time 15:22:45.455652203 $ astutil xsdate -s -z time 15:22:52.928145097-04:00
The date command acts as a generic date command and accepts optional date format fields.
$ astutil date Thu Jun 18 15:36:33 EDT 2009 $ astutil date "+%Y-%m-%d %T %:z" 2009-06-18 15:36:36 -04:00
For more details on usage see the astutil(1) man page.