BUILDLOG2HTML

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
USAGE
EXAMPLES
FILES
SEE ALSO

Nokia nmake 16 BUILDLOG2HTML(1)

NAME

buildlog2html − transform XML build logs to HTML

SYNOPSIS

buildlog2html [ −b basedir ] [ −d build-designator ] [ −i ] [ −s sdir ] [ −t text-buildlog ] [ −x ] [ −q ] [ −h ]

buildlog2html [ −c ] [ −g ] [ −n index-file-name ] [ −v name:value ] [ −q ] [ −h ] build-log-dir ...

DESCRIPTION

buildlog2html transforms XML structured build logs to HTML and other formats to provide enhanced build log visualization, navigation, summarization, and analysis. XML structured build logs are created using xmakelog(1). In the following description, the term build directory refers to the directory where a build is performed, and the term build log directory refers to the directory containing the set of generated HTML files for a build log.

There are 2 command forms. The first form sets up a build log directory and by default transforms the XML structured build log to HTML in that directory. The default name of the created build log directory is derived from values for build attributes project (project name) and build (build id) as specified to the xmakelog(1) command using −−info options and stored in the XML build log.

The second form of this command transforms a sequence of already existing build log directories. Each build log directory must contain an XML formatted build log and should contain a regular textual log. The pre-existing build log directories are typically set up using the first form of buildlog2html with the −x option. If a build log directory already contains an index.html file, the directory is deemed up-to-date and transformation of that directory is skipped.

By default, the second form also creates, in the current directory, HTML and XML indices of all specified build logs. The ordering of entries in the index follows command line order. If a build log index is created, the build log directories must all be specified as relative paths.

OPTIONS

Options for first command form:
−b
basedir

Location of new build log parent directory. Default: current directory.

−d build-designator

Build designator to use for name of new subdirectory. Default: project-id_build-id_build-host.

−i

Suppress copy of default versions of icon.gif and buildlog.css into the parent of the new build log directory.

−s sdir

Directory containing build results to process: makelog.xml, text logs. See −t option for more on text logs. Default: current directory.

−t textlog

Name or relative path identifying textual build log. Default: makelog.txt, buildlog.txt, or nohup.out, whichever is found first.

−x

Suppress the transformation, just set up the directory. Default: run the transformation.

Options for second command form:

−c

Suppress build log index creation. Default: create index.

−g

Suppress HTML generation in individual build log directories. Default: Generate HTML.

−n index-file-name

Name of HTML and XML build log index files generated in current directory. For example, specifying weekly45 would result in generation of weekly45.html, weekly45.xml. Default: index.html and build_index.xml.

−v name:value

Specify name-value pair providing information relating to the generated index. Any number of −v options may be specified provided they have differing names. By convention, names title, subtitle, and htitle specify index page title, subtitle, and HTML title. Name/value pairs having other names are not currently displayed by the HTML index, however all name/value pairs are stored in the build index XML file so are available for use.

Common options for both command forms:

−q

Run quietly. Suppress execution trace.

−h

Print help message

USAGE

The build designator specified with the optional −d option should uniquely identify the build since it becomes the name of the build log directory. If −d is not specified, the default is project-id_build-id_build-host where project-id and build-id are as specified using −−info options to the xmakelog(1) command and stored in the XML build log. If no value was provided for build id, build date/time is used as default. There is no default for project-id.

Use −x to just set up the build log directory and skip the log transformation step. In this case the build log transformation step could be performed at a later time, and possibly on another machine, using the second form of this command. When using −x, an optimization is possible by also specifying the build log directory name using −d. This bypasses the XML analysis step which would otherwise be needed to obtain values used to generate the default build log directory name, thus avoiding the need to parse a possibly large XML file.

Files buildlog.css and icon.gif in the parent of the constructed build log directory define the web page styling and the page icon used during HTML display. By default, buildlog.css and icon.gif are copied into the parent of the constructed build log directory from default versions supplied by nmake, and are automatically updated whenever buildlog2html detects that the default version changed (e.g. possibly after updating to a new release of nmake). Alternate versions for the css and icon files may be specified by setting environment variables BUILDLOG_CSS and TITLE_ICON to file paths of the alternate files. Use the −i option to suppress copying of these files entirely.

EXAMPLES

cd builddir
xmakelog --info project:myproj --info build:mybld \
  --info generic:mygen -k install 2>&1 | tee makelog.txt
buildlog2html

This example runs a build in directory builddir using xmakelog(1). buildlog2html will then create a new build log directory as a subdirectory of the current directory with default name of form myproj_mybld_myhost. It will then transform the build log with output directed to that new subdirectory. The HTML result may be viewed by opening index.html in a browser. The default values for myproj and mybld used in the generated directory name are derived from values for the project and build attributes specified to xmakelog using −−info options and stored in the XML build log.

cd builddir
xmakelog --info project:myproj --info build:mybld \
  --info generic:mygen -k install 2>&1 | tee makelog.txt
buildlog2html -b $WEB/buildlog -d myproj_mybld_myhost -x

Run a build using xmakelog(1) creating makelog.xml and buildlog.txt in the build directory builddir. Then run buildlog2html to create a build log directory under $WEB/buildlog but do not run a transformation. Build log directory $WEB/buildlog/myproj_mybld_myhost will be created. Specifying −d eliminates the need to analyze the XML file to obtain values needed to generate the default build log directory name.

cd $WEB/buildlog
buildlog2html myproj_*_myhost

Transform build log directories created as in the previous example, then generate a build index in the current directory listing all specified builds. View the generated index by opening index.html in a browser. This step could be run at a later time or on a machine other than the build machine.

FILES

makelog.xml

Input XML build log file.

makelog.txt

Input plain text build log file.

buildlog.css

HTML style sheet for generated HTML. By default, this file is copied to the parent of the build log directory to allow sharing among multiple build log directories.

icon.gif

Icon for generated page headers. By default, this file is copied to the parent of the build log directory to allow sharing among multiple build log directories.

index.html

Default name of generated multi-build HTML index.

build_index.xml

Default name of generated multi-build XML index.

SEE ALSO

xmakelog(1)
Structured Build Logs
nmake User’s Guide
nmake Reference Manual
nmake Web Site


nmake 16 June 2014 BUILDLOG2HTML(1)