The Build Utility

< BACK  NEXT >
[oR]

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 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 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.
graphics/cfig01.gif

BUILD uses several command files (located in the DDK's binary directory, \BIN:).

  • MAKEFILES.DEF is the master control file. It references other files to perform its work.

  • MAKEFILE.PLT selects the platform for a build operation.

  • i386MK.INC, ALPHAMK.INC, and ia64mk.inc contain platform-specific compiler and linker switches for Intel, Alpha, and 64-bit Intel Itanium processors, respectively.

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 BUILD

Once the source code is ready for compilation, the use of the BUILD utility requires that the following steps be followed:

  1. In the source file directory, create a file called SOURCES that identifies the components that comprise the driver. A description of the format of this file follows in the next section.

    Figure c.2. Directory structure for BUILD product.
    graphics/cfig02.gif
  2. In the source directory, create a file called MAKEFILE that contains only the following line:

     !INCLUDE $(NTMAKEENV)\MAKEFILE.DEF 

    This stub invokes the standard makefile needed by all drivers created with BUILD. Do not add source files to this makefile. Instead, use the SOURCES file.

  3. Use Windows Explorer or the MKDIR command to set up the directory tree for the BUILD products. Refer to Figure C.2.

  4. In the Program Manager group for the Windows 2000 DDK, select either the Checked Build Environment or the Free Build Environment. A command window appears with the appropriate BUILD environment variables set.

  5. Navigate (using the CD command) to the source file directory for the driver.

  6. Run the BUILD utility (i.e., type BUILD) to create the driver executable.

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:

  • The filename must be SOURCES (no extension).

  • The file contents are of the form

     keyword=value 
  • A single BUILD command can be extended over multiple lines by using the backslash (\) character at then end of a line.

  • The value of a BUILD keyword must be simple text. BUILD itself does little processing of NMAKE macros and does not handle conditional statements.

  • Ensure that there is no white space between a BUILD keyword and the equal sign (=) character. White space after the equal sign is acceptable.

  • Comments in a SOURCE file line start with a sharp (#) character.

Table c.1. Common BUILD Utility Keywords
Common BUILD Keywords
Keyword Meaning
INCLUDES List of paths containing header files
SOURCES List of source files making up BUILD product (required)
TARGETPATH Top-level directory for BUILD product tree (required)
TARGETNAME Name of BUILD product, sans extension
TARGETEXT File extension for the BUILD product
TARGETTYPE Case sensitive keyword describing BUILD
  • DRIVER

  • GDI_DRIVER

  • MINIPORT

  • LIBRARY

  • DYNLINK (for DLLs)

TARGETLIBS List of libraries to be linked with driver
LINKER_FLAGS Linker switches of the form -flag.value
PRECOMPILED_INCLUDE File containing precompiled #include directives

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

lists the commands invoked by NMAKE.



BUILD.WRN

contains warnings generated during the build.



BUILD.ERR

contains a list of errors generated during the build.



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.

DIRS

lists subdirectories that should always be built. Entries in the list are separated by spaces or tabs.



OPTIONAL_DIRS

lists subdirectories that should be built only if they are named on the original BUILD command line.



Besides performing multiplatform builds, the recursive BUILD feature can be used to generate a kernel-mode and user-mode component at the same time.

< BACK  NEXT >


The Windows 2000 Device Driver Book(c) A Guide for Programmers
The Windows 2000 Device Driver Book: A Guide for Programmers (2nd Edition)
ISBN: 0130204315
EAN: 2147483647
Year: 2000
Pages: 156

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net