You may want to add your own folder of dependencies (as fw4spl-ext-deps or fw4spl-ar-deps).
In this case your main need to create a CMakeLists.txt in the root of your folder (myDepsFolder/CMakeLists.txt) in order to list the subdirectories of your deps.
.. code:: cmake
cmake_minimum_required(VERSION 2.8)
project(CustomDeps)
list(APPEND SUBDIRECTORIES myDeps1)
list(APPEND SUBDIRECTORIES myDeps2)
...
Then when you do a *ccmake* or *cmake-gui* in the build of your deps, you need to add the path to your custom repository in the *ADDITONNAL_DEPS* option.
Then cmake will automaticaly parsed your folder.
How can I add a custom bundle in fw4spl
----------------------------------------
You may want to add a new bundle/lib/app in an existing repository or you may want to add your custom repository to fw4spl.
.. tip::
You need to know that the main CMakeLists.txt is in fw4spl repository, and you can add as many additional repository as you want.
Use the *ADDITIONAL_PROJECTS* option in cmake to add path of your custom folders.
Add a new bundle/lib/app in fw4spl
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The only thing to do is to write a CMakeLists.txt and a Properties.cmake (see section Cmake for Fw4spl for more informations).
Add a custom repository to fw4spl
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As the main CMakeLists.txt is in fw4spl repository,you need to add the path of your folder in *ADDITIONAL_PROJECTS* option when you launch *ccmake* of *cmake-gui* on the build folder of fw4spl.
Then your folder will automaticaly be parsed by cmake.
.. note::
All your bundle/lib/application need to respect the fw4spl-cmake conventions and have a CMakeLists.txt and a Properties.cmake.
Fw4spl and it's dependencies are based on `CMake <http://www.cmake.org/>`_ .
Note that the minimal version of cmake to have is 3.1.
CMake files for dependencies
-----------------------------
fw4spl dependencies are based on the `ExternalProject <http://www.cmake.org/cmake/help/v3.0/module/ExternalProject.html>`_ concept from lastest versions of cmake.
The concept is to create custom targets to build projects in external trees.
Each project has custom steps for download, update/patch, configure, build and install.
- TYPE: Type of the target (can be library, bundle or executable)
- DEPENDENCIES: Link the target with the given libraries (see `target_link_libraries <http://www.cmake.org/cmake/help/v3.0/command/target_link_libraries.html?highlight=target_link_libraries>`_ )
- REQUIREMENTS: Ensure that the depends are build before target (see `add_dependencies <http://www.cmake.org/cmake/help/v3.0/command/add_dependencies.html?highlight=add_dependencies>`_ )
Standard CMake functions and macros should be written in lower case. Each word is generally separated by an underscore (this is a rule of CMake anyway).
.. code-block:: cmake
.. code-block:: cmake
add_subdirectory("library/")
include_directories(SYSTEM "/usr/local")
...
...
@@ -14,7 +14,7 @@ CMakeLists coding
Custom macros should be written in camel case.
.. code-block:: cmake
.. code-block:: cmake
fwLoadProperties()
fwLink("boost")
...
...
@@ -23,7 +23,7 @@ CMakeLists coding
Variables should be written in upper case letters separated if needed by underscores.
.. code-block:: cmake
.. code-block:: cmake
set(VARIABLE_NAME "")
...
...
@@ -31,7 +31,7 @@ CMakeLists coding
In the past, CMake enforced to specify the label or expression in block ending, for instance :
.. code-block :: cmake
.. code::
function(name arg1 arg2)
...
...
...
@@ -45,7 +45,7 @@ CMakeLists coding
This is no longer needed in latest CMake versions, and we recommend to use this possibility for the sake of simplicity.
The code must be documented with **Doxygen**, an automated tool to generate documentation.
.. rule:: Location of the documentation
.. rule:: Location of the documentation
Every documentation that can be useful to a user must be placed inside the header files. Thus a user of a module can
find the declaration of a class and its documentation at the same place. Inside the implementation file, the
...
...
@@ -14,7 +16,7 @@ Documentation
Moreover, every documentation must be placed next to the entity it is refering to, in order to help searching inside
the code.
.. recommendation:: Lightweight documentation
.. recommendation:: Lightweight documentation
Inside a documentation block, only use necessary tags. This will avoid to overload the documentation and makes it
readable. By the way, empty tags will be presented inside the generated documentation and will be useless.
...
...
@@ -79,15 +81,15 @@ Example 3 : Function documentation
std::string m_thing;
};
.. recommendation:: Structured documentation
.. recommendation:: Structured documentation
Doxygen provides a default structure when you generate the documentation. However, when dealing with a big
documented entity, it is often recommended to use the group feature (``@name``). With this feature you will build a
logical view of the class interfaces.
.. rule:: Document service
.. rule:: Document service
The service must be properly documented.
The service must be properly documented.
This should include first a brief description, then a long description if necessary.
...
...
@@ -95,7 +97,7 @@ Example 3 : Function documentation
/**
* @brief This is the short description.
*
*
* This is the long description.
*
...
...
@@ -103,22 +105,24 @@ Example 3 : Function documentation
.. code-block:: cpp
*
/**
* ...
* @section Signals Signals
* - \b signal2(::fwData::Mesh::sptr) : Emitted when the mesh has changed.
* - \b signal1(std::int64_t) : Emitted when ...
*
* @section Slots Slots
* - \b modified() : Modify the data.
*
*/
Last the xml configuration of the service must be described into a dedicated section.
Last the xml configuration of the service must be described into a dedicated section.
It should indicate first the input, input/outputs and outputs in three subsections. The type and the name of the data should appear along with a short description.
A fourth subsection describes the rest of the parameters, and tells if it they are optional or not.
.. code-block:: cpp
*
/**
* ...
* @section XML XML Configuration
*
* @code{.xml}
...
...
@@ -144,5 +148,11 @@ Example 3 : Function documentation
*
*/
Please follow the template above as much as possible to keep the documentation as clear and homogeneous as possible.
**The XML documentation is important**, it is parsed to register properly the service.
The `Input`, `Output` and `InOut` sections must follow the defined format:
@@ -110,16 +107,17 @@ In this latter case, do you need to share this object between different services
- If the answer is yes, then you need create a new object like fwData::Image and a wrapping with fwData::Image<=>itk::Image and fwData::Image<=>vtkImage.
- Otherwise, you can just encapsulated an itk::Image in fwData::Image and create an accessor on it. ( however, this choice implies that all applications that use fwData::Image need ITK library for running. )
.. _campPath:
What is a sesh@ path ?
What is a camp path ?
======================
A **sesh@ path** is a path used to browse an object (and sub-object) using the introspection (see fwDataCamp and :ref:`Serialization`). The path begins
A **camp path** (also called sesh@ path) is a path used to browse an object (and sub-object) using the introspection (see fwDataCamp and :ref:`Serialization`). The path begins
with a '@' or a '!'.
- ``@`` : the returned string is the fwID of the sub-object defined by the path.
- ``!`` : the returned string is the value of the sub-object, it works only on String, Integer, Float and Boolean object.
Sadly, we do not have yet a document giving the paths for all existing data. To know how an object can be accessed with a sesh@ path, you canal
Sadly, we do not have yet a document giving the paths for all existing data. To know how an object can be accessed with a sesh@ path, you can
have a look at the corresponding fwDataCamp implementation of the object. For instance, the file *fwDataCamp/Image.cpp* shows :
.. code:: c++
...
...
@@ -141,22 +139,23 @@ have a look at the corresponding fwDataCamp implementation of the object. For in
;
}
Which means that each property is a possible **sesh@ path**. For instance the height of the image can be retrieved using:
Which means that each property is a reachable by a **camp path**. This is notably used by services in the ``ctrlCamp`` bundle, like ``SExtractObjObj`` or ``SCopy``.
For instance the height of the image can be retrieved using:
.. code:: xml
@values.size.1
@size.1
Other examples:
----------------
To get the fwID of an image contained in a Composite with the key "myImage"
To get the image contained in a ``::fwData::Composite`` with the key ``myImage``
.. code:: xml
@values.myImage
To get the fwID of the first reconstruction of a ModelSeries contained in a Composite with the key "myModel"
To get the first reconstruction of a ModelSeries contained in a ``::fwData::Composite`` with the key ``myModel``
The ``@PROJECT_VERSION@`` will be automatically replaced by the version defined in the Properties.cmake.
The ``<requirement>`` tags contain the bundles that must be started before to start your bundle (see https://rawgit.com/fw4spl-org/fw4spl-dox/dev/group__requirement.html).
Then the extensions are defined. There are different types of extensions, the most common are:
- ``::fwServices::registry::AppConfig`` to define configurations for applications (see :ref:`tuto01`)
- ``::fwActivities::registry::Activities`` to define activities
- ``:fwServices::registry::ServiceConfig`` to define configurations of services (mostly used to configure readers/writers)
- ``::fwServices::registry::ServiceFactory`` to define services
.. TODO add links to documentation for the extensions
.. note::
To separate the configuration in several files, you can use ``<xi:include href="..." />``
.. _serviceBundle:
Service bundles
----------------
You don't need to create the ``plugin.xml`` file for the bundle that contains only services, it will be automatically generated.
A ``CMake`` script parses the services macro and doxygen to generate the ``::fwServices::registry::ServiceFactory`` extension
(see :ref:`serviceCreation` and :ref:`serviceNotFound`)
The bundle contains the service header files in the `include` folder and the `source` files in the `src` folder.
It must also contain a ``Plugin`` class used to register the bundle.
The ``Plugin.hpp`` in the *include* folder should look like:
.. code-block:: cpp
#pragma once
#include <fwRuntime/Plugin.hpp>
namespace myBundle
{
class MYBUNDLE_CLASS_API Plugin : public ::fwRuntime::Plugin
