CreaTools: Library Crea - Developers

crea is the base library of the creaTools suite. It provides :

CMake macros for developers
a template C++ project creator : creaNewProject
Basic usefull C++ ressources

crea depends on CMake, vtk and wxWidgets

Download
Build from the sources
Using crea in an external project with CMake

Build from the sources

Follow the usual CMake project generation stages (instructions here) and build with your favorite compiler

Using crea in an external project with CMake

The cmake commands to find and use the crea lib are:

# Messages during cmake configuration process ?

SET(CREA_VERBOSE_CMAKE TRUE)

# Finds and uses the crea library

FIND_PACKAGE(crea REQUIRED)

IF (crea_FOUND)

INCLUDE(${crea_USE_FILE})

ENDIF(crea_FOUND)

The variable ${crea_LIBRARIES} then contains the libraries provided by crea, to be linked with, e.g. you can type a command like:
TARGET_LINK_LIBRARIES( MyTarget ${crea_LIBRARIES})

The cmake macros provided by crea are automatically included by the use file.

NOTE for version 0.1.0 :

crea 0.1.0 needs wxWidgets and vtk. They are automatically found and used when you use FIND_PACKAGE(crea) and include crea USE FILE , hence you do not need to find them again if you need them in your code. You can directly use the variables set by their use files (e.g. VTK_LIBRARIES, WX_LIBRARIES) exactly like if you had used crea macro FIND_AND_USE_LIBRARIES with USE_VTK and USE_WXWIDGETS set to ON.

CREA_ADD_EXECUTABLE ( EXE_NAME )

Generates the cmake commands to build and install the executable EXE_NAME

${EXE_NAME}_LINK_LIBRARIES must contain the list of libraries to link against.

${EXE_NAME}_SOURCES must contain the list of files to compile to build the executable.

If ${EXE_NAME}_HAS_GUI is set to TRUE then on windows generates a Win32 application

If ${EXE_NAME}_CONSOLE is set to TRUE then on windows the application will have a console attached.

CREA_ADD_LIBRARY ( LIBRARY_NAME)
Generates the cmake commands to build and install the library LIBRARY_NAME
Uses CREA_MANAGE_SHARED_LIBRARY and CREA_INSTALL_LIBRARY_FOR_CMAKE
hence one needs to set the mandatory variables for these two macros.
Additionnaly one needs to set :

${LIBRARY_NAME}_HEADERS : the list of headers to install

${LIBRARY_NAME}_SOURCES : the list of files to compile to build the lib

${LIBRARY_NAME}_LINK_LIBRARIES : the list of libs to link with

CREA_DYNAMIC_LIBRARY_EXPORT ( LIBRARY_NAME)

Manages cross-platform dynamic library creation/use and in particular Windows dll_import/export issues. Creates a file call ${LIBRARY_NAME}_EXPORT.h in current binary dir which defines the macros :
- ${LIBRARY_NAME}_EXPORT
- ${LIBRARY_NAME}_CDECL
  Which must be used for symbols to be imported/exported such as classes. For example if your library is called MyLib, then define a class MyClass like this :

#include "MyLib_EXPORT.h"

class MyLib_EXPORT MyClass

{

...

};

The macro also defines :

${LIBRARY_NAME}_BUILD_SHARED : which indicates that the lib is built as a shared lib

${LIBRARY_NAME}_EXPORT_SYMBOLS : which indicates that the lib has to export its symbols.

CREA_DYNAMIC_LIBRARY_EXPORT_OPTION ( library_name )

Does the same than CREA_DYNAMIC_LIBRARY_EXPORT but also defines a user option ${LIBRARY_NAME}_BUILD_SHARED.

If the option is set to ON then :

the variable ${LIBRARY_NAME}_SHARED is set to SHARED. Hence a command like :

ADD_LIBRARY( ${LIBRARY_NAME} ${${LIBRARY_NAME}_SHARED} ... )
automatically builds a shared lib if required and generates the file

the variable ${LIBRARY_NAME}_EXPORT_SYMBOLS is defined (see above).

CREA_DEFINE ( symbol )
Defines a C preprocessor symbol. All the definitions made this way are stored in a variable which is used to correctly set preprocessor definitions when running tools like doxygen.
CREA_DEFINE_WITH_VAL ( symbol value )
Defines a C preprocessor symbol to have a certain value. All the definitions made this way are stored in a variable which is used to correctly set preprocessor definitions when running tools like doxygen.
CREA_MKDIR( path )
Creates the directory path if it does not exist.
CREA_CPDIR( source dest )
Copies the content of the source directory and all its files and sub-directories to the dest directory, excluding CVS folders

CREA_FIND_AND_USE_LIBRARIES()

# Example of using the CREA_FIND_AND_USE_LIBRARIES macro

# Each library/program below set to ON will be searched for and the INCLUDE_DIRECTORIES, LINK_DIRECTORIES updated.

# For each library LIBNAME required, the variable LIBNAME_LIBRARIES is set to the libraries to link against,

# e.g. if one sets USE_VTK to ON then VTK_LIBRARIES is set to vtk libraries to link against

SET(USE_GDCM ON)

SET(USE_GDCM_VTK OFF)

SET(USE_WXWIDGETS ON)

SET(USE_VTK OFF)

SET(USE_ITK OFF)

SET(USE_BOOST OFF)

SET(USE_DOXYGEN OFF)

SET(USE_LATEX OFF)

# Invoke the macro

CREA_FIND_AND_USE_LIBRARIES()

# Link against gdcm and wxWidgets

TARGET_LINK_LIBRARIES( MyTargetWhichUsesGDCMandWxWidgets ${GDCM_LIBRARIES} ${WXWIDGETS_LIBRARIES} )

CREA_INSTALL_LIBRARY_FOR_CMAKE ( LIBRARY_NAME )

Creates and install the necessary files to find the library called LIBRARY_NAME with cmake FIND_PACKAGE mechanism.
This macros uses default installation settings. Use CREA_ADVANCED_INSTALL_LIBRARY_FOR_CMAKE to customize them.
The default settings are :

libraries to link against	LIBRARY_NAME
cmake files install dir	INSTALL_PREFIX/lib/LIBRARY_NAME
headers install dir	INSTALL_PREFIX/include/LIBRARY_NAME
library install dir	INSTALL_PREFIX/lib
build tree headers dir	current source directory (where the macro is invoked)
build tree library dir	LIBRARY_OUTPUT_PATH (+ Debug or Release on win32)

CREA_ADVANCED_INSTALL_LIBRARY_FOR_CMAKE ( LIBRARY_NAME )
Creates and install the necessary files to find the library called 'name' with cmake FIND_PACKAGE mechanism.


# Inputs :
# --------
#  LIBRARY_NAME : name of the library to find
#
# The following variables **MUST** have been set previously :
#
# * ${LIBRARY_NAME}_BUILD_TREE_RELATIVE_INCLUDE_PATHS
#    The list of include paths
#    when someone uses a *BUILD TREE* version of ${LIBRARY_NAME}.
#    NB :
#     THE PATHS *MUST BE RELATIVE* TO THE ROOT DIR OF THE PROJECT **SOURCES** !
#    Assume your project architecture is :
#     install/ : directory in which the macro is invoked
#     src/part1/include/ : first include dir
#     src/part2/include/ : second include dir
#    Then you should set the var with :
#    SET(${LIBRARY_NAME}_BUILD_TREE_RELATIVE_INCLUDE_PATHS
#     src/part1/include
#     src/part2/include )
#    Which will result in actual include paths :
#     ${PROJECT_SOURCE_DIR}/src/part1/include;
#     ${PROJECT_SOURCE_DIR}/src/part2/include
# * ${LIBRARY_NAME}_BUILD_TREE_RELATIVE_LIBRARY_PATHS
#    Like the previous var but for the library paths.
#    NB :
#     THE PATHS *MUST BE RELATIVE* TO THE ROOT DIR OF THE **BUILD TREE**
#     THAT IS POINT TO THE FOLDERS WHERE THE LIBS WILL BE BUILD
#    Assume that your project architecture is :
#     src/part1/src/ : first source dir, in which the lib 'part1' is built
#     src/part2/src/ : first source dir, in which the lib 'part2' is built
#    Then you should set the var with
#    SET(${LIBRARY_NAME}_BUILD_TREE_RELATIVE_LIBRARY_PATHS
#     src/part1/src
#     src/part2/src
#     )
#    Which will result in actual library paths :
#     ${PROJECT_BINARY_DIR}/src/part1/src
#     ${PROJECT_BINARY_DIR}/src/part2/src
# * ${LIBRARY_NAME}_INSTALL_TREE_RELATIVE_INCLUDE_PATHS
#    The list of include paths
#    when someone uses an *INSTALLED* version of ${LIBRARY_NAME}
#    The paths *MUST BE RELATIVE* to INSTALL_PREFIX
#    A typical example is "include/${LIBRARY_NAME}"
# * ${LIBRARY_NAME}_INSTALL_TREE_RELATIVE_LIBRARY_PATHS
#    Like the previous var but for library paths.
#    A typical example is "lib"
# * ${LIBRARY_NAME}_LIBRARIES
#    The list of libraries to link against when using ${LIBRARY_NAME}
#
# The following variables can be set optionally :
#
# * ${LIBRARY_NAME}_REQUIRED_C_FLAGS
# * ${LIBRARY_NAME}_REQUIRED_CXX_FLAGS
# * ${LIBRARY_NAME}_REQUIRED_LINK_FLAGS
# * ${LIBRARY_NAME}_MAJOR_VERSION
# * ${LIBRARY_NAME}_MINOR_VERSION
# * ${LIBRARY_NAME}_BUILD_VERSION
# * ${LIBRARY_NAME}_INSTALL_FOLDER : if set then installs the generated cmake files
#   in INSTALL_PREFIX/lib/${LIBRARY_NAME}_INSTALL_FOLDER
#   instead of INSTALL_PREFIX/lib/${LIBRARY_NAME}
#
#
# To provide a user defined
# couple of Config/Use file (in addition to the standard one) use :
#  SET( ${LIBRARY_NAME}_HAS_ADDITIONAL_CONFIG_FILE  TRUE )
# and store the *ABSOLUTE* paths to the additional files in the vars :
#  ${LIBRARY_NAME}_ADDITIONAL_CONFIG_FILE
#  ${LIBRARY_NAME}_ADDITIONAL_USE_FILE
# (e.g. ${CMAKE_CURRENT_SOURCE_DIR}/MyConfig.cmake)
#
# Outputs :
# --------
# At cmake run-time, the macro creates the following files
# in the current dir of the build tree (where the macro is invoked) :
#  Use${LIBRARY_NAME}.cmake
#  ${LIBRARY_NAME}Config.cmake
#  ${LIBRARY_NAME}BuildSettings.cmake
# And if the vars ${LIBRARY_NAME}_ADDITIONAL_CONFIG_FILE and
# ${LIBRARY_NAME}_ADDITIONAL_USE_FILE are set, it also creates :
#  Additional${LIBRARY_NAME}Config.cmake
#  AdditionalUse${LIBRARY_NAME}.cmake
#
# At install-time, the same files are installed
# in INSTALL_PREFIX/lib/${LIBRARY_NAME}_INSTALL_FOLDER
# and the file :
#  Find${LIBRARY_NAME}.cmake
# is installed in ${CMAKE_ROOT}/Modules/
#

CREA_PREVENT_IN_SOURCE_BUILD

If this macro is used then a cmake fatal error occurs when running cmake in the source tree.
Its effect can be disabled by setting CREA_ALLOW_IN_SOURCE_BUILD to TRUE

creaNewProject

The script creaNewProject.bat for Windows and creaNewProject.sh for linux create a void project structure on your disk.

Their usage is the same : creaNewProject <project-path> <project-name>

crea also provides the application creaNewProject which simply pops up a directory selector dialog and an input text dialog an then runs the script with the user's answer.

The void project structure is as follows :

|-- CMakeLists.txt

|-- appli

| |-- CMakeLists.txt

| |-- template_appli

| | `-- CMakeLists.txt

| `-- template_wx_appli

| `-- CMakeLists.txt

`-- lib

|-- CMakeLists.txt

`-- template_lib

`-- CMakeLists.txt

You must first customize the project settings in the root CMakeLists.txt.

Then, to create a new application to your project:

copy the folder appli/template-appli in the same folder.
rename the newly created folder, e.g. to MyApp
edit appli/CMakeLists.txt and add the command : SUBDIRS(MyApp)
edit appli/MyApp/CMakeLists.txt and customize your application settings

The same route holds for creating a new wx application (folder appli/template_wx_appli) or a new library (folder lib/template_lib).

C++ Library

Some samples are provided in the samples directory :

creaSample_preprocessor
creaSample_MessageManager

TO BE CONTINUED...

CreaTools: Library Crea - Developers

Build from the sources

Using crea in an external project with CMake

CMake macros provided by crea

CREA_ADD_LIBRARY ( LIBRARY_NAME)

CREA_DYNAMIC_LIBRARY_EXPORT ( LIBRARY_NAME)

CREA_DYNAMIC_LIBRARY_EXPORT_OPTION ( library_name )

CREA_DEFINE ( symbol )

CREA_DEFINE_WITH_VAL ( symbol value )

CREA_MKDIR( path )

CREA_CPDIR( source dest )

CREA_FIND_AND_USE_LIBRARIES()

CREA_INSTALL_LIBRARY_FOR_CMAKE ( LIBRARY_NAME )

CREA_ADVANCED_INSTALL_LIBRARY_FOR_CMAKE ( LIBRARY_NAME )

CREA_PREVENT_IN_SOURCE_BUILD

creaNewProject

C++ Library