$Id: cmake.omh 3760 2015-12-01 04:12:28Z 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
                    GNU General Public License Version 3.

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$$
$mindex makefile install prefix postfix include directories lib datadir documentation package compile flags profile maximum number threads sparsity internal structure vector sets memory usage tape ctor implicit explicit$$


$head The CMake Program$$
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$$
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 %%                                                                     \
    -D CMAKE_VERBOSE_MAKEFILE=%cmake_verbose_makefile%                       \
    -G %generator%                                                           \
	\
    -D cppad_prefix=%cppad_prefix%                                           \
    -D cppad_postfix=%cppad_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_profile_flag=%cppad_profile_flag%                               \
    \
    -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_deprecated=%cppad_deprecated% \
    \
    ..
%$$

$head cmake_verbose_makefile$$
This value should be either $code YES$$ or $code NO$$.
The default value, when it is not present, is $code NO$$.
If it is $code YES$$, then the output of the $code 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.

$head generator$$
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 cppad_prefix$$
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 cppad_prefix$$ is $code /usr$$,
$icode cmake_install_includedirs$$ is $code include$$, and
$icode cppad_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 cppad_prefix$$ is $code /usr$$.

$head cppad_postfix$$
This is the bottom level relative path below which
all of the CppAD files are installed.
For example,
if $icode cppad_prefix$$ is $code /usr$$,
$icode cmake_install_includedirs$$ is $code include$$, and
$icode cppad_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 cppad_postfix$$ is empty; i.e,
there is no bottom level relative directory for the installed files.


$head 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 $icode cppad_prefix$$ is $code /usr$$,
$icode cmake_install_includedirs$$ is $code include$$, and
$icode cppad_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$$
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 cppad_prefix$$ is $code /usr$$,
$icode cmake_install_libdirs$$ is $code lib$$,
$icode cppad_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$$
This is the middle level relative path below which
the CppAD data files are installed.
For example,
if $icode cppad_prefix$$ is $code /usr$$,
$icode cmake_install_datadir$$ is $code share$$, and
$icode cppad_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$$
This is the middle level relative path below which
the CppAD documentation files are installed.
For example,
if $icode cppad_prefix$$ is $code /usr$$,
$icode cmake_install_docdir$$ is $code share/doc$$, and
$icode cppad_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$$
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$$
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
(unless it is a Microsoft compiler; i.e., $code _MSC_VER$$ is defined).

$head cppad_profile_flag$$
This specifies an addition compiler and link flag that is used
for $cref/profiling/speed_main/package/profile/$$ the speed tests.
A profile version of the speed test is only build when this argument
is present.

$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$$
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$$
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$$
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$$
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_deprecated$$
The default value for $icode cppad_deprecated$$ is $code NO$$.
If it is $code YES$$, then all the CppAD
$cref deprecated$$ features are included in the
$cref/installation/install/Instructions/Step 4: Installation/$$.
Otherwise, some of the deprecated features
may be excluded from the installation.
(The intention here is to exclude more deprecated features as time marches on.)

$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
