= Plugins = ''Authors: Francois Tadel'' Brainstorm connects with features from many third-party libraries of methods. The external software can be downloaded or updated automatically by Brainstorm when needed. This tutorial presents the API to register and manage plugins. <> == Interactive management == The Brainstorm interface offers menus to Install/Update/Uninstall plugins. {{attachment:example1.gif}} '''Install''': Downloads and unzips the package and all its dependencies in the Brainstorm user folder:''' '''<
>$HOME/.brainstorm/plugins/ '''Uninstall''': Deletes the plugin folder, all its subfolders, and all the other plugins that depend on it. '''Load''': Adds all the subfolders needed by the plugin to the Matlab path, plus other optional taks. Loading a plugin causes the recursive load of all the other plugins required by this plugin. '''Unload''': Removes all the plugin folders from the Matlab path, and all the plugins that depend on it. '''Update''': Some plugins are designed to update themselves automatically whenever a new version is available online, or requested by Brainstorm. Others plugins must be updated manually. Updating is equivalent to uninstalling without removing the dependencies, and then nstalling again. '''Manual install''': If you already have a given plugin installed on your computer (eg. FieldTrip, SPM12) and don't want Brainstorm to manage the download/update or the Matlab path for you, reference it with the menu: '''Custom install''' > Set installation folder. '''List''': You can list all the installed plugins with the menu List: {{attachment:list.gif||width="544",height="156"}} == Command-line management == The calls to install or manage plugins are all documented in the header of '''bst_plugin.m''': <)>><><)>> == Plugin definition == The plugins registered in Brainstorm are listed in '''bst_plugin.m''' / '''GetSupported'''. Each one is an entry in the PlugDesc array, following the structure defined in '''db_template('plugdesc')'''. The fields allowed are described below. Mandatory fields: * '''Name''': String: Plugin name = subfolder in the Brainstorm user folder * '''Version''': String: Version of the plugin (eg. '1.2', '21a', 'github-master', 'latest') * '''URLzip''': String: Download URL, zip or tgz file accessible over HTTP/HTTPS/FTP * '''URLinfo''': String: Information URL = Software website Optional fields: * '''AutoUpdate''': Boolean: If true, the plugin is updated automatically when there is a new version available (default: false). * '''Category''': String: Sub-menu in which the plugin is listed * '''ExtraMenus''': Cell matrix {Nx2}: List of entries to add to the plugins menu * ExtraMenus{i,1}: String: Label of the menu * ExtraMenus{i,2}: String: Matlab code to eval when the menu is clicked * '''TestFile''': String: Name of a file that should be located in one of the loaded folders of the plugin (eg. 'spm.m' for SPM12). This is used to test whether the plugin was correctly installed, or whether it is available somewhere else in the Matlab path. * '''ReadmeFile''': String: Name of the file to display after installing the plugin. Text filename, (relative to the plugin path) - If empty, try using brainstorm3/doc/plugin/_readme.txt * '''LogoFile''': Logo filename (relative to the plugin path) - If empty, try using brainstorm3/doc/plugin/_logo.[gif|png] * '''MinMatlabVer''': Minimum Matlab version, as returned by bst_get('MatlabVersion') * '''RequiredPlugs''': Cell-array of required plugin names, to install/load before this one: {Nx2}=>{'plugname','version';...} or {Nx1}=>{'plugname';...} * '''UnloadPlugs''': Cell-array of incompatible plugin names, to remove from path before adding * '''LoadFolders''': Cell-array of subfolders to add to the path when setting the plugin up (use {'*'} to load all subfolders) * '''GetVersionFcn''': String to eval to get the version (after installation) * '''InstalledFcn''': String to eval or function handle to call after installing the plugin * '''UninstalledFcn''': String to eval or function handle to call after uninstalling the plugin * '''LoadedFcn''': String to eval or function handle to call after loading the plugin * '''UnloadedFcn''': String to eval or function handle to call after unloading the plugin Fields set when installing or loading the plugin: * '''SubFolder''': If all the code is in a subfolder: detect this at installation time * '''Path''': Set at runtime: Installation path for this plugin * '''Processes''': List of process functions to be added to the pipeline manager * '''isLoaded''': Set at runtime: 0=Not loaded, 1=Loaded (folder and specific subfolders added to Matlab path) * '''isManaged''': Set at runtime: 0=Installed by the user, 1=Installed automatically by Brainstorm