# SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
# SPDX-FileCopyrightText: Bradley M. Bell <bradbell@seanet.com>
# SPDX-FileContributor: 2003-25 Bradley M. Bell
# ----------------------------------------------------------------------------

{xrst_begin cmake}
{xrst_spell
   ansi
   autotools
   colpack
   cstdint
   cxx
   datadir
   dev
   dlls
   docdir
   dylib
   exe
   ext
   fadbad
   gprof
   grep
   hsc
   includedirs
   libcppad
   libdirs
   makefile
   makefiles
   mingw
   mkdir
   msys
   pacman
   profiler
   sacado
   sed
   testvector
   txt
   uint
   usr
   vcvarsall
   wshadow
   yyyy
   yyyymmdd
}

Using CMake to Configure CppAD
##############################

The CMake Program
*****************
The cmake program enables one to create a single set of scripts,
called ``CMakeLists.txt`` ,
that can be used to test and install a program on Unix, Microsoft, or
Apple operating systems; see
`cmake resources <https://cmake.org/resources/>`_ .

Build Directory
***************
Create ``build`` , a subdirectory of the
:ref:`download@Distribution Directory` ,
change into the ``build`` .

Eigen
*****
The cmake command will automatically search for the eigen package.
If it is found,
the  corresponding examples will be tested and the
:ref:`sparse2eigen-name` utility will be installed; see :ref:`eigen-name` .
The results of cppad's search for Eigen are reported in the output of
the cmake command.

CMake Command
*************

Simple
======
The simplest version of the ``cmake`` command is

   ``cmake ..``

This assumes that you are starting in the ``build`` directory
(so that ``..`` refers to the distribution directory).
The command also assumes that ``cmake`` is in your execution
path with version greater than or equal 2.8.
If not, you can put the path to the version of ``cmake``
in font the command.
It is suggested that you should start with the simple version of the
cmake command above and then add options one at a time.

Warning
=======
Version 3.10.2 of cmake will generates the following warning if boost
is not present your system:

| ``CMake Warning at /usr/share/cmake-3.10/Modules/FindBoost.cmake:567`` ( ``message`` ):
| |tab| ``Imported targets and dependency information not available for Boost version``
| |tab| ( ``all versions older than 1.33`` )
| |tab| ...

This is not a problem because CppAD will automatically exclude the
examples and tests that use boost.
Newer version of cmake; e.g., 3.13.4, do not generate this warning
(when boost is not present on your system).

true_or_false
=============
The syntax ``-D`` *name* = *true_or_false* , mean that
the variable *name* can be assigned the value ``true`` or ``false`` .


Options
=======
The full version of the command, with all its optional arguments is:

| ``cmake``                                                                 \\
| |tab| ``-D CMAKE_VERBOSE_MAKEFILE`` = *cmake_verbose_makefile*            \\
| |tab| ``-D CMAKE_BUILD_TYPE`` = *cmake_build_type*                        \\
| |tab| ``-G`` *generator*                                                  \\
| |tab| \\
| |tab| ``-D cppad_prefix`` = *cppad_prefix*                                \\
| |tab| ``-D cppad_postfix`` = *cppad_postfix*                              \\
| |tab| \\
| |tab| ``-D cmake_install_includedirs`` = *cmake_install_includedirs*      \\
| |tab| ``-D cmake_install_libdirs`` = *cmake_install_libdirs*              \\
| |tab| \\
| |tab| ``-D cmake_install_datadir`` = *cmake_install_datadir*              \\
| |tab| ``-D cmake_install_docdir`` = *cmake_install_docdir*                \\
| |tab| \\
| |tab| ``-D include_doc`` = *true_or_false*                                \\
| |tab| ``-D cmake_defined_ok`` = *true_or_false*                           \\
| |tab| ``-D cppad_static_lib`` = *true_or_false*                           \\
| |tab| ``-D cppad_debug_and_release`` = *true_or_false*                    \\
| |tab| \\
| |tab| ``-D include_adolc`` = *true_or_false*                              \\
| |tab| ``-D include_ipopt`` = *true_or_false*                              \\
| |tab| ``-D include_cppadcg`` = *true_or_false*                            \\
| |tab| \\
| |tab| ``-D colpack_prefix`` = *colpack_prefix*                            \\
| |tab| ``-D fadbad_prefix`` = *fadbad_prefix*                              \\
| |tab| ``-D sacado_prefix`` = *sacado_prefix*                              \\
| |tab| \\
| |tab| ``-D cppad_cxx_flags`` = *cppad_cxx_flags*                          \\
| |tab| ``-D cppad_link_flags`` = *cppad_link_flags*                        \\
| |tab| ``-D cppad_profile_flag`` = *cppad_profile_flag*                    \\
| |tab| ``-D cppad_testvector`` = *cppad_testvector*                        \\
| |tab| ``-D cppad_max_num_threads`` = *cppad_max_num_threads*              \\
| |tab| ``-D cppad_tape_id_type`` = *cppad_tape_id_type*                    \\
| |tab| ``-D cppad_tape_addr_type`` = *cppad_tape_addr_type*                \\
| |tab| ``-D cppad_debug_which`` = *cppad_debug_which*                      \\
| |tab| \\
| |tab| ..

msys2
=====
The `msys2 <https://www.msys2.org/>`_ system,
with ``mingw-64`` and ``g++`` ,
the following seems to work:
Use ``pacman`` to install
``make`` , ``gcc`` , and ``mingw-w64-x86_64-cmake`` .

Visual Studio
=============

#. Make sure you have a version of
   `git for windows <https://git-scm.com/download/win>`_ .

#. Launch the Visual Studio
   `developer command window <https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022>`_

#. At the command prompt enter
   ::

      where cmake.exe

   to see if ``cmake.exe`` comes with your version of Visual Studio.
   If not, download and install the win64-x64 version of the
   `cmake program <https://cmake.org/download/>`_.
   Make sure you select the box that adds ``cmake`` to your execution path.

#. Download the CppAD repository, and make it the current directory,
   using the following commands
   {xrst_code bat}
   clone https://github.com/coin-or/CppAD.git cppad.git
   cd cppad.git
   {xrst_code}

#. Execute the following commands:
   {xrst_literal
      bin/build.bat
   }

Note that when using windows DLL's, CppAD builds a static version
of ``cppad_lib`` . There are problems using a DLL for ``cppad_lib``
because Windows makes separate copies of static class member functions,
one for library and one for the rest of the program.

autotools
=========
The autotools build with the Visual Studio compiler should work
with the following configure and test commands
::

   mkdir build
   cd build
   ../configure CC=cl CXX=cl CXX_FLAGS="-DEBUG"
   make test

An optimized versions was tested using
::

   ../configure CXX=cl CC=cl CXX_FLAGS="-DNDEBUG -O2 -EHsc"
   make test

The commands above need to be run a Dos window,
that has the ``vcvarsall.bat`` settings,
extend path that includes the ``msys2`` bin directory,
and was running the bash shell inside the Doc window.
It is highly recommended that you use the ``cmake`` commands above,
an not ``../configure`` , when building with Visual Studio.

make check
**********
Important information about the CppAD configuration is output
by this command. If you have the ``grep`` program,
and store the output in ``cmake.log`` , you can get a list of
all the test options with the command:
::

   grep 'make check' cmake.log

cmake_verbose_makefile
**********************
This value should be either ``true`` or ``false`` .
The default value, when it is not present, is ``false`` .
If it is ``true`` , then the output of the ``make`` commands
will include all of the files and flags used to run the compiler
and linker. This can be useful for seeing how to compile and link
your own applications.

cmake_build_type
****************
This value should be one of the valid CMake build types; e.g.,
``Debug`` ,
``Release`` ,
``RelWithDebInfo`` ,
``MinSizeRel`` .
The value of this option is not case sensitive; e.g.,
``Debug`` and ``debug`` yield the same result.
If *cmake_build_type* is specified,
:ref:`cmake@cppad_debug_which`
must be the empty string.

generator
*********
The CMake program is capable of generating different kinds of files.
Below is a table with a few of the possible files

.. csv-table::
   :widths: auto

   *generator*,Description
   ``"Unix Makefiles"``,make files for unix operating system
   ``"NMake Makefiles"``,make files for Visual Studio
   ``"MSYS Makefiles"``,make files for msys2
   ``Ninja``, `Ninja`_ build system

.. _Ninja: https://en.wikipedia.org/wiki/Ninja_(build_system)

Other generator choices are available; see the cmake
`generators <https://cmake.org//cmake/help/cmake2.6docs.html#section_Generators>`_ documentation.

cppad_prefix
************
This is the top level absolute path below which
all of the CppAD files are installed by the command

   ``make install``

For example,
if *cppad_prefix* is ``/usr`` ,
*cmake_install_includedirs* is ``include`` , and
*cppad_postfix* is not specified,
the file ``cppad.hpp`` is installed in the location

   / ``usr/include/cppad/cppad.hpp``

The default value for *cppad_prefix* is the value of
*CMAKE_INSTALL_PREFIX* ; see the cmake documentation.
(Before 2019-10-02 the default value was ``/usr`` ; see
the heading 10-02 on :ref:`2019<2019@mm-dd@10-02>` .)

cppad_postfix
*************
This is the bottom level relative path below which
all of the CppAD files are installed.
For example,
if *cppad_prefix* is ``/usr`` ,
*cmake_install_includedirs* is ``include`` , and
*cppad_postfix* is ``coin-or`` ,
the file ``cppad.hpp`` is installed in the location

   / ``usr/include/coin-or/cppad/cppad.hpp``

The default value for *cppad_postfix* is empty; i.e,
there is no bottom level relative directory for the installed files.

cmake_install_includedirs
*************************
This is one directory, or a list of directories separated
by spaces or by semi-colons.
This first entry in the list is the middle level relative path below which
the CppAD include files are installed.
The entire list is used for searching for include files.
For example,
if *cppad_prefix* is ``/usr`` ,
*cmake_install_includedirs* is ``include`` , and
*cppad_postfix* is not specified,
the file ``cppad.hpp`` is installed in the location

   / ``usr/include/cppad/cppad.hpp``

The default value for this directory list is ``include`` .

cmake_install_libdirs
*********************
This is one directory, or a list of directories separated
by spaces or by semi-colons.
This first entry in the list is the middle level relative path below which
the CppAD library files are installed.
The entire list is used for searching for library files.
The default value for this directory list is ``lib;lib64`` .

cppad_lib
=========
As an example of where the CppAD library is installed,
if *cppad_prefix* is ``/usr`` ,
*cmake_install_libdirs* is ``lib`` ,
*cppad_postfix* is not specified,
the CppAD library is installed in

   / ``usr/lib/libcppad_lib.`` *ext* . *major* . *release*

Here *major* is the major library version number,
*release* is the release number for this version,
and *ext* is the extension for shared libraries on this system.
If *yyyymmdd* is the CppAD :ref:`download@Version` number,
the major CppAD library version number is

   *major* = *dd* ``- 1`` + 31 * ( *mm* ``- 1`` + 12 * ( *yyyy* ``- 2019`` ) )

If there is no :ref:`download@Release` for this version of CppAD,
the CppAD library is installed in

   / ``usr/lib/libcppad_lib.`` *ext* . *major*

The Mac is special, *ext* is ``dylib`` and comes
at the end of the file name for that system.

cmake_install_datadir
*********************
This is the middle level relative path below which
the CppAD data files are installed.
For example,
if *cppad_prefix* is ``/usr`` ,
*cmake_install_datadir* is ``share`` , and
*cppad_postfix* is not specified,
the :ref:`pkgconfig-name` file ``cppad.pc`` is installed in the location

   / ``usr/share/pkgconfig/cppad.pc``

The default value for *cmake_install_datadir* is ``share`` .

cmake_install_docdir
********************
This is the middle level relative path below which
the CppAD user documentation files are installed.
For example,
if *cppad_prefix* is ``/usr`` ,
*cmake_install_docdir* is ``share/doc`` , and
*cppad_postfix* is not specified,
the file ``user_guide.html`` is installed in the location

   / ``usr/share/doc/cppad/user_guide.html``

If *cmake_install_docdir* is not specified,
or :ref:`cmake@include_doc` is false,
the documentation files are not installed.

cmake_defined_ok
****************
The default value for this option is true.
It must be true when running cmake with a non-empty
``CMakeCache.txt`` file.
If it is false, some checks will be made to make sure
certain variables are not defined twice.

include_doc
***********
The default value for this option is false.
If it is true, is in the command line, the
`xrst <https://xrst.readthedocs.io/latest/>`_
program must be installed.
In this case, the user and developer documentation targets
``doc_user`` and ``doc_dev`` will be available.
For example, if the :ref:`cmake@generator` is ``Ninja``
the commands ``ninja doc_user`` and ``ninja doc_dev``
will build the  corresponding documentation in the
``build/html`` sub-directory of the
:ref:`download@Distribution Directory` .

cppad_static_lib
****************
The default value for this option is true on
``msys``, ``cygwin`` and ``Windows`` and false otherwise.
the cppad library will be a static (shared) library.
If the target system uses windows dlls, this setting should be true and
if it is false, a warning will be issued and it will be ignored.

cppad_debug_and_release
***********************
The default value for this option is true.
If it is true,
the debug and release versions of CppAD can be mixed in the same program.
This must be true if
:ref:`cmake@cppad_debug_which` is ``debug_even`` or ``debug_odd`` .
If ``NDEBUG`` is defined and *cppad_debug_and_release* is false,
:ref:`thread_alloc-name` does more error checking.
For programs that do a lot of memory allocation,
this can take a significant amount of time.
This is meant for testing CppAD and as a last resort when debugging.

include_adolc
*************
The default value for this option is false.
If it is true,
the :ref:`adolc-name` examples will be compiled and tested.
In this case, ``adolc.pc`` must be in the ``PKG_CONFIG_PATH`` .

include_ipopt
*************
The default value for this option is false.
If it is true,
the :ref:`ipopt-name` examples will be compiled and tested.
In this case, ``ipopt.pc`` must be in the ``PKG_CONFIG_PATH`` .
In addition, :ref:`ipopt_solve-name` and :ref:`cppad_ipopt_nlp-name`
will be installed.

include_cppadcg
***************
The default value for this option is false.
If it is true,
the :ref:`cppadcg-name` examples will be compiled and tested.
**Warning** :
Do not use this option when installing cppad because
the cppadcg package depends on cppad and using this option
makes cppad depend on cppadcg.
This option, and the script :ref:`get_cppadcg.sh-name` are only intended
for testing purposes.

package_prefix
**************
Each of these packages do not have ``pkg-config`` files
corresponding to optional CppAD examples.
If a prefix listed below is on the command line,
the corresponding examples will be compiled and run:

.. csv-table::
   :widths: auto

   colpack_prefix,:ref:`colpack_prefix-title`
   fadbad_prefix,:ref:`fadbad_prefix-title`
   sacado_prefix,:ref:`sacado_prefix-title`

cppad_cxx_flags
***************
This specifies the compiler flags
that are used when compiling the CppAD examples, tests, and library.
This flags are in addition to the flags automatically generated by
cmake for debug and release build; i.e.,
*CMAKE_CXX_FLAGS_DEBUG* and *CMAKE_CXX_FLAGS_RELEASE* .
The default value for these flags is the empty string ``""`` .
These flags must be valid for the C++ compiler
on your system.
For example, if you are using ``g++`` you could specify
::

   -D cppad_cxx_flags="-Wall -ansi -pedantic-errors -std=c++17 -Wshadow"

C++17
=====
In order for the compiler to take advantage of features that are in C++17
,but not in C++11, the *cppad_cxx_flags* must enable these features.

cppad_link_flags
****************
This specifies additional flags to use during linking.
The default value for these flags is the empty string ``""`` .

-m32
====
If you are on a 64 bit machine and using g++ to
compile for 32 bit code, you need to add ``-m32`` to both
the additional compiler and linker flags.
If ``-m32`` is in *cppad_link_flags* ,
the OpenMP, Boost, :ref:`jit <example_jit-name>` , and
:ref:`speed_cppad_jit-name` examples will not be tested.

cppad_profile_flag
******************
This specifies an addition compiler and link flag that is used
for :ref:`profiling<speed_main@package@profile>` the speed tests.
A profile version of the speed test is only build when this argument
is present.
If this flag is specified, you can run the gnu profiler with the following
command:

| |tab| ``cd build/speed/profile``
| |tab| ``make check_speed_profile``
| |tab| ./ ``speed_profile`` *test seed option_list*
| |tab| ``gprof -b speed_profile`` | ``sed -f gprof.sed``

cppad_testvector
****************
See :ref:`cppad_testvector-title`.

cppad_max_num_threads
*********************
The value *cppad_max_num_threads*
must be greater than or equal to four; i.e.,
*max_num_threads*  >= 4 .
The current default value for *cppad_max_num_threads* is 48,
but it may change in future versions of CppAD.
The value *cppad_max_num_threads* in turn specifies
the default value for the preprocessor symbol
:ref:`multi_thread@CPPAD_MAX_NUM_THREADS` .

cppad_tape_id_type
******************
The type *cppad_tape_id_type*
is used for identifying different tapes.
The valid values for this type are
``unsigned char`` ,
``unsigned short int`` ,
``unsigned int`` , and
``size_t`` .
The smaller the value of ``sizeof`` ( *cppad_tape_id_type* ) ,
the less memory is used.
On the other hand, the value

   ``std::numeric_limits<`` *cppad_tape_id_type* >:: ``max`` ()

must be larger than the maximum number of tapes used by one thread times
:ref:`multi_thread@CPPAD_MAX_NUM_THREADS` .

cstdint
=======
If all of the following ``cstdint`` types are defined,
they can also be used as the value of *cppad_tape_addr_type* :
``uint8_t`` ,
``uint16_t`` ,
``uint32_t`` ,
``uint64_t`` .

cppad_tape_addr_type
********************
The type *cppad_tape_addr_type*
is used for address in the AD recordings (tapes).
The valid values for this argument are
``unsigned char`` ,
``unsigned short int`` ,
``unsigned int`` ,
``size_t`` .
The smaller the value of ``sizeof`` ( *cppad_tape_addr_type* ) ,
the less memory is used.
On the other hand, the value

   ``std::numeric_limits<`` *cppad_tape_addr_type* >:: ``max`` ()

must be larger than any of the following:
:ref:`fun_property@size_op` ,
:ref:`fun_property@size_op_arg` ,
:ref:`fun_property@size_par` ,
:ref:`fun_property@size_text` ,
:ref:`fun_property@size_VecAD` .

cstdint
=======
If all of the following ``cstdint`` types are defined,
they can also be used as the value of *cppad_tape_addr_type* :
``uint8_t`` ,
``uint16_t`` ,
``uint32_t`` ,
``uint64_t`` .

cppad_debug_which
*****************
All of the CppAD examples and test can optionally be tested
in debug or release mode (see exception below).
This option controls which mode is chosen for the corresponding files.
The value *cppad_debug_which* be one of the following:

.. csv-table::
   :widths: auto

   *cppad_debug_which*,*CMAKE_BUILD_TYPE*
   ``debug_all``,``Debug``
   ``debug_none``,``Release``
   ``debug_even``,not specified
   ``debug_odd``,not specified
   empty string,not changed

If ``CMAKE_BUILD_TYPE`` is specified on the command line,
then *cppad_debug_which* must be the empty string (its default value).

{xrst_toc_hidden
   bin/get_optional.sh
   xrst/install/adolc.xrst
   xrst/install/eigen.xrst
   xrst/install/cppadcg.xrst
   xrst/install/ipopt.xrst
   xrst/install/fadbad_prefix.xrst
   xrst/install/sacado_prefix.xrst
   xrst/install/colpack_prefix.xrst
   xrst/install/testvector.xrst
}

{xrst_end cmake}
