Plugins

Plugins

NCrystal release v2.2.0 (December 2020) introduces support for plugins. This is mainly intended to provide a mechanism with which one can extend the existing NCrystal features, for instance by introducing new or alternative physics models, or adding support for new file formats.

The wiki page PluginsDevelopment contains information for people who would like to develop new plugins. Each plugin will be developed in a separate git repository and have a unique name. To enable a given plugin there are two approaches, dynamic and static, as explained in the following sections. For debugging purposes, the command nctool --plugins can be used to print a list of enabled plugins (NOTE: the nctool command was formerly known as ncrystal_inspectfile).

Dynamic plugins

After having installed NCrystal, the plugin is compiled separately (against that NCrystal installation). This creates a shared library file for the plugin, which must be added to the environment variable NCRYSTAL_PLUGIN_LIST (multiple entries in this list must be separated by a colon, :). At runtime NCrystal will go through the shared libraries in this list, load them and call special symbols inside them to activate the plugins. An example shell command which adds a given plugin would be:

export NCRYSTAL_PLUGIN_LIST="/path/to/somewhere/libNCPlugin_myplugin.so:$NCRYSTAL_PLUGIN_LIST"

Static (builtin) plugins

Plugins can also be compiled directly into a given NCrystal installation. This is technically done by using the CMake configuration variable -DBUILTIN_PLUGIN_LIST="<pluginlist>", where <pluginlist> is a semicolon (;) separated list of plugin locations. Each plugin location can be either:

1. Local filesystem path to the root of a plugin repository (e.g. cloned from github, or perhaps downloaded as a tar-ball and unpacked).
2. A git repository URL, optionally followed by ::<gitref> where <gitref> is a git branch name, commit hash or tag (will default to main if not specified).
3. Shorthand for GitHub repos: username:pluginname. This is expanded to https://github.com/<username>/ncplugin-<pluginname>.git.

Examples:

• /some/where/ncplugin-FunnyStuff (local directory with git-clone or unpacked tar-ball of FunnyStuff plugin)
• https://github.com/jchadwick/ncplugin-CoolStuff.git (HEAD of main branch in jchadwick's CoolStuff plugin repo)
• https://github.com/jchadwick/ncplugin-CoolStuff.git::develop (HEAD of develop branch in jchadwick's CoolStuff plugin repo)
• jchadwick:CoolStuff (HEAD of main branch in jchadwick's ncplugin-CoolStuff plugin repo at GitHub)
• jchadwick:CoolStuff::develop (HEAD of develop branch in jchadwick's ncplugin-CoolStuff plugin repo at GitHub)
• jchadwick:CoolStuff::dc010317a (commit dc010317a in jchadwick's ncplugin-CoolStuff plugin repo at GitHub)

So when configuring NCrystal with CMake, one might specify this like:

cmake <other options here> -DNCRYSTAL_BUILTIN_PLUGINS="jchadwick:CoolStuff::develop;/some/where/ncplugin-FunnyStuff;jchadwick:AmazingStuff"

Which plugins are available?

At the time of writing (Dec. 2020), there are no plugins available yet, which is of course not surprising since the plugin support is only introduced now :-)

But it is the hope that people will be interested in developing plugins, and do so according to the official recommendations. If so, plugins should show up as forks of the ncplugin-template repo. The list of such forks can be browsed here.