Project references in Visual Studio and C++


Especially when projects get larger some kind of modularization is needed. In native projects, this is normally done by splitting the code base into several libraries. If all libraries are Visual Studio projects, there is the possibility to use references to other projects, which I want to examine in this article. The test project files I used can be found on Github.

To use the code from another project, the other project has to be built as a static or dynamic library, whereby here I will only focus on static libraries. On Windows, this produces a *.lib file which the client can link at. As an example consider a Visual Studio solution with a project named ParentProject (normal project with a main()-method) and two child projects Child1Project and Child2Project. Both child projects are built as a static library. In this test case, the following should be achieved:

Example of project dependencies with two internal (Child1Project and Child2Project) and on external (ImageLibrary) library
Example of project dependencies with two internal (Child1Project and Child2Project) and one external (ImageLibrary) library. All libraries are static.

To use the code from a child project in the parent project two things need to be done:

  1. The path to the header interface files from the child project needs to be added to the include path to the parent project.
  2. The produced *.lib must be added as input library to the linker in the parent project.

The first step must be done manually by adding the appropriate path to the project settings from ParentProject. E.g. by adding the paths to Project propertiesVC++-directoriesInclude directories.

For the second step, there is an easier way in Visual Studio if the other project is also a Visual Studio project (and not some normal *.lib file). This is where the mentioned project-to-project references find a use. In Visual Studio they can be set by right click on the reference entry of ParentProjectAdd reference → check the child project. After this step, the parent project automatically links against the produced *.lib files from the child project. The reference entry for the parent project should look similar to the following screenshot.

Project references in Visual Studio
Project references in Visual Studio.

The code is used from a child project as usual: include the appropriate header file in the parent project (using #include <header.h>) and use the functions/classes.

The child projects mentioned before were all created from within the same solution. But sometimes it is also necessary to include code from another project, like an existing module. It would also be cool to make the process a little bit easier (e.g. don't add the include path and the project reference manually all the time).

In this example an external project named ImageLibrary should be included (see figure above). To make things easier I prepared an ImageLibrary.props file for this library which looks like:


<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ImportGroup Label="PropertySheets" />
  <PropertyGroup Label="UserMacros" />

  <!-- Include path -->
  <PropertyGroup>
    <IncludePath>$(MSBuildThisFileDirectory);$(IncludePath)</IncludePath>
  </PropertyGroup>

  <ItemDefinitionGroup />
  <ItemGroup />

  <!-- Project reference -->
  <ItemGroup>
  <ProjectReference Include="$(MSBuildThisFileDirectory)\ImageLibrary.vcxproj">
    <Project>{DD9F7D1D-B22C-4B88-8167-7F1884709C19}</Project>
	<UseLibraryDependencyInputs>true</UseLibraryDependencyInputs>
  </ProjectReference>
  </ItemGroup>

</Project>

The used variable $(MSBuildThisFileDirectory) holds the path to the directory of the property sheet file. So the first thing is that the directory of the property sheet is added to the include path. This must, of course, fit to the folder structure. Secondly, the project reference to the project ImageLibrary is added. Here is, besides the path, also necessary to add the ProjectGuid, which I just copied from the ImageLibrary.vcxproj file (ID which will be automatically created from Visual Studio for each new solution).

To use the ImageLibrary project from the ParentProject two things need to be done:

  1. Add the ImageLibrary project to the solution. This can be achieved with right click on SolutionAddExisting project.
  2. Add the ImageLibrary.props file to the parent project (this step adjusts the include path and the project reference). This can be done in the Property Manager.

There are two steps because the first adjusts the solution file and the second the project file.