Output File Definition Directives

Overview

The output file definition directives are used to explicitly declare output files created by Visual Studio custom build steps, build events and custom build rules. This is required in two scenarios:

1. Distribution of Custom Build Steps, Custom Build Rules and Build Events

When one of the above tasks is distributed, it is necessary to explicitly declare any output files created by the distributed task in order for these files to be copied back to the initiating machine when the step has run.
With custom build steps it is also possible to use the "Output Files" field in the custom build step property dialog to declare output files.
See here for more details on distributing custom build steps, custom build rules and build events.

2. Minimal Directory Synchronization Mode

When used in conjunction with the minimal directory synchronization mode, the directives declare that the step modifies a specified set of files.

When operating in this mode, IncrediBuild performs additional source-file timestamp-checking throughout a build only when there's an indication that the source file may have changed as a result of a build step. Because of this, it is essential that build steps that modify source files declare this explicitly. Failing to do so may result in build errors, older versions of these files being used in the build, or certain build steps not being performed due to IncrediBuild being oblivious to the fact that their input files have changed.

MSVC provides the ability to define a set of output files for custom build steps (both file-level and project-level), but does not provide a way for defining this with pre-build/pre-link/post-build steps. IncrediBuild's output file definition directives complete this functionality.

The Directives

To use one of the output file definition directives in a custom, pre-build, pre-link or post-build step, enter it as one of the command lines for that step, preceded by a "Rem" (remark) directive (see examples below).

IncrediBuild_OutputFile

The IncrediBuild_OutputFile directive specifies that an output file matching the given string may be modified or created by this step. Several IncrediBuild_OutputFile directives may be used (each in a separate line) in one step, to specify several output files. The directive should be followed by the path and name of the output file. Wildcard expressions may also be used. For example:

Rem IncrediBuild_OutputFile ..\files\myGenFile1.cpp
Rem IncrediBuild_OutputFile $(EnvDefinedFile)
Rem IncrediBuild_OutputFile c:\out\*.obj

IncrediBuild_OutputFileMask

The IncrediBuild_OutputFileMask directive specifies that an output file matching the given string may be modified or created by this step in any folder on the file system. Several IncrediBuild_OutputFileMask directives may be used (each in a separate line) in one step, to specify several output files masks. The directive should be followed by a standard wildcard expression specifying the file name (do not enter folder paths with this directive as it implies "any location"). For example:

Rem IncrediBuild_OutputFileMask *.out
Rem IncrediBuild_OutputFileMask Res??.txt

IncrediBuild_OutputDir

The IncrediBuild_OutputDir directive specifies that any file in a single directory may be modified by this step. Several IncrediBuild_OutputDir directives may be used (each in a separate line) in one step, to specify several directories. The directive should be followed by the name of the directory. For example:

Rem IncrediBuild_OutputDir c:\myproj\src\GenFiles\
Rem IncrediBuild_OutputDir $(EnvDefinedDir)

IncrediBuild_OutputDirTree

The IncrediBuild_OutputDirTree directive is identical to the IncrediBuild_OutputDir directive, except for the fact that it indicates that files not only in the specified directory, but also in all of its subdirectories may be changed by this step.

Rem IncrediBuild_OutputDirTree ..\src\Genfiles
Rem IncrediBuild_OutputDirTree $(EnvDefinedDir)

The IncrediBuild_OutputDirTree directive currently can only be used in conjunction with the minimal directory synchronization mode, and cannot be used to specify output files for distributed tasks.

IncrediBuild_OutputReset

The IncrediBuild_OutputReset directive will, when using the minimal directory synchronization mode , notify IncrediBuild that after running this step any source file could have been modified, and therefore all source-file timestamps must be rechecked before use. The IncrediBuild_OutputReset directive is used with no additional parameters. For example:

Rem IncrediBuild_OutputReset

The IncrediBuild_OutputDirTree directive currently can only be used in conjunction with the Minimal Directory Synchronization mode, and cannot be used to specify output files for distributed tasks.

Notes

All directives that accept files/directories as parameters can accept absolute and relative paths, as well as environment variables (see example above).

Converted from CHM to HTML with chm2web Standard 2.7 (unicode)