3.1.1 BUILD Macros

You describe build products in a file called sources, which resides in each source code directory. This file contains a series of macro definitions that are recognized by BUILD. Following is a list of macros that are typically defined in a sources file:

TARGETNAME

Specifies the name of the library being built, excluding the file extension.

TARGETPATH

Specifies a directory name that is the destination of all build products (EXEs, DLLs, LIBs, and so on). Note that object files are always created in the \obj subdirectory.

TARGETTYPE

Specifies the type of product being built. This is typically LIBRARY or DYNLINK (for DLLs), but can specify other values.

INCLUDES

Contains a list of paths to be searched for include files during compilation. Entries in this list are separated by semicolons and can be absolute or relative.

SOURCES

Contains a list of source filenames (except for the file containing main) with extensions. This is the list of source files which will comprise the library or DLL being constructed. Entries in this list are separated by spaces or tabs.

UMTYPE

Specifies the type of product being built:

windows	Specifies Win32 (user-mode)
NT	Specifies kernel-mode
console	Specifies a Win32 Console application

UMTEST

Contains a list of named source files containing a main function. These filenames are specified without extensions, and are separated by asterisks. Each file in this list is compiled and linked with the library or DLL generated by the SOURCES line.

UMAPPL

Contains a list of named source files containing a main function. These filenames are specified without extensions, and are separated by asterisks. Each file in this list is compiled and linked with the library or DLL generated by the SOURCES line. The difference between UMTEST and UMAPPL is that if you use UMTEST, you must specify the executable names that need to be built through the command line to build.exe. If you use UMAPPL, you need not specify anything on the command line, and build.exe will automatically build all the executables.

UMAPPLEXT

Specifies the filename extension (.com, .scr, and so on) if you want image files to have something other than .exe as the extension.

TARGETEXT

Specifies the filename extension, such as .cpl, if you want DLLs to have something other than .dll as the extension.

UMLIBS

Contains a list of library path names to be linked to the files specified by UMTEST or UMAPPL. The library generated by SOURCES should be included here. Entries in this list are separated by spaces or tabs. Currently, these path names must be absolute.

The UMLIBS path names need to be defined in a special way. Since BUILD provides a mechanism for building products for several hardware targets, 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 CPU for which the products were built. For example, if you define TARGETPATH as OBJ, and request a build for i386 and MIPS, the build products would be directed to the following subdirectories:

obj\i386\		// build products for i386
obj\mips\		// build products for MIPS

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

<targetpath>\*\<library_name>

where targetpath is identical to the TARGETPATH defined in the sources file, and library_name is the full filename of the library to be linked to the application. The “*” is automatically replaced by the current CPU target during the build process.

It is possible to build your applications on a logical drive other than the one that has the DDK source tree, by making use of the BASEDIR environment variable. BUILD defines this environment variable to be \ddk_root by default. If you have your source tree on a logical drive that is different from the one that has the DDK sources, then you need to prepend the BASEDIR environment variable to the libraries that you need to link to, as follows:

$(BASEDIR)\lib\*\base.lib

In addition to sources, a standard file called makefile is required in each directory containing source code to be built. This file should not vary from one source directory to another and should never be altered.

To build a particular executable, change to the directory containing the sources file and invoke BUILD. BUILD automatically builds the library specified in sources, but it builds the executables only if explicitly told to do so (unless you use UMAPPL).

For example, if a sources file defined a library called “mylib” (as TARGETNAME), and an executable (UMTEST) called “myexe,” both products would be built for the i386 with the following invocation:

build -386 myexe

If “myexe” were not specified, only “mylib” would be built by default.

On the other hand, if you had defined a library called “mylib” (as TARGETNAME) and an executable (UMAPPL) called “myexe,” both products would be built for the i386 with the following invocation:

build -386

For simple programs consisting of a single source file, a library is not required. In this situation, define the sources file as follows:

• Set TARGETNAME and TARGETPATH as if you were going to generate a library.

• Set TARGETTYPE to be UMAPPL_NOLIB.

• Set SOURCES to nothing.

• Do not include the TARGETNAME library in UMLIBS.

• Invoke BUILD, specifying the filename listed in UMTEST.

BUILD will generate the executable file.