MSBuild ProjectReference item documentation
c++, msbuild, visual-c++
Solution
Starting from the MSBuild source code links that Jason Pyeron provided in his comment, I learned that when MSBuild prepares build dependencies, it includes all item metadata (what you refer to as subtags) from each `ProjectReference` item. As a result, downstream Tasks and Targets can and sometimes do read arbitrary `ProjectReference` metadata.
For answers to your questions about C++ projects, you can examine `Microsoft.CppBuild.targets` and `Microsoft.CppCommon.targets` (their default path in MSBuild 14, coinciding with Visual Studio 2015, is `C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V140\`). As the following example shows, however, it is not simple to do so:
- In `Microsoft.CppBuild.targets`, the Target `ResolvedXDCMake` creates `_ResolvedNativeProjectReferencePaths` Items dynamically.
- From those Items, the Target `ComputeReferenceLinkInputs` creates `ProjectReferenceToLink` items dynamically.
- For each of those Items that do not have `CopyLocal` metadata, the same Target adds it, copying any `Private` metadata value.
- For each those Items with a distinct path, the same target creates a `Link` item dynamically.
- Switching now to `Microsoft.CppCommon.targets`, `Link` items are passed in the `Sources` parameter of the `Link` Task in the `Link` Target! Although to be fair, their metadata was cleared in the previous step, so you do not have to dive into the `Link` Target documentation in this particular case.
Here are additional portions that relate your question:
Parameters
- `Include` (attribute): Path to project file
- `Project` (metadata): Project GUID, in the form {00000000-0000-0000-0000-000000000000}
- `ReferenceOutputAssembly` (metadata): Boolean specifying whether the outputs of the project referenced should be passed to the compiler. Default is true.
- `SpecificVersion` (metadata): Whether the exact version of the assembly should be used.
- `Targets` (metadata): Semicolon-separated list of targets in the referenced projects that should be built. Default is the value of `$(ProjectReferenceBuildTargets)` whose default is blank, indicating the default targets.
- `OutputItemType` (metadata): Item type to emit target outputs into. Default is blank. If `ReferenceOutputAssembly` is set to "true" (default) then target outputs will become references for the compiler.
- `EmbedInteropTypes` (metadata): Optional boolean. Whether the types in this reference need to embedded into the target assembly - interop asemblies only
Remarks
When the `OutputItemType` parameter is used, additional parameters (metadata) may be applicable. For example, when `OutputItemType` is set to `Content`, `CopyToOutputDirectory` can be used:
- CopyToOutputDirectory (metadata): Optional string. Determines whether to copy the file to the output directory. Values: `Never`, `Always`, `PreserveNewest`.
Problem
I cannot find documentation about `ProjectReference` tag in MSBuild projects. Where can I read detailed description of it? Edit: I have a `.vcxproj` created by others. It contains `ProjectReference` item. `ProjectReference` contains subtags: `Private`, `ReferenceOutputAssembly`, `CopyLocalSatelliteAssemblies`, `LinkLibraryDependencies`, `UseLibraryDependencyInputs`. Where I can read about those tags? Which values can they contain? What other subtags can `ProjectReference` contain? I have searched in MSDN and Google but have not found documentation pages, only discussions and documentation about other products, not MSBuild.