Public interface of CMake modules. More...

Collaboration diagram for Public CMake Interface:

Files
file	BasisPack.cmake
	CPack configuration. Include this module instead of CPack.
file	BasisTest.cmake
	CTest configuration. Include this module instead of CTest.
file	BasisTools.cmake
	Definition of functions and macros used by BASIS project.
Functions
function	basis_add_component (in COMPNAME, in ARGN)
	Add component.
function	basis_add_component_group (in GRPNAME, in ARGN)
	Add component group.
function	basis_add_definitions (in ARGN)
	Add compile definitions.
function	basis_add_dependencies (in ARGN)
	Add dependencies to build target.
function	basis_add_doc (in TARGET_NAME, in ARGN)
	Add documentation target.
function	basis_add_executable (in TARGET_NAME, in ARGN)
	Add executable target.
function	basis_add_install_type (in ARGN)
	Add pre-configured install type.
function	basis_add_library (in TARGET_NAME, in ARGN)
	Add library target.
function	basis_add_test (in TEST_NAME, in ARGN)
	Add test.
function	basis_add_test_driver (in TESTDRIVER_NAME, in ARGN)
	Create and add a test driver executable.
function	basis_configure_downloads (in ARGN)
	Configure installation-time downloads of selected components.
macro	basis_find_package (in PACKAGE, in ARGN)
	Find external software package or other project module.
macro	basis_get_filename_component ()
	Alias for the overwritten get_filename_component() function.
function	basis_get_property (in VAR, in SCOPE, in ELEMENT, in ARGN)
	Get a property.
function	basis_get_relative_path (in REL, in BASE, in PATH)
	Get path relative to a given base directory.
function	basis_get_target_property (in VAR, in TARGET_NAME, in ARGN)
	Get value of property set on target.
function	basis_get_test_property (in VAR, in TEST_NAME, in ARGN)
	Get a property of the test.
function	basis_include_directories (in ARGN)
	Add directories to search path for include files.
function	basis_install ()
	Specify rules to run at install time.
function	basis_install_directory (in ARGN)
	Install content of source directory excluding typical files.
function	basis_install_link (in OLD, in NEW)
	Add installation rule to create a symbolic link.
function	basis_link_directories (in ARGN)
	Add directories to search path for libraries.
macro	basis_project (in ARGN)
	Defines project meta-data, i.e., attributes.
macro	basis_project_impl ()
	Implementation of root `CMakeLists.txt` file of BASIS project.
function	basis_remove_definitions (in ARGN)
	Remove previously added compile definitions.
function	basis_set_property (in SCOPE, in ARGN)
	Set a named property in a given scope.
function	basis_set_script_path (in VAR, in PATH, in ARGV3)
	Set path relative to script file.
function	basis_set_target_properties (in ARGN)
	Set properties on a target.
function	basis_set_tests_properties (in ARGN)
	Set a property of the tests.
function	basis_target_link_libraries (in TARGET_NAME, in ARGN)
	Add link dependencies to build target.
macro	basis_use_package (in PACKAGE)
	Use found package.

Detailed Description

Public interface of CMake modules.

The variables, functions, and macros listed here are intended to be used by the developer of a software development project based on BASIS in their project specific CMake implementation and the CMakeLists.txt files.

Function Documentation

function basis_add_component	(	in	COMPNAME,
		in	ARGN
	)

Add component.

Attention:: This functionality is not yet entirely implemented.

Todo:: Come up and implement components concept which fits into superproject concept.

Parameters:

[in]	COMPNAME	Name of the component.
[in]	ARGN	Further arguments passed to cpack_add_component().

Returns:: Adds the component named COMPNAME.

See also:: http://www.cmake.org/pipermail/cmake/2008-August/023336.html; cpack_add_component()

function basis_add_component_group	(	in	GRPNAME,
		in	ARGN
	)

Add component group.

Attention:: This functionality is not yet entirely implemented.

Todo:: Come up and implement components concept which fits into superproject concept.

Parameters:

[in]	GRPNAME	Name of the component group.
[in]	ARGN	Further arguments passed to cpack_add_component_group().

Returns:: Adds the component group GRPNAME.

See also:: http://www.cmake.org/pipermail/cmake/2008-August/023336.html; cpack_add_component_group()

function basis_add_definitions ( in ARGN )

Add compile definitions.

This function replaces CMake's add_definitions() command.

Parameters:

[in] ARGN List of arguments for add_definitions().

Returns:: Adds the given definitions.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:add_definitions

function basis_add_dependencies ( in ARGN )

Add dependencies to build target.

This function replaces CMake's add_dependencies() command and extends its functionality. In particular, it maps the given target names to the corresponding target UIDs.

Parameters:

[in] ARGN Arguments for add_dependencies().

Returns:: Adds the given dependencies of the specified build target.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:add_dependencies

function basis_add_doc	(	in	TARGET_NAME,
		in	ARGN
	)

Add documentation target.

This function is especially used to add a custom target to the "doc" target which is used to generate documentation from input files such as in particular source code files. Other documentation files such as HTML, Word, or PDF documents can be added as well using this function. A component as part of which this documentation shall be installed can be specified.

Parameters:

[in]	TARGET_NAME	Name of the documentation target or file.
[in]	ARGN	List of arguments. The valid arguments are:

COMPONENT component	Name of the component this documentation belongs to. Defaults to `BASIS_LIBRARY_COMPONENT` for documentation generated from in-source comments and `BASIS_RUNTIME_COMPONENT`, otherwise.
GENERATOR generator	Documentation generator, where the case of the generator name is ignored, i.e., `Doxygen`, `DOXYGEN`, `doxYgen` are all valid arguments which select the `Doxygen` generator. The parameters for the different supported generators are documented below. The default generator is `None`. The `None` generator simply installs the document with the filename `TARGET_NAME` and has no own options.
DESTINATION dir	Installation directory prefix. Defaults to `INSTALL_DOC_DIR` or `INSTALL_DOC_DIR/<target>` in case of the Doxygen generator, where `<target>` is the `TARGET_NAME` in lowercase only.

Generator: None

The documentation files are installed in/as INSTALL_DOC_DIR/TARGET_NAME as part of the component specified by the COMPONENT option.

OUTPUT_NAME filename Name of installed documentationf file. Default: TARGET_NAME.

Example:

 basis_add_doc ("User Manual.pdf" OUTPUT_NAME "BASIS User Manual.pdf")
 basis_add_doc (DeveloperManual.docx COMPONENT dev)
 basis_add_doc (SourceManual.html    COMPONENT src)

Generator: Doxygen

Uses the Doxygen tool to generate the documentation from in-source code comments.

DOXYFILE file	Name of the template Doxyfile.
PROJECT_NAME name	Value for Doxygen's `PROJECT_NAME` tag which is used to specify the project name. Default: `PROJECT_NAME`.
PROJECT_NUMBER version	Value for Doxygen's `PROJECT_NUMBER` tag which is used to specify the project version number. Default: `PROJECT_VERSION_AND_REVISION`.
INPUT path1 [path2 ...]	Value for Doxygen's `INPUT` tag which is used to specify input directories/files. Any given input path is added to the default input paths. Default: `PROJECT_CODE_DIR`, `BINARY_CODE_DIR`, `PROJECT_INCLUDE_DIR`, `BINARY_INCLUDE_DIR`.
INPUT_FILTER filter	Value for Doxygen's `INPUT_FILTER` tag which can be used to specify a default filter for all input files. Set to either one of `None`, `NONE`, or `none` to use no input filter. Default: `doxyfilter` of BASIS.
FILTER_PATTERNS pattern1 [pattern2...]	Value for Doxygen's `FILTER_PATTERNS` tag which can be used to specify filters on a per file pattern basis. Default: BASIS Doxygen filter patterns.
INCLUDE_PATH path1 [path2...]	Doxygen's `INCLUDE_PATH` tag can be used to specify one or more directories that contain include files that are not input files but should be processed by the preprocessor. Any given directories are appended to the default include path considered. Default: Directories added by basis_include_directories().
EXCLUDE_PATTERNS pattern1 [pattern2 ...]	Additional patterns used for Doxygen's `EXCLUDE_PATTERNS` tag which can be used to specify files and/or directories that should be excluded from the INPUT source files. Default: No exclude patterns.
OUTPUT_DIRECTORY dir	Value for Doxygen's `OUTPUT_DIRECTORY` tag which can be used to specify the output directory. The output files are written to subdirectories named "html", "latex", "rtf", and "man". Default: `CMAKE_CURRENT_BINARY_DIR/TARGET_NAME`.
COLS_IN_ALPHA_INDEX n	Number of columns in alphabetical index if `GENERATE_HTML` is `YES`. Default: 3.
GENERATE_HTML	If given, Doxygen's `GENERATE_HTML` tag is set to YES, otherwise NO.
GENERATE_LATEX	If given, Doxygen's `GENERATE_LATEX` tag is set to YES, otherwise NO.
GENERATE_RTF	If given, Doxygen's `GENERATE_RTF` tag is set to YES, otherwise NO.
GENERATE_MAN	If given, Doxygen's `GENERATE_MAN` tag is set to YES, otherwise NO.

See here for a documentation of the Doxygen tags. If none of the GENERATE_<*> options is given, GENERATE_HTML is set to YES.

Example:

 basis_add_doc (
   api
   GENERATOR Doxygen
     DOXYFILE        "Doxyfile.in"
     PROJECT_NAME    "${PROJECT_NAME}"
     PROJECT_VERSION "${PROJECT_VERSION}"
   COMPONENT dev
 )

Returns:: Adds a custom target TARGET_NAME for the generation of the documentation or configures the given file in case of the None generator.

function basis_add_executable	(	in	TARGET_NAME,
		in	ARGN
	)

Add executable target.

This is the main function to add an executable target to the build system, where an executable can be a binary file or a script written in a scripting language. In general we refer to any output file which is part of the software (i.e., excluding configuration files) and which can be executed (e.g., a binary file in the ELF format) or interpreted (e.g., a BASH script) directly, as executable file. Natively, CMake supports only executables build from C/C++ source code files. This function extends CMake's capabilities by adding custom build commands for non-natively supported programming languages and further standardizes the build of executable targets. For example, by default, it is not necessary to specify installation rules separately as these are added by this function already (see below).

Programming languages

Besides adding usual executable targets build by the set C/CXX language compiler, this function inspects the list of source files given and detects whether this list contains sources which need to be build using a different compiler. In particular, it supports the following languages:

CXX	The default behavior, adding an executable target build from C/C++ source code. The target is added via CMake's add_executable() command.
PYTHON\|PERL\|BASH	Executables written in one of the named scripting languages are built by configuring and/or copying the script files to the build tree and installation tree, respectively. During the build step, certain strings of the form @VARIABLE@ are substituted by the values set during the configure step. How these CMake variables are set is specified by a so-called script configuration file, which itself is a CMake script.
MATLAB	Standalone application build from MATLAB sources using the MATLAB Compiler (mcc). This language option is used when the list of source files contains one or more .m files. A custom target is added which depends on custom command(s) that build the executable. Attention: The .m file with the entry point/main function of the executable has to be given before any other *.m file.

Helper functions: If the programming language of the input source files is not specified explicitly by providing the LANGUAGE argument, the extensions of the source files are inspected using basis_get_source_language(). Once the programming language is known, this function invokes the proper subcommand. In particular, it calls basis_add_executable_target() for C++ sources (.cxx), basis_add_mcc_target() for MATLAB scripts (.m), and basis_add_script() for all other source files.

Note:: DO NOT use the mentioned subcommands directly. Always use basis_add_library() to add a library target to your project. Only refer to the documentation of the subcommands to learn about the available options of the particular subcommand.

Output directories: The built executable file is output to the BINARY_RUNTIME_DIR or BINARY_LIBEXEC_DIR if the LIBEXEC option is given. If this function is used within the PROJECT_TESTING_DIR, however, the built executable is output to the TESTING_RUNTIME_DIR or TESTING_LIBEXEC_DIR instead.

Installation: An install command for the added executable target is added by this function as well. The executable will be installed as part of the component COMPONENT in the directory INSTALL_RUNTIME_DIR or INSTALL_LIBEXEC_DIR if the option LIBEXEC is given. Executable targets are exported such that they can be imported by other CMake-aware projects by including the CMake configuration file of this package (<Package>Config.cmake file). No installation rules are added, however, if this function is used within the PROJECT_TESTING_DIR. Test executables are further only exported as part of the build tree.

Note:: If this function is used within the PROJECT_TESTING_DIR, the built executable is output to the TESTING_RUNTIME_DIR or TESTING_LIBEXEC_DIR instead. Moreover, no installation rules are added. Test executables are further only exported as part of the build tree.

Parameters:

[in]	TARGET_NAME	Name of the target. If a source file is given as first argument, the build target name is derived from the name of this source file.
[in]	ARGN	This argument list is parsed and the following arguments are extracted, all other arguments are passed on to add_executable() or the respective custom commands used to build the executable.

COMPONENT name	Name of the component. Default: `BASIS_RUNTIME_COMPONENT`.
DESTINATION dir	Installation directory relative to `INSTALL_PREFIX`. If "none" (the case is ignored) is given as argument, no installation rules are added for this executable target. Default: `INSTALL_RUNTIME_DIR` or `INSTALL_LIBEXEC_DIR` (if `LIBEXEC` is given).
LANGUAGE lang	Source code language. By default determined from the extensions of the given source files.
LIBEXEC	Specifies that the built executable is an auxiliary executable which is only called by other executables.
NO_BASIS_UTILITIES	Do not add the BASIS C++ utilities as link dependency.
NO_EXPORT	Do not export the target.
WITH_PATH , WITH_EXT	See documentation of basis_add_script().
CONFIG , CONFIG_FILE	See documentation of basis_add_script().

Returns:: Adds an executable build target. In case of an executable which is not build from C++ source files, the function basis_add_custom_finalize() has to be invoked to finalize the addition of the custom build target. This is done automatically by the basis_project_impl() macro.

See also:: basis_add_executable_target(); basis_add_script(); basis_add_mcc_target()

function basis_add_install_type ( in ARGN )

Add pre-configured install type.

Parameters:

[in] ARGN Arguments for cpack_add_install_type().

Returns:: Adds a pre-configured installation type.

See also:: CPack.cmake; cpack_add_install_type ()

function basis_add_library	(	in	TARGET_NAME,
		in	ARGN
	)

Add library target.

This is the main function to add a library target to the build system, where a library can be a binary archive, shared library, a MEX-file or a module written in a scripting language. In general we refer to any output file which is part of the software (i.e., excluding configuration files), but cannot be executed (e.g., a binary file in the ELF format) or interpreted (e.g., a BASH script) directly, as library file. Natively, CMake supports only libraries build from C/C++ source code files. This function extends CMake's capabilities by adding custom build commands for non-natively supported programming languages and further standardizes the build of library targets. For example, by default, it is not necessary to specify installation rules separately as these are added by this function already (see below).

Programming languages

Besides adding usual library targets built from C/C++ source code files, this function can also add custom build targets for libraries implemented in other programming languages. It therefore tries to detect the programming language of the given source code files and delegates the addition of the build target to the proper helper functions. It in particular supports the following languages:

CXX	Source files written in C/C++ are by default built into either `STATIC`, `SHARED`, or `MODULE` libraries. If the `MEX` option is given, however, a MEX-file (a shared library) is build using the MEX script instead of using the default C++ compiler directly.
PYTHON\|PERL\|BASH	Modules written in one of the named scripting languages are built similar to executable scripts except that the file name extension is preserved and no executable file permission is set on Unix. These modules are intended for import/inclusion in other modules or executables written in the particular scripting language only.
MATLAB	Shared libraries built from MATLAB sources using the MATLAB Compiler (mcc). This language option is used when the list of source files contains one or more *.m files. A custom target is added which depends on custom command(s) that build the library.

Helper functions: If the programming language of the input source files is not specified explicitly by providing the LANGUAGE argument, the extensions of the source files are inspected using basis_get_source_language(). Once the programming language is known, this function invokes the proper subcommand. In particular, it calls basis_add_library_target() for C++ sources (.cxx) if the target is not a MEX-file target, basis_add_mex_target() for C++ sources if the MEX option is given, basis_add_mcc_target() for MATLAB scripts (.m), and basis_add_script() for all other source files.

Note:: DO NOT use the mentioned subcommands directly. Always use basis_add_library() to add a library target to your project. Only refer to the documentation of the subcommands to learn about the available options of the particular subcommand.

Output directories: The built libraries are output to the BINARY_RUNTIME_DIR, BINARY_LIBRARY_DIR, and/or BINARY_ARCHIVE_DIR. Python modules are output to subdirectories in the BINARY_PYTHON_LIBRARY_DIR. Perl modules are output to subdirectories in the BINARY_PERL_LIBRARY_DIR. If this command is used within the PROJECT_TESTING_DIR, however, the files are output to the TESTING_RUNTIME_DIR, TESTING_LIBRARY_DIR, TESTING_ARCHIVE_DIR, TESTING_PYTHON_LIBRARY_DIR, or TESTING_PERL_LIBRARY_DIR instead.

Installation: An install command for the added library target is added by this function as well. Runtime libraries are installed as part of the RUNTIME_COMPONENT to the RUNTIME_DESTINATION. Library components are installed as part of the LIBRARY_COMPONENT to the LIBRARY_DESTINATION. Library targets are exported such that they can be imported by other CMake-aware projects by including the CMake configuration file of this package (<Package>Config.cmake file). If this function is used within the PROJECT_TESTING_DIR, however, no installation rules are added. Test library targets are further only exported as part of the build tree.

Example

 basis_add_library (MyLib1 STATIC mylib.cxx)
 basis_add_library (MyLib2 STATIC mylib.cxx COMPONENT dev)

 basis_add_library (
   MyLib3 SHARED mylib.cxx
   RUNTIME_COMPONENT bin
   LIBRARY_COMPONENT dev
 )

 basis_add_library (MyMex MEX mymex.cxx)
 basis_add_library (PythonModule MyModule.py.in)
 basis_add_library (ShellModule MODULE MyModule.sh.in)

Parameters:

[in]	TARGET_NAME	Name of the target. If a source file is given as first argument, the build target name is derived from the name of this source file.
[in]	ARGN	This argument list is parsed and the following arguments are extracted:

LANGUAGE lang	Source code language. By default determined from the extensions of the given source code files.
STATIC\|SHARED\|MODULE\|MEX	Type of the library.
COMPONENT name	Name of the component. Default: `BASIS_LIBRARY_COMPONENT`.
RUNTIME_COMPONENT name	Name of runtime component. Default: `COMPONENT` if specified or `BASIS_RUNTIME_COMPONENT`, otherwise.
LIBRARY_COMPONENT name	Name of library component. Default: `COMPONENT` if specified or `BASIS_LIBRARY_COMPONENT`, otherwise.
NO_EXPORT	Do not export build target.

Returns:: Adds a library build target. In case of a library not written in C++ or MEX-file targets, basis_add_custom_finalize() has to be invoked to finalize the addition of the build target(s). This is done automatically by the basis_project_impl() macro.

See also:: basis_add_library_target(); basis_add_script(); basis_add_mex_target(); basis_add_mcc_target()

function basis_add_test	(	in	TEST_NAME,
		in	ARGN
	)

Add test.

This command is used similar to CMake's add_test() command. It adds a test to the CTest-based testing system. Unlike CMake's add_test(), this command can, for convenience, implicitly add the necessary executable build target to the build system. Therefore, instead of the name of the executable command, specify the sources of the test implementation. An executable build target is then added by this function using basis_add_executable(), and the built executable is used as test command. If the UNITTEST option is given, the necessary unit testing libraries which are part of the BASIS installation are added as link dependencies as well as the default implementation of the main() function if none of the specified source files has the suffix -main or _main in the file name.

Generator expressions as supported by CMake's add_test() command are also supported by basis_add_test() as arguments of the test command. For the argument specifying the test command itself, however, only the generator expression $<TARGET_FILE:tgt> is allowed. Alternatively, for this special argument, the name of the executable target can be supplied directly without the use of the $<TARGET_FILE:tgt> generator expression. See documentation of basis_process_generator_expressions() for details on the supported generator expressions.

Example:

 basis_add_test (COMMAND $<TARGET_FILE:basis.testdriver> $<TARGET_FILE:myexe> ...)
 basis_add_test (COMMAND basis.testdriver $<TARGET_FILE:myexe> ...)

Parameters:

[in]	TEST_NAME	Name of the test. If a source file is given as first argument, the test name is derived from the name of this source file and the source file is added to the list of sources which implement the test command.
[in]	ARGN	The following parameters are parsed:

COMMAND cmd [arg1 [arg2 ...]]	The command to execute and optionally its arguments. The command can be the name of an executable target (including imported targets), or the name or path of an executable. Alternatively, a test can be build from sources and the build executable used as command. In this case, specify the sources using the `SOURCES` argument. The command name `cmd` if given is used as output name of the built executable. If you do not want to specify the name of the output executable explicitly, but have it derived from the `TEST_NAME`, do not specify the `COMMAND` option and use the `ARGS` option instead to only specify the arguments of the test command.
ARGS arg1 [arg2 ...]	Arguments of the test command. If this option is given, the specified arguments are appended to the arguments specified already as part of the `COMMAND` option, if any.
WORKING_DIRECTORY dir	The working directory of the test command. The generator expression $<TARGET_FILE_DIR:tgt> can be used to specify a working directory which corresponds to the output directory of a given target file. Default: `TESTING_OUTPUT_DIR` / `TEST_NAME`.
CONFIGURATIONS	If a CONFIGURATIONS option is given then the test will be executed only when testing under one of the named configurations.
SOURCES file1 [file2 ...]	The source files of the test. Use the `UNITTEST` option to specify that the sources are an implementation of a unit test. In this case, the default implementation of the main() function is added to the build of the test executable. However, if this list contains a file with the suffix `-main` or `_main` in the name, the default implementation of the main() function is not used. See the documentation of the `UNITTEST` option for further details.
LINK_DEPENDS file1\|target1 [file2\|target2 ...]	Link dependencies of test executable build from sources.
NO_DEFAULT_MAIN	Force that the implementation of the default main() function is not added to unit tests even if neither of the given source files has the suffix `-main` or `_main` in the file name.
UNITTEST	Specifies that the test is a unit test. In this case, the test implementation is linked to the default unit testing framework for the used programming language which is part of the BASIS installation.
WITH_EXT	Do not strip extension if test name is derived from source file name.
ARGN	All other arguments are passed on to basis_add_executable() if an executable target for the test is added.

Returns:: Adds build target for test executable if test source files are given and/or adds a CTest test which executes the given test command.

See also:: basis_process_generator_expressions(); http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:add_test

Todo:: Make use of ExternalData module to fetch remote test data.

function basis_add_test_driver	(	in	TESTDRIVER_NAME,
		in	ARGN
	)

Create and add a test driver executable.

Parameters:

[in]	TESTDRIVER_NAME	Name of the test driver.
[in]	ARGN	List of source files implementing tests.

function basis_configure_downloads ( in ARGN )

Configure installation-time downloads of selected components.

Parameters:

[in] ARGN Arguments for cpack_configure_downloads().

Returns:: Nothing.

See also:: CPack.cmake; cpack_configure_downloads()

macro basis_find_package	(	in	PACKAGE,
		in	ARGN
	)

Find external software package or other project module.

This function replaces CMake's find_package() command and extends its functionality. In particular, if the given package name is the name of another module of this project (the top-level project), it ensures that this module is found instead of an external package.

If the package is found, but only optionally used, i.e., the REQUIRED argument was not given to this macro, a USE_<Pkg> option is added by this macro which is by default ON. This option can be set to OFF by the user in order to force the <Pkg>_FOUND variable to be set to FALSE again even if the package was found. This allows the user to specify which of the optional dependencies should actually not be used for the build of the software even though these packages are installed on their system.

Parameters:

[in]	PACKAGE	Name of other package. Optionally, the package name can include a version specification as suffix which is separated by the package name using a dash (-), i.e., <Package>[-major[.minor[.patch[.tweak]]]]. If a version specification is given, it is passed on as `version` argument to CMake's find_package() command.
[in]	ARGN	Advanced arguments for find_package().

Return values:

<PACKAGE>_FOUND Whether the given package was found.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:find_package

macro basis_get_filename_component ( )

Alias for the overwritten get_filename_component() function.

See also:: get_filename_component()

function basis_get_property	(	in	VAR,
		in	SCOPE,
		in	ELEMENT,
		in	ARGN
	)

Get a property.

This function replaces CMake's get_property() command.

Parameters:

[out]	VAR	Property value.
[in]	SCOPE	The argument for the `SCOPE` argument of get_property().
[in]	ELEMENT	The argument for the `ELEMENT` argument of get_property().
[in]	ARGN	Arguments as accepted by get_property().

Returns:: Sets VAR to the value of the requested property.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:get_property

function basis_get_relative_path	(	in	REL,
		in	BASE,
		in	PATH
	)

Get path relative to a given base directory.

Unlike the file(RELATIVE_PATH ...) command of CMake which if PATH and BASE are the same directory returns an empty string, this function returns a dot (.) in this case instead.

Parameters:

[out]	REL	`PATH` relative to `BASE`.
[in]	BASE	Path of base directory. If a relative path is given, it is made absolute using basis_get_filename_component() with ABSOLUTE as last argument.
[in]	PATH	Absolute or relative path. If a relative path is given it is made absolute using basis_get_filename_component() with ABSOLUTE as last argument.

Returns:: Sets the variable named by the first argument to the relative path.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:file

function basis_get_target_property	(	in	VAR,
		in	TARGET_NAME,
		in	ARGN
	)

Get value of property set on target.

This function replaces CMake's get_target_properties() command and extends its functionality. In particular, it maps the given TARGET_NAME to the corresponding target UID.

Parameters:

[out]	VAR	Name of output variable.
[in]	TARGET_NAME	Name of build target.
[in]	ARGN	Remaining arguments for get_target_properties().

Returns:: Sets VAR to the value of the requested property.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:get_target_property

function basis_get_test_property	(	in	VAR,
		in	TEST_NAME,
		in	ARGN
	)

Get a property of the test.

This function replaces CMake's get_test_property() command.

Parameters:

[out]	VAR	Property value.
[in]	TEST_NAME	Name of test.
[in]	ARGN	Remaining arguments of get_test_property().

Returns:: Sets VAR to the value of the requested property.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:get_test_property

function basis_include_directories ( in ARGN )

Add directories to search path for include files.

This function replaces CMake's include_directories() command. Besides invoking CMake's internal command with the given arguments, it updates the PROJECT_INCLUDE_DIRECTORIES property on the current project (see basis_set_project_property()). This list contains a list of all include directories used by a project, regardless of the directory in which the basis_include_directories() function was used.

Parameters:

ARGN	List of arguments for include_directories() command.

Returns:: Nothing.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:include_directories

function basis_install ( )

Specify rules to run at install time.

This function replaces CMake's install() command.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:install

function basis_install_directory ( in ARGN )

Install content of source directory excluding typical files.

Files which are excluded are typical backup files, system files, files from revision control systems, and CMakeLists.txt files.

Example:

 basis_install_directory("${INSTALL_DATA_DIR}")
 basis_install_directory(. "${INSTALL_DATA_DIR}")
 basis_install_directory("${CMAKE_CURRENT_SOURCE_DIR}" "${INSTALL_DATA_DIR}")
 basis_install_directory(images "${INSTALL_DATA_DIR}/images")

Parameters:

[in] ARGN The first two arguments are extracted from the beginning of this list in the named order (without option name), and the remaining arguments are passed on to CMake's install(DIRECTORY) command.

SOURCE	Source directory. Defaults to current source directory if only one argument, the `DESTINATION`, is given./td>
DESTINATION	Destination directory.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:install

function basis_install_link	(	in	OLD,
		in	NEW
	)

Add installation rule to create a symbolic link.

Note that the installation rule will only be effective on a Unix-like system, i.e., one which supports the creation of a symbolic link.

Parameters:

[in]	OLD	The value of the symbolic link.
[in]	NEW	The name of the symbolic link.

Returns:: Adds installation rule to create the symbolic link NEW.

function basis_link_directories ( in ARGN )

Add directories to search path for libraries.

This function replaces CMake's link_directories() command. Even though this function yet only invokes CMake's internal command, it should be used in BASIS projects to enable the extension of this command's functionality as part of BASIS if required.

Parameters:

[in] ARGN List of arguments for link_directories().

Returns:: Adds the given paths to the search path for libraries.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:link_directories

macro basis_project ( in ARGN )

Defines project meta-data, i.e., attributes.

Any BASIS project has to call this macro in the file BasisProject.cmake located in the top level directory of the source tree in order to define the project attributes required by BASIS to setup the build system. Moreover, if the BASIS project is a module of another BASIS project, this file and the variables set by this macro are used by the top-level project to identify its modules and the dependencies among them.

Project version:

The version number consists of three components: the major version number, the minor version number, and the patch number. The format of the version string is "<major>.<minor>.<patch>", where the minor version number and patch number default to "0" if not given. Only digits are allowed except of the two separating dots.

A change of the major version number indicates changes of the softwares API (and ABI) and/or its behavior and/or the change or addition of major features.
A change of the minor version number indicates changes that are not only bug fixes and no major changes. Hence, changes of the API but not the ABI.
A change of the patch number indicates changes only related to bug fixes which did not change the softwares API. It is the least important component of the version number.

Dependencies:: Dependencies on other BASIS projects, which can be subprojects of the same BASIS top-level project, as well as dependencies on external packages such as ITK have to be defined here using the DEPENDS argument option. This will be used by a top-level project to ensure that the dependencies among its subprojects are resolved properly. For each external dependency, the BASIS functions basis_find_package() and basis_use_package() are invoked by basis_project_initialize(). If an external package is not CMake aware and additional CMake code shall be executed to include the settings of the external package (which is usually done in a so-called Use<Pkg>.cmake file if the package would be CMake aware), such code should be added to the Settings.cmake file of the project.

Parameters:

[in] ARGN This list is parsed for the following arguments:

NAME name	The name of the project.
VERSION major[.minor[.patch]]	Project version string. Defaults to "1.0.0"
DESCRIPTION description	Package description, used for packing. If multiple arguments are given, they are concatenated using one space character as delimiter.
PACKAGE_VENDOR name	The vendor of this package, used for packaging. If multiple arguments are given, they are concatenated using one space character as delimiter. Default: "SBIA Group at University of Pennsylvania".
DEPENDS name[, name]	List of dependencies, i.e., either names of other BASIS (sub)projects or names of external packages.
OPTIONAL_DEPENDS name[, name]	List of dependencies, i.e., either names of other BASIS (sub)projects or names of external packages which are used only if available.
TEST_DEPENDS name[, name]	List of dependencies, i.e., either names of other BASIS (sub)projects or names of external packages which are only required by the tests.
OPTIONAL_TEST_DEPENDS name[, name]	List of dependencies, i.e., either names of other BASIS (sub)projects or names of external packages which are used only by the tests if available.

Returns:: Sets the following non-cached CMake variables:

Return values:

PROJECT_NAME	`NAME` argument.
PROJECT_VERSION	`VERSION` argument.
PROJECT_DESCRIPTION	Concatenated `DESCRIPTION` arguments.
PROJECT_PACKAGE_VENDOR	Concatenated `PACKAGE_VENDOR` argument.
PROJECT_DEPENDS	`DEPENDS` arguments.
PROJECT_OPTIONAL_DEPENDS	`OPTIONAL_DEPENDS` arguments.
PROJECT_TEST_DEPENDS	`TEST_DEPENDS` arguments.
PROJECT_OPTIONAL_TEST_DEPENDS	`OPTIONAL_TEST_DEPENDS` arguments.

macro basis_project_impl ( )

Implementation of root CMakeLists.txt file of BASIS project.

This macro implements the entire logic of the top-level CMakeLists.txt file. At first, the project is initialized and the BASIS settings configured using the project information given in the BasisProject.cmake file which must be located in the same directory. The, the code in the CMakeLists.txt files in the subdirectories is executed in order. At the end, the configuration of the build system is finalized, including in particular also the addition of custom build targets which perform the actual build of custom build targets such as the ones build using the MATLAB Compiler.

See also:: BasisProject.cmake; basis_project()

function basis_remove_definitions ( in ARGN )

Remove previously added compile definitions.

This function replaces CMake's remove_definitions() command.

Parameters:

[in] ARGN List of arguments for remove_definitions().

Returns:: Removes the specified definitions.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:remove_definition

function basis_set_property	(	in	SCOPE,
		in	ARGN
	)

Set a named property in a given scope.

This function replaces CMake's set_property() command.

Parameters:

[in]	SCOPE	The argument for the `SCOPE` parameter of set_property().
[in]	ARGN	Arguments as accepted by. set_property().

Returns:: Sets the specified property.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:set_property

function basis_set_script_path	(	in	VAR,
		in	PATH,
		in	ARGV3
	)

Set path relative to script file.

This function can be used in script configurations. It takes a variable name and a path as input arguments. If the given path is relative, it makes it first absolute using PROJECT_SOURCE_DIR. Then the path is made relative to the directory of the built script file. A CMake variable of the given name is set to the specified relative path. Optionally, a third argument, the path used for building the script for the install tree can be passed as well. If a relative path is given as this argument, it is made absolute by prefixing it with INSTALL_PREFIX instead.

Note:: This function can only be used in script configurations such as in particular the ScriptConfig.cmake.in file. The actual definition of the function is generated by basis_add_script_finalize() and added to the top of the build script. The definition in CommonTools.cmake is only used to include the function in the API documentation.

Parameters:

[out]	VAR	Name of the variable.
[in]	PATH	Path to directory or file.
[in]	ARGV3	Path to directory or file inside install tree. If this argument is not given, PATH is used for both the build and install tree version of the script.

function basis_set_target_properties ( in ARGN )

Set properties on a target.

This function replaces CMake's set_target_properties() command and extends its functionality. In particular, it maps the given target names to the corresponding target UIDs.

Note:: Due to a bug in CMake (http://www.cmake.org/Bug/view.php?id=12303), except of the first property given directly after the PROPERTIES keyword, only properties listed in BASIS_PROPERTIES_ON_TARGETS can be set.

Parameters:

[in] ARGN List of arguments. See set_target_properties().

Returns:: Sets the specified properties on the given target.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:set_target_properties

function basis_set_tests_properties ( in ARGN )

Set a property of the tests.

This function replaces CMake's set_tests_properties() command.

Note:: Due to a bug in CMake (http://www.cmake.org/Bug/view.php?id=12303), except of the first property given directly after the PROPERTIES keyword, only properties listed in BASIS_PROPERTIES_ON_TESTS can be set.

Parameters:

[in] ARGN List of arguments for set_tests_properties().

Returns:: Sets the given properties of the specified test.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:set_tests_property

function basis_target_link_libraries	(	in	TARGET_NAME,
		in	ARGN
	)

Add link dependencies to build target.

This function replaces CMake's target_link_libraries() command.

The main reason for replacing this function is to treat libraries such as MEX-files which are supposed to be compiled into a MATLAB executable added by basis_add_executable() special. In this case, these libraries are added to the LINK_DEPENDS property of the given MATLAB Compiler target.

Another reason is the mapping of build target names to fully-qualified build target names as used by BASIS (see basis_get_target_uid()).

Example:

 basis_add_library (MyMEXFunc MEX myfunc.c)
 basis_add_executable (MyMATLABApp main.m)
 basis_target_link_libraries (MyMATLABApp MyMEXFunc OtherMEXFunc.mexa64)

Parameters:

[in]	TARGET_NAME	Name of the target.
[in]	ARGN	Link libraries.

Returns:: Adds link dependencies to the specified build target. For custom targets, the given libraries are added to the DEPENDS property of these target, in particular.

See also:: http://www.cmake.org/cmake/help/cmake-2-8-docs.html#command:target_link_libraries

macro basis_use_package ( in PACKAGE )

Use found package.

This macro includes the package's use file if the variable <Pkg>_USE_FILE is defined. Otherwise, it adds the include directories to the search path for include paths if possible. Therefore, the corresponding package configuration file has to set the proper CMake variables, i.e., either <Pkg>_INCLUDES, <Pkg>_INCLUDE_DIRS, or <Pkg>_INCLUDE_DIR.

If the given package name is the name of another module of this project (the top-level project), this function includes the use file of the specified module.

Note:: As some packages still use all captial variables instead of ones prefixed by a string that follows the same capitalization as the package's name, this function also considers these if defined instead. Hence, if <PKG>_INCLUDES is defined, but not <Pkg>_INCLUDES, it is used in place of the latter.; According to an email on the CMake mailing list, it is not a good idea to use basis_link_directories() any more given that the arguments to basis_target_link_libraries() are absolute paths to the library files. Therefore, this code is commented and not used. It remains here as a reminder only.

Parameters:

[in] PACKAGE Name of other package. Optionally, the package name can include a version specification as suffix which is separated by the package name using a dash (-), i.e., <Package>[-major[.minor[.patch[.tweak]]]]. A version specification is simply ignored by this macro.

Files

Functions

Detailed Description

Function Documentation