Scanning the Project Files

  • Article

In its first step, the Build utility scans the project source tree and creates a list of the work that is required to build the project. This is a one-time step and the Build utility does not do any further scanning during subsequent build passes.

A directory that contains a Sources file has information for building a part of the project. Such a directory is called a leaf node. If the Build utility finds a Sources file in a directory, it records information from macros in the file such as TARGETNAME, TARGETTYPE, SOURCES and INCLUDES.

A project directory that has a Dirs File might contain subdirectories. If it does, the Build utility treats the directory as the root of a subtree. If the Build utility finds a Dirs file in a directory, it uses information in the DIRS and OPTIONAL_DIRS macros in the file to identify the additional subdirectories to scan.

Unlike the DIRS macro, the OPTIONAL_DIRS macro describes directories that are not always built. For example, consider a Dirs file that contains the following macros:

DIRS=lib sauron driver

OPTIONAL_DIRS=app

Based on this example, the Build utility will produce these results when you start it from the command-line in the following ways:

  • build -cz
    This will build the lib, sauron, and driver projects.

  • build -cz app
    This will build the lib, sauron, driver, and app projects.

With the OPTIONAL_DIRS macro, you do not have control over ordering because optional directories are always built after the required directories that are specified through the DIRS macro.

During the scan phase, the Build utility also creates an _objects.mac file for each leaf node in the project. This file contains the object dependencies for each platform, including the library path and the output path.

The Build utility completes the scan when it has performed the following tasks:

  • The Build utility has scanned the root directory of the project.

  • If Dirs File file is present in the root directory, the Build utility has recursively scanned the following:

    • All of the subdirectories specified in the DIRS macro.
    • If optional projects are specified from the command-line when the Build utility is started, it has scanned all the subdirectories specified in the OPTIONAL_DIRS macro.

After the scan is complete, the Build utility has an internal list of the tasks that it has to run to build the project. These tasks are organized by build pass. The Build utility determines which build tasks have to occur during which build pass based on the following:

  • The types of the files in the project.

  • The macros and other directives specified within the Sources file.

Based on the list of tasks, the Build utility starts the NMAKE utility (Nmake.exe) to build each leaf node within the project source tree during each build pass.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011