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_script (in TARGET_NAME, in ARGN)
	Add single arbitrary or executable script.
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 (out VAR, in SCOPE, in ELEMENT, in ARGN)
	Get a property.
function	basis_get_relative_path (out REL, in BASE, in PATH)
	Get path relative to a given base directory.
function	basis_get_target_property (out VAR, in TARGET_NAME, in ARGN)
	Get value of property set on target.
function	basis_get_test_property (out 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)
	Define 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 (out 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.
macro	basis_slicer_module ()
	Define project meta-data of Slicer module.
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 used to add a software documentation files to the project which are either just copied to the installation or generated from input files such as in particular source code files and documentation files marked up using one of the supported lightweight markup languages.

The supported generators are:

None	This generator simply installs the given file or all files within the specified directory.
Doxygen	Used to generate API documentation from in-source code comments and other related files marked up using Doxygen comments. See basis_add_doxygen_doc() for more details.
Sphinx	Used to generate documentation such as a web site from reStructuredText. See basis_add_sphinx_doc() for more details.

Parameters:

[in]	TARGET_NAME	Name of the documentation target or file.
[in]	ARGN	Documentation generator as "GENERATOR generator" option and additional arguments for the particular generator. The case of the generator name is ignored, i.e., `Doxygen`, `DOXYGEN`, `doxYgen` are all valid arguments which select the `Doxygen` generator. The default generator is the `None` generator.

Returns:: Adds a custom target TARGET_NAME for the generation of the documentation.

See also:: basis_install_doc(); basis_add_doxygen_doc(); basis_add_sphinx_doc()

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 Python script) directly, as executable file. Natively, CMake supports only executables built 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\|JYTHON\|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, which itself is either a CMake script file or a string of CMake code set as value of the `COMPILE_DEFINITIONS` property of the executable target.
MATLAB	Standalone application 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 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 and if necessary the first line of script files are inspected by the basis_get_source_language() function. Once the programming language is known, this function invokes the proper subcommand which adds the respective build target. 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_executable() to add an executable target to your project. Only refer to the documentation of the subcommands to learn about the available options of the particular subcommand and considered target properties.

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 specified COMPONENT in the directory INSTALL_RUNTIME_DIR or INSTALL_LIBEXEC_DIR if the option LIBEXEC is given. Executable targets are exported by default 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 or if "none" (case-insensitive) is given as DESTINATION. Test executables are further only exported as part of the build tree, but not the installation as they are by default not installed.

Parameters:

[in]	TARGET_NAME	Name of the target. If an existing source file is given as first argument, it is added to the list of source files and the build target name is derived from the name of this 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 add an executable build target.

COMPONENT name	Name of component as part of which this executable will be installed if the specified `DESTINATION` is not "none". (default: `BASIS_RUNTIME_COMPONENT`)
DESTINATION dir	Installation directory relative to `CMAKE_INSTALL_PREFIX`. If "none" (case-insensitive) is given as argument, no default installation rules are added for this executable target. (default: `INSTALL_RUNTIME_DIR` or `INSTALL_LIBEXEC_DIR` if the `LIBEXEC` option is given)
LANGUAGE lang	Programming language in which source files are written (case-insensitive). If not specified, the programming language is derived from the file name extensions of the source files and, if applicable, the shebang directive on the first line of the script file. If the programming language could not be detected automatically, check the file name extensions of the source files and whether no unrecognized additional arguments were given or specify the programming language using this option. (default: auto-detected)
LIBEXEC	Specifies that the built executable is an auxiliary executable which is only called by other executables. (default: `FALSE`)
[NO]EXPORT	Whether to export this target. (default: `TRUE`)
NO_BASIS_UTILITIES	Specify that the BASIS utilities are not used by this executable and hence no link dependency on the BASIS utilities shall be added. (default: `NOT` `BASIS_UTILITIES`)
USE_BASIS_UTILITIES	Specify that the BASIS utilities are used and required by this executable and hence a link dependency on the BASIS utilities has to be added. (default: `BASIS_UTILITIES`)

Returns:: Adds an executable build target. In case of an executable which is not build from C++ source files, the function basis_finalize_targets() has to be invoked to finalize the addition of the custom build target. This is done at the end of 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 module(s) 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 Python module) directly, as library file. Natively, CMake supports only libraries built 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\|JYTHON\|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	Libraries of M-files or shared libraries built 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. If the type of the library is `SHARED`, a shared library is build using the MATLAB Compiler. Otherwise, the M-files are configured and installed such that they can be used in MATLAB.

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_file() for C++ sources if the MEX option is given, basis_add_mcc_target() for MATLAB scripts (.m), and basis_add_script_library() 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 and the considered target properties.

Output directories: In case of modules written in a scripting language, the libraries are output to the BINARY_<LANGUAGE>_LIBRARY_DIR if defined. Otherwise, the built libraries are output to the BINARY_RUNTIME_DIR, BINARY_LIBRARY_DIR, and/or BINARY_ARCHIVE_DIR. If this command is used within the PROJECT_TESTING_DIR, however, the files are output to the corresponding directories in the testing tree, instead.

Installation: An installation rule for the added library target is added by this function if the destination is not "none" (case-insensitive). 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 further 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 build target. If an existing file is given as argument, it is added to the list of source files and the target name is derived from the name of this file.
[in]	ARGN	This argument list is parsed and the following arguments are extracted. All unparsed arguments are treated as source files.

STATIC\|SHARED\|MODULE\|MEX	Type of the library. (default: `SHARED` for C++ libraries if `BUILD_SHARED_LIBS` evaluates to true or `STATIC` otherwise, and `MODULE` in all other cases)
COMPONENT name	Name of component as part of which this library will be installed if the `RUNTIME_DESTINATION` or `LIBRARY_DESTINATION` is not "none". Used only if `RUNTIME_COMPONENT` or `LIBRARY_COMPONENT` not specified. (default: see `RUNTIME_COMPONENT` and `LIBRARY_COMPONENT`)
DESTINATION dir	Installation directory for runtime and library component relative to `CMAKE_INSTALL_PREFIX`. Used only if `RUNTIME_DESTINATION` or `LIBRARY_DESTINATION` not specified. If "none" (case-insensitive) is given as argument, no default installation rules are added. (default: see `RUNTIME_DESTINATION` and `LIBRARY_DESTINATION`)
LANGUAGE lang	Programming language in which source files are written (case-insensitive). If not specified, the programming language is derived from the file name extensions of the source files and, if applicable, the shebang directive on the first line of the script file. If the programming language could not be detected automatically, check the file name extensions of the source files and whether no unrecognized additional arguments were given or specify the programming language using this option. (default: auto-detected)
LIBRARY_COMPONENT name	Name of component as part of which import/static library will be intalled if `LIBRARY_DESTINATION` is not "none". (default: `COMPONENT` if specified or `BASIS_LIBRARY_COMPONENT` otherwise)
LIBRARY_DESTINATION dir	Installation directory of the library component relative to `CMAKE_INSTALL_PREFIX`. If "none" (case-insensitive) is given as argument, no installation rule for the library component is added. (default: `INSTALL_ARCHIVE_DIR`)
RUNTIME_COMPONENT name	Name of component as part of which runtime library will be installed if `RUNTIME_DESTINATION` is not "none". (default: `COMPONENT` if specified or `BASIS_RUNTIME_COMPONENT` otherwise)
RUNTIME_DESTINATION dir	Installation directory of the runtime component relative to `CMAKE_INSTALL_PREFIX`. If "none" (case-insensitive) is given as argument, no installation rule for the runtime library is added. (default: `INSTALL_LIBRARY_DIR` on Unix or `INSTALL_RUNTIME_DIR` Windows)
[NO]EXPORT	Whether to export this target. (default: `TRUE`)
NO_BASIS_UTILITIES	Specify that the BASIS utilities are not used by this executable and hence no link dependency on the BASIS utilities shall be added. (default: `NOT` `BASIS_UTILITIES`)
USE_BASIS_UTILITIES	Specify that the BASIS utilities are used and required by this executable and hence a link dependency on the BASIS utilities has to be added. (default: `BASIS_UTILITIES`)

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

See also:: basis_add_library_target(); basis_add_script_library(); basis_add_mex_file(); basis_add_mcc_target()

function basis_add_script	(	in	TARGET_NAME,
		in	ARGN
	)

Add single arbitrary or executable script.

Note:: This function should not be used directly for executable scripts or module libraries. Use basis_add_executable() or basis_add_library() in such (most) cases instead.

This function can be used to add a single arbitrary script file (i.e., any text file which is input to a program), such as a CTest script for example, to the build if neither basis_add_executable() nor basis_add_library() are appropriate choices. In all other cases, either basis_add_executable() or basis_add_library() should be used. Note that the script file is by default not considered to be an executable. Instead it is assumed that the program which interprets/processes the script must be executed explicitly with this script as argument. Only scripts built with the EXECUTABLE or LIBEXEC type option are treated as executable files, where in case of Unix a shebang directive implicitly states the program used by the shell to interpret the script and on Windows a Windows Command which imitates the behavior of Unix shells is generated by BASIS. Do not use these type options, however, but only use the default MODULE option. The basis_add_executable() function should be used instead to add an executable script. The basis_add_script() function shall only be used for none-executable arbitrary script files which cannot be built by basis_add_executable() or basis_add_library().

If the script name ends in .in, the .in suffix is removed from the output name. Further, in case of executable scripts, the file name extension is removed from the output file name. Instead, a shebang directive is added on Unix to the built script. In order to enable the convenient execution of Python and Perl scripts also on Windows without requiring the user to setup a proper associate between the filename extension with the corresponding interpreter executable, a few lines of Batch code are added at the top and bottom of executable Python and Perl scripts. This Batch code invokes the configured interpreter with the script file and the given script arguments as command-line arguments. Note that both the original script source code and the Batch code are stored within the single file. The file name extension of such modified scripts is by default set to .cmd, the common extension for Windows NT Command Scripts. Scripts in other languages are not modified and the extension of the original scripts script file is preserved on Windows in this case. In case of non-executable scripts, the file name extension is kept in any case.

Certain CMake variables within the source file are replaced during the built of the script. See the <a href="https://www.cbica.upenn.edu/sbia/software/basis/scripttargets/> Build System Standard for details. Note, however, that source files are only configured if the file name ends in the .in suffix.

A custom CMake build target with the following properties is added by this function to the build system. These properties are used by basis_build_script() to generate a build script written in CMake code which is executed by a custom CMake command. Before the invokation of basis_build_script(), the target properties can be modified using basis_set_target_properties().

Note:: Custom BASIS build targets are finalized by BASIS at the end of basis_project_impl(), i.e., the end of the root CMake configuration file of the (sub-)project.

Properties on script targets

BASIS_TYPE	Read-only property with value "SCRIPT_FILE" for arbitrary scripts, "SCRIPT_EXECUTABLE" for executable scripts, and "SCRIPT_LIBEXEC" for auxiliary executable scripts. (default: see `MODULE`, `EXECUTABLE`, `LIBEXEC` options)
BASIS_UTILITIES	Whether the BASIS utilities are used by this script. For the supported scripting languages for which BASIS utilities are implemented, BASIS will in most cases automatically detect whether these utilities are used by a script or not. Otherwise, set this property manually or use either the `USE_BASIS_UTILITIES` or the `NO_BASIS_UTILITIES` option when adding the script target. (default: auto-detected or `UNKNOWN`)
BINARY_DIRECTORY	Build tree directory of this target. (default: `CMAKE_CURRENT_BINARY_DIR`)
COMPILE	Whether to compile the script if the programming language allows such pre-compilation as in case of Python, for example. If `TRUE`, only the compiled file is installed. (default: `BASIS_COMPILE_SCRIPTS`)
COMPILE_DEFINITIONS	CMake code which is evaluated after the inclusion of the default script configuration files. This code can be used to set the replacement text of the CMake variables ("@VAR@" patterns) used in the source file. See Build System Standard for details. (default: "")
COMPILE_DEFINITIONS_FILE	CMake script file with compile definitions, also referred to as script configuration file. The named files are included after the default BASIS script configuration and before the `COMPILE_DEFINITIONS` code is being evaluated. (default: `BINARY_CONFIG_DIR/ScriptConfig.cmake`)
COMPONENT	Name of component as part of which this script is installed if `INSTALL_DIRECTORY` is not set to "none". (default: see `COMPONENT` argument)
EXPORT	Whether to export this build target in which case an import library target is added to the custom exports file with the path to the built/installed script set as `IMPORT_LOCATION`. (default: `TRUE`)
INSTALL_DIRECTORY	Installation directory of script file configured for use in installation tree relative to `CMAKE_INSTALL_PREFIX`. Set to "none" (case-insensitive) to skip the addition of an installation rule. (default: see `DESTINATION` argument)
LANGUAGE	Read-only property of programming language of script file in uppercase letters. (default: see `LANGUAGE` argument)
LINK_DEPENDS	Paths or target names of script modules and libraries used by this script. In case of an (auxiliary) executable script, the directories of these modules are added to the search path for modules of the given programming language if such search paths are supported by the language and BASIS knows how to set these (as in case of Python/Jython, Perl, and MATLAB, in particular). Moreover, for each listed build target a dependency is added between this script target and the named build targets. Use basis_target_link_libraries() to add additional link dependencies. (default: BASIS utilities module if used or empty list otherwise)
OUTPUT_DIRECTORY	Output directory for built script file configured for use in build tree. (default: `BINARY_LIBRARY_DIR` for arbitrary scripts, `BINARY_RUNTIME_DIR` for executable scripts, and `BINARY_LIBEXEC_DIR` for auxiliary executables)
OUTPUT_NAME	Name of built script file including file name extension (if any). (default: basename of script file for arbitrary scripts, without extension for executable scripts on Unix, and `.cmd` extension on Windows in case of executable Python/Jython or Perl script)
SOURCE_DIRECTORY	Source directory of this target. (default: `CMAKE_CURRENT_SOURCE_DIR`)
SOURCES	Read-only property which lists the source file of this script target. Note that the first element in this list actually names a directory in the build, the one where the build script for this target is located instead of a source file and thus should be ignored. The second entry corresponds to the source file of this script target.

Attention:: Properties documented as read-only must not be modified.

Note:: If this function is used within the PROJECT_TESTING_DIR, the built executable is output to the BINARY_TESTING_DIR directory tree instead. Moreover, no installation rules are added. Test executables are further not exported, regardless of the EXPORT property.

Parameters:

[in]	TARGET_NAME	Name of build target. If an existing file is given as argument, it is added to the list of source files and the target name is derived from the name of this file.
[in]	ARGN	The remaining arguments are parsed and the following arguments recognized. All unparsed arguments are treated as source files, where in particular exactly one source file is required if the `TARGET_NAME` argument does not name an existing source file.

MODULE\|EXECUTABLE\|LIBEXEC	Type of script to built, i.e., either arbitrary module script which cannot be executed directly, an executable script with proper shebang directive and execute permissions on Unix or Windows Command on Windows, or an auxiliary executable. The type of the script mainly changes the default values of the target properties such as the output and installation directories. To add an (auxiliary) executable script, use basis_add_executable(), however, instead of this function. The `EXECUTABLE` and `LIBEXEC` options are only intended for internal use by BASIS. (default: MODULE)
COMPONENT name	Name of installation component as part of which this script is being installed if the `INSTALL_DIRECTORY` property is not "none". (default: `BASIS_LIBRARY_COMPONENT` for arbitrary scripts or `BASIS_RUNTIME_COMPONENT` for executable scripts)
DESTINATION dir	Installation directory for script file relative to `CMAKE_INSTALL_PREFIX`. If an absolute path is given as argument, it is made relative to the configured installation prefix. (default: `INSTALL_LIBRARY_DIR` for arbitrary scripts, `INSTALL_RUNTIME_DIR` for executable scripts, and `INSTALL_LIBEXEC_DIR` for auxiliary executable scripts)
LANGUAGE lang	Programming language in which script file is written (case-insensitive). If not specified, the programming language is derived from the file name extension of the source file and the shebang directive on the first line of the script if any. If the programming language could not be detected automatically, the `LANGUAGE` property is set to `UNKNOWN`. Note that for arbitrary script targets, the script file will still be built correctly even if the scripting language was not recognized. The automatic detection whether the BASIS utilities are used and required will fail, however. In this case, specify the programming language using this option. (default: auto-detected or `UNKNOWN`)
[NO]EXPORT	Whether to export this target. (default: `TRUE`)
NO_BASIS_UTILITIES	Specify that the BASIS utilities are not used by this script. If the programming language of the script is known and BASIS utilities are available for this language, BASIS will in most cases automatically detect whether these utilities are used by a script or not. Use this option to skip this check because the script does not make use of the BASIS utilities.
USE_BASIS_UTILITIES	Specify that the BASIS utilities are used and thus required by this script. If the programming language of the script is known and BASIS utilities are available for this language, BASIS will in most cases automatically detect whether these utilities are used by a script or not. Use this option to skip this check because it is already known that the script makes use of the BASIS utilities. Note that an error is raised if this option is given, but no BASIS utilities are available for the programming language of this script or if the programming language is unknown, respectively, not detected correctly. In this case, consider the use of the `LANGUAGE` argument.

Returns:: Adds a custom CMake target with the documented properties. The actual custom command to build the script is added by basis_build_script().

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.

Returns:: Nothing.

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

Returns:: Nothing.

macro basis_get_filename_component ( )

Alias for the overwritten get_filename_component() function.

See also:: get_filename_component()

Returns:: Nothing.

function basis_get_property	(	out	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	(	out	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	(	out	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	(	out	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

Returns:: Nothing.

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

Returns:: Nothing.

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 )

Define 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.
SUBPROJECT name	Use this option instead of `NAME` to indicate that this project is a subproject of the package `PACKAGE`. This results, for example, in target UIDs such as "<package>.<name>.<target>" instead of "<package>.<target>". Moreover, the libraries and shared files of a subproject are installed in subdirectores whose name equals the name of the subproject. This option should only be used for projects which are modules of another BASIS project, where these modules should reside in their own sub-namespace rather than on the same level as the top-level project.
PACKAGE pkg	Name of the package this project (module) belongs to. Defaults to the name of the (top-level) project. This option can further be used in case of a top-level project to specify a different package name for the installation. In case of a subproject which is a module of another BASIS project, setting the package name explicitly using this option enables the build of the subproject as separate project while preserving the directory structure and other namespace settings. Therefore, this option is required if the `SUBPROJECT` option is given and the project shall be build independently as stand-alone package. (default: name of top-level package)
PACKAGE_VENDOR vendor	The vendor of this package, used for packaging and installation. (default: vendor of top-level project or empty string)
PROVIDER vendor	This option can be used as an alternative to `PACKAGE_VENDOR`.
VERSION major[.minor[.patch]]	Project version string. (default: 1.0.0)
DESCRIPTION description	Package description, used for packing. If multiple arguments are given, they are concatenated using one space character as delimiter.
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_PACKAGE	`PACKAGE` argument.
PROJECT_PACKAGE_VENDOR	`PACKAGE_VENDOR` argument.
PROJECT_VERSION	`VERSION` argument.
PROJECT_DESCRIPTION	`DESCRIPTION` 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.
PROJECT_IS_SUBPROJECT	`TRUE` if `IS_SUBPROJECT` option given or `FALSE` otherwise.

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()

Returns:: Nothing.

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	(	out	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 CMAKE_INSTALL_PREFIX instead.

Note:: This function may only be used in script configurations such as in particular the ScriptConfig.cmake.in file. It requires that the variables __DIR__ and BUILD_INSTALL_SCRIPT are set properly. These variables are set by the configure_script() function. Moreover, it makes use of the global CMAKE_INSTALL_PREFIX and PROJECT_SOURCE_DIR variables.

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.

Returns:: Nothing.

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_properties

macro basis_slicer_module ( )

Define project meta-data of Slicer module.

This macro should be used instead of basis_project() for a Slicer module. It extends the considered meta-data by some additional variables that have to be set for a Slicer module and identifies this project as a Slicer module.

Returns:: Nothing.

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. Similarly, executable scripts and modules written in a scripting language may depend on other modules.

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 LINK_DEPENDS property of these targets, 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.

Returns:: Nothing.

Files

Functions

Detailed Description

Function Documentation