For the impatient

• Download the ​stable branch source zip
• Build HeuristicLab.ExtLibs.sln then build HeuristicLab 3.3.sln

For the not so impatient, this quickstart covers how to obtain and set up the development environment in order to extend HeuristicLab with new plugins. If you have troubles please check the FAQ.

Obtaining the source

We will use the sources of the current stable build as these can be built without any prerequisites. You require a current version of Visual Studio or SharpDevelop and the .NET framework.

• Download the ​stable branch source zip
• Unpack it into the folder HeuristicLab\stable somewhere on your hard drive

We will refer to the HeuristicLab folder as HLRoot, likewise we'll call the stable folder StableRoot. The explorer should look like in the image to the right.

Building HeuristicLab

Important: HeuristicLab is split into two solutions. The one that rarely changes and needs to be built first is called HeuristicLab.ExtLibs.sln. The second one that changes more often is called HeuristicLab 3.3.sln. The rest can be ignored for now. Both solutions build into a common bin folder directly inside StableRoot. All assembly references to plugins that are not projects of the same solution reference assemblies in that bin folder. Read that again.

Option 1: Using the Build.cmd script

If you have Visual Studio 2012 or later installed you can use the Build.cmd script in StableRoot.

• Double click Build.cmd and type the number associated with HeuristicLab.ExtLibs.sln

Then hit <Enter> and each time it prompts again. Default options are given in brackets [].

• Double click Build.cmd again and type the number associated with HeuristicLab 3.3.sln

You now have built HeuristicLab and its plugins into StableRoot\bin.

Option 2: Using an IDE

Building using Visual Studio or SharpDevelop requires that you build the solutions in the correct order. The HeuristicLab 3.3.sln is quite large, please be patient until it is loaded. Solutions in Visual Studio can be built by pressing <F6>, in SharpDevelop the shortcut is <F8>.

• Open and build HeuristicLab.ExtLibs.sln
• Open and build HeuristicLab 3.3.sln

Adding a shortcut

It is convenient to add a shortcut to the HeuristicLab.exe file that directly starts the Optimizer and bypasses the starter window.

• Create a shortcut from StableRoot\bin\HeuristicLab.exe by right-clicking it and choosing "Create Shortcut"
• Open the properties of the new shortcut by right-clicking it
• Append the following switches /start:Optimizer /hideStarter to the "Target" box
• Move the shortcut to HLRoot or another convenient place and rename it to "HeuristicLab 3.3 Optimizer"

Creating a new plugin

We now want to extend the functionality of HeuristicLab.

• Create a new folder extension in HLRoot

New plugin with Visual Studio

• Open a new instance of Visual Studio 2012 or later
• Select "File > New > Project..." or press <Ctrl+Shift+N>
• In the dialog on the top select ".NET Framework 4"
• On the right choose "Other Project Types > Visual Studio Solutions" and select the "Blank Solution" template or alternatively type "Blank Solution" in the search box on the right
• Use "GreatIdea" as Name and click "Browse..." to select the extension folder and click Ok
• In the Solution Explorer right-click the "GreatIdea" solution and select "Add > New Project..."
• On the right choose "Visual C#" and select the "Class Library" template
• As name pick "HeuristicLab.GreatIdea.ThePlugin"

You're presented with a minimal project set up for developing a new class library (dll). Before we continue we want to adjust the project configuration to make development convenient.

• Open the project properties and go to "Build"
• Change the first box from "Active (Debug)" to "All Configurations"
• Enter ..\..\..\stable\bin in the output path
• Then click on "Debug" on the left, choose "Start external program" and select HeuristicLab.exe inside StableRoot\bin - this setting is stored in the .csproj.user file
• Then click on "Signing" on the left, activate "Sign the assembly" and create a new key
• Call it "TheKey", but deselect the password option
• Save the project and close the properties

This ensures that the generated plugin is automatically added as a plugin to the HeuristicLab build and that we can use our solution to start a debugging session (shortcut <F5>). Now, we want to make this class library a HeuristicLab plugin. This requires that we include a special class that designates this dll to be a plugin.

• For the project add a reference to HeuristicLab.PluginInfrastructure.dll in StableRoot\bin
• Open the properties of the reference and set "Copy Local" to false
• Rename Class1.cs to Plugin.cs by selecting it and pressing <F2>
• Replace the code in the file with the following code snippet

using HeuristicLab.PluginInfrastructure;

namespace HeuristicLab.GreatIdea.ThePlugin {
  [Plugin("HeuristicLab.GreatIdea.ThePlugin", "Provides an implementation of a great idea", "3.3.9.0")]
  [PluginFile("HeuristicLab.GreatIdea.ThePlugin.dll", PluginFileType.Assembly)]
  public class Plugin : PluginBase {
  }
}

Important: The plugin class needs to derive from HeuristicLab.PluginInfrastructure.PluginBase so that the dll is realized as a plugin. The attributes specify the details of the plugin and which files it provides. The filename given in PluginFile has to be the same as the assembly output filename in the "Application" tab of the project's properties.

Important: Version numbers for plugins can be specified in the style major.minor.build.revision. Changing major or minor version numbers in the course of development marks a breaking change to files. If HeuristicLab's persistence comes across an item saved with a plugin version of 3.3.8 it will accept a new plugin of 3.3.9 to open it, but not when the new plugin version is 3.4.0 or 4.0. For this reason HeuristicLab plugin assemblies are always marked with major and minor number at the end, e.g. HeuristicLab.Core-3.3.dll. This allows to have the same assembly in two conflicting versions.

New plugin with SharpDevelop

We can now build HeuristicLab and extends it with own plugins. Below are some remarks for experienced developers.

For the experienced

At some point it might be beneficial for you to build against the code in our SVN repositories. The advantage is that you can update it and get new features as we release them. Also you will get notice of breaking changes to our API earlier. You'll have to install ​Tortoise SVN because the build process makes use of one of its tools (SubWCRev). You need to have the binary path (bin) of TortoiseSVN (usually C:\Program Files\TortoiseSVN\bin) in your PATH environment variable. Changing the PATH variable requires you to re-login to your Windows account to put them into effect.

• Stable branch: ​http://dev.heuristiclab.com/svn/hl/core/stable (recommended, tested and reviewed changes only)
• Main trunk: http://dev.heuristiclab.com/svn/hl/core/trunk/sources (not recommended, frequent and unreviewed changes, moderate testing)