Plugins

From emergent
Jump to: navigation, search
Emergent Logo
Main Developer Docs

IMPORTANT NEWS for updating plugins to version 7.0.0 and higher, and version 6.2 and higher -- see Plugins v7.0 and Plugins v6.2

Emergent can be extended via user-written libraries called plugins.

See Plugin development for more details and background information about plugins and how to develop them.

Potential Plugin Applications

  • New extensions to network algorithms (e.g., new learning rules, activation functions, etc)
  • Data generation
  • Input patterns
  • Analyzing output
  • Wizards - help w/ build/optimize proj

Creating a Plugin

The easiest way to create a plugin is to use the Plugin Wizard

  1. Open emergent; select the PluginWizard in the root window browser tree under .wizards
  2. enter a plugin name
  3. choose the type: User (installed only for current user) or System (installed for all users) (Pick User if uncertain)
  4. choose a location for the plugin files -- can be put anywhere -- generally NOT within the main emergent code base and NOT in the final plugin install directory
  5. press the Validate button -- this insures the name of the plugin and its basic classes will not conflict with existing classes
  6. press Create to create the initial plugin files from a standard template
  7. press Compile to actually build the plugin (this won't do anything useful to begin with, but makes sure everything is working and ready to go)
    ...check the console for environment setup warnings when this test compilation is run.
  8. edit the <plugin_name>.h and <plugin_name>.cpp files in an editor or press Editor to use the simple editor built into emergent
  9. build and test the plugin

Building Plugins

The Compile button in the Plugin Wizard is the simplest way to build the plugin initially -- this runs the CMake steps for the currently-running emergent configuration (see Running CMake Manually below).

For Windows users, you will need to make sure the plugin_make_env_cmd command in the emergent Options is set correctly for your Microsoft Visual Studio build environment. Note that the prepackaged emergent 5.3.0 version is compiled under Visual C++ 2010 (VC++ 10), so plugins which will be used in emergent 5.3.0 should also be compiled under VC++ 10 -- see Build_(Win) for more details.

plugin_make_env_cmd call "C:\Program Files\Microsoft Visual Studio 10.0\VC\vcvarsall.bat" x86
  • change last argument to either x86 for a 32-bit platform or x64 for a 64-bit platform:

Make sure the Environment variables are set properly if building in a non-standard location.

Compile from PluginWizard vs. Compile from Plugin Object

When compiling a plugin from within the emergent GUI, there can be some confusion between the PluginWizard view of a plugin, and the actual plugin object that appears in the plugins group in the root object after a plugin has been built. The PluginWizard only directly knows about the original source code location of the plugin, whereas the plugin object in the root object only directly knows about the installed version of the plugin. When a plugin is built from the source code by the wizard, the compiled object code is installed into a specific location (depending on whether it is specified as a User or System plugin), and a copy of the source code is also installed into the same specific location. Thus, it is always possible to rebuild a plugin from source, because the source code follows the compiled object around.

However, the presence of two copies of the source code can cause some confusion. In particular, the plugin object Compile button (on the plugin object itself) only re-builds from the installed library source, not the original source code. In contrast, the PluginWizard Compile command builds from the original source code, and should be used if you are actually editing the code. You can just use the LoadWiz button on the plugin object to get back to the PluginWizard interface for the object, where you can edit and recompile the original source.

In short:

  • if you're modifying the source, do Compile from the PluginWizard
  • if you're just rebuilding already installed code, you can Compile from the plugin object under .plugins

Running CMake Manually

For Linux/Mac users, just run the configure script (no need to pass any arguments unless doing something special)

bash configure [--debug] [--prefix=User|System]
cd build
make
[sudo] make install      # sudo needed if a System install

(note: run the configure command without any options to see a listing of the various other lower-frequency options that it supports)

For Windows users, you'll need to use the CMake system directly (other platforms are welcome to do this too). Open a command console (must be a Visual Studio command console in Windows), and enter the following command in the main source code directory for the plugin (the QT arg is required for emergent8 until the default is changed in the configure script - other args are optional, except that Windows users need the -G "NMake Makefiles", and Linux/Mac users use 'make' instead of 'nmake'):

cd C:\src\emergent\build
set EMERGENTDIR=C:\Program Files\Emergent
cmake ..\ -G "NMake Makefiles" [-DQT_USE_5=ON] [-DCMAKE_BUILD_TYPE=Debug|Release] [-DEMERGENT_PLUGIN_TYPE=User|System]  
nmake
nmake install

The EMERGENT_PLUGIN_TYPE (--prefix in the configure script) specifies where to install the plugin (See Plugin directories):

  • User: install the plugin to your user area (recommended and default value) -- the plugin will only be available to you, not to other users on your system.
  • System: install the plugin to your emergent system area -- the plugin will be available to everyone on the system, but you will need superuser privileges to install and update it.

Using Emergent Command Line to Make/Clean All Installed Plugins After Source Update

VERY IMPORTANT: Plugins are only loaded when run from the final installed location, because plugins are built against the installed version of the code -- if you run from the source compile version prior to install, it will not load plugins, and all the following functions similarly only work when run from the installed location.

Emergent can recompile all of the installed plugins (from the installed plugin source code), which is a good idea after you or your sysadmin has installed a new version of code. Use the following emergent command:

emergent --make_all_plugins     
# other emergent options: 
#   emergent --make_all_user_plugins 
#   emergent --make_all_system_plugins 
#   emergent --make_user_plugin <plugin name> 
#   emergent --make_system_plugin <plugin name>

[optional] Similarly, if you are compiling the main emergent code base from source, you can also use make commands built into the make system to recompile the plugin -- do this only after make install:

make plugins    
# use nmake for Windows. This calls emergent --make_all_plugins 
# other make options: 
#   make user_plugins (calls emergent --make_all_user_plugins)
#   make system_plugins (calls emergent --make_all_system_plugins)

To remove any installed plugins (clean), use the following emergent command:

emergent --clean_all_plugins   
# other emergent options: 
#   emergent --clean_all_user_plugins 
#   emergent --clean_all_system_plugins

[optional] Similarly, the installed plugins can be removed (clean) using the following make commands:

make clean_plugins 
# use nmake for Windows. This calls emergent --clean_all_plugins
# other make options: 
#   make clean_all_user_plugins (calls emergent --clean_all_user_plugins) 
#   make clean_all_system_plugins (calls emergent --clean_all_system_plugins)

The clean commands only remove the compiled plugin object (library file) -- they do not remove the installed source code, so the plugins can be rebuilt from source later if desired.

Enabling and Disabling Plugins

When a plugin is first encountered, it is listed in the .plugins folder in the root browser window (left browser -- just click open the .plugins directory to see it), but is not enabled by default. This is to provide user control, security, and to help avoid adding unexpected plugin dependencies to projects. In addition, some plugins could have additional system dependencies not established until they are loaded, which could cause problems if the dependencies are not available.

To enable a plugin from within the emergent GUI, do the following:

  • navigate to the plugin entry, to make its properties available in the editor
  • check the enabled checkbox
  • (repeat for as many plugins as desired)
  • close and reopen the application

To disable a currently enabled plugin from within the emergent GUI, do the following:

  • navigate to the plugin entry, to make its properties available in the editor
  • uncheck the enabled checkbox
  • (repeat for as many plugins as desired)
  • close and reopen the application

Using Emergent Command Line to Enable/Disable All Installed Plugins

The emergent command line can be used enable or disable all of the installed plugins. Following an emergent update, all user and system plugins encountered are automatically disabled, and should be recompiled before they are re-enabled.

To enable all installed plugins (useful after updating emergent and/or recompiling plugins), use the following emergent command:

emergent --enable_all_plugins

To disable all installed plugins (can be useful when debugging), use the following emergent command:

emergent --no_plugins

Viewing Plugin Status

There are three key parameters associated with a plugin:

  1. whether it is available
  2. whether it is enabled
  3. whether it is loaded
  • available plugins exists and are functioning, ie., it has been probed.
  • enabled plugins have been set by the user to be enabled -- note though that it can only be actually loaded if it available.
  • loaded plugins are available, enabled, and have been successfully integrated in the temt/emergent type system and application.

To view a plugin's status, do the following:

  • navigate to the plugin entry in the root browser view (this will make its properties available in the editor panel)
  • view the properties in the editor panel

To get a list of all installed plugins, use the following emergent command:

emergent --list_plugins
0: "ExamplePluginName"  "enabled/disabled"  "plugin description"  "plugin unique ID"  "plugin version"  "path and filename for compiled plugin"
1: "ExamplePluginName"  "enabled/disabled"  "plugin description"  "plugin unique ID"  "plugin version"  "path and filename for compiled plugin"

Plugin Load Log

The plugin loading process creates a log each time the application starts. It saves the content of this file after making each entry, so if the application is crashing, it is likely caused by the most recent action. The log contains lines of the forms "about to..." and "status of..." for each action, so if there is no status message after an "about to" message, it is likely that plugin causing the crash.

The plugin log can be found, depending on the platform:

  • Windows: <user folder>\Emergent\log\plugins.log
  • Mac: ~/Library/Emergent/log/plugins.log
  • Linux: ~/lib/Emergent/log/plugins.log

Troubleshooting

Here's some steps for solving plugin problems:

  • if emergent is crashing when trying to probe plugins, start emergent using the --no_plugins startup argument
  • do emergent --make_all_plugins or hit the MakeAllPlugins button in the PluginWizard (or individually Compile specific plugins in the .plugins section of the root) to rebuild plugins -- often solves problems by making sure the plugin is up-to-date
  • look into the plugin load log (plugins.log described above) when things don't seem to be working properly (e.g., you can't get a plugin to be enabled) -- the log often has useful specific information.