wiki:UsersHowtosImplementPlugins
Last modified 6 weeks ago

  1. How to ... create HeuristicLab plugins (in more detail)
    1. 1. Create a new C# class library project
    2. 2. Adjust the project properties
      1. Output and Reference Path
    3. 3. Use the configuration manager
    4. 4. Create frame files
    5. 5. Configuring the plugin file
    6. (6. HL Core Developers only)
    7. 7. Additional Remarks

How to ... create HeuristicLab plugins (in more detail)

This quick guide will help you to develop your own HeuristicLab plugins. We are assuming that you are using Visual Studio 2010 as development environment.

1. Create a new C# class library project

such as HeuristicLab.Problems.Mine. Adjust the folder structure so that your project file is located in \HeuristicLab.Problems.Mine\3.3\HeuristicLab.Problems.Mine-3.3.csproj.

2. Adjust the project properties

  • The class library name should be post-fixed with the major and minor version number, such as HeuristicLab.Problems.Mine-1.0
  • The default namespace should not contain version information
  • Target Framework: 4.0 (Attention: VS 2010 will set the default target framework to client profile version for new projects, plugins need to be targeted to the full framework however)
  • Optional pre-build events: If you have your code checked in to an SVN repository and you're using .frame files for automatic versioning (such as in trunk) you need to call SubWCRev on your frame files before building. Check another plugin to see how this can be achieved. Note that you need the PreBuildEvent.cmd in a location accessible during the build process.

Output and Reference Path

All HeuristicLab projects are built to one single folder which is \trunk\sources\bin\ (or as configured in the project properties: ..\..\bin\). This speeds up build time as it saves one copy operation per project. The advantage is also that you can have multiple branches which reference and build into this folder. Therefore you have to change the Output path in the project properties to ..\..\bin\ if your project resides in sources or adapt it to the location of your project (e.g. ..\..\..\..\trunk\sources\bin\ if you are developing a branch).

If you are working within the HeuristicLab solution, you can reference other projects as you need them. If you are working in your own solution, reference the assemblies from \trunk\sources\bin\. In both cases, if you add references, switch the Copy local option in the Properties of the reference to false (again to reduce build time).

3. Use the configuration manager

Create configurations for debug and release builds and all platforms (Any CPU, x86, x64).

4. Create frame files

Each HeuristicLab Plugin has two frame template files, AssemblyInfo.frame and !Plugin.cs.frame. We use these .frame files and SubWCRev to automatically convert those into .cs files and add the repository version number to the revision-version. You can also do this if you have your source code checked in to an SVN repository, or you just use the Properties\AssemblyInfo.cs and Plugin.cs file from another project and adapt to your plugin. Note that for HL core developers having the frame files is mandatory.

  • AssemblyInfo.frame
    • AssemblyVersion --> if this one changes all dependent plugins must be built as well
    • AssemblyFileVersion --> not relevant for build process
  • !Plugin.cs.frame
    • Used to replace build number on SVN commit; You need to add your project to subversion for the build to work.
  • HL Core Developers: Set subversion properties to exclude AssemblyInfo.cs and !Plugin.cs on commit

5. Configuring the plugin file

  • Plugin attribute [Plugin("HeuristicLab.Problems.Mine", "1.0.0.#revision#")]
  • PluginDependencies --> Please make sure that you list all referenced plugins.
    • Version numbers: At least major and minor, maybe build number too. Major and minor must be the same, for build and revision higher values are also accepted by the PluginInfrastructure.

(6. HL Core Developers only)

Attention HL Core Developers:

New functionality should be developed in a branch and not in the trunk. The merge back into the trunk will occur, after a new feature reaches maturity. This requires at least a code review and clearance by head developer Stefan Wagner!

This section is only relevent of you are working in the main development trunk:

  • Add your project to the build dependencies of the HeuristicLab-3.3 project to ensure that your project is also built on every rebuild (Right click on the solution, Properties, Project Dependencies, select the HeuristicLab-3.3 project)
  • Add your plugin as a reference to the HeuristicLab.Tests project and to the Builder.testsettings so that the build server can run unit tests on your plugin.
  • Sign the project with the HeuristicLab Key
  • Don't forget the license headers!
  • If you want to add a custom resource (say, an image), it belongs into HeuristicLab.Common.Resources. Mail Stefan W. if you require custom resources. Note that the image should not have license restrictions that are incompatible with the GPL.

7. Additional Remarks

  • Make sure types and the namespaces they are defined in are not named equally.