Appendix C. Building Drivers
There is nothing
Although it sometimes may appear
The DDK provides a utility, BUILD, that is convenient for batch and production builds of device drivers (as well as other production-level binaries). With proper environment settings, however, the driver author may successfully use Visual Studio. Indeed, it may be appropriate to use Visual Studio throughout the development phase and introduce BUILD during the later release stages of the project.
The purpose of this appendix is to provide background material on the BUILD utility, as well as provide the Visual Studio settings necessary for successful driver builds.
The Build Utility
The DDK-supplied BUILD utility is ideal for production releases because it works from a single "makefile" concept to batch-build a variety of
What BUILD Does
The 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
Figure c.1. The BUILD utility process.
BUILD uses several command files (located in the DDK's binary directory, \BIN:).
BUILD helps manage
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 BUILD
Once 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 File
The 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. Common BUILD Utility Keywords
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 BUILD
In 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 Operations
BUILD 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