View source for Documentation/CTK Plugin Framework: Setting up a project

This tutorial will show you how to set-up your own project using the CMake build system and how to integrate it with the CTK Plugin Framework.

The described set-up will allow for an arbitrary number of applications and CTK plug-ins, contained in one project.

==== Project Layout ====

[[File:CTKPluginProject_Layout.png|frame|Fig. 1 Example Project Layout]]
A possible project layout is shown in Fig. 1. It contains one application (UseCTKPlugin) and one plugin (org.mydomain.serviceeventlistener). The code for the application and different plugins is explained in other tutorials. We will cover only the four CMake files seen in Fig. 1.

==== Top-Level CMake File ====

The top-level CMake file is in charge of finding CTK and Qt4. You can add any CMake commands you want, the only requirement for a CTK Plugin integration is the availability of CTK and Qt4 (by using FIND_PACKAGE). You can have a look at an example file by clicking on the CMakeLists.txt link below. We will discuss one important part of this file in more detail:

[https://github.com/saschazelzer/CTKPluginTutorials/blob/master/CMakeLists.txt CMakeLists.txt]
<syntaxhighlight lang="cmake" line sectionmarker="|\s*#&gt;|" filtersections="Extract all" url>
https://github.com/saschazelzer/CTKPluginTutorials/raw/master/CMakeLists.txt
</syntaxhighlight>

To be able to take advantage of CTKs sophisticated dependency checking system inside your own build system, you need to write a small CMake macro called ''GetMyTargetLibraries''. It is used as a callback inside CTKs own CMake macros and functions to distinguish between targets being build in your project and targets external to your project (e.g. targets coming from CTK). It works by taking a list of target names and filtering out the names belonging to your own project using regular expressions. You can use as many regular expressions as you want in the call to ''ctkMacroListFilter'', between ''_tmp_list'' and ''OUTPUT_VARIABLE''.

Together with the ''FIND_PACKAGE'' commands for CTK and Qt4, that is all you need in your top-level CMake file.

==== Application Integration ====

The [https://github.com/saschazelzer/CTKPluginTutorials/blob/master/Apps/CMakeLists.txt CMakeLists.txt] file inside the ''Apps'' directory is not required to use any CTK specific CMake code. In the described set-up it just adds a build option for our ''CTKUsePlugin'' application and adds its directory to be parsed by CMake.

Here is an example CMake file for our ''CTKUsePlugin'' application which needs to call methods in the CTK Plugin Framework library:

[https://github.com/saschazelzer/CTKPluginTutorials/blob/master/Apps/CTKUsePlugin/CMakeLists.txt CMakeLists.txt]
<syntaxhighlight lang="cmake" line url>
https://github.com/saschazelzer/CTKPluginTutorials/raw/master/Apps/UseCTKPlugin/CMakeLists.txt
</syntaxhighlight>

This is standard CMake code, adding the CTK include directories and linking the application to the CTK Plugin Framework library ''CTKPluginFramework''.

==== Plugin Integration ====

In contrast to the CMake file in the ''Apps'' directory, the CMakeLists.txt file in the ''Plugins'' directory makes use of some dependency checking from the CTK build system:

[https://github.com/saschazelzer/CTKPluginTutorials/blob/master/CMakeLists.txt CMakeLists.txt]
<syntaxhighlight lang="cmake" line sectionmarker="|\s*#&gt;|" filtersections="Create a list" url>
https://github.com/saschazelzer/CTKPluginTutorials/raw/master/CMakeLists.txt
</syntaxhighlight>

The first step is to create a list containing one entry for each plug-in in the ''Plugins'' directory. Each entry consists of the directory name containing the plug-in followed by a '':'' and the default build option value. This list is then passed to the ''ctkFunctionSetupPlugins'' function, which executes the following steps:

* Create a CMake option for each given plugin. You can customise the option name with a prefix by supplying "BUILD_OPTION_PREFIX ''MyPrefix''" as the last arguments to the function (''MyPrefix'' defaults to BUILD_).
* Generate a dependency graph of your plugins and external dependencies (other plugins and libraries).
* Validate the dependencies of enabled plugins. If one of your own plugins depends on other plugins in your project, they will be automatically enabled. Unsatisfied external dependencies will result in a CMake configuration error.
* Add the subdirectories of enabled plugins.

==== Plugin CMake File ====

Plugins external to CTK are build exactly the same way as plugins contained within the CTK project itself. An example CMakeLists.txt file for a plugin named ''org.mydomain.serviceeventlistener'' is shown below:

[https://github.com/saschazelzer/CTKPluginTutorials/blob/master/Plugins/org.mydomain.serviceeventlistener/CMakeLists.txt CMakeLists.txt]
<syntaxhighlight lang="cmake" line url>
https://github.com/saschazelzer/CTKPluginTutorials/raw/master/Plugins/org.mydomain.serviceeventlistener/CMakeLists.txt
</syntaxhighlight>

The ''PROJECT'' command in line one sets the name for your plugin sub-project. Additionally, this name is used as the target name for the shared library and should be globally unique. A good convention is to use the reverse domain scheme for the project name and also for the directory containing the plugin code. Note that the project name must not contain periods.

Calling the macro ''ctkMacroBuildPlugin'' will do the heavy lifting and set-up all include paths and library dependencies. The definition of plugin dependencies and the usage of this macro is covered in the [{{fullurl:Documentation/CTK_Plugin_Framework: Creating a new CTK Plugin}}?action=purge Creating a new CTK Plugin] tutorial.

==== Related Tutorials ====

* [{{fullurl:Documentation/CTK_Plugin_Framework: Creating a new CTK Plugin}}?action=purge Creating a new CTK Plugin]
* [{{fullurl:Documentation/CTK_Plugin_Framework: Embedding the CTK Plugin Framework}}?action=purge Embedding the CTK Plugin Framework]