.. _cmake-pkg:

CMake Package
~~~~~~~~~~~~~

A CMake package provides support for processing a `CMake`_ supported module.

.. code-block:: python

   LIBFOO_TYPE = 'cmake'

During the configuration stage of a CMake package, ``cmake`` will be invoked to
generate build files for the module. For the build stage, ``cmake --build`` will
be invoked to generated build files. Similar approach for the installation stage
where the build option is invoked again but with the ``install`` target invoked:
``cmake --build --target install``. Each stage can be configured to manipulate
environment variables and options used by the CMake executable.

The default configuration built for projects is ``RelWithDebInfo``. A developer
can override this option by explicitly adjusting the configuration option
``--config`` to, for example, ``Debug``:

.. code-block:: python

   LIBFOO_CONF_DEFS = {
      'CMAKE_BUILD_TYPE': 'Debug',
   }

   LIBFOO_BUILD_OPTS = {
      '--config': 'Debug',
   }

   LIBFOO_INSTALL_OPTS = {
      '--config': 'Debug',
   }

The following sections outline configuration options are available for a CMake
package.

.. _cmake_build_defs:
.. include:: developer-guide/packages-build-defs

.. _cmake_build_env:
.. include:: developer-guide/packages-build-env

.. _cmake_build_opts:
.. include:: developer-guide/packages-build-opts

LIBFOO_CMAKE_NOINSTALL
^^^^^^^^^^^^^^^^^^^^^^

Specifies whether or not the CMake package should skip an attempt to invoke
the install command. Ideally, projects will have an `install <cmake-install_>`_
rule configured to define how a project will install files into a target (or
staging) environment. Not all CMake projects may have this rule defined, which
can cause the installation stage for a package to fail. A developer can
specify this no-install flag to skip a CMake-driven install request and
manage installation actions through other means (such as post-processing).
By default, the installation stage is invoked with a value of ``False``.

.. code-block:: python

   LIBFOO_CMAKE_NOINSTALL = True

.. _cmake_conf_defs:
.. include:: developer-guide/packages-conf-defs

.. _cmake_conf_env:
.. include:: developer-guide/packages-conf-env

.. _cmake_conf_opts:
.. include:: developer-guide/packages-conf-opts

.. _cmake_install_defs:
.. include:: developer-guide/packages-install-defs

.. _cmake_install_env:
.. include:: developer-guide/packages-install-env

.. _cmake_install_opts:
.. include:: developer-guide/packages-install-opts


.. _cmake-install: https://cmake.org/cmake/help/latest/command/install.html
