Output File Definition

Note: Support for Visual Studio 2008 and earlier has been deprecated as these versions are no longer supported by Microsoft.

When custom build steps, build events, and custom build rules are 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.

This is achieved in two ways:

Output Files Field

With custom build steps, use the Output Files field in the custom build step property dialog to declare output files.

Output File Definition Directives

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. The Incredibuild output file definition directives are used to explicitly declare output files created by Visual Studio custom build steps, build events, and custom build rules. The directives are used in conjunction with the minimal directory synchronization mode, to 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 is an indication that the source file may have changed as a result of a build step. Therefore, 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.

>To use one of the output file definition directives:

  • In a custom, pre-build, pre-link, or post-build step, enter the directive as one of the command lines for that step, preceded by a "Rem" (remark) directive.

    Note: All directives that accept files/directories as parameters can accept absolute and relative paths, as well as environment variables.

Incredibuild_OutputFile

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.cppRem Incredibuild_OutputFile $(EnvDefinedFile)Rem Incredibuild_OutputFile c:\out\*.obj

Incredibuild_OutputFileMask

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 *.outRem Incredibuild_OutputFileMask Res??.txt

Incredibuild_OutputDir

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

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\GenfilesRem 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, when using the minimal directory synchronization mode, notifies 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