
How To Build The Source Tree
============================

The source files in and beneath this directory are set up for use with the
BUILD tool from the Windows Driver Kit (WDK) for Windows 7. This kit is also
known by its build number: 7600.16385.1.

Dependence on the WDK comes about partly from wanting to build kernel-mode
device drivers, and nearly 20 years of device driver kits from Microsoft
have made BUILD effectively essential. Most of the rest of the reason is
simply that the author, with a background in writing device drivers for
Windows, finds it convenient to use the WDK's preferred methods for
everything. Another contribution is that the WDK ships with a C Run Time
(CRT) library in DLL form, as MSVCRT.DLL, that built user-mode binaries can
use without requiring prior installation of any version of Microsoft Visual
Studio.

All that said, the WDK for Windows 8 does away with BUILD - finally - and
has at least the aim of integrating with Visual Studio. So, the preferred
way to build this source tree will eventually be updated to new methods.
Until then, here's what you need to know if you're not already familiar with
building via the WDK.

Start
-----

Obviously, you must first install the WDK and be sure to include all build
tools and headers.

Note that although the WDK seems intended for kernel-mode development, it
comes with most of the headers that user-mode programmers ordinarily obtain
from the Windows Software Development Kit (SDK). The WDK also includes the
compiler and linker, etc. So, you must install the WDK but you don't need
anything except the WDK.

The starting point for any rebuild is to open your choice from the Build
Environments among the WDK's entries on the Start Menu. Each of these is a
Command Prompt with environment variables, etc, set up so that BUILD
produces binaries for a target operating system.

To prepare for building this project, CD to the top of the project's source
tree, i.e., to the directory that contains this README.TXT file.

Configure
---------

It is strongly recommended, but not essential, that you then set some
environment variables, e.g.,

  set NO_BINPLACE=
  set SIGNCODE=1

The NO_BINPLACE environment variable is defined by Microsoft. Clearing it
before running BUILD has the substantial merit of getting end products
collected into a separate directory for easier distribution. The present
configuration has the end products go into a directory named "bin" at the
same level as the one named "src". (An important consideration here is that
permissions can be set on directories such that the build products become
accessible to people who cannot see the source files.)

Among the non-Microsoft options are some for getting code signed as part of
the build. See SIGNMK.INC in the Common\Base\inc directory for details. (It
reads as a makefile inclusion.) Simply setting SIGNCODE to 1 gets all end
products self-signed for testing. The certificate to sign with must be in
your Personal store and be named "My Own Testing Authority". To vary this,
set other environment variables, as described in SIGNMK.INC.

SIGNMK.INC gets included from various PROJECT.MK files. Wherever you see a
PROJECT.MK file in the source tree, read it, because it defines macros for
many of the locations that are shared throughout the source tree.

For more, consult Microsoft's (nowadays extensive) documentation of the
BUILD tool for its configurability through command-line parameters and
environment variables and for the numerous settings that are supported in
DIRS and SOURCES files. (The DIRS files tell BUILD where to go through the
source tree to find sub-projects to build. A SOURCES file tells how to build
any one project. Both these files are makefile inclusions and have the
syntax required for Microsoft's NMAKE tool. The actual makefiles are in the
WDK's "bin" directory. If curious, start with MAKEFILE.NEW.)

Build
-----

For a clean rebuild of the whole project, run the batch file

  rebuild

in each of the opened build environments.

This batch file runs BUILD with its -c option, which typically is enough to
get everything rebuilt.

Clean
-----

After finding that the source tree rebuilds satisfactorily, you may want to
delete all the intermediate files, e.g., so that you can archive just the
source files. To do this, run the batch file

  clean

in each of the opened build environments.

This batch file also runs BUILD with its -c option, but with the additional
direction to build a pseudo-target named "clean" instead of the default
pseudo-target "all".

Source-Code Reading Order
=========================

When reading the source files with a view to understanding the code, you
will likely do best to follow the order used for describing them in the
corresponding SOURCES file.

Source-Code Style
=================

Source files are written to be displayed and/or printed traditionally, with
tabs expanding to multiples of 8 characters and with no line exceeding 80
characters.

This means the files present well in something as basic as Notepad.

If you're using some editor that is supposedly more sophisticated, you may
have to change the editor's settings for tab interpretation, else the code
might not look well laid out.

If you're modifying any source file, then please, please, please keep to the
same tab interpretation, else the files will soon become difficult to read
by everyone in all editors no matter how they're configured.

Source Files and Headers
------------------------

The general style is to favour small source files which each cover some
narrow aspect of the build product's behaviour. To each source file there
typically corresponds one header. All of a source file's implementation that
is meant to be usable from any other source file is declared in the
corresponding header. Such simple correspondence is never commented: you are
just assumed to notice it.

