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).
Copyright (C) 2001-2009 Xoreax Software Ltd. All rights reserved.