BASIS  r3148
Public CMake Interface

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]COMPNAMEName of the component.
[in]ARGNFurther 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]GRPNAMEName of the component group.
[in]ARGNFurther 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]ARGNList 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]ARGNArguments 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_NAMEName of the documentation target or file.
[in]ARGNDocumentation 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_NAMEName 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]ARGNThis 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]ARGNArguments 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_NAMEName 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]ARGNThis 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="http://www.rad.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_NAMEName 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]ARGNThe 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_NAMEName 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]ARGNThe 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_NAMEName of the test driver.
[in]ARGNList of source files implementing tests.
Returns:
Nothing.
function basis_configure_downloads ( in  ARGN)

Configure installation-time downloads of selected components.

Parameters:
[in]ARGNArguments 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]PACKAGEName 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]ARGNAdvanced arguments for find_package().
Return values:
<PACKAGE>_FOUNDWhether 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]VARProperty value.
[in]SCOPEThe argument for the SCOPE argument of get_property().
[in]ELEMENTThe argument for the ELEMENT argument of get_property().
[in]ARGNArguments 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]RELPATH relative to BASE.
[in]BASEPath of base directory. If a relative path is given, it is made absolute using basis_get_filename_component() with ABSOLUTE as last argument.
[in]PATHAbsolute 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]VARName of output variable.
[in]TARGET_NAMEName of build target.
[in]ARGNRemaining 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]VARProperty value.
[in]TEST_NAMEName of test.
[in]ARGNRemaining 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:
ARGNList 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]ARGNThe 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]OLDThe value of the symbolic link.
[in]NEWThe 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]ARGNList 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]ARGNThis 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_NAMENAME argument.
PROJECT_PACKAGEPACKAGE argument.
PROJECT_PACKAGE_VENDORPACKAGE_VENDOR argument.
PROJECT_VERSIONVERSION argument.
PROJECT_DESCRIPTIONDESCRIPTION argument.
PROJECT_DEPENDSDEPENDS arguments.
PROJECT_OPTIONAL_DEPENDSOPTIONAL_DEPENDS arguments.
PROJECT_TEST_DEPENDSTEST_DEPENDS arguments.
PROJECT_OPTIONAL_TEST_DEPENDSOPTIONAL_TEST_DEPENDS arguments.
PROJECT_IS_SUBPROJECTTRUE 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]ARGNList 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]SCOPEThe argument for the SCOPE parameter of set_property().
[in]ARGNArguments 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]VARName of the variable.
[in]PATHPath to directory or file.
[in]ARGV3Path 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]ARGNList 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]ARGNList 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_NAMEName of the target.
[in]ARGNLink 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]PACKAGEName 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.