diff --git a/Documentation/Doxygen/NewPlugin.dox b/Documentation/Doxygen/NewPlugin.dox index be78bbb056..8ccb986694 100755 --- a/Documentation/Doxygen/NewPlugin.dox +++ b/Documentation/Doxygen/NewPlugin.dox @@ -1,102 +1,107 @@ /** \page NewPluginPage How to create a new MITK Plug-in +\attention The procedure described here will generate legacy BlueBerry bundles. MITK switched to using the +CTK plugin framework and hence it is recommended to create CTK plug-ins instead of BlueBerry bundles. Until +there is similar generator for CTK-based MITK projects available, please read +Set-up a MITK-based Project. + \section CmakePluginGen CMake-based plug-in generator The BundleGenerator is a tool to simplify the process of creating your own MITK project (optional) and plug-ins. \par Introduction This how-to will show you how to create a new MITK project together with a new plug-in. You will not need to touch either the MITK source tree or any MITK binary tree. MITK will be used in the sense of a Software Development Kit (SDK), providing only header files and binaries (shared objects). \par Limitations The CMake based generator will generate only very few classes for you. It can generate an Activator class and a View class for GUI contributions. Nevertheless, you are advised to use it because it generates the correct plug-in directory structure. In the future, there will be a more sophisticated generator available. \par Prerequisites We will use MITK as a SDK, which we have to set up first. Since there is no SDK package available yet which you could download and install, we have to follow the steps in SetupMitkQt4BlueBerry. This will set up a binary MITK tree which we can be used later on to link our plug-ins to. \par After you have build MITK, you have to think about a name and an id for your new plug-in and/or your new project. The generator uses the CMake GUI for configuration. \par Windows \li Start the CMake GUI \li Choose \c \/Build/Tools/BundleGenerator as source directory \li Choose a directory for the source code of your project and/or plug-in (create it if it doesn't exist) \li Press "Configure" and don't care about the generator \li Follow the steps for "All" \par Linux \li Create a directory for the source code of your project and/or plug-in and cd into it. \li Start ccmake with \/Build/Tools/BundleGenerator as source directory \li Press "Configure" \par All \image html BundleGenerator1.png \n \li CUSTOM_PROJECT_NAME (optional): The name of your new project. If empty, only the source code for your plug-in is generated. MBI members should not supply a value. \li GUI_SUPPORT: you usually want to contribute to the UI, so leave this ON \li PLUGIN_ID: Enter an id for the new plug-in. It must be a unique identifier, so the following form is recommended: \c my.domain.identifier. MBI members should use an id similar to \c org.mitk.gui.qt.isosurface. \li PLUGIN_NAME: The name of your plug-in in human-readable form. For example: MITK IsoSurface Plug-in \li PLUGIN_TEMPLATE: Leave this as it is, unless you really know what you are doing. \li Press "Configure" again and you will get the following screen: \n \n \image html BundleGenerator2.png \n \li ACTIVATOR_CLASS (optional): The name of a class (without namespaces) which can be used to react to lifecycle events of your plug-in. See berry::IBundleActivator . \li CUSTOM_PROJECT_EXECUTABLE (optional/required): If you supplied a CUSTOM_PROJECT_NAME, this variable will hold the name of your executable which will start an BlueBerry Workbench. \li PLUGIN_VENDOR: The person or institution from which this plug-in comes from. Change to your needs. \li PLUGIN_VERSION: The version number of your plug-in. This will be used by the platform for managing plug-in dependencies. \li REQUIRED_PLUGINS: The ids of plug-ins your plug-in directly depends on. Usually you won't need to change something. \li VIEW_BASE_CLASS: The class from which your new view inherits from. Usually not changed. \li VIEW_BASE_CLASS_H: The header file for the base class of your new view. Usually not changed. \li VIEW_CLASS: The name of your new view (i.e. functionality) class. \li VIEW_ID: A unique id for your new view. Again, it is recommended to use something like my.domain.views.id. MBI members should use an id similar to \c org.mitk.views.isosurface \li VIEW_NAME: The name of your view in human-readable form. This name will be shown in the UI of your application. \li Press "Configure" again, which will give the following screen: \n \n \image html BundleGenerator3.png \n If everything looks okay, press "Generate" and CMake will create a directory named Generated/\ (if you set a value for it) or a directory named Generated/\. You can move or rename the \ directory (or the \ directory if you did not create a project) somewhere else if you want to get rid of the parent directories. \par Integrating your new plug-in If you supplied a CUSTOM_PROJECT_NAME value, create a new directory outside of the \ directory for your project's binary tree. Start CMake again and use \ as source directory and your newly created directory as binary directory. Go through the configuration and generation process again (you will have to set the variable MITK_DIR to your MITK binary directory) and you will get project files for your chosen environment. On Windows, use the supplied \b startVS2008.bat file in your binary tree to start Visual Studio (this will correctly set your path environment variable). \par If you did not want to create a new project (because you already have one), copy your new plug-in from the temporary directory in your project's source tree. (Hint for MBI members: put it in \c \/Modules/Bundles or \c \/mbi-sb/Bundles !) Switch back to the CMake configuration of your custom project (MBI: MITK). On Windows you can just switch the "Where to build the binaries" combobox back to your projects (MBI: MITKs) binary directory. After pressing "Configure" a new build option for your plug-in should appear. \section BuildSystem Build system for plug-ins Just put new files in your plug-in's \c src or \c src/internal directory and edit the \c files.cmake file there. If you have any fancy stuff like external libraries and include directories you should have a look at the CMake manual and general MITK build system documentation. \section Troubleshooting Troubleshooting \par I get "Could not find library" messages and similar stuff when I try to start my project's executable. This is mostly due to wrong environment settings. On Windows, make sure that you use the supplied batch files to start Visual Studio or your project's executable. If you still get errors, double check the value of the PATH variable in your batch files (it must contain MITK's binary directory and paths to the ITK, VTK and Qt libraries. \par On Linux, set your LD_LIBRARY_PATH variable accordingly. */