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>