OOF2: The Manual

7.5. Internal Extensions
Prev  Chapter 7. Extending OOF2  Next

7.5. Internal Extensions

Internal extensions are easier to build and use than external extensions because they use the OOF2 installation machinery. However they have two disadvantages:

  1. They require the developer to have permission to write files in the OOF2 source code directories.

  2. The directory containing internal extensions will be rewritten when a new version OOF2 is installed, so any changes there will be lost.

All of the source code for an internal extension should be put in a subdirectory of SRC/EXTENSIONS in the main OOF2 source directory. If an add_subdirectory(extensionname) line is added to SRC/EXTENSIONS/CMakeLists.txt, then the code in the subdirectory extensionname will be compiled and installed when OOF2 is built. If a subdirectory of this directory contains an __init__.py file, the directory will be imported automatically if OOF2 is started with the --autoload option.

7.5.1. Internal Extension Files

The files required for an internal extension depend on whether the extension contains C++ code or is purely Python.

7.5.1.1. Pure Python Internal Extensions

If the extension contains only Python files, all of the files in its entire subdirectory, including any nested subdirectories, will be installed when OOF2 is installed. No CMakeLists.txt file is required in the extension's directory, and the extension does not have to be listed in any other OOF2 CMakeLists.txt file.

The extension's directory must contain an __init__.py, which should import the extension's other Python files, if those files need to be imported when the extension is loaded. Files defining new Fields or Properties generally should be loaded at start up time.

7.5.1.2. C++ Internal Extensions

To build an extension called “oofextension”, do the following:

  1. Create a subdirectory called oofextension in SRC/EXTENSIONS/

  2. Edit SRC/EXTENSIONS/CMakeLists.txt and add the line


                    add_subdirectory(oofextension) 

  3. Inside SRC/EXTENSIONS/oofextension, write the C++ code for the extension, following the guidance in Chapter 8. The C++ files do not have to be named oofextension.C, but they can be. Write swig files to create the Python interface to those parts of the extension that have to be accessible from Python.

  4. Create a CMakeLists.txt in the extension's directory. It should look like Example 7.5. If there are subdirectories containing C++ code within oofextension, create CMakeLists.txt files there too.

Example 7.5. CMakeLists.txt for an internal extension

oof_swig_sources( # 1
  SWIGFILES oofextension # 2
  SOURCES oofextension.C # 3
  LIBRARIES oof2common oof2engine # 4
  )

add_subdirectory(subdirectoryname) # 5

1

oof_swig_sources is a wrapper for swig_sources, and works the same way. It sets SWIGDEST and the C++ include path appropriately.

2

This is the name of the swig file, without its suffix. CMake will look for oofextension.swg. The name of the file does not have to be the same as the name of the extension, but it can be. More than one swig file can be listed, but only if SOURCES is not used.

3

Additional C++ source files that need to be compiled are listed here. There can be more than one. The C++ file generated by swig should not be listed. Don't use this if more than one swig file is included in SWIGFILES.

4

The OOF2 libraries that this extension uses are listed here. oof2common should always be included. An extension that adds Properties or anything related to Skeletons or Meshes should include oof2engine, and an extension working with images should include oof2image.

Note that when building external extensions, oof2common, etc. are not defined, but can be accessed through CMake variables ${OOF2COMMON}, etc.

5

If there are subdirectories, add a line like this for each, and put a CMakeLists.txt file in each one.


7.5.2. Loading Internal Extensions

Internal extensions are loaded automatically if the --autoload option is used when starting OOF2.

An individual extension can be loaded manually by typing 

        import ooflib.EXTENSIONS.extensionname

in the OOF2 Console Window, or by putting that line a script and loading the script.

Prev  Up  Next
7.4. Running OOF2 with External Extensions  Home  Chapter 8. Writing OOF2 Extensions