1. WDK Build Tools
KMDF drivers are built with the WDK build utility build.exe.
This is a command line tool that is essentially identical to the tool
that is used to build Windows itself. The build utility can be used for
a variety of project types including user mode applications, but it
must be used for drivers.
The build utility requires a number of supporting files. The following are required for any project:
Source code files— A project must have at least one source code file (.c or .cpp) and typically one or more header files (.h).
Make file—
This file contains build instruction. It should be named makefile and
consist of the following statement that includes the standard WDK make file:
!INCLUDE $(NTMAKEENV)\makefile.def
Sources file—
This file contains project-specific information that is used to build
the driver, such as the list of source files. The following example
shows the content of a basic Sources file.
TARGETNAME=WdfSimple
TARGETTYPE=DRIVER
KMDF_VERSION=1
SOURCES=WdfSimple.c
Optional files include
Makefile.inc—
Project with custom targets, such as Windows Management
Instrumentation-(WMI)-related files, must put the necessary directives
in Makefile.inc. Do not modify the standard make file.
Dirs—
This file is used by projects that have source files in multiple
subfolders or to build multiple projects with a single build command.
Resource files (.rc)— These files contain resources such as string tables.
Managed object format (MOF) resource files (.mof)— Drivers that support WMI must have a MOF resource file (.mof).
INX file (.inx)— An INX file is an architecture-independent INF file. When the appropriate instructions are specified, the Build utility uses the data in an INXINF file for the project. file to produce an appropriate
You can use any names that are convenient for most
project files and folders, with one important restriction: the names
cannot contain spaces or nonANSI characters. However, the build utility assumes by default that the make, makefile.inc, Sources, and Dirs files are named makefile, makefile.inc, sources, and dirs, respectively.
The supporting files must all be created manually.
However, you can usually simplify the process by copying the files from
an appropriate sample and modifying them to suit the project.
Visual Studio can be used in only a limited way for
driver development. In particular, its compiler and debugger are not
designed to be used with drivers. However, if you are accustomed to
using Visual Studio, you can still use its integrated development
environment (IDE) to edit source code and build the driver.
Essentially, you reprogram the Visual Studio Build command to bypass
the Visual build utility and instead run a command line that launches
the WDK build utility. You still must manually create the build utility supporting files that were discussed earlier in this section.
KMDF drivers, like WDM drivers, are built in the WDK build environment. KMDF drivers include the header files Wdf.h (shipped with KMDF) and ntddk.h.
To build a KMDF driver, you must set the /GS flag on the compiler and the KMDF_VERSION environment variable in the Sources file. Setting KMDF_VERSION=1 indicates that the driver should be built with the first version of KMDF.
2. Build Environment
There are two basic types of build:
Checked builds
are similar to the Debug builds that are used in application
development. They generate detailed debugging information and enable
certain types of debugging-related code such as ASSERT macros. Checked builds are normally used during the earlier stages of driver development because they are much easier to debug than free builds. Checked builds are typically somewhat slow.
Free builds are similar to the Release builds that are used in application development. They lack the detailed debugging information of a checked build and are fully optimized. Free builds
are more difficult to debug, so they are typically used at the end of
the development cycle for final testing and performance tuning.
To simplify the process of setting up the build environment, the WDK includes a set of console windows with the correct settings for each build environment/platform/architecture combination.
To open a build environment window:
1. | On the taskbar, click Start, and then click All Programs.
|
2. | Click Windows Driver Kits, click the latest WDK version, and then click Build Environments.
|
3. | Click the appropriate CPU architecture, and then open a checked or free build environment window for the appropriate Windows version.
|
The build environment window for a specified version of Windows works for that version and all later versions.
3. Building a Project
After you have launched the correct build window, use cd to move to the project folder and run the build utility to compile and link the driver. The command syntax is simple:
The build utility assumes by default that the project has a make file that is named makefile, a Sources file with the list of source files, and so on. There is no need to specify these files explicitly. a[b[c]...] represents the build arguments, most of which consists of a single case-sensitive character. The WDK has a complete list of flags, but here are some of the commonly used ones:
?— Displays a list of all command-line flags.
c— Deletes all object files.
e— Generates log, error, and warning files.
g— Uses colored text to display warnings, errors, and summaries.
Z— Prevents dependency checking or scanning of source files.
The following example shows a commonly used build command:
The build utility produces several output files, including
TargetName.sys— The driver binaries.
SourceFileName.obj— Object files that are produced from the corresponding source files.
TargetName.pdb— The driver’s symbol tables.
TargetName.inf— The project’s INF file. This file is produced by the build utility only if the project uses an INX file. Otherwise, you must create the INF file separately.
The output normally goes in a subfolder of
the project folder. The default output folder name depends on the build
environment. For example, the default output folder for a Windows XP
x86 free build is named Project-Folder\objfre_wxp_x86\i386.
