Setting up a build environment

Files:

The Opticks SDK provides a few files to help you set up a plug-in build environment.

The Dependencies directory contains a utility to automatically download Opticks dependencies. See the README.windows and README.solaris files for information on using this utility.

Plug-ins are distributed in dynamic modules (.dll files on Windows and .so files on Solaris) which can contain multiple plug-ins. In addition to plug-in source files, each module requires a ModuleManager.cpp file which acts as a factory for the plug-ins in the module. Below is the ModuleManager.cpp file for the tutorial.

/*
 * The information in this file is
 * Copyright(c) 2007 Ball Aerospace & Technologies Corporation
 * and is subject to the terms and conditions of the
 * GNU Lesser General Public License Version 2.1
 * The license text is available from   
 * http://www.gnu.org/licenses/lgpl.html
 */

#include "PlugInRegistration.h"

REGISTER_MODULE(OpticksTutorial);

Build Files

The Opticks SDK also provides utilities for building your modules.

Windows

The easiest way to build a module on Windows is to create a directory in the Opticks SDK Application/PlugIns/src directory. Create a Visual Studio 2010 project file for your plug-in. The Opticks SDK contains a number of Visual Studio property sheets in the Application/CompileSettings directory. They set various options required to build a plug-in. Some property sheets are required, others add optional functionality. Look in the tutorial project file and the various example plug-in project files for examples of which property sheets should be used. Some sheets have child sheets for specific configurations in which case, the child sheets should be used. Below is a list of common property sheets for the debug 32-bit configuration. Other configurations need to make appropriate substitutions.

Macros
Xerces-Debug
AllCommonSettings-Debug-32bit
PlugInCommonSettings
32bitSettings

You should remove most property overrides in the project files. See the example project files for more details. A common way to create a new project file is to copy an existing one. If you do this, there are a few things in the project file which need to be edited with a text editor before adding it to a Visual Studio solution. As an example, I'll copy the tutorial project file to MyModule.vcxproj. I open the new project file in a text editor such as notepad.exe and change the following lines.

    <ProjectGuid>{93926B8A-738B-4DEB-9045-AE7C0BB4ABD4}</ProjectGuid>

This GUID must be changed to a unique GUID. The "Create GUID" tool in Visual Studio can be used.

    <RootNamespace>Tutorial</RootNamespace>

This is generally the same as your project name and is used by Visual Studio when creating certain directories.

      <TypeLibraryName>.\Debug/Tutorial.tlb</TypeLibraryName>

Change the base name to match your project file base name. This line occurs multiple times in a project file, once for each configuration.

    <ClCompile Include="ModuleManager.cpp" />
    <ClCompile Include="Tutorial1.cpp" />
    <ClCompile Include="Tutorial2.cpp" />
    <ClCompile Include="Tutorial3.cpp" />
    <ClCompile Include="Tutorial4.cpp" />
    <ClCompile Include="Tutorial5.cpp" />
  </ItemGroup>
  <ItemGroup>
    <ClInclude Include="Tutorial1.h" />

You can remove the <ClCompile> and <ClInclude> entries for the old project's files now or you can remove them after you add the project to the solution.

Once you've made these changes, save the project file and add it to a Visual Studio solution. Make changes to the list of property sheets in the Property Manager inside Visual Studio. Add files for your module including a ModuleManager.cpp and build your plug-ins.

There are a few environment variables which are required for this build system to function.

OPTICKSDEPENDENCIES is an absolute path to the dependencies files.
OPTICKS_CODE_DIR is an absolute path to the Opticks SDK folder. These should be set before you start Visual Studio or the build system will not be able to locate certain important files. Your plug-in will be build in the SDK's Build folder in a sub-folder defined by your platform configuration. When you run Opticks, you should either change the plug-in path to point to the PlugIns directory in the appropriate folder or copy your module to the main PlugIns directory in your Opticks installation.

Solaris

The Solaris build system is based on a tool called SCons. You should create a directory in the SDK's Application/PlugIns/src directory. You don't need to create a plug-in specific build file as a default will be created the first time you build your module. You can build your module by changing your working directory to the Application/PlugIns/src directory and running scons. The -h and -H options will print help messages for the scons tool.

The scons equivalent of property sheets are the .py files in the Application/CompileSettings directory. If your plug-in requires a library not included in the default set such as libtiff, you can edit the SConscript file that is created in your module's directory. This shows how to include the libtiff tool.

Import('env build_dir')

Change this line and add the following lines.

Import('env build_dir TOOLPATH')
env = env.Clone()
env.Tool("libtiff",toolpath=[TOOLPATH])

The tool name is the name of the .py file in Application/CompileSettings.

This scons build system uses the same environment variables as the Visual Studio build system.