camitk

The CMake macros especially defined to configure CMake projects using CamiTK. More...

Collaboration diagram for camitk:

Modules
	cdash
	CamiTK CMake macros used for continuous integration purpose.
	packaging
	CamiTK CMake macros used to create package of the CamiTK project (a custom CEP or the CamiTK project itself).
	test
	CamiTK CMake macros used for testing.

Functions
void	camitk_add_subdirectory ()
	camitk_add_subdirectory is a utility macro that add a source subdirectory only if:
void	camitk_application ()
	macro camitk_application simplify writing a CMakeLists.txt for CamiTK application extension
void	camitk_extension ()
	Macro camitk_extension simplifies writing a camitk extension (component, action, viewer)
void	camitk_extension_generator ()
	Macro camitk_extension_generator is called in camitk_extension macro.
void	camitk_extension_project ()
	macro camitk_extension_project creates an optional (disabled by default) CEP (CamiTK Extension Project) subdirectory the build.
void	camitk_install_all_headers ()
	camitk_install_all_headers is a macro that install all header files of a project at build and install time
void	camitk_library ()
	macro camitk_library simplifies the declaration of a library inside CamiTK and is to be used for all inner project libraries
void	camitk_translate ()
	macro camitk_translate allows one to perform the translation of any project (action, component, application and libraries) in several languages.

Detailed Description

The CMake macros especially defined to configure CMake projects using CamiTK.

Function Documentation

camitk_add_subdirectory()

void camitk_add_subdirectory

(

)

camitk_add_subdirectory is a utility macro that add a source subdirectory only if:

1. it exists
2. it contains a CMakeLists This can avoid CMake warning (see cmake –help-policy CMP0014), but do the opposite: it prints out an information message when it succeed including the directory.

Usage:

camitk_add_subdirectory(subdir)

Parameters

subdir

(required) the name of the source subdirectory to include BEWARE subdir is a relative path to current directory

camitk_application()

void camitk_application

(

)

macro camitk_application simplify writing a CMakeLists.txt for CamiTK application extension

Note

After the execution of this macro, the variable APPLICATION_TARGET_NAME holds the name of the CMake target produced by this macro. The target name itself is equals to camitk-name, where name is the name of the current folder in lowercase.

On Unix additional system resources can also be automatically installed or configured: man pages, desktop file and XPM icons.

• Man pages should be resources/camitk-appdirname.1 or resources/camitk-appdirname.1.in (in this case, it will be configured first).
• Desktop file should be in resources/camitk-appdirname.desktop (refer to http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html and http://standards.freedesktop.org/menu-spec/1.0/apa.html for valid category details)
• XPM icons should be found in resources/camitk-appdirname.xpm (an icon can also be used in to set the application icon (use setWindowIcon(QIcon(":/resources/camitk-appdirname.xpm")) as well)

To write a simple man page, please refer to SDK application examples. If you need to generate a simple manpage or analyze the command line arguments, the CamiTK team recommands to use Code Synthesis CLI configuration (see http://codesynthesis.com/projects/cli)

usage:

camitk_application(
             [DISABLED]
             [APPLICATION_NAME]
             [INTERNAL_TEST_APPLICATION]
             [NO_CAMITKCORE_REQUIRED]
             [NO_GUI]
             [QTEST]
             [TEST_RUN_SERIAL]
             [SOURCES source1.cpp source2.cpp ...]
             [NEEDS_ITK]
             [NEEDS_PYTHON]
             [NEEDS_CEP_LIBRARIES CEPLib1 CEPLib12 ...]
             [NEEDS_COMPONENT_EXTENSION component1 component2 ...]
             [NEEDS_ACTION_EXTENSION ation1 action2 ...]
             [NEEDS_VIEWER_EXTENSION viewer1 viewer2 ...]
             [NEEDS_EXTENSIONGENERATOR]
             [DEFINES flag1 flag2 ...]
             [CXX_FLAGS flag1 flag2 ...]
             [ADDITIONAL_SOURCES source.cxx source.cpp ...]
             [QRC_SOURCES file.qrc]
             [INCLUDE_DIRECTORIES dir1 dir2 ...]
             [EXTERNAL_LIBRARIES lib1 lib2 ...]
             [EXTRA_TRANSLATE_LANGUAGE]
    )

Parameters

DISABLED	means this is a default application is NOT to be compiled automatically
APPLICATION_NAME	this overrides the default name for the application (directory name)
INTERNAL_TEST_APPLICATION	means this application's objective is to build an internal test, not to be distributed. Using this flag will automatically set the name and target to "test-APPLICATION_NAME". test applications won't be distributed / installed.

Note

use in combination with NO_CAMITKCORE_REQUIRED if the application does not depends from camitkcore nor qtpropertybrowser libraries.

use in combination with NO_GUI if the application can be ran in console mode (useful for windows)

use in combination with QTEST if the application is using QTest framework

Parameters

NO_CAMITKCORE_REQUIRED	This application does not need camitkcore nor qtpropertybrowser
NO_GUI	means this application doesn't require a GUI and it will be compile to be ran into a console mode (useful on windows)
QTEST	this application is a qtest application, all tests functions will be separated into different specific tests named after the function.
TEST_RUN_SERIAL	Do not run this test in parallel with any other test. Use when the test can take a loooooonnnnng time and break the CI pipeline due to ressources limitation
SOURCES	if provided CMake won't look automatically (gather) headers and sources. Can be used in conjunction with QRC_SOURCES.
NEEDS_ITK	means this application requires ITK to be compiled / run.
NEEDS_CEP_LIBRARIES	list of needed camitk CEP libraries
NEEDS_COMPONENT_EXTENSION	list of needed component extensions
NEEDS_ACTION_EXTENSION	list of needed action extensions
NEEDS_VIEWER_EXTENSION	list of needed viewer extensions
NEEDS_EXTENSIONGENERATOR	add this flag if your application requires only public library extensiongenerator
DEFINES	list of define flags to add at compilation time
CXX_FLAGS	list of compiler flags to add (such as warning levels (-Wall ...)).
ADDITIONAL_SOURCES	list of additional sources (that cannot be automatically found by gather_headers_and_sources macro)
QRC_SOURCES	list of .qrc resource file to include in your application (only checked when SOURCES is provided)
CEP_NAME	specify the CEP_NAME, which is used to categorized the application for packaging purpose No CEP_NAME provided will result in default categorization (generic application).
DESCRIPTION	Simple description of the application. Used for packaging presentation for instance.
INCLUDE_DIRECTORIES	additional include directories
EXTERNAL_LIBRARIES	external libraries to add to the link command
EXTRA_TRANSLATE_LANGUAGE	Additionnal extra language to translate the application

camitk_extension()

void camitk_extension

(

)

Macro camitk_extension simplifies writing a camitk extension (component, action, viewer)

The name of the extension is automatically the name of the directory from where this macro is called, unless it is overriden by the TARGET_NAME parameter.

Note

To be more precise, after the execution of this macro, the variable type_TARGET_NAME (i.e., ACTION_TARGET_NAME, COMPONENT_TARGET_NAME, or VIEWER_TARGET_NAME) holds the name of the CMake target produced by this macro. The target name itself is equal to either action-name, component-name or viewer-name (depending on the type of the extension), where name is the name of the current folder in lowercase, unless TARGET_NAME is provided On windows, the - (dash) is replaced by _ (underscore)

usage:

camitk_extension( <type>
                  [DISABLED]
                  [CAMITK_FILE file]
                  [NEEDS_ITK]
                  [NEEDS_LIBXML2]
                  [NEEDS_OPENCV]
                  [NEEDS_IGSTK]
                  [NEEDS_XSD]
                  [NEEDS_GDCM]
                  [NEEDS_ACTION_EXTENSION action1 action2 ...]
                  [NEEDS_VIEWER_EXTENSION viewer1 viewer2 ...]
                  [NEEDS_COMPONENT_EXTENSION component1 component2 ...]
                  [NEEDS_CEP_LIBRARIES CEPLib1 CEPLib2 ...]
                  [INCLUDE_DIRECTORIES dir1 dir2 ...]
                  [DEFINES flag1 flag2 ...]
                  [CXX_FLAGS flag1 flag2 ...]
                  [EXTERNAL_SOURCES file1 file2 ...]
                  [EXTERNAL_LIBRARIES lib1 lib2 ...]
                  [HEADERS_TO_INSTALL header1.h header2.h ...]
                  [INSTALL_ALL_HEADERS]
                  [TARGET_NAME non-default-targetname]
                  [DESCRIPTION description]
                  [EXTRA_TRANSLATE_LANGUAGE]
                  [ENABLE_AUTO_TEST]
                  [TEST_FILES file1 file2 ...]
                  [AUTO_TEST_LEVEL 1]
                  [AUTO_TEST_LEVEL 2]
                  [ENABLE_INTEGRATION_TEST]
  )

Parameters

<type>	REQUIRED. The selected type of extension you wish to build. possible values : ACTION_EXTENSION, COMPONENT_EXTENSION or VIEWER_EXTENSION.
DISABLED	means this is a not a default extension, it will not be compiled automatically
CAMITK_FILE	the .camitk file to generate action source code that uses user action class (if not present, this extension is a classic extension, and is not auto-generated)
NEEDS_ITK	add this if your extension needs ITK. Do not forget to add the needed list of ITK libraries in the LIBRARIES parameter
NEEDS_LIBXML2	add this if your extension needs libxml2
NEEDS_XSD	add this if your extension needs Codesynthesis xsd cxx (xml schema compiler)
NEEDS_OPENCV	add this if your extension needs OpenCV
NEEDS_IGSTK	add this if your extension needs IgsTK
NEEDS_XERCESC	add this if your extension needs XercesC library
NEEDS_GDCM	Add this if your extension requires GDCM library
NEEDS_CEP_LIBRARIES	list of needed CEP libraries (not external dependencies)
NEEDS_COMPONENT_EXTENSION	list of needed component extensions
NEEDS_ACTION_EXTENSION	list of needed action extensions
NEEDS_VIEWER_EXTENSION	list of needed viewer extensions
INCLUDE_DIRECTORIES	additional include directories
DEFINES	list of define flags to add at compilation time.
CXX_FLAGS	list of compiler flags to add (such as warning levels (-Wall ...)).
EXTERNAL_SOURCES	list of extra source/headers files (external to the current directory) that needed to be added to the SOURCES variable. Note: EXTERNAL_SOURCES are not installed
EXTERNAL_LIBRARIES	external libraries to add to the link command
HEADERS_TO_INSTALL	list of headers to install, if present this will automatically create an "install-EXTENSION_NAME" target, that can be used anywhere else to manage dependencies to this extension. The headers are installed ${CAMITK_BUILD_INCLUDE_DIR}/EXTENSION_TYPE/EXTENSION_NAME when the target "install-EXTENSION_NAME" is called.
INSTALL_ALL_HEADERS	install all of the headers (this is the lazy solution, please consider making a list and using HEADERS_TO_INSTALL parameter instead. Only the files matching the regex *.h will be install. If you need to add other files, you need to use the HEADERS_TO_INSTALL option.
TARGET_NAME	specify a target name different than the default (default is the extension source code directory name) this can be very useful for example when you have an extension source code directory in your CEP that has the same name as one in the camitk community edition.
CEP_NAME	specify the CEP_NAME, which is used to categorized the extension for packaging purpose No CEP_NAME provided will result in default categorization (generic extension).
DESCRIPTION	Simple description of the extension. Used for packaging presentation for instance.
EXTRA_TRANSLATE_LANGUAGE	Additionnal extra language to translate the application
ENABLE_AUTO_TEST	Create automatic test with either testactions or testcomponents. By default, auto test are run at the highlest level (level 3) unless AUTO_TEST_LEVEL is specified See also TEST_FILES and AUTO_TEST_LEVEL options
TEST_FILES	List of files to use for testing. If provided, only the filenames are required (not the absolute paths), each of them should be found in the testdata build dir. If no test files are provided: for component extension auto test: all the files in the component testdata subdir are used by default for action extension auto test: all the files available in the testdata build dir (i.e., all the component testdata) are used by default (which might be too many!).
AUTO_TEST_LEVEL	i for automatic test of component extensions: set the highest level of automatic test to perform: level 1: load the component extension, open and close a testdata component file level 2: same as level 1, but save the component before closing it. level 3 (default): same as level 2, but also compare the saved component to the input.
ENABLE_INTEGRATION_TEST	add a specific integration test (see camitk_add_integration_test) CamiTK CMake macro. Since CamiTK 4.1 It does add an integration test using the action-state-machine to process a chain of actions (requires that subdirectory integration-testdata exists, and contains a file called "asm-input.scxml" and at least one file name "output-*.*") Check the wiki for more information about integration test

camitk_extension_generator()

void camitk_extension_generator

(

)

Macro camitk_extension_generator is called in camitk_extension macro.

In turns it calls the camitk-extensiongenerator application to generate the source code in the build directory from the given .camitk file.

It calls camitk-extensiongenerator a first time for a first generation, list the files that are generated and set up a custom command to re-generate theses files everytime the .camitk is modified.

Note

When a new action is added in the .camitk, the user MUST restart the CMake configuration stage as the list of generated source files will have to be updated so that they will be updated whenever the .camitk is modified. Also the moc process will also be generating its own source code from the generated files and won't be able to find them after regeneration.

usage:

camitk_extension_generator(CAMITK_FILE file)

Parameters

CAMITK_FILE

REQUIRED The .camitk file used to generate the source code

camitk_extension_project()

void camitk_extension_project

(

)

macro camitk_extension_project creates an optional (disabled by default) CEP (CamiTK Extension Project) subdirectory the build.

Usage:

camitk_extension_project(CONTACT
                         [ENABLED]
                         [NAME cepName]
                         [DESCRIPTION longDescription]
                         [DEFAULT_APPLICATION exeName]
                         [NEEDS_CEP cep1 cep2...]
                         [LICENSE licenseName]
                         [ENABLE_TESTING]
                         [ENABLE_TEST_COVERAGE]
)

Parameters

CONTACT	Mandatory, this is the person(s) to contact to get more information about the CEP
ENABLED	If used, this CEP is forced by default (otherwise the user as to tick the option in CMake GUI or defined a -DCEP_<cepName>:BOOL=TRUE on the command line
NAME	By default the name of a CEP is given automatically by the name of the top level source directory If you specify a name here, the directory name will be ignored
DESCRIPTION	A (not so) small description of this CEP (objective, content, implementation information)
DEFAULT_APPLICATION	The default application to run (for MSVC launchers), default is camitk-imp
LICENSE	The name of the license for this CEP, default is LGPL-v3
ENABLE_TESTING	Enable the testing framework ("make test" will run all the test)
ENABLE_TEST_COVERAGE	Enable the test coverage report ("make camitk-ce-test-coverage" will run all the test and generate a report in the camitk-ce-test-coverage subdirectory. Only works with the g++ compiler.
NEEDS_CEP	(TODO) Dependencies to other CEP

camitk_install_all_headers()

void camitk_install_all_headers

(

)

camitk_install_all_headers is a macro that install all header files of a project at build and install time

Duplicate headers installation:

• one is used at compiled time and puts everything in ${CMAKE_BINARY_DIR}/include/${CAMITK_SHORT_VERSION_STRING}/${GroupName}/${ComponentName}/...
• the other one is used at installation time and puts everything in ${CMAKE_INSTALL_PREFIX}/include/${CAMITK_SHORT_VERSION_STRING}/${GroupName}/${ComponentName}/...

This macro keeps header files directories tree structure at installation. In other words, if your extension has its header files located in subdirectories, this tree structure will be kept the same at installation.

Note that only file matching regex "*.h" in the source dir and subdir are considered headers. If you need to add other files, you need to use the HEADERS_TO_INSTALL option.

Usage:

camitk_install_all_headers(  COMPONENT ComponentName
                             [GROUP GroupName]
                          )

Parameters

COMPONENT	(required) Name of the component to use. This is also the include subdirectory name used for copying the file
GROUP	(optional) Name of the group this install should be using group will be prepend to the component name. This is either actions, components, viewers or libraries.

Example invocation:

#--------------
# installation
#--------------
camitk_install_headers( COMPONENT ${MYPROJECT_NAME}
                        GROUP libraries
)

Here, in this example, we will install all the header files, in the ${CAMITK_INCLUDE_DIR}/include/libraries/${MYPROJECT_NAME} directories (at build and installation times) If my header files are located in some subdirectories, this structure will be kept the same at build and installation times.

camitk_library()

void camitk_library

(

)

macro camitk_library simplifies the declaration of a library inside CamiTK and is to be used for all inner project libraries

The name of the CEP library is automatically deduced from the name of the directory, unless LIBNAME is provided

Note

To be more precise, after the execution of this macro, the variable LIBRARY_TARGET_NAME holds the name of the CMake target produced by this macro. The target name itself is equals to library-name, wherenameis the name of the current folder in lowercase unlessLIBNAME` is provided.

If the library is compiled as shared, it adds the needed library properties If it needs relocation flag fPIC (on some plateforms), this macro should determine if this is the case and specify this flag.

usage:

camitk_library(
    SHARED|STATIC
    SOURCES source1.cpp source1.h...
    [LIBNAME libname]
    [OUTPUT_SUBDIRECTORY actions|components|viewers]
    [PUBLIC]
    [NEEDS_CEP_LIBRARIES lib1 lib2...]
    [NEEDS_ITK]
    [NEEDS_LIBXML2]
    [NEEDS_XERCESC]
    [NEEDS_XSD]
    [NEEDS_QT]
    [NEEDS_CAMITKCORE]
    [DEFINES flag1 flag2 ...]
    [EXTERNAL_LIBRARIES lib1 lib2... ]
    [INCLUDE_DIRECTORIES dir1 dir2...]
    [LINK_DIRECTORIES dir1 dir2...]
    [HEADERS_TO_INSTALL]
    [INSTALL_NO_HEADERS]
    [CEP_NAME]
    [DESCRIPTION]
    [EXTRA_TRANSLATE_LANGUAGE lang1 lang2...]
    [CXX_FLAGS flag1 flag2 ...]
 
)

Parameters

SHARED	optional, if the library should be compiled as shared
OUTPUT_SUBDIRECTORY	optional, added to the output directory (for private lib dir, e.g. "actions")
SOURCES	all sources to be included in the library
INCLUDE_DIRECTORIES	all needed include directories (${CMAKE_CURRENT_SOURCE_DIR} and ${CMAKE_CURRENT_BINARY_DIR} are automatically added)
EXTERNAL_LIBRARIES	all the libraries to be used during the link (shared or static)
NEEDS_CEP_LIBRARIES	all the libraries to be used during the link (shared or static)
NEEDS_ITK	add this if your component needs ITK.
NEEDS_LIBXML2	add this if the CEP library needs libxml2
NEEDS_XERCESC	add this if your action / component needs XercesC library
NEEDS_XSD	add this if your action needs Codesynthesis xsd cxx (xml schema compiler)
NEEDS_QT	add this if your library depends on Qt 5.x
NEEDS_CAMITKCORE	add this if your library depends on CamiTK (implies NEEDS_QT)
LIBNAME	force the CEP library name to be different from the directory it is in
LINK_DIRECTORIES	additional directories to use in link_directories(...)
DEFINES	list of define flags to add at compilation time
PUBLIC	The library is a public library that has to be loaded directly by the operating system. It is generally only needed for SDK library. A public library should not be installed in the lib/${CAMITK_SHORT_VERSION_STRING} but directly in lib/ (on Unix/MacOS) or bin/ (on windows)
HEADERS_TO_INSTALL	list of header files to install. File would be copied at build and installation time in the ./include/libraries/library-name subdirectory. Note that, if no header files are provided, all header files (*.h) will be install.
INSTALL_NO_HEADERS	No headers will be installed (do not use with HEADERS_TO_INSTALL)
CEP_NAME	specify the CEP_NAME, which is used to categorized the extension for packaging purpose No CEP_NAME provided will result in default categorization (generic extension).
DESCRIPTION	Simple description of the extension. Used for packaging presentation for instance.
EXTRA_TRANSLATE_LANGUAGE	Additional extra language to translate the application
CXX_FLAGS	list of compiler flags to add (such as warning levels (-Wall ...)).

camitk_translate()

void camitk_translate

(

)

macro camitk_translate allows one to perform the translation of any project (action, component, application and libraries) in several languages.

usage:

camitk_translate(
    [EXTRA_LANGUAGE lang1 lang2...]
    [USE_FLAGS]
)

Parameters

EXTRA_LANGUAGE	optional, allows the translation of this additional language
USE_FLAGS	optional, use the flag directory to associate a flag per language