Plugin build files

(NOTE: This page is currenty deprecated and will be removed soon, a  new and automated way of creating Build files is available)

Plugin files are built independently from the core GUI. As such, they have their own Visual Studio projects on Windows, Makefiles for Linux, and Xcode projects for OS X.

Visual Studio Project

The "Plugins.sln" solution file located in "Builds/VisualStudio2013/Plugins" contains the projects for all default plugins. New plugins don't necessarily need to be included in this solution, but they must be configured correctly.

To generate a new plugin:

1. Create a new C++ Empty Project in Visual Studio by either adding it to the existing Plugins solution (right click on the Solution in the Solution Explorer, and select Add > New project) if its to be included in the Open Ephys main repository or in its own solution (File > New > Project), if it's going to be developed or distributed in a standalone way. Remember to give it name.
2. Add the .h and .cpp files, plus the OpenEphysLib.cpp file, to the "Source Files" folder of your project. If you don't have an OpenEphysLib.cpp file, copy one from another plugin and change the name, type, and creator fields. These files should live in the Source/Plugins/<PluginName> directory.
3. Create x64 build configurations for the project if they are not created automatically.
   1. Open the Configuration Manager (Right click on the project, select "Properties," and then click on the "Configuration Manager" button in the upper right)
   2. Select x64 as Active solution platform on the top of the screen. If it doesn't appear, select "New" and select x64 in "Type or select the new platform", "Win32" on "Copy Settings from" and Check the "Create new project platforms".
   3. In the project list, if when x64 is selected in "Active solution platform" it still shows "Win32" on the "Platform" column, click there and either select x64 or new with the same settings as the when creating the solution platform, except unchecking the "Create new project platforms" this time (as we're already creating them).
   4. Check that for all 4 build combinations (Debug Win32, Release Win32, Debug x64, Release x64) the "Configuration" and "Platform" columns of the project match with the "Active solution configuration/platform" and that the "Build" checkbox is checked in all four.
4. In the project properties pages window (Right click on the project, and select "Properties"), select "All configurations" in the "Configuration" field and "All platforms" in the "Platform" field and in "Configuration properties/General" set the "Project defaults/Configuration type" as "Dynamic Library (.dll)". In "Configuration Properties/C/C++/General", if "SDL checks" is set to "Yes", change it to "<inherit from parent or project defaults>". Save the changes immediately either by the OK or the Apply buttons.
5. Close the "Property Pages" window and open the "Property Manager" of VS (View Menu > Other Windows > Property Manager). Open your project and, for all four configurations, load (right click in the config, load existing property sheet) the corresponding ".props" file located on "Builds/VisualStudio2013/Plugins"

Note the following, in both cases:

• If additional libraries are needed for the specific plugin, add the required folders and libs in the "C++/General/Additional Include Directories", "Linker/General/Additional Library Directories" and "Linker/Input/Additional dependencies"
• To build plugins on Windows, VisualStudio needs the "open-ephys.lib" file generated when building the core GUI.
• The default settings, both by creating a new project or by copying the ExampleProcessor one, assume the plugin project is in the same places as the default ones. The properties that need to be changed if a different folder is used are the following:
  
  • C++/General/Additional Include Directories: Modify the path to the plugin headers to the actual one
  • Linker/General/Additional Library Directories; Change the "$(GUIDir)" macro with the path to the open-ephys.lib file for the desired architecture and configuration.
  • Build Events/Pre-Link Event & Post-Build Event; Change the "$(PluginDir)" macro with the destination path of the built plugin dlls (usually the "plugins" folder next to the open-ephys binary file)

Linux Makefile

The Makefile.plugins file residing in the Builds/Linux folder contains the basic configuration for building plugins on Linux. This Makefile automatically scans all folders located under "Source/Plugins" for those containing a Makefile and then uses them to build the different plugins.

The Makefile for every plugin is basically the same, with only slight variations if a particular plugin needs specific libraries or preprocessor definitions. We recommend using the Makefile.example located under the ExampleProcessor folder as a template.

This assumes that the plugin is being created inside the main source tree. If it were to be created in a standalone way, separate to the main GUI code, we recommend maintaining the specific plugin Makefile the same as the other, as it is generic in nature, and creating a new Makefile.plugins to build all your custom plugins in its new locations. It might just be a copy of the standard Makefile.plugins file with changes to the following macros:

• PLUGIN_DIR must point to the root folder of all your plugins
• OUTDIR for both Debug and Release must point to the point where the built plugins will be created
• In RESFLAGS and CPPFLAGS modify the header path so it points to the location plugin headers folder of the Open Ephys source code in your system

Other macros refer to intermediate files in the build process, modify them if needed according to your build structure.

Xcode Project

The folder Builds/MacOSX/Plugins contains Xcode projects for all default plugins.  Each project gets most of its build settings from shared Xcode configuration files in Builds/MacOSX/Plugins/Config.  All of the default plugin projects are included in the Xcode workspace Builds/MacOSX/OpenEphys.xcworkspace.  Building the "All" scheme in this workspace builds both the core GUI and all standard plugins.

To compile a new plugin on macOS, you must create an Xcode project for it.  The steps for creating this project are as follows:

1. If the new plugin will be part of the default set, open OpenEphys.xcworkspace.  Otherwise, just open Xcode.
2. Select File->New->Project.  In the dialog that pops up, choose macOS->Framework & Library->Bundle, and click Next.  Give your product a name (e.g. "ExampleProcessor"), then click Next.  A file selection dialog will pop up, allowing you to choose where the new project is created.  For non-default plugins, any location is fine.  Projects for default plugins should go in Builds/MacOSX/Plugins; also, in the "Add to" pop-up menu, select the OpenEphys workspace, then, in the "Group" menu that appears, select "Plugins".  Click Create, and Xcode should open the new project.
3. Select File->Add Files to "<your project name>" to add source files to the project. Click the Options button, and in the "Add to targets" section, uncheck all targets. This will ensure that the files are referenced, not copied. Then, click Add.

The next steps depend on whether the project is for a default plugin (included in the plugin-GUI source tree) or not.

Non-default Plugin

For non-default plugins, you need to manually add some build settings at the project level:

Once this is done, your plugin should compile successfully.

To install the plugin, copy the generated bundle (e.g. ExampleProcessor.bundle) to the folder ~/Library/Application Support/open-ephys/PlugIns, then restart the GUI.  The processor(s) provided by your plugin should now appear in the processor list.

Default Plugin

To simplify configuration management, all default plugin projects get (most of) their build settings from shared Xcode configuration files in Builds/MacOSX/Plugins/Config. To use these files with a new plugin project, follow these steps:

1. Go to File->Add Files to "<your project name>", and select the files Plugin_Debug.xcconfig and Plugin_Release.xcconfig in the Config folder. Click the Options button, and in the "Add to targets" section, uncheck all targets. Then, click Add.
2. Select the project file in Xcode, and navigate to the top-level "Info" panel for the project.  In the "Configurations" section, expand Debug and Release, and select the appropriate configuration file for each configuration (Plugin_Debug for Debug, Plugin_Release for Release).
3. Navigate to the project-level build settings.  Select "All" and "Levels".  Then, select all settings in the list, and press delete.  Once this is done, the column for project-level settings should be empty.
4. Navigate to the target-level build settings.  Delete all settings except "Info.plist File", "Product Bundler Identifier", and "Product Name".
5. (Optional) Add plugin-specific build settings (e.g. paths to external libraries) as needed.

The final step is adding the new plugin to the "All" scheme.  In the scheme selection drop-down menu, select "Manage Schemes", then double-click on the "All" scheme. Navigate to the Build section, and add the new plugin bundle to the list of targets.  (If desired, you can now delete the scheme that Xcode generated for the new plugin project.)