Build Utility (build.exe/build)

Specifying the "~" ("not") option removes a directory from the default build.

When you use this tool on UNIX system-based platforms, /? might expand to a filename. Instead either use the /help option variation, use -?, or enclose the /? option in quotes: "/?".

If -M is not specified, n defaults to one processor.  If -M is specified but n is not, then n defaults to the number of processors on the computer.

Same as -3.

You should define the following macros in your dirs file:

c:\> build -eswM -nmake -i

is equivalent to:

c:\> set BUILD_DEFAULT=-eswM -nmake -i
c:\> build

// DIRS file:
DIRS=dir1 dir2 dir3
OPTIONAL_DIRS=OptDir1 OptDir2 OptDir3

c:\> build OptDir1 OptDir2 OptDir3

is equivalent to:

c:\> set BUILD_OPTIONS=OptDir1 OptDir2 OptDir3
c:\> build

INCLUDES=bunny;inc
INCLUDES=.\
INCLUDES=.\inc

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.

Specify header files that do not exist but might be built as part of the build process in USER_INCLUDES.

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.

TARGETLIBS Paths
Paths specified in TARGETLIBS must be absolute. Separate the entries in this list with spaces or tabs.

For example:

TARGETLIBS=$(SDK_LIB_PATH)\kernel32.lib \
$(SDK_LIB_PATH)\advapi32.lib \
$(SDK_LIB_PATH)\user32.lib \
$(SDK_LIB_PATH)\spoolss.lib

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:

%TARGETPATH%\<cpu_type>\

where TARGETPATH is defined in the sources file, and cpu_type specifies the platform for which the products were built.

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:

lib\i386\

Because of this convention, TARGETLIBS entries must specify library names in the following form:

<targetpath>\*\<library_name>

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.

LINKLIBS and UMLIBS
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.

Use LINKLIBS only for the case that meets the following conditions:

• You are building a dynamic link.
• You are exporting something that is defined in some other component library that you also build.
• 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.

There is a similar macro called UMLIBS that you can use if you are building UMAPPLs.

If you specify something unexpected, you will see a message "Unexpected Target Ext."

TARGETPATH=obj

PROGLIB - Executable program that also exports functions for other programs.

PROGRAM - User-mode program that does not export anything.

DYNLINK - Dynamic-link library (DLL). This could be a control panel program or anything that can be dynamically loaded.  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.

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.)

$(BASEDIR)\public\sdk\lib\placefil.txt

is used by default.

For more information, see binplace.exe.

 You might specify:

C_DEFINES = /DDEBUG_BUILD

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:

• MSC_OPTIMIZATION
• MSC_WARNING_LEVEL
• USER_C_FLAGS

usermode 0x60000000 0x20000000
MyDll1 0x70000000 0x00010000
MyDll2 0x70010000 0x00010000

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.

DEBUG_CRTS=1

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.

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.

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).

The most common usage is:

DLLDEF=mydll.def

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:

DLLDEF=$O\mydll.def

DLLENTRY=_DllMainCRTStartup

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.

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.

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.

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.

This macro can be used instead of NTPROFILEINPUT.

If $FREEBUILD (do things for a retail build)

Use this macro to specify the libraries that you need to link against.

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.

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.

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.

As a result, it is almost always better to use TARGETLIBS. Use LINKLIBS only for cases that meet the following conditions:

• You are building a dynamic link.

• You are exporting something that is defined in some other component library that you also build.

• 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.

There is a similar macro called UMLIBS that you can use if you are building UMAPPLs.
 

MAKEDLL=1

Typically, you do not set this value. You might do a test in your make file to instruct the build utility:

IF MAKEDLL=1
do things that you want to do on the second pass of the build

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:

nmake MAKEDLL=1

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:

• You know the dependencies.
• The source file has changed and you do not care about the header file dependency generation.
• You are in a leaf node subdirectory.

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® NT-based operating systems are created.

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.

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.

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.

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.

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.

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.

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.

NT_UP=1

To specify multiprocessor, set:

NT_UP=0

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.

If you set:

NTNOPCH=1

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.

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.

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.

NTTARGETFILE0=

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.

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:

NTTARGETFILE0=myfile.a

then the build utility builds myfile.a as part of pass zero.

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.

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.

The makefile.inc file will provide additional information about the build process, including dependencies, command line rules, and other build rules.

• C
• C++
• RC
• MC
• IDL

Use the PASS0_CLIENTDIR, PASS0_HEADERDIR, and PASS0_SERVERDIR macros to specify a directory location for the output from the MC and the Microsoft® IDL Compiler (MIDL).

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.

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.

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.

To create the headers in the current subdirectory, set PASS0_HEADERDIR to dot ("."):

PASS0_HEADERDIR=.

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.

To create the server part in the current subdirectory, set PASS0_SERVERDIR to dot ("."):

PASS0_SERVERDIR=.

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.

To create the source code generated by MIDL and maketype.lib in the current subdirectory, set PASS0_SOURCEDIR to dot ("."):

PASS0_SOURCEDIR=.

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.

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.

To use the precompiled header with C++ files, specify

PRECOMPILED_CXX=1

PRECOMPILED_INCLUDE=precomp.h

If you omit this instruction, you will not be able to use precompiled headers. PRECOMPILED_INCLUDE sets the build process to use precompiled headers.

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.

You can override those names by setting the PRECOMPILED_OBJ and PRECOMPILED_TARGET macros.

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.

You can override those names by setting the PRECOMPILED_OBJ and PRECOMPILED_TARGET macros.

$(BASEDIR)\public\sdk\inc

$(BASEDIR)\public\sdk\lib\*

When you specify:

SOURCES_USED=filename_someplace_else

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.

For example, a sources file typically includes some other file. Just beneath that directive you could specify:

SOURCES_USED=that_filename

This instruction establishes a link between that file and the sources file. When that other file changes, NMAKE regenerates the _objects.mac file.

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:

TARGET_CPP=name_of_compiler

TARGET_DIRECTORY=some_sourcefile:some_dependency_file

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.

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:

obj\$(TARGET_DIRECTORY)\filename.obj; filename.c

Using the TARGET_DIRECTORY macro ensures that the specified file will be placed in the appropriate subdirectory. For example, \obj\i386subdirectory\obj\.

There are some default targets. One of them is .cod. If you issue the following instruction from a subdirectory containing source files:

nmake SOURCE_FILE_NAME=.cod

it will create an assembler listing that you can review to determine the location of the compiler error.

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.

If you issue the following instruction from a subdirectory containing source files:

nmake SOURCE_FILE_NAME=.pp

the build utility will preprocess the file.

The .cod and .pp files are very useful for tracking bugs in the build process.

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:

TARGETPATH=publicsdk.lib

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.

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:

UMAPPL=a*b*c*d

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.

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.

For example, if you are building kernel32.dll, the build utility will look up kernel32 in coffbase.txt to find that base address.

UMENTRY=main

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.

The specified paths must be absolute. Separate the entries in this list with spaces or tabs.

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:

%TARGETPATH%\<cpu_type>\

where TARGETPATH is defined in the sources file, and cpu_type specifies the platform for which the products were built.

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:

lib\i386\

Because of this convention, UMLIBS entries must specify library names in the following form:

<targetpath>\*\<library_name>

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.

UMTEST=a*b*c*d

The build utility compiles and links each file in this list.

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 "").

The different libraries specified by these macros are as follows:

• USE_CRTDLL                      
  • 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.
• USE_MSVCRT
  • Same as USE_CRTDLL.
• USE_LIBCMT
  • Use the multithreaded static libraries.
• USE_LIBCNTPR
  • Use the kernel run-time libraries.
• USE_NTDLL
  • Use ntdll.dll (the DLL for Windows NT-based operating systems).
• USE_NOLIBS
  • Do not use any run-time libraries.

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.

USE_INCREMENTAL_LINKING=1

Using incremental linking can speed up builds on slower hardware.

USE_NATIVE_EH=1

This instruction directs the build utility to turn on some required compiler switches.

Rather than manually change all your file names to a.cpp, b.cpp, you can specify:

USECXX_FLAG=/Tp

This switch directs the compiler to use the C++ compiler rather than the C compiler to compile the specified subdirectory.

Unlike C_DEFINES, USER_C_FLAGS is not sent to the RC compiler.

Normally, you use the INCLUDES macro in your sources file to indicate the location of your build headers.

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.

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.