Common and external libraries#
Not only do plugins make it easier to share new features with other users, they can also take advantage of a wide array of C++ libraries without adding new dependencies to the host application. While there are many plugins that only rely on the Open Ephys Plugin API, JUCE, and the C++ standard library, in some cases it is essential to call functions from more specialized libraries. External libraries can add powerful features with minimal extra code.
Some examples of plugins that use external libaries include:
Neuropixels PXI (Neuropixels API)
ZMQ Interface (ZeroMQ)
It’s also possible to create a custom library that can be used by multiple plugins, or to wrap an existing library in a way that makes it easier to use with the Open Ephys GUI. These “Common Libraries” are Open Ephys-specific libraries that can be used by any plugin built using the Plugin API.
Some examples of common libraries and plugins that use them include:
- OpenEphysHDF5Lib (Common Library)
- OpenEphysFFTW (Common Library)
This page will demonstrate how to use common libraries and external libraries in your plugins. These instructions assume you have already compiled the Open Ephys host application. If you haven’t done that yet, follow the instructions on this page.
Common libraries#
The first step in creating a new common library is to create a repository from the OECommonLib template.
Log in to your GitHub account.
Browse to the Common Library template repository.
Click the green “Use this template” button and choose the “Create a new repository” option.
Choose a name for your common library. It should succinctly capture the library’s functionality.
Click the green “Create repository from template” button.
On your local machine, create an “OEPlugins” directory within the same directory that contains your plugin-GUI repository: Then, using the command line or the GitHub Desktop app, clone your the common library repository into this new folder. Your directory structure should look something like this:
OEPlugins
└─ CommonLib
├─ Build/
├─ Source/
├─ CMakeLists.txt
├─ CMAKE_README.txt
├─ link_open_ephys_lib.cmake
└─ README.md
Modifying the source code#
The template repository already comes with the boilerplate code for the common library. You can start writing your code after changing all the class and file names to match your common library’s name.
#ifndef COMMONLIB_H_INCLUDED
#define COMMONLIB_H_INCLUDED
#include <CommonLibHeader.h>
namespace CommonLibrary
{
class COMMON_LIB LibraryClass
{
public:
LibraryClass();
~LibraryClass();
};
}
#endif
#include "CommonLib.h"
using namespace CommonLibrary;
LibraryClass::LibraryClass()
{
}
LibraryClass::~LibraryClass()
{
}
Note
For every class you want to export for use by plugins, you need to add the COMMON_LIB macro to the class declaration as demonstrated above.
Using the common library in a plugin#
For all the plugins that are going to use you common library, we first need to copy the link_open_ephys_lib.cmake script from the OECommonLib template repo to the plugin’s base directory. This script will find and link the common library that is specified when calling it. Then modify the plugin’s CMakeLists.txt file to include and run this script as follows:
include(link_open_ephys_lib.cmake)
link_open_ephys_lib(${PLUGIN_NAME} <common_lib_name>)
Now, when you build & install the common library and then build plugin, it will find the installed common library and link to it. After that, installing the plugin and loading it into the GUI should load the common library symbols that the plugin needs.
External libraries#
Header-only / Class Libraries#
These types of libraries are either a single header file or a set of C++ files with classes and functions defined in them. They do not need to be separately compiled, packaged, and installed in order to be used. All that is required is to copy the library files into your plugin’s source code directory (usually in a sub-folder), point the compiler to the location of the headers, and then #include the header files in any plugin source files that need to access the associated classes. Besides being easy to add to your plugin, header-only and class libraries make it possible for the compiler to optimize the code more effectively. They do have some drawbacks, however, including duplication of code, longer compilation time, and the fact that any changes to the library requires recompilation of all the source files that depend on it.
Examples of such libraries that are used by some the GUI or its plugins include:
cpp-httplib (header-only)
oscpack (class-based)