ProjectSettings.cmake

Go to the documentation of this file.

##############################################################################
# @file  ProjectSettings.cmake
# @brief Default project-dependent settings.
#
# @note The file ProjectSettings.cmake is automatically generated by
#       BASIS from the template file ProjectSettings.cmake.in which is part
#       of the BASIS installation.
#
# @note More general, project-independent settings are defined in the file
#       CommonSettings.cmake which is part of the BASIS installation.
#
# This module defines global CMake constants and variables which are used
# by the BASIS CMake functions and macros. Hence, these values can be used
# to configure the behavior of these functions to some extent without the
# need to modify the functions themselves.
#
# @attention Be careful when caching any of the variables. Usually, this
#            file is included in the root CMake configuration file of the
#            project which may also be a module of another project and hence
#            may overwrite this project's settings. For project-wide variables
#            which are modified by the BASIS functions consider the use of
#            so-called project properties as implemented by the BASIS functions
#            basis_set_project_property() and basis_get_project_property().
#
# Variables in this file which are only set if not set previously, i.e.,
# by using basis_set_if_empty(), are set when this file is included the first
# time by a project, but not changed when it is included by a module of this
# project. This is important in order to merge the module's output files with
# the files of the project it is part of.
#
# Copyright (c) 2011, 2012 University of Pennsylvania. All rights reserved.<br />
# See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file.
#
# Contact: SBIA Group <sbia-software at uphs.upenn.edu>
#
# @ingroup BasisSettings
##############################################################################

## @addtogroup BasisSettings
# @{


# ============================================================================
# options
# ============================================================================

## @brief Request build/installation of documentation.
if (EXISTS "${PROJECT_DOC_DIR}")
  option (BUILD_DOCUMENTATION "Request build and/or installation of documentation." ON)
endif ()

## @brief Request build/installation of example.
if (EXISTS ${PROJECT_EXAMPLE_DIR})
  option (BUILD_EXAMPLE "Request build and/or installation of example." ON)
endif ()

# ============================================================================
# project namespaces
# ============================================================================

## @brief Whether BASIS shall use fully-qualified target UIDs.
#
# If this option is OFF, the namespace of the top-level BASIS project is
# not prepended to the actual CMake build target names.
#
# For example, instead of the fully-qualified target UID
# "sbia.basis.target", the CMake target name will simply
# be "target". Only when the target is referenced from another project,
# the fully-qualified target UID is usually required.
basis_set_if_empty (BASIS_USE_FULLY_QUALIFIED_UIDS OFF)

## @brief Whether BASIS should use a separate namespace for each module.
#
# If this option is ON, BASIS will use a separate namespace for each module.
# Otherwise, all modules of a project reside dirctly in the namespace of the
# top-level project itself.
basis_set_if_empty (BASIS_USE_MODULE_NAMESPACES OFF)

## @brief Global namespace of BASIS projects.
if (NOT DEFINED BASIS_NAMESPACE)
  set (BASIS_NAMESPACE "SBIA")
endif ()
string (TOLOWER "${BASIS_NAMESPACE}" BASIS_NAMESPACE_LOWER)
string (TOUPPER "${BASIS_NAMESPACE}" BASIS_NAMESPACE_UPPER)

## @brief CMake namespace of top-level project.
#
# This is the common namespace of a BASIS project and its modules.
# It is the part of the namespace which is only required if the project's
# targets are referenced from another project, but not within the project.
if (NOT PROJECT_IS_MODULE)
  if (BASIS_NAMESPACE)
    set (BASIS_PROJECT_NAMESPACE_CMAKE "${BASIS_NAMESPACE_LOWER}.basis")
  else ()
    set (BASIS_PROJECT_NAMESPACE_CMAKE "basis")
  endif ()
endif ()
basis_sanitize_for_regex (
  BASIS_PROJECT_NAMESPACE_CMAKE_REGEX "${BASIS_PROJECT_NAMESPACE_CMAKE}"
)

## @brief CMake namespace of project.
#
# The CMake namespace of a BASIS project is made up of its name in lower case
# only as well as the namespace the project belongs to, i.e., the namespace of
# the project this project is a module of.
#
# Example:
# @code
# basis_make_target_uid(TARGET_UID "mycmd")
# # sets TARGET_UID to "sbia.basis.mycmd"
# @endcode
#
# @sa basis_make_target_uid()
# @sa basis_get_target_uid()
# @sa basis_make_test_uid()
# @sa basis_get_test_uid()
if (NOT PROJECT_IS_MODULE)
  set (PROJECT_NAMESPACE_CMAKE "${BASIS_PROJECT_NAMESPACE_CMAKE}")
else ()
  if (BASIS_USE_MODULE_NAMESPACES)
    set (PROJECT_NAMESPACE_CMAKE "${PROJECT_NAMESPACE_CMAKE}.basis")
  endif ()
endif ()
basis_sanitize_for_regex (PROJECT_NAMESPACE_CMAKE_REGEX "${PROJECT_NAMESPACE_CMAKE}")

## @brief CMake variable of C++ namespace of project.
#
# The C++ namespace of a BASIS project is made up of its name in lower case
# only as well as the namespace the project belongs to, i.e., the namespace of
# the project this project is a module of.
#
# Example:
# @code
# namespace sbia {
# namespace basis {
# // your code goes here
# }
# }
# @endcode
#
# @ingroup BasisCxxUtilities
if (NOT PROJECT_IS_MODULE)
  if (BASIS_NAMESPACE)
    set (PROJECT_NAMESPACE_CXX "${BASIS_NAMESPACE_LOWER}::basis")
  else ()
    set (PROJECT_NAMESPACE_CXX "basis")
  endif ()
else ()
  if (BASIS_USE_MODULE_NAMESPACES)
    set (PROJECT_NAMESPACE_CXX "${PROJECT_NAMESPACE_CXX}::basis")
  endif ()
endif ()

## @brief CMake variable of Java package name of project.
#
# The Java package name of a BASIS project is made up of its name in lower case
# only as well as the package name of the project it belongs to.
#
# Example:
# @code
# package sbia.basis;
# @endcode
#
# @ingroup BasisJavaUtilities
if (NOT PROJECT_IS_MODULE)
  if (BASIS_NAMESPACE)
    set (PROJECT_NAMESPACE_JAVA "${BASIS_NAMESPACE_LOWER}.basis")
  else ()
    set (PROJECT_NAMESPACE_JAVA "basis")
  endif ()
else ()
  if (BASIS_USE_MODULE_NAMESPACES)
    set (PROJECT_NAMESPACE_JAVA "${PROJECT_NAMESPACE_JAVA}.basis")
  endif ()
endif ()

## @brief CMake variable of Python package name of project.
#
# The Python package name of a BASIS project is made up of its name in lower case
# only as well as the package name of the project it belongs to.
#
# Example:
# @code
# import sbia.basis
# @endcode
#
# @ingroup BasisPythonUtilities
if (NOT PROJECT_IS_MODULE)
  if (BASIS_NAMESPACE)
    set (PROJECT_NAMESPACE_PYTHON "${BASIS_NAMESPACE_LOWER}.basis")
  else ()
    set (PROJECT_NAMESPACE_PYTHON "basis")
  endif ()
else ()
  if (BASIS_USE_MODULE_NAMESPACES)
    set (PROJECT_NAMESPACE_PYTHON "${PROJECT_NAMESPACE_PYTHON}.basis")
  endif ()
endif ()

## @brief CMake variable of Perl package name of project.
#
# The Perl package name of a BASIS project is made up of the project name which
# must be either all capital letters or mixed case starting with a captital letter.
# Note that Perl informally reserves lowercase module names for "pragma" modules
# such as <tt>integer</tt> and <tt>strict</tt>.
#
# Example:
# @code
# package SBIA::BASIS;
# @endcode
#
# @ingroup BasisPerlUtilities
if (NOT PROJECT_IS_MODULE)
  if (BASIS_NAMESPACE)
    set (PROJECT_NAMESPACE_PERL "${BASIS_NAMESPACE}::BASIS")
  else ()
    set (PROJECT_NAMESPACE_PERL "BASIS")
  endif ()
else ()
  if (BASIS_USE_MODULE_NAMESPACES)
    set (PROJECT_NAMESPACE_PERL "${PROJECT_NAMESPACE_PERL}::BASIS")
  endif ()
endif ()

## @brief CMake variable of BASH namespace of project.
#
# In BASH, there exists no such concept of a namespace or package. However,
# variable and function names defined in a module which is supposed to be
# sourced by other BASH scripts should use a unique prefix for variable and
# function names.
#
# The BASH module namespace of a BASIS project is made up of its name in upper
# case only to distinguish it from the actual variable or function name as well
# as the namespace of the project it belongs to.
#
# Example:
# @code
# # The project's namespace is SBIA_BASIS and the name of the
# # module in this example is mymodule.sh. This gives the fully-qualified module
# # namespace SBIA_BASIS_MYMODULE. Note that private identifiers
# # are further
# # prefixed with an underscore '_'.
#
# # return if already loaded
# [ "${_SBIA_BASIS_MYMODULE_INCLUDED:-0}" -eq 1 ] && return 0
# _SBIA_BASIS_MYMODULE_INCLUDED=1
#
# # define private global variable
# _SBIA_BASIS_MYMODULE_verbose=0
#
# # define public function
# #
# # Note: To not complicate the use of the module, the name must not necessarily
# #       include the fully-qualified namespace identifier, but the name should
# #       chosen carefully to avoid name conflicts with other modules.
# MYMODULE_string()
# {
#     # ...
# }
# @endcode
#
# @ingroup BasisBashUtilities
if (NOT PROJECT_IS_MODULE)
  if (BASIS_NAMESPACE)
    set (PROJECT_NAMESPACE_BASH "${BASIS_NAMESPACE_UPPER}_BASIS")
  else ()
    set (PROJECT_NAMESPACE_BASH "BASIS")
  endif ()
else ()
  if (BASIS_USE_MODULE_NAMESPACES)
    set (PROJECT_NAMESPACE_BASH "${PROJECT_NAMESPACE_BASH}_BASIS")
  endif ()
endif ()

## @brief CMake variable of MATLAB package name of project.
#
# The MATLAB package name of a BASIS project is made up of its name in lower case
# only as well as the package name of the project it belongs to.
#
# For information on MATLAB's package and class folders, visit the following
# web page from MathWorks:
# @sa http://www.mathworks.com/help/techdoc/matlab_oop/brfynt_-1.html
#
# Example:
# @code
# import sbia.basis.cls
# @endcode
#
# @ingroup BasisMatlabUtilities
if (NOT PROJECT_IS_MODULE)
  if (BASIS_NAMESPACE)
    set (PROJECT_NAMESPACE_MATLAB "${BASIS_NAMESPACE_LOWER}.basis")
  else ()
    set (PROJECT_NAMESPACE_MATLAB "basis")
  endif ()
else ()
  if (BASIS_USE_MODULE_NAMESPACES)
    set (PROJECT_NAMESPACE_MATLAB "${PROJECT_NAMESPACE_MATLAB}.basis")
  endif ()
endif ()

## @brief Prefix for public header files.
#
# The prefix used for the output directory of the configured public header
# files in the build tree and the installation of these under the
# @c INSTALL_INCLUDE_DIR. The header files have to be included in a
# source file using the entire relative path, e.g.,
# @code
# #include <sbia/basis/config.h>
# @endcode
# This avoids name conflicts among projects in a more reliable way then only
# changing the order of paths in the include search path and is similar to
# prefixing the file name of header files, but at the time avoids the use
# of such prefixing of the file name itself for the developer.
#
# If this project is a module of another project, it appends its name to the
# already set include prefix. Otherwise, the include prefix is set to the
# common default prefix of BASIS projects first, i.e., "sbia", and then the
# name of the project is appended.
#
# @note If the header file is private, i.e., not required by a public library
#       and thus located in the @c PROJECT_CODE_DIR instead of the
#       @c PROJECT_INCLUDE_DIR and therefore not installed, it can be
#       included without the use of such relative path.
#
# @note The include prefix must end with a trailing slash if it is a
#       subdirectory. BASIS will not use a slash by itself to separate the
#       prefix from the header file name. This behavior eases the transition
#       to a file name prefix if ever desired.
if (NOT PROJECT_IS_MODULE)
  if (BASIS_NAMESPACE)
    set (INCLUDE_PREFIX "${BASIS_NAMESPACE_LOWER}/basis/")
  else ()
    set (INCLUDE_PREFIX "basis/")
  endif ()
else ()
  if (BASIS_USE_MODULE_NAMESPACES)
    set (INCLUDE_PREFIX "${INCLUDE_PREFIX}/basis/")
  endif ()
endif ()


## @}
# end of Doxygen group