Defining Include Projects

Include projects allow you to specify a set of C# files and / or other resources which should be included in projects that reference the include project. This allows libraries to include additional code or resources into executables that use them.

For example, a library may provide a default main entry point for programs using that library, so that the developer does not have to manually configure application start up (unless they want to). The library can define an include project which is then pulled in by the application so that the main entry point class is defined in the correct (executable) assembly.

Project structure

A simple example of an include project definition is shown below.

<?xml version="1.0" encoding="utf-8" ?>
<IncludeProject Name="MyInclude" Path="MyInclude">
  <Files>
    <Compile Include="SomeClass.cs" />
    <Compile Include="AndroidOnly.cs">
      <Platforms>Android</Platforms>
    </Compile>
    <Compile Include="CustomLinkPath.cs">
      <Link>CustomLinkPath.cs</Link>
    </Compile>
  </Files>
</IncludeProject>

Project definition location

All project definitions for your module should be placed under the Build\Module directory and have a .definition extension. The name of the project should match the name of the file as well; for a project called “MyProject”, the project definition should reside at Build\Module\MyProject.definition.

Tip

This is the location for all project definitions, including application, console, library, content, include and external projects.

Including files

Declaring files for inclusion in an include project uses the exact same structure used in application, console and library projects, including the ability to declare files for specific platforms or services.

See Declaring files for documentation on how to declare files in a project.

Referencing include projects

Referencing include projects works like any other Protobuild project, either from an application, console or library project:

<?xml version="1.0" encoding="utf-8"?>
<Project Name="MyApplication" Path="MyApplication" Type="App">
  <References>
    <Reference Include="System" />
    <Reference Include="System.Core" />
    <Reference Include="MyInclude" />
  </References>
  <Files>
    <Compile Include="Program.cs" />
  </Files>
</Project>

or from an external project:

<?xml version="1.0" encoding="utf-8" ?>
<ExternalProject Name="MyExternal">
  
  <!-- Reference to a Protobuild include project -->
  <Reference Include="MyInclude" />
  
</ExternalProject>

Apply include projects as extensions

Rather than declare an include project as a reference in a normal project, you can also use the AppliesTo attribute on the include project to specify that it should be applied to another project.

This allows you to define include projects that works as extensions - extending the functionality of another project that is not aware of your include project.

You can set the AppliesTo attribute on the IncludeProject node, like so:

<?xml version="1.0" encoding="utf-8" ?>
<IncludeProject Name="MyInclude" Path="MyInclude" AppliesTo="AnotherProject">
  <Files>
    <Compile Include="SomeClass.cs" />
    <Compile Include="AndroidOnly.cs">
      <Platforms>Android</Platforms>
    </Compile>
    <Compile Include="CustomLinkPath.cs">
      <Link>CustomLinkPath.cs</Link>
    </Compile>
  </Files>
</IncludeProject>

Limiting platforms

If you have an include project that you only want to apply when certain platforms are being generated for, you can use the Platforms attribute to restrict what platforms this include project is included for.

An example of using the Platforms attribute to restrict when an include project is included can be seen below.

<?xml version="1.0" encoding="utf-8" ?>
<IncludeProject Name="MyInclude" Path="MyInclude" Platforms="Windows,Linux">
  <Files>
    <Compile Include="SomeClass.cs" />
    <Compile Include="AndroidOnly.cs">
      <Platforms>Android</Platforms>
    </Compile>
    <Compile Include="CustomLinkPath.cs">
      <Link>CustomLinkPath.cs</Link>
    </Compile>
  </Files>
</IncludeProject>