Usage
=====

The dcm package can be used in a variety of ways:


Copying
-------

In the most basic and straightforward way you can copy over the CMake files
directly into your project. This does not require any further dependencies,
but won't provide you with an easily updatable system.

CPM
---

Using `CPM <https://github.com/cpm-cmake/CPM.cmake>`_ the dcm package can be
installed as follows:

.. code-block:: cmake

   # ----------------------------------------------------
   # Install the dcm package
   # ----------------------------------------------------
   cpmaddpackage(
       NAME
       dcm
       GIT_REPOSITORY
       "https://git.dotcircle.dev/dotcircle.co/cmake-modules.git"
       GIT_TAG
       "v2.3.5"
       SYSTEM
       YES
   )

   list(PREPEND CMAKE_MODULE_PATH
       "${dcm_SOURCE_DIR}/modules"
       "${dcm_SOURCE_DIR}/find-modules"
   )

   # ----------------------------------------------------
   # Start using the dcm provided functions
   # ----------------------------------------------------
   include(dcmStandardProjectSettings)

   include(dcmCompilerWarnings)
   set_project_warnings(project_name)


Conan
-----

Using `conan <https://conan.io>`_ the dcm package can be installed as follows:


Using a conanfile.txt
~~~~~~~~~~~~~~~~~~~~~

In the example below ``DCM_VERSION`` should be replaced with a valid conan
package version for dcm. Currently the latest version is |version|.

.. code-block:: text

   [requires]
   dcm/$DCM_VERSION@dotcircle+cmake-modules/stable

   [generators]
   cmake


.. code-block:: cmake

   include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
   conan_basic_setup()


Using the conan CMake module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In the example below ``DCM_VERSION`` should be a valid conan package version for
dcm. Currently the latest version is |version|.

.. code-block:: CMake

   # ----------------------------------------------------
   # Download conan.cmake automatically
   # ----------------------------------------------------
   if(NOT EXISTS "${CMAKE_BINARY_DIR}/conan.cmake")
       message(STATUS "Downloading conan.cmake from https://github.com/conan-io/cmake-conan")
       file(DOWNLOAD "https://github.com/conan-io/cmake-conan/raw/v0.16.1/conan.cmake"
           "${CMAKE_BINARY_DIR}/conan.cmake"
       )
   endif()

   # ----------------------------------------------------
   # Include conan.cmake
   # ----------------------------------------------------
   include(${CMAKE_BINARY_DIR}/conan.cmake)

   # ----------------------------------------------------
   # Add remotes
   # ----------------------------------------------------
   conan_add_remote(NAME dotcircle URL https://conan.dotcircle.dev/artifactory/conan conan)

   # ----------------------------------------------------
   # Install the dcm package
   # ----------------------------------------------------
   conan_cmake_run(
       REQUIRES
       dcm/${DCM_VERSION}@dotcircle+cmake-modules/stable

       BASIC_SETUP
   )
   find_package(dcm REQUIRED NO_MODULE)

   # ----------------------------------------------------
   # Start using the dcm provided functions
   # ----------------------------------------------------
   include(dcmStandardProjectSettings)

   include(dcmCompilerWarnings)
   set_project_warnings(project_name)