|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
Specifying Custom Build Steps
A custom build step provides the build system with the information it needs to build output files from an input file. A custom build step is attached to its input file; it contains the commands to run, a list of the output files that are generated by those commands, and (optionally) a description of the command.
For general information on custom build steps, see Understanding Custom Build Steps and Build Events.
To specify a custom build step
Open the project's Property Pages dialog box. For details, see Setting Visual C++ Project Properties.
In the Configuration box, select the configuration for which you want to specify a custom build step.
In Solution Explorer, select the input file for the custom build step.
If the Custom Build Step folder does not appear, the file you selected has a default step associated with it. For example, .c and .cpp files have a default step to invoke the compiler. To override a default setting, modify the Tool property, which is in the Configuration Settings folder.
Specify the properties associated with the custom build step:
In Additional Dependencies, specify any additional files beyond the one for which the custom build step is being defined (the file associated with the custom build step is implicitly considered an input to the step). Having additional input files is not a requirement for a custom build step. If you have more than one additional input, separate them with semicolons.
If an Additional Dependencies file's date is later than the input file, then the custom build rule will be run. If all of the Additional Dependencies files are older than the input file, and the input file is older than the Outputs file, then the custom build step will not run.
For example, suppose you have a custom build step that takes MyInput.x as input and generates MyInput.cpp, and that MyInput.x includes a header file, MyHeader.h. You can specify MyHeader.h as an input dependency to MyInput.x, and the build system will build MyInput.cpp when it is out-of-date with respect to MyInput.x or MyHeader.h.
Input dependencies can also ensure that your custom build steps run in the order you need them to. In the preceding example, suppose that MyHeader.h is actually the output of a custom build step. Because MyHeader.h is a dependency of MyInput.x, the build system will first build Myheader.h before running the custom build step on MyInput.x.
In Command Line, specify the syntax of the custom build rule. This syntax can include any command that is legal at the command line or in a .bat file. You may want to use Macros for Build Commands and Properties to specify locations for files or to get the actual name of the input file in the case of multiple selections. The name of a batch file should be preceded by call to ensure that all subsequent commands will be executed.
In Description, type a description of the custom build step. This will be printed to the Output window when the build system processes this step.
In Outputs, specify the name of the output file. This is a required entry; without a value for this property, the custom build step will not run. If a custom build step has more than one output, separate file names with a semicolon.
The name of the output file should be what is specified in the Command Line property. The project build system will look for the file and check its date. If the file is newer than the input file or if the file is not found, then the custom build step will run. If all of the Additional Dependencies files are older than the input file, and the input file is older than the Outputs file, then the custom build step will not run.
If you want the build system to operate on an output file generated by the custom build step, you must manually add it to the project. The custom build step will update the file during the build.
Assume that you want to include in your project a file named parser.l. You want a lexical analyzer to process parser.l to produce a .c file with the same base name (parser.c).
First, you add parser.l and parser.c to the project. If the files don't yet exist, you just add a reference to the files. You create a custom build step for parser.l and type the following in the Commands property:
lexer $(InputPath) .\$(InputName).c
This command will run the lexical analyzer on parser.l and output parser.c to the project directory.
In the Outputs property, type the following:
When you build the project, the build system compares the timestamps of parser.l and parser.c. If parser.l is more recent, or if parser.c doesn't exist, the build system runs the Command property to bring parser.c up to date. Since parser.c was also added to the project, the build system will then proceed to compile parser.c.