Skip to main content

Compiling Tulip plugins (Tulip 3)

Hi there,

I recently posted about compiling Tulip using CMake, I'm now going to tell you how to build your plugin and install them onto your Tulip installation.

The first thing you need is a working version of Tulip. Since pre-compiled packages on our website come as standalone applications (meaning that every required librarie, like Qt or so, are provided with the Tulip executable), you won't be able to develop plugins using one of those packages.

So the first thing you'll have to do is to follow the instructions of our Independent CMake tutorial to get a working, compiled from source, version of Tulip.

Note: Reasons why you can't use a pre-compiled version of Tulip for this are detailed at the bottom of this page.

 

1 - Writing your CMakeLists.txt

Ok, now we'll assume that you have a working Tulip that you compiled and installed from sources. Say you installed it into the /home/user/tulip directory. Say also that you are going to put the sources of your plugin into the /home/user/myplugin directory.

Let's assume that your plugin is composed of two source files: MyPlugin.cpp and MyClass.cpp. Just put those two files into the /home/user/myplugin directory and add a third, empty file called CMakeLists.txt.

Note: I attached an archive to this tutorial containing the files mentionned above. Just extract this archive into your directory and you'll be fine :)

Download archive here

The CMakeLists is kind of an equivalent to a Makefile. It contains directives for CMake to set up compilation settings like include directories, linked libraries and so forth. While the archive attached to this tutorial contains a commented CMakeLists.txt which should be self-explanatory, I'm going to give a more detailed version here:

Note: If your not interested by a full explanation of the CMakeLists.txt file content, you can just skip it and go directly to the compilation part.

FIND_PACKAGE(TULIP3 REQUIRED)
FIND_PACKAGE(Qt4 REQUIRED)
INCLUDE(${QT_USE_FILE})

As you probably know by now, CMake uses global variables to control compilation behavior. When using external libraries with CMake, we will need to know where the lib files and the headers are located.
To do this, CMake provides us with the FIND_PACKAGE command.

Calling FIND_PACKAGE(MyPackage REQUIRED) will tell CMake too look for the FindMyPackage.cmake files. CMake will first look into some pre-defined directories (eg. /usr/share/cmake-2.x/Modules on Linux systems).

If the FindMyPackage file has not been found there, CMake will look into the CMAKE_MODULE_PATH variable which is set by the user. This variable defines additional paths for CMake to look for package files. So, while Qt will be available in your system path (the FindQt4.cmake file is shipped along with CMake), the FindTULIP3.cmake file won't. We'll have to manually define the CMAKE_MODULE_PATH for CMake to find it.

SET(CPP_FILES
MyPlugin.cpp
MyClass.cpp)

SET(MOC_HEADERS
)

SET(UI_FILES
)

SET(RESOURCE_FILES
)

This block defines several variables. Those are internal variables containing list of files that will be put into your plugin:

  •  The CPP_FILES contains the list of all source (.cpp) files for your plugins. Here we have our two files MyPlugin.cpp and MyClass.cpp.
  • The MOC_HEADERS variable contains the list of headers (.h) declaring the Q_OBJECT macro. (See Qt specific documentation for details about the QObject system)
  • The UI_FILES variable contains the list of Designer forms (.ui) files. Those file will be parsed using the uic tool (See Qt designer and uic documentation)
  • The RESOURCES_FILES contains the list of Qt resource files (.qrc) that will be parsed using the rcc utility. (See Qt resource system documentation)
     

Note: Since our plugin doesn't use any fancy Qt feature, we are only defining cpp files and the other variable stays empty.

STRING(REGEX REPLACE ".*/" "" PLUGIN_NAME ${CMAKE_CURRENT_SOURCE_DIR})
STRING(TOLOWER ${PLUGIN_NAME} PLUGIN_NAME)

Here we auto-generate the name of the compiled plugin library file. The name is taken from the containing directory name (in lowercase), concatenated with the full tulip version. In this example, we'll get a myplugin-X.Y.Z.so file.

INCLUDE_DIRECTORIES(${TULIP_INCLUDE_DIR} ${QT_INCLUDE_DIR} ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR})

We now tell CMake to add several directories to the include directive (-I). Tulip includes are provided in a TULIP_INCLUDE_DIR variable while Qt's include are defined into the QT_INCLUDE_DIR variable.

We also add the build directory (CMAKE_CURRENT_BINARY_DIR) and the source directory (CMAKE_CURRENT_SOURCE_DIR)

QT4_WRAP_UI(UI_SRCS ${UI_FILES})
QT4_WRAP_CPP(MOC_SRCS ${MOC_HEADERS})
QT4_ADD_RESOURCES(RCC_SRCS ${RESOURCE_FILES})

This will call Qt tools (moc, uic, rcc) on variables specified above. Output file paths will be stored in the UI_SRCS, MOC_SRCS and RCC_SRCS variables

ADD_LIBRARY(${PLUGIN_NAME}-${TULIP_PLUGIN_VERSION} SHARED ${CPP_FILES} ${UI_SRCS} ${MOC_SRCS} ${RCC_SRCS})

TARGET_LINK_LIBRARIES(${PLUGIN_NAME}-${TULIP_PLUGIN_VERSION} ${TULIP_LIBRARY} ${TULIP_OGL_LIBRARY} ${TULIP_QT4_LIBRARY} ${QT_LIBRARIES})

Finally, we tell CMake to compile all this into a shared library. And we link it against Tulip and Qt libraries (defined into TULIP_LIBRARY, TULIP_OGL_LIBRARY, TULIP_QT4_LIBRARY and QT_LIBRARIES)

 

2 - Compiling it

Since you already followed our tutorial on how to compile Tulip from sources with CMake (oh yes you did), you should be fairly familiar with CMake tools. So just create your build directory, run the cmake-gui utility and set-up your source and build directory accordingly.

Before hitting the Configure button, you'll have to set two variables:

  •  First, we'll have to define the CMAKE_MODULE_PATH variable for CMake to find the FindTULIP3.cmake file. This file is located either in your Tulip sources directory or into your <tulip installation directory>/share. So just hit the Add Entry button, type CMAKE_MODULE_PATH as the variable name, select PATH for the variable type and set one of the two directories mentioned above as the variable value.
  • For the FindTULIP.cmake script to work, you'll have to define a second variable, called TULIP_DIR. This variable contains the PATH poiting to your Tulip installation root directory.

You can now hit the Configure button, set-up your build type and other variables, click back on this damned Configure button. Then click on Generate and issue your favorite make command.

 

And that should be all ! When installing your plugin, it will be copied into the <tulip install dir>/lib/tulip directory and it will be automatically loaded at Tulip startup.

To get more information from here, you may want to consult our developer handbook for additional plugins information. If you still encounter problems when building your plugins, feel free to post on our forums for help.