Running your plug-ins

This document will describe the options available to you when running your newly written plug-ins with Opticks.

Two approaches to configuring Opticks to run your plug-ins will be presented. Following that is a more detailed section that describes all the necessary configuration for running Opticks. It is highly recommended that you read this entire document before deciding which approach is most appropriate for you.

Approach 1: Use an Opticks installation

This approach involves copying your plug-ins into an existing Opticks installation. The installers only provide a release mode build of Opticks. On Windows, you must use either the 32-bit or 64-bit install of Opticks, depending on whether you are building 32-bit or 64-bit plug-ins. On Solaris, we only provide a 64-bit binary. Also on Solaris, there is no distiction between debug and release, so you put either compilation type of your plug-in into a Solaris installation of Opticks. In order to use this approach on either Windows or Solaris, you need to perform the following steps:
  1. Copy your compiled plug-in (i.e. .dll or .so) into the PlugIns folder of the Opticks installation.
  2. Copy any third party dependency libraries (i.e. .dll or .so's that are not plug-ins) into the Bin folder of the installation.
  3. Copy any custom settings default files (i.e. *.cfg, see ConfigurationSettings) into the DefaultSettings folder of the installation.
  4. Copy any plug-in on-line help into the Help folder of the installation.
  5. Copy any product templates into the Templates folder of the installation.
  6. Copy any wizard files into either the Wizards folder of the installation or the SupportFiles/Wizards folder of the installation.
  7. Copy any other custom supporting data files into the SupportFiles folder of the installation.
  8. On Windows, if you wished to run your plug-ins in debug mode, you would need to perform the following additional steps:
    1. Rename the existing Bin folder in the installation to Bin-release
    2. Rename the existing PlugIns folder in the installation to PlugIns-release
    3. Create a new Bin folder in the installation by copying either the SDK_HOME\Build\Binaries-Win32-Debug\Bin or SDK_HOME\Build\Binaries-x64-Debug\Bin folder depending on whether you are trying to run 32-bit or 64-bit plug-ins respectively.
    4. Create a new PlugIns folder in the installation by copying either the SDK_HOME\Build\Binaries-Win32-Debug\PlugIns or SDK_HOME\Build\Binaries-x64-Debug\PlugIns folder depending on whether you are trying to run 32-bit or 64-bit plug-ins respectively.
    5. Copy your compiled plug-in (i.e. .dll or .so) into the PlugIns folder that you just created in the installation folder.
    6. Copy any third party dependency libraries (i.e. .dll or .so's that are not plug-ins) into the Bin that you just created in the installation folder.
    7. At this point, you could run your plug-ins in debug mode. If you wished to revert back to running in release mode, you would have to reverse the above steps. Also, note that with this approach you cannot run debug mode and release mode simultaneously.

Approach 2: Create a custom workspace

This approach involves creating a custom workspace. You will need to perform the following steps:
  1. Create a new folder anywhere on the filesystem. This directory will be called WS_HOME from this point forward.
  2. Copy the DefaultSettings, Help, SupportFiles, Templates folders from an Opticks installation into the WS_HOME folder.
  3. Create a UserSettings folder in the WS_HOME folder.
  4. Create a Build folder in the WS_HOME folder.
  5. On Windows, perform the following steps:
    1. If you will run plug-ins in release 32-bit mode, then copy the Bin and PlugIns folder from SDK_HOME\Build\Binaries-Win32-Release into WS_HOME\Build\Binaries-Win32-Release folder.
    2. If you will run plug-ins in debug 32-bit mode, then copy the Bin and PlugIns folder from the SDK_HOME\Build\Binaries-Win32-Debug into WS_HOME\Build\Binaries-Win32-Debug folder.
    3. If you will run plug-ins in release 64-bit mode, then copy the Bin and PlugIns folder from the SDK_HOME\Build\Binaries-x64-Release into WS_HOME\Build\Binaries-x64-Release folder.
    4. If you will run plug-ins in debug 64-bit mode, then copy the Bin and PlugIns folder from the SDK_HOME\Build\Binaries-x64-Debug into WS_HOME\Build\Binaries-x64-Debug folder.
  6. On Solaris, perform the following steps:
    1. Copy the Bin and PlugIns folder from an Opticks installation into the WS_HOME/Build/Binaries-solaris-sparc-release folder.
  7. For both Windows and Solaris, perform the following steps:
    1. Create a opticks.dep file (it must be named exactly this) in all the Bin folders you have created thus far in the WS_HOME/Build/Binaries-* folders with the content shown below.
         !depV1
         deployment:
            UserConfigPath: ../../UserSettings
            AppHomePath: ../..
         
      For more details on the opticks.dep file, please see Using deployment files to control the plug-in path, support files, default settings and user settings .

Once you have created this workspace, you would copy any custom plug-ins into the appropriate PlugIns folder. The advantage of this approach is that this workspace is entirely self-contained. This means that you can follow this procedure as many times as you wish on a single computer even using the same version of Opticks and each WS_HOME you create will not interfere with any WS_HOME you've created on the same machine. This approach also has the advantage that you can easily switch between debug and release on Windows. All you need to do is run the Opticks.exe in the appropriate Build\Binaries-* folder, no other configuration is necessary to switch back and forth.

Additional notes about running Opticks

In general, when running Opticks there are two classes of things that Opticks requires to run properly. Opticks requires:
  1. Executable code
  2. Other supporting data
  3. User settings

The "Executable Code" consists of:

  1. The Opticks and OpticksBatch executable.
  2. Opticks plug-ins.
  3. Third-party dependency libraries.

The first and third items should reside in the same folder, for an Opticks installation this is the Bin folder. The plug-ins need to all reside in a single folder, for an Opticks installation this is the PlugIns folder. The location of the PlugIn folder is controlled by the "PlugInPath" setting in the deployment file. You can read Using deployment files to control the plug-in path, support files, default settings and user settings to determine the default location Opticks searches for plug-ins if a deployment file is not present along with documentation on how to provide a custom deployment file.

The "Other supporting data" consists of:

  1. DefaultSettings
  2. Help
  3. Templates
  4. SupportFiles

The DefaultSettings and Help must always be located in the folder specified by the "AppHomePath" setting in the deployment file. You can read Using deployment files to control the plug-in path, support files, default settings and user settings to determine the default location Optick uses for the "AppHomePath" along with ways to change that path.

The Templates and SupportFiles are controlled by ConfigurationSettings. Specifically ProductView::getSettingTemplatePath(), ProductView::setSettingTemplatePath(), ConfigurationSettings::getSettingSupportFilesPath(), ConfigurationSettings::setSettingSupportFilesPath(). This means that each individual user that runs Opticks can have a custom SupportFiles and Template path just for their user account. By default, this does not occur. In a traditional installation, the SupportFiles defaults to AppHomePath/SupportFiles and Templates defaults to AppHomePath/Templates. If the user wants to change the paths, they can use "Tools\Options..." in the application.

The "User Settings" consist of a .cfg file that is saved to the disk during application shutdown. This file contains all of the setting values in ConfigurationSettings that have been overridden by the user, see ConfigurationSettings::isUserSetting(), ConfigurationSettings::setSetting() for more details. This file is saved to the folder specified by the "UserConfigPath" setting in the deployment file. You can read Using deployment files to control the plug-in path, support files, default settings and user settings to determine the default location Opticks uses for "UserConfigPath" along with ways to change that path. The user setting file is named according the following convention, "UserSettings-[version]-[operating system]-[arch][mode].cfg" In practice this means that all Opticks installations on the same machine that use the same "UserConfigPath" that have the same arch (e.g. 32-bit, 64-bit) and mode (e.g. debug, release) will share one user settings file. This can cause confusion and the solution to this problem is to use a deployment file to specify a different value for the "UserConfigPath" for the problematic installations.


Software Development Kit - Opticks 4.9.1 Build 16498