| MsvcConf - The msvcconf.xml configuration file |
|
The mscvconf.xml configuration is a simple XML formatted file that describes the dependencies of one or more projects.
MsvcConf looks for the configuration file in the directory containing the .vcproj file for each Visual C++ project, and falls back to checking the Visual Studio solution directory if it fails to find one in the project directory.
The following sections describe the XML elements that can appear in the configuration file:
Every configuration file must contain one root MsvcConf element:
<?xml version="1.0" encoding="utf-8"?>
<MsvcConf>
<!-- Dependencies for one or more projects -->
</MsvcConf>
This element ignores all attributes.
Only Project elements are valid children.
In order to do something useful, you should include a Project element in the MsvcConf element. You can include more than one Project element if you are supplying one configuration file for a solution of multiple projects.
<?xml version="1.0" encoding="utf-8"?>
<MsvcConf>
<Project Name="ExampleProject1">
<!-- Dependencies for ExampleProject1 -->
</Project>
<Project Name="ExampleProject2">
<!-- Dependencies for ExampleProject2 -->
</Project>
</MsvcConf>
The Name attribute of a project must match the name of the project within the Visual Studio solution as MsvcConf uses this attribute to map between the configuration file and the solution. All other attributes are ignored.
Platform dependencies are specified by using Include and Library child elements.
Finer control of project configurations is provided by using either Configuration or Platform child elements.
Configuration elements allow you to apply dependency rules only to a certain project configuration, such as Debug or Release.
<?xml version="1.0" encoding="utf-8"?>
<MsvcConf>
<Project Name="ExampleProject">
<Configuration Name="Debug">
<!-- Dependencies for Debug build of ExampleProject -->
</Configuration>
</Project>
</MsvcConf>
The Name attribute of a configuration must match the name of the configuration of the project within the Visual Studio solution as MsvcConf uses this attribute to map between the configuration file and the solution. All other attributes are ignored.
Configuration elements must be children of a Project or Platform element.
Platform dependencies are specified by using Include and Library child elements.
Finer control of project configurations is provided by using a using a Platform child element.
Platform elements allow you to apply dependency rules only to a certain project platform, such as Win32 or x64.
<?xml version="1.0" encoding="utf-8"?>
<MsvcConf>
<Project Name="ExampleProject">
<Platform Name="Win32">
<!-- Dependencies for Win32 build of ExampleProject -->
</Platform>
</Project>
</MsvcConf>
The Name attribute of a platform must match the name of the platform of the project within the Visual Studio solution as MsvcConf uses this attribute to map between the configuration file and the solution. All other attributes are ignored.
Platform elements must be children of a Project or Configuration element.
Platform dependencies are specified by using Include and Library child elements.
Finer control of project platforms is provided by using a using a Configuration child element.
Include elements instruct MsvcConf to find the file specified by the Name attribute using the C++ header files rules.
If the file is found then the 'Additional Include Directories' of the current project configuration is updated to point to the found location of the file.
If a Define attribute is supplied, then the the pre-processor directives of the current project configuration are updated to include the attribute value.
If an Optional attribute is not supplied, or its value is not "true", then an error is reported if the specified file cannot be found.
<?xml version="1.0" encoding="utf-8"?>
<MsvcConf>
<Project Name="ExampleProject1">
<Include Name="zlib.h" Define="HAVE_ZLIB_H" Optional="true" />
</Project>
</MsvcConf>
Include elements ignore any child elements.
Search directories
The following directories are searched, in the following order:
The 'Additional Include Directories' of the current project configuration.
Any non-existent directories are removed from the list and the project is reconfigured.
The 'C++ Include Directories' of the platform of the current project configuration.
Each directory is searched in order for the specified file. If it is not found, then a linear search of all local fixed drives on the computer are searched for the file. The search skips hidden, temporary and system files.
If the file is found, then the 'Additional Include Directories' of the current project configuration is updated to include the path to the found file.
If multiple versions of the file are found, then the version with the newest creation date is selected, and a warning is reported in the Visual Studio Output window.
Any 'Additional Include Directories' of the current project configuration not associated with an Include element are left untouched, unless they are invalid.
If the file is found then the pre-processor directives of the current project configuration are updated to include the value of the Define attribute.
If the file is not found, the value of the Define attribute is removed from the project configuration pre-processor directives.
Any pre-processor directives of the project configuration not associated with an Include or Library element are left unaltered.
The Append attribute is used when file to be found must be found in a specific subdirectory, and ensures that extra text is appended to the location when the project configuration is updated.
<?xml version="1.0" encoding="utf-8"?>
<MsvcConf>
<Project Name="ExampleProject1">
<Include Name="msvc\wx\setup.h" Append="msvc" />
</Project>
</MsvcConf>
In the example above, the file "setup.h" is searched for in a subdirectory "*\msvc\wx\". If it is found, then the 'Additional Include Directories' of the project configuration is updated to include "<Found location>\msvc\".
This allows the source code to use the expression #include <wx\setup.h> to include the correct file.
This is attribute is normally not required, but is useful with some cross-platform toolkits that lay out their header files in platform-specific subdirectories.
Library elements instruct MsvcConf to find the file specified by the Name attribute using the C++ libraries rules.
If the file is found then the 'Additional Library Directories' of the current project configuration is updated to point to the found location of the file.
If an Optional attribute is not supplied, or its value is not "true", then an error is reported if the specified file cannot be found.
<?xml version="1.0" encoding="utf-8"?>
<MsvcConf>
<Project Name="ExampleProject1">
<Library Name="sqlite3.lib" Optional="false" />
</Project>
</MsvcConf>
Library elements ignore any child elements.
Library elements support Define and Append attributes in the same way as Include elements.
Search directories
The following directories are searched, in the following order:
The 'Additional Library Directories' of the current project configuration.
Any non-existent directories are removed from the list and the project is reconfigured.
The 'C++ Library Directories' of the platform of the current project configuration.
Each directory is searched in order for the specified file. If it is not found, then a linear search of all local fixed drives on the computer are searched for the file. The search skips hidden, temporary and system files.
If the file is found, then the 'Additional Library Directories' of the current project configuration is updated to include the path to the found file.
If multiple versions of the file are found, then the version with the newest creation date is selected, and a warning is reported in the Visual Studio Output window.
Any 'Additional Library Directories' of the current project configuration not associated with a Library element are left untouched, unless they are invalid.
Note:
MsvcConf will also validate any libraries specified in the 'Linker, Additional Libraries' of the current project configuration, as if they had been supplied as Library elements with Optional="false".
This helps to detect missing libraries before linker errors are reported during a build.
| MsvcConf |
|
|
Microsoft is a U.S. registered trademark of Microsoft Corporation. Visual Studio is a registered trademark of Microsoft Corporation in the U.S. and/or other countries. |
Version: 1.0 Last modified: 18 May 2010, Rick Taylor |