.. cmake-manual-description: Cetmodules Project Variables Reference

cetmodules-project-variables(7)
*******************************

Within Cetmodules, a *project variable* ``<pvar>`` refers to a CMake
cache variable ``<project-name>_<pvar>`` created by the function
:command:`project_variable`. A project variable may have
:manual:`property <cmake-ref-current:manual:cmake-properties(7)>`\ -like
attributes with it that may be interrogated, set or altered. In
addition, project variables may be propagated to dependent packages via
the project's CMake config file as generated by
:command:`cet_cmake_config` along with appropriate treatment for path or
file-like values in the context of the installed package.

.. _project-variables-types:

Project Variable :prop_cache:`Type <cmake-ref-current:prop_cache:TYPE>`
=======================================================================

As they are CMake :command:`CACHE
<cmake-ref-current:command:set(cache)>` variables, project variables
have a type. However, project variables have two additional types:
``FILEPATH_FRAGMENT`` and ``PATH_FRAGMENT``. These types are similar to
their non-``_FRAGMENT`` equivalents, but are considered to be relative
to a project's top level source directory, binary directory, or install
prefix, depending on context.

Architecture-Specific Project Variables
=======================================

Project variables of type ``FILEPATH_FRAGMENT`` or ``PATH_FRAGMENT`` may
be architecture specific according to their ``<var-name>`` as determined
by:

#. Cetmodules' defaults as defined by
   :variable:`CETMODULES_DEFAULT_ARCH_DIRS`.

#. :variable:`\<PROJECT-NAME>_ADD_ARCH_DIRS` and
   :variable:`\<PROJECT-NAME>_ADD_NOARCH_DIRS`.

The initial value of relative architecture-specific project variables as
determined by :command:`project_variable` will have
:variable:`${CETMODULES_CURRENT_PROJECT_NAME}_EXEC_PREFIX
<\<PROJECT-NAME>_EXEC_PREFIX>` prepended to their value if defined.

Project Variable Properties
===========================

Several :manual:`property
<cmake-ref-current:manual:cmake-properties(7)>`\ -like attributes may be
defined for project variables by :command:`project_variable` and
interrogated via :command:`cet_get_pv_property`, and more may be set by
the user via :command:`cet_set_pv_property`. These are not CMake
properties in the formal sense, but are semantically similar and stored
in CMake's cache.

Properties defined by :command:`project_variable`
-------------------------------------------------

``CONFIG``, ``MISSING_OK``, ``OMIT_IF_EMPTY``, ``OMIT_IF_MISSING``, ``OMIT_IF_NULL``
  Boolean proprties indicating whether the corresponding option was
  specified to :command:`project_variable`.

``IS_PATH``
  ``TRUE`` if the variable should be treated as the location of a file
  or directory in the filesystem.

``ORIGIN``
  The origin of the initial value of the project variable, following the
  `defined order of precedence
  <project-variable-init-value-precedence>`_. Valid values are:

  * The name of the variable from which the initial value was taken.

  * ``<initial-value>``

  * ``<backup-default>``

``TYPE``
  The defined type of the project variable. Valid values are the
  :prop_cache:`CMake CACHE variable types
  <cmake-ref-current:prop_cache:TYPE>`, plus ``FILEPATH_FRAGMENT`` and
  ``PATH_FRAGMENT``.

Project Variables and CMake Config files
========================================

Any project variable defined with the ``CONFIG`` attribute will be
propagated to dependent packages: a suitable definition will be
generated in :file:`<PROJECT-NAME>Config.cmake` by the
:command:`cet_cmake_config` function. In the case of project variables
of type ``(FILE)?PATH(_FRAGMENT)?``, the path will be localized
appropriately for the package's installation location. Additional
attributes (:ref:`project_variable-MISSING_OK`,
:ref:`project_variable-OMIT_IF_EMPTY`,
:ref:`project_variable-OMIT_IF_MISSING`,
:ref:`project_variable-OMIT_IF_NULL`) modify the details of that
definition.