eigen/doc/TopicCMakeGuide.dox

namespace Eigen {

/**

\page TopicCMakeGuide Using %Eigen in CMake Projects

%Eigen provides native CMake support which allows the library to be easily
used in CMake projects.

\note %CMake 3.5 (or later) is required to enable this functionality.

%Eigen exports a CMake target called `Eigen3::Eigen` which can be imported
using the `find_package` CMake command and used by calling
`target_link_libraries` as in the following example:
\code{.cmake}
cmake_minimum_required (VERSION 3.5)
project (myproject)

find_package (Eigen3 REQUIRED NO_MODULE)

add_executable (example example.cpp)
target_link_libraries (example Eigen3::Eigen)
\endcode

The above code snippet must be placed in a file called `CMakeLists.txt` alongside
`example.cpp`. After running
\code{.sh}
$ cmake path-to-example-directory
\endcode
CMake will produce project files that generate an executable called `example`.
Here, `path-to-example-directory` is the path to the directory that contains
both `CMakeLists.txt` and `example.cpp`.  Note that if you have multiple
instances of %Eigen installed, `find_package` will use the first one
encountered.  To request a specific version of %Eigen, use the `<version>`
option in `find_package`:
```
find_package(Eigen3 3.4 REQUIRED NO_MODULE)  # Restricts to 3.4.z
```
Starting with Eigen 3.4.1, we also support a range spanning major versions:
```
find_package(Eigen3 3.4...5 REQUIRED NO_MODULE)  # Any version >=3.4.1 but <6.0.0.
```

Do not forget to set the <a href="https://cmake.org/cmake/help/v3.7/variable/CMAKE_PREFIX_PATH.html">\c CMAKE_PREFIX_PATH </a> variable if Eigen is not installed in a default location or if you want to pick a specific version. For instance:
\code{.sh}
$ cmake path-to-example-directory -DCMAKE_PREFIX_PATH=$HOME/mypackages
\endcode
An alternative is to set the \c Eigen3_DIR cmake's variable to the respective path containing the \c Eigen3*.cmake files. For instance:
\code{.sh}
$ cmake path-to-example-directory -DEigen3_DIR=$HOME/mypackages/share/eigen3/cmake/
\endcode

If the `REQUIRED` option is omitted when locating %Eigen using
`find_package`, one can check whether the package was found as follows:
\code{.cmake}
find_package (Eigen3 NO_MODULE)

if (TARGET Eigen3::Eigen)
  # Use the imported target
endif (TARGET Eigen3::Eigen)
\endcode

\section title_fetchcontent Using FetchContent

Starting with CMake 3.11, you can use the
<a href="https://cmake.org/cmake/help/latest/module/FetchContent.html">FetchContent</a>
module to download and include %Eigen directly in your project without
installing it first.

A basic example:
\code{.cmake}
cmake_minimum_required(VERSION 3.11)
project(myproject)

include(FetchContent)
FetchContent_Declare(
  Eigen
  GIT_REPOSITORY https://gitlab.com/libeigen/eigen.git
  GIT_TAG        master
  GIT_SHALLOW    TRUE
  EXCLUDE_FROM_ALL
)
FetchContent_MakeAvailable(Eigen)

add_executable(example example.cpp)
target_link_libraries(example Eigen3::Eigen)
\endcode

\subsection title_fetchcontent_options Disabling Eigen build options

When %Eigen is added as a sub-project, its documentation, testing, and
pkg-config targets may collide with your project's own targets. Disable
them before calling \c FetchContent_MakeAvailable:
\code{.cmake}
set(EIGEN_BUILD_DOC OFF CACHE BOOL "" FORCE)
set(EIGEN_BUILD_TESTING OFF CACHE BOOL "" FORCE)
set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
set(EIGEN_BUILD_PKGCONFIG OFF CACHE BOOL "" FORCE)

FetchContent_MakeAvailable(Eigen)
\endcode

\subsection title_fetchcontent_exclude Using EXCLUDE_FROM_ALL

Projects that depend on %Eigen should typically exclude installing %Eigen by
default to avoid overwriting a previous installation. Pass
\c EXCLUDE_FROM_ALL in the \c FetchContent_Declare call (as shown above) or
the equivalent \c add_subdirectory option so that %Eigen's install rules are
not included in the default install target.

\subsection title_fetchcontent_cmake330 Note for CMake 3.30 and later

CMake 3.30 changed the default value of the
<a href="https://cmake.org/cmake/help/latest/policy/CMP0168.html">CMP0168</a>
policy so that \c FetchContent_Declare uses
\c FetchContent_Populate internally with a different sub-build strategy.
If you encounter issues with sub-builds you can either upgrade to a
compatible %Eigen version or set the policy explicitly:
\code{.cmake}
cmake_policy(SET CMP0168 OLD)
\endcode

*/

}