admin/SSCLI-sscli_20021101
1
0
Fork 0
mirror of https://github.com/SSCLI/sscli_20021101 synced 2026-06-08 12:28:57 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
SSCLI-sscli_20021101/docs/buildtools/buildutility.html
T
yallie 9fa3874800 Added the contents of the archive. 
Moved the original file to the archive subfolder.
2017-11-20 16:11:42 +03:00

1710 lines
73 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Build Utility (build.exe)</title>
<link rel="stylesheet" type="text/css" href="../rotor.css">
</head>
<body>
<h1>Build Utility (build.exe/build)</h1>
<p>Contents:</p>
<ul>
<li><a href="#Overview">Overview</a></li>
<li><a href="#Usage">Usage</a></li>
<li><a href="#Features">Features</a></li>
<li><a href="#SpecialFiles">Special Files</a></li>
<li><a href="#EnvironmentVariables">Environment Variables</a></li>
<li><a href="#MacroDefinitions">Macro Definitions</a></li>
<li><a href="#OptionalMacros">Optional Macros</a></li>
<li><a href="#Multi-processorBuildIssues">Multiprocessor Build Issues</a></li>
<li><a href="#SpecifyingLibraries">Specifying Libraries</a></li>
<li><a href="#PrecompiledHeaders">Precompiled Headers</a></li>
</ul>
<h4><a name="Overview"></a>Overview</h4>
<p>The build utility is the core of the Shared Source CLI (SSCLI) build process.&nbsp; It is also
included
with the Microsoft&reg; Windows&reg; Device Driver Development Kit (DDK). You can find
additional documentation by searching for &quot;build utility&quot; on <a href="http://msdn.microsoft.com/">
msdn.microsoft.com</a>.</p>
<p>The application file for the build utility is named <code>build.exe</code> on Windows and
<code>build</code> on UNIX system-based platforms.</p>
<p>This tool is a driver that uses the Microsoft Program Maintenance Utility (nmake.exe) build tool.&nbsp;It is responsible for: </p>
<ol>
<li>Recursing down directories listed in <i>dirs</i> files.</li>
<li>Producing one binary output per directory.&nbsp; Sources files contain
instructions on how to produce a single binary output. This will be one of the
following:
<ul>
<li>An archive (.lib on Windows, .a on UNIX system-based platforms). </li>
<li>A static code library (.lib on both Win32 and on UNIX system-based
platforms). These are destined
to be linked together into shared libraries </li>
<li>A shared library (.dll on Windows, .so on most UNIX system-based
platforms, and .dylib on Mac&reg; OS X).</li>
<li>An executable (.exe on Win32, and no extension on UNIX system-based
platforms).</li>
</ul>
</li>
<li>Starting nmake and the other build tools, then parsing their output, to
produce the build*.log, build*.wrn, and build*.err log output files. </li>
</ol>
<p>The build utility, together with its core makefiles (in rotor/rotorenv/bin), provides a
separation of build environment (compiler flags for example) from the actual
description of the sources to be compiled, allowing for multiple target
platforms with minimal changes to the build system. It also provides
standardized error reporting, and a number of developer conveniences, such as
spreading compilation across multiple processors. </p>
<p>The build utility searches the dirs file for the macros DIRS and OPTIONAL_DIRS. It
then recurses to each directory listed where it might find another dirs file
(indicating more directories to recurse into) or a sources file (indicating
something needs to be built). If it finds a sources file, it looks for the macros SOURCES,
INCLUDES, TARGETNAME, and TARGETPATH. These are parsed to determine the
dependencies, the list of files to build, and the end result. Typically, this
information is then kept in a file called build.dat that the build utility will
create for future reference. Depending on the options you pass to the build
utility, it performs
the appropriate action and then calls a make program (For more information, see
BUILD_MAKE_PROGRAM) to build the component. There are files (makefil0 and
makefile.inc) that the build utility will recognize in special circumstances (for
instance, only on a clean build). When the entire directory tree is built, the
utility
terminates. </p>
<h4><a name="Usage"></a>Usage:</h4>
<blockquote>
<PRE>build [options] [~]<i>directories</i></PRE>
</blockquote>
<h4><a name="Features"></a>Features of the Build Utility</h4>
<p>The build utility:</p>
<ul>
<li>Automatically establishes file dependencies.</li>
<li>Provides tools to build products for multiple hardware platforms without
specifying any target-specific information.</li>
<li>Abstracts from the details of the various compilers and computer
architectures.</li>
<li>Is multiprocessor aware for speedier compilation.</li>
<li>Provides detailed information about the build process.</li>
<li>Provides feedback during compilation, including:
<ul>
<li>How much longer before the build will finish.</li>
<li>How many lines are compiling.</li>
<li>How fast lines are being compiled.</li>
<li>How many files will be linked.</li>
<li>How many targets will be created.</li>
</ul>
</li>
</ul>
<h4>Arguments</h4>
<table border=1 width="100%">
<TR VALIGN="top">
<TH width=30%>Argument</TH>
<TH width=70%>Description</TH>
</TR>
<tr>
<TD width=30% valign="top"><i>directories</i></TD>
<TD width=70% valign="top">Non-switch parameters specify additional source directories.&nbsp;
Specifying * builds all optional source directories.<p>Specifying the &quot;~&quot; (&quot;not&quot;) option
removes a directory from the default build.</TD>
</tr>
</table>
<h4>Options</h4>
<p>Options can be specified using either a dash ('-') or a slash ('/').</p>
<table border=1 width="100%">
<TR VALIGN="top">
<TH width=30%>Option</TH>
<TH width=70%>Description</TH>
</TR>
<tr>
<TD width=30% valign="top"><b>-?</b></TD>
<TD width=70% valign="top">Display usage message<p>When you use this tool on UNIX
system-based platforms, <b>/?</b> might expand to a filename. Instead either use the
<b>/help</b> option
variation, use <b>-?</b>, or enclose the <b>/?</b> option in quotes: &quot;<b>/?</b>&quot;.</TD>
</tr>
<TR VALIGN="top">
<TD width=30%><b>-#</b></TD>
<TD width=70%>Forces _objects.mac to be regenerated.</TD>
</TR>
<tr>
<TD width=30% valign="top"><b>-$</b></TD>
<TD width=70% valign="top">Displays the complete dependency tree hierarchically.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-0</b></TD>
<TD width=70% valign="top">Runs pass 0 generation only, with no compilation and
no linking.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-2</b></TD>
<TD width=70% valign="top">Performs only a two-pass build; does not run pass 0.
(Same as old <b>-Z.</b>)</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-3</b></TD>
<TD width=70% valign="top">Performs three passes, with no dependency checking or
scanning of source files. Same as <b>-Z</b>.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-a</b></TD>
<TD width=70% valign="top">Allows synchronized blocks and drains during link pass.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-b</b></TD>
<TD width=70% valign="top">Displays full error message text (does not truncate
messages).</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-B</b> <i>baseline</i></TD>
<TD width=70% valign="top">Checks the build failures against a baseline.&nbsp; If there is no
baseline, terminate the build on the first error.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-c</b></TD>
<TD width=70% valign="top">Deletes all object files.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-C</b></TD>
<TD width=70% valign="top">Deletes all .lib files only.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-d</b></TD>
<TD width=70% valign="top">Displays debug information.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-D</b></TD>
<TD width=70% valign="top">Checks dependencies before building.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-e</b></TD>
<TD width=70% valign="top">Generates build.log, build.wrn, and build.err files.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-E</b></TD>
<TD width=70% valign="top">Always keeps the .log, .wrn, and .err files (use with
<b>-z</b>).</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-f</b></TD>
<TD width=70% valign="top">Forces a rescan of all source and include files.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-F</b></TD>
<TD width=70% valign="top">Prints the full path when displaying errors or warnings to stdout.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-G</b></TD>
<TD width=70% valign="top">Enables target-specific dirs files if and only if one target
exists.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-i</b></TD>
<TD width=70% valign="top">Ignores extraneous dependency warning messages.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-I</b></TD>
<TD width=70% valign="top">Prevents display of thread index if this is a multiprocessor build.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-k</b></TD>
<TD width=70% valign="top">Prevents deletion of out-of-date targets.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-l</b></TD>
<TD width=70% valign="top">Links only, does not compile.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-L</b></TD>
<TD width=70% valign="top">Compiles only, does not perform a link phase.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-m</b></TD>
<TD width=70% valign="top">Runs build in the idle priority class.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-M</b> <i>n</i></TD>
<TD width=70% valign="top">Performs a multiprocessor build (for MP machines) where <i>n</i> is the
number of processors.&nbsp;
<p>If -M is not specified, <i>n </i>defaults to one processor.&nbsp; If -M is
specified but <i>n</i> is not, then <i>n </i>defaults to the number of processors
on the computer.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-o</b></TD>
<TD width=70% valign="top">Displays out-of-date files.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-O</b></TD>
<TD width=70% valign="top">Generates an obj[d]\_objects.mac file for current directory.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-P</b></TD>
<TD width=70% valign="top">Reports the elapsed time to build each directory.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-q</b></TD>
<TD width=70% valign="top">Queries only; does not run nmake.exe tool.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-r</b> <i>dirpath</i></TD>
<TD width=70% valign="top">Restarts a clean build at the specified directory path <i>dirpath.</i></TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-s</b></TD>
<TD width=70% valign="top">Displays a status line at the top of the display.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-S</b></TD>
<TD width=70% valign="top">Displays a status line with include file line counts.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-t</b></TD>
<TD width=70% valign="top">Displays the first level of the dependency tree.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-T</b></TD>
<TD width=70% valign="top">Displays the complete dependency tree.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-$</b></TD>
<TD width=70% valign="top">Displays the complete dependency tree hierarchically.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-u</b></TD>
<TD width=70% valign="top">Displays unused BUILD_OPTIONS.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-v</b></TD>
<TD width=70% valign="top">Enables include file version checking.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-w</b></TD>
<TD width=70% valign="top">Shows warnings on the screen.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-y</b></TD>
<TD width=70% valign="top">Shows the files scanned.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-z</b></TD>
<TD width=70% valign="top">Performs one pass with compilation and linking, but
no dependency checking or scanning of source files.
<p>&nbsp;</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-Z</b></TD>
<TD width=70% valign="top">Performs three passes, with no dependency checking or
scanning of source files.<p>Same as <b>-3.</b></TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-why</b></TD>
<TD width=70% valign="top">Lists reasons for building targets.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-386</b></TD>
<TD width=70% valign="top">Builds targets for the i386.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-x86</b></TD>
<TD width=70% valign="top">Builds targets for the i386 (same option as <b>-386</b>).</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-ia64</b></TD>
<TD width=70% valign="top">Builds targets for Itanium.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-dynamic</b> <i>machine</i></TD>
<TD width=70% valign="top">Builds targets for given <i>machine.</i></TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-x</b> <i>filename</i></TD>
<TD width=70% valign="top">Excludes include file, <i>filename,</i> from dependency checks.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-j</b> <i>filename</i></TD>
<TD width=70% valign="top">Uses <i>filename</i> as the name for log files.&nbsp; The
<b>-j</b> switch
changes the first field, so it produces filename.log, filename.wrn, and
filename.err. </TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-jpath</b> <i>pathname</i></TD>
<TD width=70% valign="top">Uses <i>pathname </i>as the path for log files instead of the
current directory.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-nmake</b> <i>arg</i></TD>
<TD width=70% valign="top">Provides the argument, <i>arg,</i> to pass to nmake.exe.</TD>
</tr>
<tr>
<TD width=30% valign="top"><b>-clean</b></TD>
<TD width=70% valign="top">Causes all existing binary built output to be erased
and rebuilt.</TD>
</tr>
</table>
<h4><a name="SpecialFiles"></a>Special Files</h4>
<table border=1 width="100%">
<TR VALIGN="top">
<TH width=30%>File name</TH>
<TH width=70% colspan="2">Description</TH>
</TR>
<tr>
<TD width=30% valign="top">build.dat</TD>
<TD width=70% colspan="2" valign="top">When you use the build utility, it looks for a sources
file and a dirs file. It processes the dependencies and builds a file called
build.dat. Build.dat is basically a dump from the build utility of what the dependency
graph looks like. </TD>
</tr>
<tr>
<TD width=30% rowspan="3" valign="top">dirs</TD>
<TD width=70% colspan="2" valign="top">You can instruct the build utility to recursively
build an entire source tree by using the dirs file. The dirs file resides in a
directory that contains subdirectories (that is, at the root of a source code
tree or subtree). Each subdirectory can be a source directory or another source
tree. Place a dirs file at the root of each source code subtree. Then go to the
leaf node in each source code subdirectory and specify the build products in a
sources file.
<p class="MsoNormal">You should define the following macros in your dirs file:</TD>
</tr>
<tr>
<TD width="35%" valign="top">DIRS</TD>
<TD width="35%" valign="top">This macro lists the directories that the build utility should
always go into. Specify a list of subdirectories to be built unconditionally.
Separate the entries in this list with spaces or tabs</TD>
</tr>
<tr>
<TD width="35%" valign="top">OPTIONAL_DIRS</TD>
<TD width="35%" valign="top">This macro lists the directories that the build utility does not
have to go into, and by default will not go into. Specify a list of
subdirectories to be built only if they are explicitly specified on the original
build command line.</TD>
</tr>
<tr>
<TD width=30% valign="top">makefile.def</TD>
<TD width=70% colspan="2" valign="top">The build utility makes use of a generic makefile
called makefile.def, which contains all the macro definitions that the sources
file uses. The build utility sets the appropriate header and library include paths, compiler
names and switches, and linker switches that are defined in makefile.def, and
invokes nmake.exe. </TD>
</tr>
<tr>
<TD width=30% valign="top">makefile.plt</TD>
<TD width=70% colspan="2" valign="top">The platform-specific information for the makefiles is
contained in makefile.plt. You can include makefile.plt in your own makefiles to
select the build target and set platform-specific variables.</TD>
</tr>
<tr>
<TD width=30% valign="top">sources </TD>
<TD width=70% colspan="2" valign="top">You describe build products in a file named <i>sources</i>
that resides in each source code subdirectory. The sources file contains a
series of macro definitions that are recognized by the build utility. </TD>
</tr>
</table>
<h4><a name="EnvironmentVariables"></a>Environment Variables</h4>
<table border=1 width="100%">
<TR VALIGN="top">
<TH width=30%>Environment variable</TH>
<TH width=70%>Description</TH>
</TR>
<tr>
<TD width=30% valign="top">BUILD_ALT_DIR</TD>
<TD width=70% valign="top">Use this to specify an alternate object directory name. It must be
ten characters or fewer and contain no spaces. The value is added to the end of
the .obj name and (if no -j switch is used for build.exe) the logfile name.<br>
If you do not set this, the default is nothing. Use this macro when you want to
build the same source in different console windows using different language,
optimizations, or debugging information.</TD>
</tr>
<tr>
<TD width=30% valign="top">BUILD_DEFAULT_TARGETS</TD>
<TD width=70% valign="top">Use this to specify the default target platform for which you are
building. Usually, you can just set it to the platform you are hosted on, such
as <i>build -x86</i></TD>
</tr>
<tr>
<TD width=30% valign="top">BUILD_DEFAULT</TD>
<TD width=70% valign="top">Use this to specify options to build. For example:<br>
&nbsp;<p>c:\&gt; build -eswM -nmake -i <br>
<br>
is equivalent to:<br>
<br>
c:\&gt; set BUILD_DEFAULT=-eswM -nmake -i<br>
c:\&gt; build</TD>
</tr>
<tr>
<TD width=30% valign="top">BUILD_MAKE_PROGRAM</TD>
<TD width=70% valign="top">Use this to specify the make program to execute. The default is
nmake.exe, which is the only make tool designed to build the SSCLI source
tree.</TD>
</tr>
<tr>
<TD width=30% valign="top">BUILD_OPTIONS</TD>
<TD width=70% valign="top">Use this to specify the OPTIONAL_DIRS to process. For example:
<p> <br>
// DIRS file:<br>
DIRS=dir1 dir2 dir3<br>
OPTIONAL_DIRS=OptDir1 OptDir2 OptDir3<br>
<br>
c:\&gt; build OptDir1 OptDir2 OptDir3<br>
<br>
is equivalent to:<br>
<br>
c:\&gt; set BUILD_OPTIONS=OptDir1 OptDir2 OptDir3<br>
c:\&gt; build</TD>
</tr>
</table>
<h4><a name="MacroDefinitions"></a>Macro Definitions</h4>
<p>Set the variables for most of the following macros in a sources file; a few
are set in your environment (for a list of these, see
<a href="#EnvironmentVariables">Environment Variables</a>). Except for DIRS and
OPTIONAL_DIRS, which are used by the build utility, these macros are all used by nmake.exe.
The build utility simply opens all the files, determines the dependencies, and
calsl nmake.exe. The other macros used in the build process are all used by
nmake. The following table lists the macro names, how they are used, and why you would want to
put them in your sources file.</p>
<table border=1 width="100%">
<TR VALIGN="top">
<TH width=30%>Macro</TH>
<TH width=70%>Description</TH>
</TR>
<tr>
<TD width=30% valign="top">INCLUDES</TD>
<TD width=70% valign="top">Use this macro in your sources file to indicate to the build
utility where to find the headers that you are including in your build. Specify
a list of the paths to be searched for include files during compilation.
Separate the entries in this list with a semicolon. Path names can be absolute
or relative. For example:<blockquote>
<p>INCLUDES=bunny;inc<br>
INCLUDES=.\<br>
INCLUDES=.\inc</p>
</blockquote>
<p>The build utility reads the INCLUDES
variable that you specify in your sources file to figure out where to find the
header files that you are including in your source code so it can build the
dependency tree.</p>
<p>Specify header files that do not exist but might be built as part of the build
process in USER_INCLUDES.</TD>
</tr>
<tr>
<TD width=30% valign="top">SOURCES</TD>
<TD width=70% valign="top">The SOURCES macro is the most important macro for the build
utility. You must have this macro in your sources file. The SOURCES macro
specifies which files are going to be compiled. The build utility will look at
these files and generate a dependency list. If any of those dependencies change,
the build utility will rebuild this source file.
<p>Use this macro to list your source filenames (except for the file containing
main. Include the filename extension and separate the entries in this list with
spaces or tabs. </TD>
</tr>
<tr>
<TD width=30% valign="top">TARGETLIBS</TD>
<TD width=70% valign="top">Use this macro to specify other libraries that you want
to link against when building your image. This macro should be the primary
method you use to specify the libraries or objects that you want to link against
to build your image.
<p><b>TARGETLIBS Paths</b><br>
Paths specified in TARGETLIBS must be absolute. Separate the entries in this
list with spaces or tabs. </p>
<p>For example: </p>
<blockquote>
<p>TARGETLIBS=$(SDK_LIB_PATH)\kernel32.lib \<br>
$(SDK_LIB_PATH)\advapi32.lib \<br>
$(SDK_LIB_PATH)\user32.lib \<br>
$(SDK_LIB_PATH)\spoolss.lib </p>
</blockquote>
<p>The TARGETLIBS path names must be defined in a special way. Because the build
utility can create build products for several hardware platforms, the
destination path for build products is constructed as follows: </p>
<blockquote>
<p>%TARGETPATH%\&lt;cpu_type&gt;\ </p>
</blockquote>
<p>where TARGETPATH is defined in the sources file, and cpu_type specifies the
platform for which the products were built. </p>
<p>For example, if TARGETPATH is defined as LIB and a build request is made for
an x86 processor, the build products will be directed to the following
subdirectory: </p>
<blockquote>
<p>lib\i386\ </p>
</blockquote>
<p>Because of this convention, TARGETLIBS entries must specify library names in
the following form: </p>
<blockquote>
<p>&lt;targetpath&gt;\*\&lt;library_name&gt; </p>
</blockquote>
<p>where targetpath is identical to the value assigned to TARGETPATH in the
sources file, and library_name is the full file name of the library to be linked
to the executable file. The build utility replaces the asterisk (*) with the
target platform type. </p>
<p><b>LINKLIBS and UMLIBS</b><br>
You can also use the LINKLIBS macro to specify the libraries that you need to
link against. This macro is needed for some DLL builds, but it must be used
carefully. For more information, see its reference page. </p>
<p>Use LINKLIBS only for the case that meets the following conditions:</p>
<ul>
<li>You are building a dynamic link.</li>
<li>You are exporting something that is defined in some other component
library that you also build.</li>
<li>In your dirs file in the subdirectory above, you have ordered it so
that the component libraries are built before you build the dynamic link.
</li>
</ul>
<p>There is a similar macro called UMLIBS that you can use if you are
building UMAPPLs.</TD>
</tr>
<tr>
<TD width=30% valign="top">TARGETEXT</TD>
<TD width=70% valign="top">Use this macro to specify the extension name (such as .cpl) when
you want the DLLs to have something other than .dll as the filename extension.<p>
If you specify something unexpected, you will see a message &quot;Unexpected Target
Ext.&quot; </TD>
</tr>
<tr>
<TD width=30% valign="top">TARGETNAME</TD>
<TD width=70% valign="top">Use this macro to specify the name of the library being built,
excluding the filename extension. You must have this macro in your sources file.</TD>
</tr>
<tr>
<TD width=30% valign="top">TARGETPATH</TD>
<TD width=70% valign="top">Use this macro to specify the target directory name that is the
destination of all build products ( such as .exe, .dll, and .lib files). Notice
that object files always end up in the obj subdirectory. You must have this
macro in your sources file. For example:<blockquote>
<p>TARGETPATH=obj</p>
</blockquote>
</TD>
</tr>
<tr>
<TD width=30% valign="top">TARGETTYPE</TD>
<TD width=70% valign="top">Use this macro to specify the type of product being
built. TARGETTYPE gives the build utility clues about some of the input files
that it should expect. You must include this macro in your sources file.The valid values for TARGETYPE include:<p>
PROGLIB - Executable program that also exports functions for other programs.</p>
<p>PROGRAM - User-mode program that does not export anything.</p>
<p>DYNLINK - Dynamic-link library (DLL). This could be a control panel program
or anything that can be dynamically loaded.&nbsp; The DLL switch is passed to the linker to indicate
it is not a stand-alone .exe file. When you build a dynamic link, you might also need
to set the TARGETEXT macro.</p>
<p>LIBRARY - Import library containing code that will be linked with other code.
This is a library of objects, not an import library. (An import library is built
as a side effect of building a dynamic link. Anytime you build a dynamic link,
you get a .lib file and a .dll file. When you build a library, you just get a
.lib file.)</TD>
</tr>
</table>
<h4><a name="OptionalMacros"></a>Optional Macros</h4>
<table border="1" width="100%">
<tr>
<TH width=30% valign="top">Macro</TH>
<TH width=70% valign="top">Description</TH>
</tr>
<tr>
<td width="33%" valign="top">BASEDIR</td>
<td width="67%" valign="top">Use this macro when referring to the base of the
source tree. By default, the source tree starts at $(_NTDRIVE)\nt, but this
is
not required. By using BASEDIR to refer to the base you eliminate
hard-coding a specific path.</td>
</tr>
<tr>
<td width="33%" valign="top">BINPLACE_FLAGS</td>
<td width="67%" valign="top">Use this macro to specify arguments that you want to pass to
the Build Output Manager. Type binplace-? to display a list of these switches. </td>
</tr>
<tr>
<td width="33%" valign="top">BINPLACE_PLACEFILE</td>
<td width="67%" valign="top">Use this macro to specify the placefile used by
the Build Output Manager. If
nothing is listed,
<blockquote>
<p>$(BASEDIR)\public\sdk\lib\placefil.txt </p>
</blockquote>
<p>is used by default. </p>
<p>For more information, see binplace.exe. </td>
</tr>
<tr>
<td width="33%" valign="top">C_DEFINES</td>
<td width="67%" valign="top">Use this macro to specify switches you want passed to the
compiler. Typically, they are compiler <b>#define</b> directives.<p>&nbsp;You might specify:</p>
<blockquote>
<p><br>
C_DEFINES = /DDEBUG_BUILD</p>
</blockquote>
<p><br>
to define DEBUG_BUILD to the compiler. There is no limit to what this #define
can be except that C_DEFINES gets passed to the compiler and it also gets
passed to the resource compiler. Therefore, you cannot put compiler
optimization or other processor-specific or tool-specific switches in the C_DEFINES
macro. Instead, use one of the following macros for this:</p>
<ul>
<li>MSC_OPTIMIZATION</li>
<li>MSC_WARNING_LEVEL</li>
<li>USER_C_FLAGS</li>
</ul>
</td>
</tr>
<tr>
<td width="33%" valign="top">COFFBASE</td>
<td width="67%" valign="top">Use this macro to specify the name to look up in
COFFBASE_TXT_FILE. If you do not specify a name, it defaults to the value of
TARGETNAME (if you are building a DYNLINK) or usermode (if you are building a
UMAPPL, PROGLIB, or PROGRAM). If you want to specify an absolute base
address for your image and not use a global file for all, see DLLBASE or
UMBASE. </td>
</tr>
<tr>
<td width="33%" valign="top">COFFBASE_TXT_FILE</td>
<td width="67%" valign="top">Use this macro to specify the name of the
file that contains the base addresses for the images you build. By default,
this is %ddkroot%\bin\coffbase.txt. If a different file is specified in this
macro, the contents of this file will be passed to the linker The file
should have three columns. The first is the name of the image. The second is
the starting address for the image. The last is the maximum size of the
image. There should also be an entry with the name &quot;usermode&quot; that is the
default value. For example:<blockquote>
<p>usermode 0x60000000 0x20000000<br>
MyDll1 0x70000000 0x00010000<br>
MyDll2 0x70010000 0x00010000</p>
</blockquote>
<p>The build utility assumes that coffbase.txt will be in \\public\sdk\lib
and will be called coffbase.txt. You can override this filename and call it
anything you want by using COFFBASE_TXT_FILE.</td>
</tr>
<tr>
<td width="33%" valign="top">COMPILER_WARNINGS</td>
<td width="67%" valign="top">Use this macro to specify the name of the
file that contains warning information. By default, this is
$(SDK_INC_PATH)\warning.h. If a different file is specified in this macro,
the name of this file will be passed to the compiler with the /FI switch.
The file contains a list of compiler options used to disable, enable, or
promote warnings for the entire build.</td>
</tr>
<tr>
<td width="33%" valign="top">CRT_INC_PATH</td>
<td width="67%" valign="top">Use this macro to specify the path to the C runtime headers. The default is
$(BASEDIR)\public\sdk\inc\crt.</td>
</tr>
<tr>
<td width="33%" valign="top">CRT_LIB_PATH</td>
<td width="67%" valign="top">Use this macro to specify the path to the C runtime
libraries. The default is $(BASEDIR)\public\sdk\lib\*</td>
</tr>
<tr>
<td width="33%" valign="top">DEBUG_CRTS</td>
<td width="67%" valign="top">Use this macro to specify which set of C runtime
libraries should be used.<blockquote>
<p>DEBUG_CRTS=1</p>
</blockquote>
</td>
</tr>
<tr>
<td width="33%" valign="top">DLLBASE</td>
<td width="67%" valign="top">Use this macro to set the base address for the DLL
image that you are creating. You only need to use this macro when you are
building a DLL (that is, when your TARGETTYPE macro is set to DYNLINK).
<p>You can override the default address by specifying an address with the
DLLBASE macro (for example, 0x04000000). You can set DLLBASE to be the
hard-coded base address or a hexadecimal address. </p>
<p>If DLLBASE is omitted or left blank, the build utility will assume that
the target name in coffbase.txt is the name of your image. It will take the
value of COFFBASE, if defined, as a key; otherwise, it will take TARGETNAME
as a key. The target name in coffbase.txt plus this key will be used to
choose the base address.</td>
</tr>
<tr>
<td width="33%" valign="top">DLLDEF</td>
<td width="67%" valign="top">Use this macro to specify the name of the .def file
that the build utility will pass to the librarian when building the export
and import files.
<p>If you do not set this value, the build utility will assume it is the
same name as the image you are building (in other words, equal to
$(TARGETNAME).def). </p>
<p>The most common usage is:</p>
<blockquote>
<p>DLLDEF=mydll.def</p>
</blockquote>
<p>Additionally, there is a standard inference rule that will run the C
preprocessor over the .def or .src file in the current directory to create
build-specific .def files in the object subdirectory. The same compiler
define directives that you key off of in your source code can be used in the
root .def or .src file to create the export list. To enable it, use
something like:</p>
<blockquote>
<p>DLLDEF=$O\mydll.def</p>
</blockquote>
</td>
</tr>
<tr>
<td width="33%" valign="top">DLLENTRY</td>
<td width="67%" valign="top">Use this macro to specify the DLL entry point. By
default, no entry point is assumed. For example, when you bring over
programs that were built in the Visual C++&reg; build environment or that use
the C runtime, you will probably set:<blockquote>
<p>DLLENTRY=_DllMainCRTStartup</p>
</blockquote>
</td>
</tr>
<tr>
<td width="33%" valign="top">DLLLIBOBJECTS</td>
<td width="67%" valign="top">Use the DLLLIBOBJECTS macro to specify extra objects to add
to an import library.
<p>Usually, when the TARGETTYPE is DYNLINK, the end result is a DLL and an
import library. If you want to have different LIB objects for each platform,
you can override this value to create different platform-specific DLL LIB
objects. DLLLIBOBJECTS enables you to specify additional objects to add to
the import library. </p>
<p>For example, you might have an OLE custom control (with GUIDs used to
identify this control) that also exports a non-OLE C interface from an
import library. Rather than build two separate libraries (for example,
mydll.lib and myuuid.lib), you can list the GUID data object(s) in
DLLLIBOBJECTS. The result is a single library that your users will link
against.</td>
</tr>
<tr>
<td width="33%" valign="top">DLLORDER</td>
<td width="67%" valign="top">Use the DLLORDER macro to specify an order file that will be
passed to the linker when you are building a DLL.<p>The order file lists the
functions and the order in which they should be linked together. By default,
the build utility passes the name of the DLL as the name of the order file.
For example, if you are building kernel32.dll, the build utility expects
kernel32.prf as the order file. </p>
<p>You can use the DLLORDER macro to specify another name. The build utility
will use whatever name you give it. It can be in a different subdirectory,
have a different name, or have a different extension. You can set DLLORDER to
whatever you want it to be, and you can give it a fully qualified path name.
</p>
<p>This macro can be used instead of NTPROFILEINPUT.</td>
</tr>
<tr>
<td width="33%" valign="top">DRIVERBASE</td>
<td width="67%" valign="top">Use this macro to specify the base address for a
driver. This macro is similar to the DLLBASE and UMBASE macros. It is not
generally necessary to set this value, because it will be relocated at run
time.</td>
</tr>
<tr>
<td width="33%" valign="top">FREEBUILD</td>
<td width="67%" valign="top">Use this macro to specify whether your build is
checked (debug) or free (retail). This macro can be used in statements of
the form:<blockquote>
<p>If $FREEBUILD <i>(do things for a retail build)</i></p>
</blockquote>
</td>
</tr>
<tr>
<td width="33%" valign="top">LANGUAGE</td>
<td width="67%" valign="top">Use this macro to specify the language when you set up
dependencies so that you can include country/region-specific parts in your build.</td>
</tr>
<tr>
<td width="33%" valign="top">LINKER_FLAGS</td>
<td width="67%" valign="top">Use this macro to override any default linker
switch that you want to pass to the linker. Type link-? to view a list of
all the linker switches. This macro just gives you a way to pass in flags
that you cannot pass in another way.</td>
</tr>
<tr>
<td width="33%" valign="top">LINKER_NOREF</td>
<td width="67%" valign="top">Use this macro to turn off switches to the linker. The build
utility turns some switches on, by default. One of them is the
OPTICAL_AND_REF switch, which says, &quot;Throw out everything that is not
referenced in this module.&quot; </td>
</tr>
<tr>
<td width="33%" valign="top">LINKLIBS</td>
<td width="67%" valign="top">
<p class="MsoNormal">Use this macro to specify the libraries that
you need to link against. <br>
<br>
The only difference between TARGETLIBS and LINKLIBS is the ordering on the
command line. LINKLIBS usually gets passed first; TARGETLIBS gets passed
second. If you order them correctly in your TARGETLIBS macro, that should
not be a problem, except when you are building a DLL.<br>
<br>
When you are building a DLL, you could be using objects that you have built
in combination with libraries from which you would like to export certain
features. For example, perhaps you compile a number of objects into a
library in subdirectory one. In subdirectory two, you compile other objects
into a library. And in subdirectory three, you build the DLL. However, this
DLL must export functions that are defined in library one or library two. In
such a case, you must put those libraries in your LINKLIBS macro.<br>
<br>
This operation must be carefully done. The LINKLIBS macro requires that the
library must be located in pass one of the build, because the build utility
builds the import libraries during pass one. You must structure your build
in such a manner that the libraries are guaranteed to exist during pass one.
You should never specify an import library in your LINKLIBS macro, primarily
because you could end up exporting something that you imported from somebody
else instead of what you actually had intended (perhaps with syntax errors or other
problems). Problems resulting from such a mishap can be undetectable for
some time.<br>
<br>
As a result, it is almost always better to use TARGETLIBS. Use LINKLIBS only
for cases that meet the following conditions:<ul>
<li>
<p class="MsoNormal">You are building a dynamic link. </li>
<li>
<p class="MsoNormal">You are exporting something that is defined in some
other component library that you also build. </li>
<li>
<p class="MsoNormal">In your dirs file in the previous subdirectory, you
have ordered it so that the component libraries are built before you build
the dynamic link. </li>
</ul>
<p class="MsoNormal">There is a similar macro called UMLIBS that you can use
if you are building UMAPPLs.<br>
&nbsp;</td>
</tr>
<tr>
<td width="33%" valign="top">MAKEDLL</td>
<td width="67%" valign="top">Use this macro to control whether any actual linking
occurs.<br>
<br>
Normally, the build process is a two-pass build. In the first pass, the
build utility compiles all the source files, and creates import libraries
and component libraries. In the second pass, it links everything against
those libraries. The default, which directs the build utility to make the
second pass, is as follows:<blockquote>
<p>MAKEDLL=1</p>
</blockquote>
<p>Typically, you do not set this value. You might do a test in your make
file to instruct the build utility:</p>
<blockquote>
<p>IF MAKEDLL=1<br>
<i>do things that you want to do on the second pass of the build</i></p>
</blockquote>
<p>A more frequent use of this macro is to run NMAKE from the command line
to run the compile and to link without running the build utility:</p>
<blockquote>
<p>nmake MAKEDLL=1</p>
</blockquote>
<p>The build utility will complete the compile operation and the link in one
step without running the build utility. This works because the build utility
is only required to determine the dependencies and call NMAKE. This method
works when:</p>
<ul>
<li>You know the dependencies.</li>
<li>The source file has changed and you do not care about the header file
dependency generation.</li>
<li>You are in a leaf node subdirectory. </li>
</ul>
</td>
</tr>
<tr>
<td width="33%" valign="top">MASTER_VERSION_FILE</td>
<td width="67%" valign="top">Use this macro to specify the file name
of a master version file.
<p>Every binary file created by the build utility has a version number on it.
These are usually based on version resources created by Microsoft when
products built for Windows&reg; NT-based operating systems are created. </p>
<p>You can use Windows Explorer or filever.exe to view properties and see
which version resource the Setup program uses when it copies that image onto
a new system. The system checks whether or not the version resource is newer
than the one already on the system. If the resource is newer it is copied onto
the system, otherwise it is not copied. </p>
<p>There is a master version file for Windows operating systems, from which
all version resources are built. The master version file for Windows operating systems is called ntverp and it is located in %ddkroot%\inc\wxp.
</p>
<p>If you do not wish to use the version specified in ntverp, you can
specify a different master version file by setting MASTER_VERSION_FILE to
the correct file name. </p>
<p>If you look at the very last line of makefile.def, you will see the one
place where MASTER_VERSION_FILE is used as a dependency for the resources.
The TARGET_DIRECTORY macro is always dependent on the master version file to
determine the name of the resource for your image. </td>
</tr>
<tr>
<td width="33%" valign="top">MISCFILES</td>
<td width="67%" valign="top">Use this macro to list items that you want to put
into the appropriate installation point when the build utility runs
binplace.exe. </td>
</tr>
<tr>
<td width="33%" valign="top">MSC_OPTIMIZATION</td>
<td width="67%" valign="top">Use this macro to override the default optimization the
build utility uses on the compiler. By default, everything is optimized. If
you want to turn off optimization to step through your code, you can set
MSC_OPTIMIZATION to whatever is appropriate for your compiler.</td>
</tr>
<tr>
<td width="33%" valign="top">MSC_WARNING_LEVEL</td>
<td width="67%" valign="top">Use this macro to set the warning level to use on the
compiler. The default is W3</td>
</tr>
<tr>
<td width="33%" valign="top">NOLINK</td>
<td width="67%" valign="top">The NOLINK and MAKEDLL macros are primarily used in the
master make file (makefile.def) to indicate which rules to enable or disable
when the build utility goes through two tools.
<p>NOLINK=1 indicates that a link is not supposed to occur, most likely
because this is pass one and the build utility cannot guarantee that the
libraries needed are built yet. </p>
<p>MAKEDLL=1 indicates that a link should occur and is used in pass two
after the libraries are built. If you run a one-pass build (by specifying -z
on the command line to the build utility), only MAKEDLL=1 is specified. </p>
<p>You can test for this macro in your make file. For example, if NOLINK=1,
you are in pass one; if MAKEDLL=1, you are in pass two. </td>
</tr>
<tr>
<td width="33%" valign="top">NT_UP</td>
<td width="67%" valign="top">Use this macro to indicate whether your driver will run on a
uniprocessor computer or multiprocessor computer. The default is uniprocessor,
as follows:<blockquote>
<p>NT_UP=1</p>
</blockquote>
<p>To specify multiprocessor, set:</p>
<blockquote>
<p>NT_UP=0</p>
</blockquote>
</td>
</tr>
<tr>
<td width="33%" valign="top">NTNOPCH</td>
<td width="67%" valign="top">Use this macro to turn off the precompiled headers
option for a single source file.
<p>If you have precompiled headers on a subdirectory, the build utility
expects you to build that subdirectory and to make subsequent changes as you
go along. Whenever you change one of the source files, you must rebuild that
file. The build utility detects the use of precompiled headers and compiles
that single source file without them. </p>
<p>If you set:</p>
<blockquote>
<p>NTNOPCH=1</p>
</blockquote>
<p>it enables you to build everything, and then to change a definition in
a header file (for example, a #define something to something else). Then you
can change the source file to use that new definition. Of course, you do not
want to regenerate the precompiled header and rebuild everything else; it is
preferable to rebuild that one source file, without using the old
precompiled header. This macro tells the build utility to turn off
precompiled headers for this source file. </p>
<p>The build utility will reread all the headers and use the new header
information. This also requires using the -Z or -z command-line options, so
that the build utility will not scan dependencies and therefore will not
regenerate the precompiled header. </td>
</tr>
<tr>
<td width="33%" valign="top">NTTARGETFILE0</td>
<td width="67%" valign="top">You can define the NTTARGETFILE0 and NTTARGETFILES macros
to cause makefile.def to include makefile.inc immediately after it specifies
the top-level targets (all, clean and loc) and their dependencies.
<p>The makefile.def file expands NTTARGETFILE0 as the first dependent for
the all target, and NTTARGETFILES as the last dependent for the all target.
Use this macro to specify additional targets and dependencies that do not
fit the general case covered by makefile.def. </p>
<blockquote>
<p>NTTARGETFILE0= </p>
</blockquote>
<p>The fact that NTTARGETFILE0 exists, even if it is defined and empty,
causes the build utility to open makefile.inc in the same subdirectory as
the sources file. </p>
<p>If you set NTTARGETFILE0 to equal a file name, the build utility will not
only include makefile.inc, but will also build the executable that the macro
defines. Thus, if you set: </p>
<blockquote>
<p>NTTARGETFILE0=myfile.a </p>
</blockquote>
<p>then the build utility builds myfile.a as part of pass zero. </p>
<p>If you do not set NTTARGETFILE0, the build utility locates the specified
subdirectory on pass zero, includes the makefile.inc in that subdirectory,
and follows any default rules that this file contains. </td>
</tr>
<tr>
<td width="33%" valign="top">NTTARGETFILE1</td>
<td width="67%" valign="top">This macro is exactly like NTTARGETFILE0,
except that it occurs later in the build process. NTTARGETFILE0 occurs on
pass zero; NTTARGETFILE1 occurs on pass two.
<p>Both of these macros cause the build utility to change directories to a
specified subdirectory and to run nmake.exe on pass zero or pass two in a case
where it ordinarily would not do so. </td>
</tr>
<tr>
<td width="33%" valign="top">NTTARGETFILES</td>
<td width="67%" valign="top">If you have unique rules in your subdirectory, you can use
the NTTARGETFILES macro to signal to the build utility that you have a
makefile.inc file in addition to the sources file in the subdirectory.
<p>The makefile.inc file will provide additional information about the build
process, including dependencies, command line rules, and other build rules. </td>
</tr>
<tr>
<td width="33%" valign="top">O </td>
<td width="67%" valign="top">Use this macro to specify the final objects subdirectory.
Define this macro in your sources file or in makefile.inc to ensure something goes into the object subdirectory. The benefit of using $(O) is
that any files that you have built and placed in the objects subdirectory
will be deleted on the next clean build. This guarantees that no collisions
will occur between two builds running on the same computer at the same time.
The builds will never override each other's files if you follow the convention
that everything you build goes in $(O).</td>
</tr>
<tr>
<td width="33%" valign="top">PASS0_CLIENTDIR</td>
<td width="67%" valign="top">Use the PASS0_CLIENTDIR, PASS0_HEADERDIR, and PASS0_SERVERDIR
macros when you have a SOURCES macro in your sources file. That
macro can contain the following types of files:
<ul>
<li>C </li>
<li>C++ </li>
<li>RC </li>
<li>MC </li>
<li>IDL </li>
</ul>
<p>Use the PASS0_CLIENTDIR, PASS0_HEADERDIR, and PASS0_SERVERDIR macros to
specify a directory location for the output from the MC and the Microsoft&reg;
IDL Compiler (MIDL). </p>
<p>If you run MIDL over sources that include interface description language
(IDL) files, the build utility generates a server part, a client part, a
header, and a default source. Use the PASS0_SERVERDIR and PASS0_CLIENTDIR
macros to specify their output location. </p>
<p>Running MC causes the generation of a header file and a source file.. Use
the PASS0_HEADERDIR and PASS0_SOURCEDIR macros to specify their output
location. </p>
<p>When you are building a MIDL stub, the protocol is remote procedure call
(RPC), so you have both what runs on the client side and what runs on the
server side. There are stub programs that communicate through RPC to each other. You can override those by default.</td>
</tr>
<tr>
<td width="33%" valign="top">PASS0_HEADERDIR</td>
<td width="67%" valign="top">Use this macro to specify the output location
of the headers generated by MC and the Microsoft IDL Compiler (MIDL). By
default, everything built in pass zero is output to the TARGETPATH
subdirectory. Use this macro to change that default.
<p>To create the headers in the current subdirectory, set PASS0_HEADERDIR to
dot (&quot;.&quot;): </p>
<blockquote>
<p>PASS0_HEADERDIR=. </p>
</blockquote>
<p>Headers can be output to any location. If your #include directives do not
specify the correct location, however, the tools later used by the build
utility will not be able to find the headers. </td>
</tr>
<tr>
<td width="33%" valign="top">PASS0_SERVERDIR</td>
<td width="67%" valign="top">Use this macro to specify an output location
for the server part that the Microsoft IDL Compiler (MIDL) generates. By
default, the results of pass zero are output to the TARGETPATH subdirectory.
Use this macro to change that default.
<p>To create the server part in the current subdirectory, set
PASS0_SERVERDIR to dot (&quot;.&quot;): </p>
<blockquote>
<p>PASS0_SERVERDIR=. </p>
</blockquote>
<p>Headers can be sent to any location. If your #include directives do not
specify the correct location, however, the tools later used by the build
utility will not be able to find the headers. </td>
</tr>
<tr>
<td width="33%" valign="top">PASS0_SOURCEDIR</td>
<td width="67%" valign="top">Use this macro to specify the sent location
for the source code generated by the Microsoft IDL Compiler (MIDL) and
maketype.lib file. By default, the results of pass zero are sent to the
TARGETPATH subdirectory. Use this macro to change that default.
<p>To create the source code generated by MIDL and maketype.lib in the
current subdirectory, set PASS0_SOURCEDIR to dot (&quot;.&quot;): </p>
<blockquote>
<p>PASS0_SOURCEDIR=. </p>
</blockquote>
<p>Your source code and maketype.lib file can be sent to any location. If
your #include directives do not specify the correct location, however, the
tools later used by the build utility will not be able to find the correct
files. </td>
</tr>
<tr>
<td width="33%" valign="top">PRECOMPILED_CXX</td>
<td width="67%" valign="top">Use this macro to indicate whether the
precompiled header you are building will be used with files written in C or
C++.
<p>The default is to use precompiled headers with files written in C.
Therefore, you should not set PRECOMPILED_CXX if your project will use the
precompiled header with files written in C. </p>
<p>To use the precompiled header with C++ files, specify </p>
<blockquote>
<p>PRECOMPILED_CXX=1 </p>
</blockquote>
</td>
</tr>
<tr>
<td width="33%" valign="top">PRECOMPILED_INCLUDE</td>
<td width="67%" valign="top">Use this macro to specify the name of the
precompiled header. For example, if you have precompiled headers that are
a.c, b.c, and c.c as your source files, and all of them include precomp.h,
specify:
<blockquote>
<p>PRECOMPILED_INCLUDE=precomp.h </p>
</blockquote>
<p>If you omit this instruction, you will not be able to use precompiled
headers. PRECOMPILED_INCLUDE sets the build process to use precompiled headers. </td>
</tr>
<tr>
<td width="33%" valign="top">PRECOMPILED_OBJ</td>
<td width="67%" valign="top">Use this macro to override the default name
given to the precompiled object.
<p>By default, the build utility takes the precompiled header with the
precompiled #include directive that you specify (for example, precomp.h).
The build utility generates precomp.obj for the precompiled object and
precomp.pch for the precompiled target. </p>
<p>You can override those names by setting the PRECOMPILED_OBJ and
PRECOMPILED_TARGET macros. </td>
</tr>
<tr>
<td width="33%" valign="top">PRECOMPILED_TARGET</td>
<td width="67%" valign="top">Use this macro to override the default name
given to the precompiled target.
<p>By default, the build utility uses the precompiled header with the
precompiled #include setting that you specify (for example, precomp.h). The
build utility uses the precompiled header to create precomp.obj for the
precompiled object and precomp.pch for the precompiled target. </p>
<p>You can override those names by setting the PRECOMPILED_OBJ and
PRECOMPILED_TARGET macros. </td>
</tr>
<tr>
<td width="33%" valign="top">SDK_INC_PATH</td>
<td width="67%" valign="top">Use this macro to specify the path to the SDK headers. The
default is:<blockquote>
<p>$(BASEDIR)\public\sdk\inc</p>
</blockquote>
</td>
</tr>
<tr>
<td width="33%" valign="top">SDK_LIB_PATH</td>
<td width="67%" valign="top">Use this macro to specify the path to the platform SDK libraries. The
default is:<blockquote>
<p>$(BASEDIR)\public\sdk\lib\*</p>
</blockquote>
</td>
</tr>
<tr>
<td width="33%" valign="top">SOURCES_USED</td>
<td width="67%" valign="top">Use this macro to indicate that there is another
sources file or make file elsewhere in the tree. Use this macro if that
additional file contains build dependencies.
<p>When you specify: </p>
<blockquote>
<p>SOURCES_USED=filename_someplace_else </p>
</blockquote>
<p>Nmake.exe regenerates the objects file when changes occur in the sources file
that resides in the specified directory. Nmake.exe will also regenerate the
objects file when changes occur in any sources file or make file that you
specified in the SOURCES_USED macro. </p>
<p>For example, a sources file typically includes some other file. Just
beneath that directive you could specify: </p>
<blockquote>
<p>SOURCES_USED=that_filename </p>
</blockquote>
<p>This instruction establishes a link between that file and the sources
file. When that other file changes, NMAKE regenerates the _objects.mac file. </td>
</tr>
<tr>
<td width="33%" valign="top">TARGET_CPP</td>
<td width="67%" valign="top">Use this macro to specify the name of the compiler.&nbsp;
<p>For example, instead of having to specify that on x86 the compiler is
CL386, on MIPS it is CLMIPS, and on PowerPC it is CLPPC, you can specify:</p>
<blockquote>
<p>TARGET_CPP=name_of_compiler</p>
</blockquote>
</td>
</tr>
<tr>
<td width="33%" valign="top">TARGET_DIRECTORY</td>
<td width="67%" valign="top">Use this macro as follows to specify the
target directory, if you want some dependency file to always end up in the
obj subdirectory:
<blockquote>
<p>TARGET_DIRECTORY=some_sourcefile:some_dependency_file </p>
</blockquote>
<p>This instruction enables you to draw upon resources contained in a single
source tree to complete multiple platform-specific builds without conflicts.
You do not have to hard-code the name of the platform. </p>
<p>For example, if you have a special build utility rule for some feature in
your code, or if you want to build a particular object from a particular C
file, you can use the following line in a sources file: </p>
<blockquote>
<p>obj\$(TARGET_DIRECTORY)\filename.obj; filename.c </p>
</blockquote>
<p>Using the TARGET_DIRECTORY macro ensures that the specified file will be
placed in the appropriate subdirectory. For example,
\obj\i386subdirectory\obj\. </p>
<p>There are some default targets. One of them is .cod. If you issue the
following instruction from a subdirectory containing source files: </p>
<blockquote>
<p>nmake SOURCE_FILE_NAME=.cod </p>
</blockquote>
<p>it will create an assembler listing that you can review to determine
the location of the compiler error. </p>
<p>There is another default target called .pp file, a preprocessed listing.
Preprocessing adds line numbers. You can use these line numbers to determine
whether the build utility retrieved headers from the correct location, and
which #define directives and structures it added. </p>
<p>If you issue the following instruction from a subdirectory containing
source files: </p>
<blockquote>
<p>nmake SOURCE_FILE_NAME=.pp </p>
</blockquote>
<p>the build utility will preprocess the file. </p>
<p>The .cod and .pp files are very useful for tracking bugs in the build
process. </td>
</tr>
<tr>
<td width="33%" valign="top">TARGETPATHLIB</td>
<td width="67%" valign="top">Use this macro to specify where to put the
import library when you are building a DLL.<p>When you are building a
DLL, you create the DLL itself and you create an import library that other
images can use that need to use your DLL. For example, a Windows NT
developer built kernel32.dll and also kernel32.lib which users of
kernel32.dll would link against. In the past you would handle all that by
specifying:</p>
<blockquote>
<p>TARGETPATH=publicsdk.lib</p>
</blockquote>
<p>and it would put both the DLL and the import library in the public tree.
By specifying TARGETPATHLIB, you can say, "Put the library in the public
tree." Then set TARGETPATH=obj and build uses the DLL in the obj
subdirectory in the source tree and put the import library in the public
tree.</td>
</tr>
<tr>
<TD width=30% valign="top">UMAPPL</TD>
<TD width=70% valign="top">This macro enables you to build multiple targets from a
single subdirectory. If you use UMAPPL, the build utility will automatically
build executable files. Listing the names of executables in the build utility
command line is unnecessary.<p>To use this macro, specify a list of source filenames containing a main
function. Specify these filenames without filename extensions and separate them
with an asterisk. For example:</p>
<blockquote>
<p>UMAPPL=a*b*c*d</p>
</blockquote>
<p>The build utility will compile and link each file in this list after the main
target in the sources file is built. The only restriction is that there can only
be one source file and you must specify what it links to using the UMLIBS
macro. </p>
<p>The build utility links against whatever things you list in the UMLIBS macro.
These could be a .res file if you have a common resource, a library that
you just built in a subdirectory, or a library or object from another subdirectory.
There is no limit to what can be listed in UMLIBS. </p>
</TD>
</tr>
<tr>
<TD width=30% valign="top">UMAPPLEXT</TD>
<TD width=70% valign="top">Use this macro to specify the file extensions for image
files built from a single source file. The default is .exe. Use UMAPPLEXT when
you want the extension to be something other than .exe. (for example, .com or
.scr). If you want the file extension to be .exe, use UMAPPL.</TD>
</tr>
<tr>
<td width="33%" valign="top">UMBASE</td>
<td width="67%" valign="top">Use this macro when you are building a
dynamic link library. Use it to set the base address for the image you are
creating. If you do not specify an address, the build utility will assume
that the target name in coffbase.txt is the name of your image. You can
override this default target name by specifying a target name with the
DLLBASE macro. You can set DLLBASE to be the hard-coded base address or a hexadecimal
address, or you can leave it blank. If you leave it blank, the build utility
will always look up the target name specified in coffbase.txt.
<p>For example, if you are building kernel32.dll, the build utility will look up
kernel32 in coffbase.txt to find that base address.</td>
</tr>
<tr>
<td width="33%" valign="top">UMENTRY</td>
<td width="67%" valign="top">Use this macro to override the default entry point
(mainCRTStartup) and specify the entry point depending on the UM Type. You
can set this name to be anything you choose. If the UM Type is Windows or
Console, the default entry point is main and you can override it with
winmain, wmain, or wwinmain.</td>
</tr>
<tr>
<td width="33%" valign="top">UMENTRYABS</td>
<td width="67%" valign="top">Use this macro to specify an absolute entry point. For
example, you might specify:<blockquote>
<p>UMENTRY=main</p>
</blockquote>
<p>However the real entry point is mainCRTStartup. If you do not want
mainCRTStartup to be the entry point, specify UMENTRYABS to make main the
absolute entry point. This prevents the build utility from going through the
translation table.</td>
</tr>
<tr>
<TD width=30% valign="top">UMLIBS</TD>
<TD width=70% valign="top">Use this macro to specify a list of library path names to be
linked to the files that are specified in UMTEST or in UMAPPL. Include the
library that is generated by the sources file.
<p>The specified paths must be absolute. Separate the entries in this list with
spaces or tabs.</p>
<p>The UMLIBS path names must be defined in a special way. Because the build
utility can create build products for several hardware platforms, the
destination path for build products is constructed as follows:</p>
<blockquote>
<p>%TARGETPATH%\&lt;cpu_type&gt;\</p>
</blockquote>
<p>where TARGETPATH is defined in the sources file, and cpu_type specifies the
platform for which the products were built. </p>
<p>For example, if TARGETPATH is defined as LIB and a build request is made for
an x86 processor, the build products will be directed to the following
subdirectory:</p>
<blockquote>
<p>lib\i386\</p>
</blockquote>
<p>Because of this convention, UMLIBS entries must specify library names in the
following form:</p>
<blockquote>
<p>&lt;targetpath&gt;\*\&lt;library_name&gt;</p>
</blockquote>
<p>where targetpath is identical to the value assigned to TARGETPATH in the
sources file, and library_name is the full file name of the library to be linked
to the executable file. The build utility replaces the asterisk (*) with the
target platform type.</TD>
</tr>
<tr>
<td width="33%" valign="top">UMTEST</td>
<td width="67%" valign="top">Use this macro to list source filenames containing a main
function. Type these filenames without filename extensions and separate them
with an asterisk.
<blockquote>
<p>UMTEST=a*b*c*d</p>
</blockquote>
<p>The build utility compiles and links each file in this list.</td>
</tr>
<tr>
<td width="33%" valign="top">UMTYPE</td>
<td width="67%" valign="top">Use this macro to specify the type of product being built</td>
</tr>
<tr>
<td width="33%" valign="top">USE_CRTDLL</td>
<td width="67%" valign="top">The USE_CRTDLL, USE_MSVCRT, USE_LIBCMT, USE_LIBCNTPR,
USE_NTDLL, and USE_NOLIBS macros indicate which run-time libraries the build
utility should use.
<p>You should define exactly one of these macros equal to one in your
sources file. The other ones should not be defined at all (you cannot
define them equal to zero or equal to &quot;&quot;). </p>
<p>The different libraries specified by these macros are as follows: </p>
<ul>
<li>USE_CRTDLL&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<ul>
<li>Use the multi-threaded run-time libraries in a DLL. In the free
build environment, this means msvcrt.lib. In the checked build
environment, this means msvcrtd.lib. </li>
</ul>
</li>
<li>USE_MSVCRT
<ul>
<li>Same as USE_CRTDLL.</li>
</ul>
</li>
<li>USE_LIBCMT
<ul>
<li>Use the multithreaded static libraries. </li>
</ul>
</li>
<li>USE_LIBCNTPR
<ul>
<li>Use the kernel run-time libraries. </li>
</ul>
</li>
<li>USE_NTDLL
<ul>
<li>Use ntdll.dll (the DLL for Windows NT-based operating systems). </li>
</ul>
</li>
<li>USE_NOLIBS
<ul>
<li>Do not use any run-time libraries.</li>
</ul>
</li>
</ul>
<p>If none of these macros are defined, the default behavior is to
statically link to the single-threaded run-time libraries. In the free build
environment, this means libc.lib. In the checked build environment, this
means libcd.lib.
</td>
</tr>
<tr>
<td width="33%" valign="top">USE_INCREMENTAL_LINKING</td>
<td width="67%" valign="top">Use this macro to direct the build
utility to use incremental linking.
<blockquote>
<p>USE_INCREMENTAL_LINKING=1 </p>
</blockquote>
<p>Using incremental linking can speed up builds on slower hardware. </td>
</tr>
<tr>
<td width="33%" valign="top">USE_NATIVE_EH</td>
<td width="67%" valign="top">Use this macro if you are using standard C++
exception handling (try, catch, and throw). Specify the following in your
sources file:
<blockquote>
<p>USE_NATIVE_EH=1 </p>
</blockquote>
<p>This instruction directs the build utility to turn on some required
compiler switches.</td>
</tr>
<tr>
<td width="33%" valign="top">USECXX_FLAG</td>
<td width="67%" valign="top">This macro enables you to go to a subdirectory
that has all C files and compile them with the C++ compiler rather than the
C compiler. (You might want to do this if you have decided to switch to
C++.)
<p>Rather than manually change all your file names to a.cpp, b.cpp, you can
specify: </p>
<blockquote>
<p>USECXX_FLAG=/Tp </p>
</blockquote>
<p>This switch directs the compiler to use the C++ compiler rather than the
C compiler to compile the specified subdirectory.</td>
</tr>
<tr>
<td width="33%" valign="top">USER_C_FLAGS</td>
<td width="67%" valign="top">Use the USER_C_FLAGS macro to specify flags that should only
be sent to the C/C++ compiler.
<p>Unlike C_DEFINES, USER_C_FLAGS is not sent to the RC compiler. </td>
</tr>
<tr>
<td width="33%" valign="top">USER_INCLUDES</td>
<td width="67%" valign="top">Use the USER_INCLUDES macro to specify header files that are
created during the build process.
<p>Normally, you use the INCLUDES macro in your sources file to indicate the
location of your build headers. </p>
<p>There are times, however, when this macro will not be useful because some
header files might not exist. For example, some header files are built as
part of the build process. </p>
<p>Use the USER_INCLUDES macro to specify header files that are created
during the build process. The build utility will search for these header
files, will not consider it an error if the files are not found and will not
perform dependency checking on them. </td>
</tr>
</table>
<h4><a name="Multi-processorBuildIssues"></a>Multiprocessor Build Issues</h4>
<p>When the build utility is run on a multiprocessor computer, different build
utility threads might be running on different processors. Therefore, you should be
careful that your products are built in the correct order. </p>
<p>The following macros can be used in your sources files to control the order
of the build: </p>
<ul>
<li>SYNCHRONIZE_BLOCK instructs the build utility to build a certain
subdirectory first. When the build utility finds this macro in a sources file,
will stop building all other directories until this directory is built. </li>
<li>SYNCHRONIZE_DRAIN instructs the build utility to build a certain
subdirectory last. A directory whose sources file contains this macro will not
be built until all other subdirectories have been built. </li>
</ul>
<p>Use SYNCHRONIZE_BLOCK when you have a subdirectory that other subdirectories
require the results from in order to build (for example, a global precompiled
header). List the precompiled directory first in the dirs file, and add
SYNCHRONIZE_BLOCK=1 to the sources file. This assures that the subsequent
directories that use the precompiled header will not be built until the header
is created. </p>
<p>Use SYNCHRONIZE_DRAIN when you have a subdirectory that needs the results
from a prior subdirectory on the same pass. For example, when building a DLL,
you might have several subdirectories with TARGETTYPE=LIBRARY, where each builds
some component. You might have another subdirectory with TARGETTYPE=DYNLINK, where
the build utility will build a DLL that exports functions from the component
libraries. In such a case, you should set LINKLIBS to the component libraries,
make sure the DLL subdirectory is the last in the parent dirs file, and add
SYNCHRONIZE_DRAIN=1 to the sources file for the DLL. </p>
<p><b>Misuse of These Macros</b><br>
You should use these macros very sparingly, because they completely stall a
multiprocessor build when they are encountered. In most cases, the problem is
not with the multiprocessor nature of the build, but rather the macros used in
the sources file. </p>
<p>A common mistake is using LINKLIBS to specify import libraries when building
a DLL. You rarely need to do this. LINKLIBS must exist during pass 1
because the libraries it specifies are used to build the import library for the
DLL. However, TARGETLIBS does not need to exist until pass 2, because the
libraries it specifies are only used to link the image. </p>
<p>Therefore, you should use LINKLIBS for component libraries only, and use
TARGETLIBS for import libraries. </p>
<h4><a name="SpecifyingLibraries"></a>Specifying Libraries</h4>
<p>Unlike some other environments that use the LIB environment variable, the
build utility always requires the full path. The purpose of this is to eliminate
any ambiguities in the build process. </p>
<p>For instance, some build processes rely on the linker to determine the
correct libraries by using paths stored in the LIB environment variable in
combination with a list of default libraries stored in the objects. However,
this approach has the inherent (and undesirable) side effect of making it
difficult to either know, or control, which libraries are used in your build
process. </p>
<p>On the other hand, the build utility requires that you specify the full path
to each library you use. It will disable any default library lookup that the
linker might attempt to use. Additionally, when specifying the libraries, you
should try to abstract any absolute dependencies that might exist in the path.
The build process provides an asterisk to take the place of the platform. You
can use the BASEDIR macro to take the place of the root of the source tree. You
can use DDK_LIB_PATH to refer to libraries that ship as part of the Windows DDK.
</p>
<p>Additionally, you should use an asterisk to indicate the target platform in
the path.&nbsp; For example, assume you are building a typical Windows .exe
file. Normally, this would require you to link against kernel32.lib, user32.lib,
gdi32.lib, and maybe your own component library, mylib.lib. The
TARGETLIBS macro would look like this: </p>
<blockquote>
<p>TARGETLIBS = \<br>
# Note: SDK_LIB_PATH already ends in &quot;\*&quot; so you should no include it when
using the macro.<br>
$(SDK_LIB_PATH)\kernel32.lib \<br>
$(SDK_LIB_PATH)\user32.lib \<br>
$(SDK_LIB_PATH)\gdi32.lib \<br>
..\mylib\obj\*\mylib.lib </p>
</blockquote>
<p>When building on x86, this would be equivalent to:</p>
<blockquote>
<p>TARGETLIBS = \<br>
$(BASEDIR)\lib\i386\kernel32.lib \<br>
$(BASEDIR)\lib\i386\user32.lib \<br>
$(BASEDIR)\lib\i386\gdi32.lib \<br>
..\mylib\obj\i386\mylib.lib </p>
</blockquote>
<p>To build a particular set of build products, switch to a directory that
contains either a dirs file or a sources file. Run the build utility. The
utility will automatically build the products specified in the sources file of
each subdirectory. </p>
<p>For example, if a sources file describes a library called &quot;mylib&quot;, using the
following command line will build the library: </p>
<blockquote>
<p>build -386 </p>
</blockquote>
<p>If the sources file contains a UMAPPL macro that identifies an executable
named &quot;myexe&quot;, this command line will also build &quot;myexe&quot;. On the other hand, if
&quot;myexe&quot; is identified using a UMTEST macro instead of a UMAPPL macro, the
following command line must be used to include &quot;myexe&quot; in the build operation:
</p>
<blockquote>
<p>build -386 myexe </p>
</blockquote>
<p>Library creation is not required for programs that consist of a single source
file. In such a situation, define the sources file as follows: </p>
<ol>
<li>Set TARGETNAME and TARGETPATH as if you were going to generate a library.
</li>
<li>Set TARGETTYPE to UMAPPL_NOLIB. </li>
<li>Set SOURCES to nothing. </li>
<li>Do not include the TARGETNAME library in UMLIBS. </li>
<li>Specify the source file name using UMAPPL or UMTEST. </li>
<li>Invoke the build utility (specifying the file name, if listed using
UMTEST). </li>
</ol>
<p>The build utility will generate the executable file. </p>
<h4><a name="PrecompiledHeaders"></a>Precompiled Headers</h4>
<p>The easiest way to use precompiled headers is to include the following statement
in your sources file: </p>
<blockquote>
<p>PRECOMPILED_INCLUDE=some_header_file_that_every_source_file_includes </p>
</blockquote>
<p>If you are building C++ code, include the statement: </p>
<blockquote>
<p>PRECOMPILED_CXX=1 </p>
</blockquote>
<p>Nothing else is required. </p>
<p>Precompiled headers are put into the directory specified by the O macro.
Their default location will be the obj\platform subdirectory. Therefore, they
should not collide during simultaneous compilations. </p>
<hr>
<p><i>Copyright (c) 2002 Microsoft Corporation. All rights reserved.</i></p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink