Nokia

Nokia nmake Product Builder

 

Nokia nmake Product Builder
nmake 12 Release Notes

Table of Contents

Released: July 2010

1. Introduction
1.1 Supported Hardware
1.2 Hardware Requirements
1.3 Software Requirements
1.4 Customer Support

2. New Features and Significant Enhancements
2.1 Capture of Triggered Target Explain Data
2.2 New Variable Edit Operators to Access Explain Data
2.3 Long --name Style Options
2.4 New --version Command Line Option

3. Bug Fixes and Enhancements
3.1 Baserules
3.2 cpp
3.3 Engine
3.4 Operators
3.5 Probe
3.6 Build Log
3.7 Miscellaneous
3.8 Variables
3.9 Options

4. Changes Impacting nmake 11 Makefiles

5. Known Problems and Remarks
5.1 Known Problems
5.2 Remarks


1. Introduction

This document announces the new release of nmake version 12. nmake is fully supported and is in wide production use throughout Alcatel-Lucent, AT&T, and elsewhere.

These nmake 12 Release Notes discuss in detail the new features, and highlight bug fixes, additional enhancements, and known problems.

1.1 Supported Hardware

The nmake 12 release has been ported to many UNIX-based and UNIX-like systems. For a current list see the Download Chart on the nmake web site, http://www.bell-labs.com/project/nmake/. Or contact the Customer Support helpdesk below.

1.2 Hardware Requirements

1.3 Software Requirements

The nmake 12 release is available for HP-UX, Linux, Solaris, AIX, and Windows (under SFU/Interix). See the nmake 12 download page for a listing of available distribution packages. nmake is generally upward compatible with later OS releases in a series (for example, the series Solaris 2.5 through 2.10); contact Technical Support with any compatibility questions or requests for porting to other systems.

The Windows-based version of nmake is based on the Windows Services for UNIX (SFU/Interix) porting/development environment from Microsoft and requires installation of the SFU package in order to run. The SFU package must be obtained from Microsoft and installed following their installation procedure. For more information see the Support for Windows page.

nmake 12 provides dependency-based Java build support. This feature currently requires an external Java source scanner called JavaDeps to extract inter-modules dependencies from Java source. nmake 12 requires JavaDeps release lu2.2.4 or greater. The latest version is downloadable from the nmake JavaDeps page. Installation instructions are also on that page. THIS PACKAGE IS ONLY REQUIRED BY PROJECTS PERFORMING JAVA BUILDS USING THE :JAVA: ASSERTION OPERATOR. JavaDeps release lu2.2.4 is itself written in Java; it requires jdk1.2.1 or higher version on its PATH in order to run. (Note that this does not restrict the project being built to jdk1.2.1 or higher.)

The buildlog2html command requires Java runtime 1.5 or above. It will also use Graphviz dot and neato commands, if available, to generate diagrams showing build log structure. Graphviz versions 2.16 or above are known to work. buildlog2html generates an HTML log from a structured build log.

1.4 Customer Support

We provide patch support, where code changes are required, for the latest 2 point releases of nmake (currently releases nmake 12 and 11). Customers using older releases can still acquire help in using the product, but genuine problems found in older releases will not be fixed. Such problems may require an upgrade to a current release or, when possible, a makefile work-around will be provided.

Fee-based services are also available. These include makefile rewrites, conversion of non-nmake makefiles to nmake, integration with vendor tools, build assessments, and porting nmake to new machines.

Contact Customer Support for any questions regarding nmake.


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.

[example 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.

edit operator description
$(VAR:T=QE) Query the Explain Message. Returns the explain message, if it has been set, for each token in a useful presentation format, otherwise returns null. Typically the explain message is set for targets that have been triggered.
$(VAR:T=QEU) Query the Unformatted Explain Data. Returns the raw explain data, if it has been set, for each token, otherwise returns null. Same as QE but the message is returned in a compact fielded format allowing easy extraction of data using standard nmake tokenization operations.
$(VAR:F=%(explain)S) Formats the raw explain data in a useful presentation format.

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.

short option long option description
-d level --debug=level Provide debug trace output at the specified level.
-e --explain Print explanation for actions taken.
-f makefile --file=makefile Read the specified makefile or state file.
-F --force Force all active targets to be out of date.
-g makefile --global=makefile Read the specified global makefile.
-k --keepgoing Continue working if the shell action for the current target returns an error.
-j level --jobs=level Execute up to level concurrent jobs.

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

3. Bug Fixes and Enhancements

3.1 Baserules

  1. 090009 - force_shared does not relink app in library makefile
    In some cases when a shared library was made with the :LIBRARY: operator and linked to an executable in the same makefile, using force_shared=1 did not relink the executable when the shared library was updated. This is fixed so the executable is relinked as expected.
  2. 090028 - include file triggers ccxopt rule
    A C/C++ file included with a prefix of cc+*, cc-*, cca+* or cca-* (eg. "cc++/file.h") no longer triggers the common action to compile in a sub-directory with the specified compiler flags.

3.2 cpp

  1. No changes to cpp in this release.

3.3 Engine

  1. 020013 - add command line option to show version
    Long command line options are now supported using the existing option names preceded by -- (dash dash). The --version command line option is now supported to print the version string and exit.
    For details see - New Features and Enhancements: Long --name Style Options and New --version Command Line Option
  2. 030110 - CC.REQUIRE infinite loop
    nmake no longer goes into an infinite loop when a library requires itself more than once using the CC.REQUIRE feature. For example, CC.REQUIRE.abc = -labc -labc would cause an infinite loop when -labc was specified as a prerequisite library.
  3. 040064 - jobs=[null] compiled into .mo
    When an option that take a numeric value, such as the jobs option, was both specified on the command line and set in the makefile a null value for the option would be compiled into the nmake object file (.mo) causing warnings and incorrect option settings on subsequent builds. This has been fixed so the value specified in the makefile is correctly compiled into the nmake object file.
  4. 070008 - custom archive rule does not get .o files in vpath
    Archive targets with custom shell actions would not pick up .o files in the viewpath when a copy of the archive was in the current node. This has been fixed so .o files are now picked up from the viewpath.
  5. 070040 - retrieve explain info from state file
    "Explain" data is now recorded in the state file describing why certain actions were taken during the build. Explanations for triggered targets can be retrieved after a build is complete to provide enhanced build diagnostics. New edit operators can be used to access the explain data during a build.
    For details see - New Features and Enhancements: Capture of Triggered Target Explain Data and New Variable Edit Operators to Access Explain Data
  6. 080026 - aix .ACTIONWRAP breaks archive scan
    nmake is now able to scan archive libraries on AIX platforms when .ACTIONWRAP is enabled, such as when using nmakelog for output serialization.
  7. 090022 - error message appearing before makelog element
    A problem was fixed where makefile warnings could appear outside of <makelog> elements in a structured build log. The problem was seen primarily on Interix platforms.
  8. 990047 - .ENTRIES fails to identify archive libs on AIX
    The .ENTRIES attribute now works as expected on AIX platforms. Support for AIX big format archives has been added so nmake can internally recognise and scan all AIX archive libraries.

3.4 Operators

  1. 090018 - jar support on aix 4.3
    Fixed an issue where :JAR: failed to archive members when the local find command did not support the -follow option. It now works with find commands that support -L, -follow or neither.
  2. 090020 - jar 1.1.x gets zero size jar file
    The :JAR: operator no longer creates a zero sized jar file when no members are found when using JDK 1.1.x, except when all the members are removed in an update.
  3. 090039 - scanning class files causes java rebuilds
    The :JAVA: operator was fixed so it no longer needlessly recompiles java source files when the .SCAN.java scan rule is applied to class files.
  4. 100010 - java clobber with no source files causes error
    The :JAVA: operator no longer exits with an error when the clobber common action is used with no java source code present.

3.5 Probe

  1. No changes to probe in this release.

3.6 Build Log

  1. 090019 - multi-build index should use build-name
    The "Build" column of the multi-build index generated by buildlog2html now uses the build-name from the --info build:... option when specified instead of the compressed build id.
  2. 090024 - old version of neato hangs buildlog2html
    The buildlog2html command now checks the version of Graphviz (dot, neato commands) and Java to avoid and report compatibility issues. Environment variables GVVER and JAVAVER allow the user to override required minimum versions in the format of major.minor or set to 0 to skip the version check.
  3. 100002 - capture explain data in structured build log
    "Explain" data is now captured by default in the structured build log by xmakelog. The makelog_format variable was updated to allow specification of explain message capture in structured build logs.
    For details see - New Features and Enhancements: Capture of Triggered Target Explain Data
  4. 100003 - structured build log feature documentation
    Complete documentation for the structured build log feature is available from the Structured Build Logs page on. the nmake web site.
  5. 100005 - extend buildlog2html for explain data
    "Explain" data is now presented in the HTML log generated by buildlog2html in the triggered target's attribute table.
    For details see - New Features and Enhancements: Capture of Triggered Target Explain Data
  6. 100006 - update build log user document for 100002
    The structured build log user document has been fully updated with details for capturing and handling the explain data. The user document can be found on the Structured Build Logs.
  7. 100012 - upgrade to latest version of Saxon-B
    The version of Saxon-B included in the nmake distribution package has been upgraded to version 9.1.0.8. Saxon-B is a XSLT and XQuery processor used by buildlog2html.
  8. 100013 - improve buildlog2html java command handling
    Improvements have been made to the way buildlog2html detects and executes the java command. It now uses java.exe on Interix platforms. The exptools search locations is user configurable with the JAVA_EXPTOOLS_SEARCH environment variable. The default exptools search no longer includes j2sdk1.4 since it requires special configuration. The environment variable JAVA_PATH_SEARCH has been introduced to configure the PATH search.

3.7 Miscellaneous

  1. 060066 - bug in string separator handling
    This was not a bug but was behaving as documented because newlines are treated as separate tokens by variable edit operators. The documentation has been updated to better explain the behavior.
  2. 090026 - nmakelog man page references nmakelog_format
    The nmakelog man page incorrectly identified an environment variable as nmakelog_format. It has been corrected to makelog_format.
  3. 090035 - add nmake version and release date to man pages
    The man pages now show the nmake version and release date.

3.8 Variables

  1. New variable GVVER - see 090024.
  2. New variable JAVAVER - see 090024.
  3. Change to variable makelog_format - see 100002.
  4. New variable JAVA_EXPTOOLS_SEARCH - see 100013.
  5. New variable JAVA_PATH_SEARCH - see 100013.

3.9 Options

  1. New option --explainlog - see 070040.
  2. New option --version - see 020013.

4. Changes Impacting nmake 11 Makefiles

The changes in nmake 12 are largely backward compatible with nmake 11. Every effort has been made to insure code changes do not unexpectedly change the documented behavior of nmake features. For makefiles that conform to nmake's documentation there will be no makefile updates necessary to migrate from nmake 11 based release to nmake 12.


5. Known Problems and Remarks

5.1 Known Problems

The following is a list of known problems:

  1. 980009 - problem in link=*
    The problem about using linking (specified using the link variable) to install targets in any adjacent nodes in viewpathing still exists. You may still use linking to install, but only in alternate nodes -- installation using copying must alternate with installation using linking. The problem occurs with both symbolic and hard linking.
  2. 030042 - :cc: generated header rebuild
    If a C file is built by using :cc: and this C file shares a generated header file with a C++ file specified in the same makefile, the generated header file may get regenerated during the build causing the source files to keep recompiling. This can be avoided by building the C++ files before the C files, or by generating the header file in a separate makefile at an earlier time during the build.
  3. 990099 - metarules not searched when CC.REPOSITORY is set
    The metarules may not be searched under the following conditions: there is a user defined metarule for a non-compiled file, variable CC.REPOSITORY is defined and CC.DIALECT contains either PTRIMPLICIT or PTRMKDIR, and :: is used to trigger the metarule. Note that CC.REPOSITORY and CC.DIALECT are defined as such in the probe file for some C++ compilers. The work-around is to add .IMPLICIT to the :: assertion, or to not use the :: assertion (such as add the target to :ALL: instead.)
  4. 020018 - adding shared lib building in same makefile won't re-link
    An executable target will not be re-linked when a shared library that is built in the same makefile is added as a prerequisite to the executable. The work-around is to set force_shared=1.
  5. 020051 - first metarule is used by mistake
    When multiple metarules generate the same source file target, such as %.c, the first metarule defined matching an existing file will be triggered instead of the metarule matching the explicit file prerequisite.
  6. 070010 - fails to bind large files
    nmake does not have large file support and cannot reference files over 2 GiB in size.

5.2 Remarks

  1. :LINK: does not handle archive files that are generated by :: or :LIBRARY: assertion operators. Users should avoid use of :LINK: on archive files.
  2. When the cpp -I-S flag is on, -D-M is disabled. Users should not use these two flags together.
  3. Users should avoid including the same header file with both <...>-style and "..."-style #include statements in source files managed by a single makefile. nmake will assign .STD.INCLUDE and .LCL.INCLUDE attributes to the header file, and this can result in incorrect -I lists in the compiler command lines generated.
  4. When the SHELL environment variable points to ksh93 you may get the following warnings when building your shell scripts: warning: line 1: `...` obsolete, use $(...). The warning is generated running your script with ksh -n. To eliminate the warning either update your shell scripts as indicated by the message or set SHELL to another version of ksh that does not generate the warning, such as ksh88.
  5. The Solaris 10 ksh initializes PWD to the full, physical path with no symbolic links. When running nmake somewhere under a symbolic link make sure the nmake ksh is in the PATH first to avoid viewpathing problems caused by the Solaris ksh PWD.

Last Update: Friday,12-Aug-2016 12:24:58 EDT