The DDK-supplied BUILD utility is ideal for production releases because it works from a single "makefile" concept to batch-build a variety of targeted binaries. For example, a single set of source files can be used to generate driver binaries for both Intel x86 platforms and Alpha platforms. Similarly, both the retail (free) and checked (debug) versions can be built from a single procedure. What BUILD DoesThe BUILD utility is just an elaborate wrapper around NMAKE. (NMAKE is Microsoft's attempt at the Unix make utility.) A batch file of instructions provides a recipe for the construction of one or more target configurations (e.g., checked and free). Using a set of keywords, a source file list, and miscellaneous switches, BUILD constructs an appropriate makefile and then invokes NMAKE to actually perform the build to produce one or more BUILD products. Figure C.1 shows how this process works. BUILD itself is actually a rather simple-minded program. Most of the build process is controlled by a set of standard command files that BUILD passes to NMAKE. These files contain all the platform-specific rules and option settings needed to create a BUILD project. By separating the rules from the utilities, there is less version interdependency. Figure c.1. The BUILD utility process.BUILD uses several command files (located in the DDK's binary directory, \BIN:).
BUILD helps manage multiplatform projects by separating binary files according to their platform type. To do this, it uses different directories for different platforms. So long as cross-hosted compilers and linkers are available, a single BUILD process can generate binaries for all the supported platforms. The directory structure for the output files takes the form shown in Figure C.2. Notice that BUILD uses separate directories for the checked and free versions of the generated binaries. The DBG symbol is defined as 1 when performing the checked build. How to Build a Driver with BUILDOnce the source code is ready for compilation, the use of the BUILD utility requires that the following steps be followed:
The binary output is created in the CHECKED or FREE directory of the appropriate platform. Any on-screen errors are also written to the BUILD log file. Writing a SOURCES FileThe BUILD operation is controlled by a series of keywords. These keywords specify the type of driver to be generated, the source files that comprise the product, and the directories for various files. While some keywords can be passed as command-line options to BUILD, the more useful procedure is to place the keywords into the SOURCES file. The following general rules apply to the SOURCES file:
Table C.1 lists the common SOURCES keywords for building drivers. The DDK includes additional keywords and details regarding these keywords. The following is an example of a minimal SOURCES file for building a kernel-mode driver: TARGETNAME= DRIVER TARGETTYPE= DRIVER TARGETPATH= . SOURCES= init.c dispatch.c driver.c \ pnp.c Log Files Generated by BUILDIn addition to screen output, the BUILD utility generates several text files that can be used to determine the status of a BUILD product.
BUILD generates these files in the same directory as the SOURCES files. The warning and error files appear only if needed. Recursive BUILD OperationsBUILD can be used to maintain an entire source code tree by creating a file called DIRS. This file is placed in a directory containing other subdirectories. Each subdirectory can be a source directory (containing a SOURCES file) or the root of another source tree (containing another DIRS file). When BUILD runs from the topmost DIRS directory, it creates all the BUILD products described in the now linked SOURCES files. The rules for writing a DIRS file are the same as those for a SOURCES file, with the restriction that only two keywords are allowed.
Besides performing multiplatform builds, the recursive BUILD feature can be used to generate a kernel-mode and user-mode component at the same time.
|