$Id: cmake.omh 3664 2015-02-24 14:28:15Z bradbell $
/* --------------------------------------------------------------------------
CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-15 Bradley M. Bell

CppAD is distributed under multiple licenses. This distribution is under
the terms of the
                    Eclipse Public License Version 1.0.

A copy of this license is included in the COPYING file of this distribution.
Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
-------------------------------------------------------------------------- */

$begin cmake$$
$escape $$
$spell
	cstdint
	uint
	pkgconfig
	ctor
	op
	arg
	sizeof
	testvector
	std
	Wshadow
	namespace
	adouble
	colpack
	dir
	makefile
	usr
	hpp
	xml
	ipopt
	libcppad
	CppAD
	txt
	Microsoft
	Makefiles
	cmake
	Dcmake
	cppad
	adolc
	boost
	eigen
	fadbad
	sacado
	datadir
	docdir
	includedirs
	libdirs
	cxx
	max num
	postfix
	id
	addr
$$

$section Using CMake to Configure CppAD$$
$index cmake, configure cppad$$
$index configure, cppad$$
$index cppad, cmake configure$$


$head The CMake Program$$
$index cmake$$
The
$href%http://www.cmake.org/cmake/help/install.html%cmake%$$
program enables one to create a single set of scripts,
called $code CMakeLists.txt$$,
that can be used to test and install a program on Unix, Microsoft, or
Apple operating systems.
For example, one can use it to automatically generate Microsoft project files.

$head CMake Command$$
$index cmake, command$$
$index configure, cppad$$
$index cppad, configure$$
The command below assumes that $code 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 $code cmake$$
in font the command.
Only the $code cmake$$ command and the path to the distribution directory
($code ..$$ at the end of the command below) are required.
In other words, the first and last lines below are required
and all of the other lines are optional.

$subhead Build Directory$$
Create a $code build$$ subdirectory of the
$cref/distribution directory/download/Distribution Directory/$$,
change into the $code build$$  directory,
and execute the following command:
$codei%
cmake %%                                                                     \
    -G %generator%                                                           \
	\
    -D cmake_install_prefix=%cmake_install_prefix%                           \
    -D cmake_install_postfix=%cmake_install_postfix%                         \
	\
    -D cmake_install_includedirs=%cmake_install_includedirs%                 \
    -D cmake_install_libdirs=%cmake_install_libdirs%                         \
	\
    -D cmake_install_datadir=%cmake_install_datadir%                         \
    -D cmake_install_docdir=%cmake_install_docdir%                           \
    \
    -D adolc_prefix=%adolc_prefix%                                           \
    -D colpack_prefix=%colpack_prefix%                                       \
    -D eigen_prefix=%eigen_prefix%                                           \
    -D fadbad_prefix=%fadbad_prefix%                                         \
    -D ipopt_prefix=%ipopt_prefix%                                           \
    -D sacado_prefix=%sacado_prefix%                                         \
    \
    -D cppad_cxx_flags=%cppad_cxx_flags%                                     \
    \
    -D cppad_testvector=%cppad_testvector%                                   \
    -D cppad_max_num_threads=%cppad_max_num_threads%                         \
    -D cppad_sparse_list=%cppad_sparse_list%                                 \
    -D cppad_tape_id_type=%cppad_tape_id_type%                               \
    -D cppad_tape_addr_type=%cppad_tape_addr_type%                           \
    -D cppad_implicit_ctor_from_any_type=%cppad_implicit_ctor_from_any_type% \
    \
    ..
%$$

$head generator$$
$index makefile, generator$$
$index generator, makefile$$
The CMake program is capable of generating different kinds of files.
Below is a table with a few of the possible files
$table
$icode generator$$ $cnext Description $rnext
$code "Unix Makefiles"$$   $cnext make files for unix operating system $rnext
$code "NMake Makefiles"$$  $cnext make files for Visual Studio
$tend
Other generator choices are available; see the cmake
$href%http://www.cmake.org/cmake/help/cmake2.6docs.html#section_Generators%
generators%$$ documentation.

$head cmake_install_prefix$$
$index install, prefix$$
$index prefix, install$$
This is the top level absolute path below which
all of the CppAD files are installed by the command
$codei%
	make install
%$$
For example,
if $icode cmake_install_prefix$$ is $code /usr$$,
$icode cmake_install_includedirs$$ is $code include$$, and
$icode cmake_install_postfix$$ is not specified,
the file $code cppad.hpp$$ is installed in the location
$codei%
	/usr/include/cppad/cppad.hpp
%$$
The default value for $icode cmake_install_prefix$$ is $code /usr$$.

$head cmake_install_postfix$$
$index install, postfix$$
$index postfix, install$$
This is the bottom level relative path below which
all of the CppAD files are installed.
For example,
if $icode cmake_install_prefix$$ is $code /usr$$,
$icode cmake_install_includedirs$$ is $code include$$, and
$icode cmake_install_postfix$$ is $code coin$$,
the file $code cppad.hpp$$ is installed in the location
$codei%
	/usr/include/coin/cppad/cppad.hpp
%$$
The default value for $icode cmake_install_postfix$$ is empty; i.e,
there is no bottom level relative directory for the installed files.


$head cmake_install_includedirs$$
$index install, include directories$$
$index include, install directories$$
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 $icode cmake_install_prefix$$ is $code /usr$$,
$icode cmake_install_includedirs$$ is $code include$$, and
$icode cmake_install_postfix$$ is not specified,
the file $code cppad.hpp$$ is installed in the location
$codei%
	/usr/include/cppad/cppad.hpp
%$$
The default value for this directory list is $code include$$.


$head cmake_install_libdirs$$
$index install, lib directories$$
$index lib, install directories$$
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.
For example,
if $icode cmake_install_prefix$$ is $code /usr$$,
$icode cmake_install_libdirs$$ is $code lib$$,
$icode cmake_install_postfix$$ is not specified,
and $icode ipopt_prefix$$ is specified,
the file $code libcppad_ipopt.a$$ is installed in the location
$codei%
	/usr/lib/libcppad_ipopt.a
%$$
The default value for this directory list is $code lib$$.

$head cmake_install_datadir$$
$index install, datadir$$
$index datadir, install$$
This is the middle level relative path below which
the CppAD data files are installed.
For example,
if $icode cmake_install_prefix$$ is $code /usr$$,
$icode cmake_install_datadir$$ is $code share$$, and
$icode cmake_install_postfix$$ is not specified,
the $cref pkgconfig$$ file $code cppad.pc$$ is installed in the location
$codei%
	/usr/share/pkgconfig/cppad.pc
%$$
The default value for $icode cmake_install_datadir$$ is $code share$$.

$head cmake_install_docdir$$
$index install, documentation$$
$index documentation, install$$
This is the middle level relative path below which
the CppAD documentation files are installed.
For example,
if $icode cmake_install_prefix$$ is $code /usr$$,
$icode cmake_install_docdir$$ is $code share/doc$$, and
$icode cmake_install_postfix$$ is not specified,
the file $code cppad.xml$$ is installed in the location
$codei%
	/usr/share/doc/cppad/cppad.xml
%$$
There is no default value for $icode cmake_install_docdir$$.
If it is not specified, the documentation files are not installed.

$head package_prefix$$
$index package, prefix$$
$index prefix, package$$
Each of these packages corresponds to optional CppAD examples,
that can be compiled and tested if the corresponding prefix is provided:
$table
$rref adolc_prefix$$
$rref colpack_prefix$$
$rref eigen_prefix$$
$rref fadbad_prefix$$
$rref ipopt_prefix$$
$rref sacado_prefix$$
$tend

$head cppad_cxx_flags$$
$index c++, compile flags$$
$index compile, c++ flags$$
$index flags, c++ compile$$
This specifies the addition compiler flags,
besides the debug and release flags,
that are used when compiling the CppAD examples and tests.
The default value for these flags is the empty string $code ""$$.
These flags must be valid for the C++ compiler
on your system.
For example, if you are using $code g++$$ you could specify
$codep
	-D cppad_cxx_flags="-Wall -ansi -pedantic-errors -std=c++11 -Wshadow"
$$
$subhead C++11$$
In order for the compiler to take advantage of features that are new in C++11,
the $icode cppad_cxx_flags$$ must enable these features.
The compiler may still be used with a flag that disables the new features.

$subhead Eigen and Fadbad$$
The packages
$cref/eigen/eigen_prefix/$$ and $cref/fadbad/fadbad_prefix/$$
currently generate a lot of shadowed variable warnings.
If the $code -Wshadow$$ flag is present, it is automatically removed when
compiling examples and test that use these packages.

$head cppad_testvector$$
See $tref cppad_testvector$$.

$head cppad_max_num_threads$$
$index maximum, number threads$$
$index threads, maximum number$$
The value $icode cppad_max_num_threads$$
must be greater than or equal to four; i.e.,
$icode%max_num_threads% >= 4%$$.
The current default value for $icode cppad_max_num_threads$$ is 48,
but it may change in future versions of CppAD.
The value $icode cppad_max_num_threads$$ in turn specifies
the default value for the preprocessor symbol
$cref/CPPAD_MAX_NUM_THREADS/multi_thread/CPPAD_MAX_NUM_THREADS/$$.

$head cppad_sparse_list$$
$index sparsity, internal structure$$
$index sparsity, vector of sets$$
There are two possible values for this option, $code YES$$ and $code NO$$.
This affect the internal data structure used to store a
$cref/sparsity pattern/glossary/Sparsity Pattern/$$ when the
users version of the sparsity pattern is a vector of $code std::set<size_t>$$.
If $icode cppad_sparse_list$$ is $code NO$$
the vectors of standard sets are also used internally.
If $icode cppad_sparse_list$$ is $code YES$$,
a special sparse list structure is used instead.
This should affect the speed and memory required by the
$cref sparse_jacobian$$, $cref sparse_hessian$$, and
$cref/sparse drivers/sparse/$$
The default value for $icode cppad_sparse_list$$ is $code YES$$

$head cppad_tape_id_type$$
$index memory, usage$$
$index memory, tape$$
$index tape, memory$$
The type $icode cppad_tape_id_type$$
is used for identifying different tapes.
The valid values for this type are
$code unsigned char$$,
$code unsigned short int$$,
$code unsigned int$$, and
$code size_t$$.
The smaller the value of $codei%sizeof(%cppad_tape_id_type%)%$$,
the less memory is used.
On the other hand, the value
$codei%
	std::numeric_limits<%cppad_tape_id_type%>::max()
%$$
must be larger than the maximum number of tapes used by one thread times
$cref/CPPAD_MAX_NUM_THREADS/multi_thread/CPPAD_MAX_NUM_THREADS/$$.

$subhead cstdint$$
If all of the following $code cstdint$$ types are defined,
they can also be used as the value of $icode cppad_tape_addr_type$$:
$code uint8_t$$,
$code uint16_t$$,
$code uint32_t$$,
$code uint64_t$$.

$head cppad_tape_addr_type$$
$index memory, usage$$
$index memory, tape$$
$index tape, memory$$
The type $icode cppad_tape_addr_type$$
is used for address in the AD recordings (tapes).
The valid values for this argument are
$code unsigned char$$,
$code unsigned short int$$,
$code unsigned int$$,
$code size_t$$.
The smaller the value of $codei%sizeof(%cppad_tape_addr_type%)%$$,
the less memory is used.
On the other hand, the value
$codei%
	std::numeric_limits<%cppad_tape_addr_type%>::max()
%$$
must be larger than any of the following:
$cref/size_op/seq_property/size_op/$$,
$cref/size_op_arg/seq_property/size_op_arg/$$,
$cref/size_par/seq_property/size_text/$$,
$cref/size_par/seq_property/size_par/$$,
$cref/size_par/seq_property/size_VecAD/$$.

$subhead cstdint$$
If all of the following $code cstdint$$ types are defined,
they can also be used as the value of $icode cppad_tape_addr_type$$:
$code uint8_t$$,
$code uint16_t$$,
$code uint32_t$$,
$code uint64_t$$.

$head cppad_implicit_ctor_from_any_type$$
$index ctor, implicit or explicit$$
$index implicit, ctor$$
$index explicit, ctor$$
The default value for $icode cppad_implicit_ctor_from_any_type$$ is $code NO$$.
If it is $code YES$$, there is a
$cref/deprecated/ad_ctor/x/deprecated/$$
implicit type constructor (type conversion)
from any type to $codei%AD<%Base%>%$$.
Otherwise this constructor is
$cref/explicit/ad_ctor/x/explicit/$$.


$children%
	omh/install/adolc_prefix.omh%
	omh/install/colpack_prefix.omh%
	omh/install/eigen_prefix.omh%
	omh/install/fadbad_prefix.omh%
	omh/install/ipopt_prefix.omh%
	omh/install/sacado_prefix.omh%
	omh/install/testvector.omh
%$$


$end