% =============================================================================
% The CGAL Developers' Manual
% Chapter: Tools
% -----------------------------------------------------------------------------
% file   : tools.tex
% authors: Geert-Jan Giezeman <geert@cs.uu.nl>
% -----------------------------------------------------------------------------
% $Id$
% $Date$
% =============================================================================

\chapter{Scripts and Other Tools\label{chap:tools}}
\ccIndexMainItemBegin{tools}
\ccChapterRelease{Chapter Version: 1.0}
\ccChapterAuthor{Geert-Jan Giezeman ({\tt geert@cs.uu.nl})}

There are a number of tools that automate some of the tedious and
error-prone tasks that are unavoidable when developing for \cgal.
Most of these scripts can be in at least two places.
\begin{itemize}
   \item in every internal release (directory {\tt developer\_scripts} or
         {\tt scripts})
   \item in the package
         \ccAnchor{https://gforge.inria.fr/plugins/scmsvn/viewcvs.php/trunk/Scripts/?root=cgal}
         {Scripts} on the SVN server%
         \index{SVN server!Scripts package@\texttt{Scripts} package}%
         \begin{ccTexOnly}
        (\path|https://gforge.inria.fr/plugins/scmsvn/viewcvs.php/trunk/Scripts/?root=cgal|)
         \end{ccTexOnly}.
\end{itemize}


\section{{\tt create\_new\_release}}
\label{sec:create_new_release}
\index{create_new_release script@{\tt create\_new\_release} script|(}
\ccIndexMainItem{release building}

The script
\ccAnchor{https://gforge.inria.fr/plugins/scmsvn/viewcvs.php/trunk/Scripts/developer_scripts/create_new_release?root=cgal&view=markup}
{{\tt create\_new\_release}} builds a tarball of CGAL from an SVN working
copy of the trunk (or a branch).
The command
\begin{verse}
{\tt create\_new\_release}
\end{verse}
creates a directory {\tt tmp} which contains the tarball, as well as its
public and SRPM versions.

This script takes as argument the name of an SVN working copy of a branch,
and it default to {\tt trunk}.  It also supports the following options:
\begin{description}
\item[--rpm]      create SRPM files as well
\item[--public]   create a public version as well
\item[--do-it]    (reserved to the release manager) moves it on the web server,
                  tags...
\item[--do-not-tag] option that allows to create a new release with
  \texttt{--do-it} without creating the tag.
\end{description}
\index{create_new_release script@{\tt create\_new\_release} script|)}


\section{{\tt create\_assertions.sh}}
\label{sec:create_assertions}
\index{create_assertions.sh script@{\tt create\_assertions.sh} script|(}
\ccIndexMainItem{assertions}

The shell script
\ccAnchor{https://gforge.inria.fr/plugins/scmsvn/viewcvs.php/trunk/Scripts/developer_scripts/create_assertions.sh?root=cgal&view=markup}
{{\tt create\_assertions.sh}} generates assertion header files.
The command
\begin{verse}
{\tt create\_assertions.sh minkowski}
\end{verse}
creates a file {\tt minkowski\_assertions.h}.
This file is usually placed in directory {\tt include/CGAL} and included in
files that implement the minkowski package.
The file contains several macros for adding checks (preconditions,
postconditions, {\em etc.}) that can be switched on or off with compile
flags.
You can read more about the use of these package-level checks in
Section~\ref{sec:checks_controlling}.
\index{create_assertions.sh script@{\tt create\_assertions.sh} script|)}


\section{{\tt cgal\_create\_makefile}}
\label{sec:cgal_create_makefile}
\index{cgal_create_makefile script@{\tt cgal\_create\_makefile} script|(}
\ccIndexSubitemBegin{\tt makefile}{creating}

The shell script
\ccAnchor{https://gforge.inria.fr/plugins/scmsvn/viewcvs.php/trunk/Scripts/scripts/cgal_create_makefile?root=cgal&view=markup}
{{\tt cgal\_create\_makefile}} creates a \cgal\ makefile
in the current working directory.
The makefile will have rules to make an executable from every {\tt .C}
and {\tt .cpp} file which contains the word {\tt main} in the directory.
The following options are available to indicate the kind of makefile
to create:
\begin{description}
\item[-d]   create a default CGAL makefile
\item[-t]   create a CGAL makefile for the test suite
\item[-q]   create a CGAL makefile with Qt support
\end{description}

You should use this script to create makefiles for testing before submitting
your packages, but you should {\bf avoid} customizing the makefile for your
package and then submitting the makefiles for your test suite and example
programs.\ccIndexSubitem{\tt makefile}{submitting}
Makefiles get created automatically when a release is made. This ensures
that the most up-to-date makefiles are created. Experience has shown
that makefiles need to be updated from time to time, especially if new
compilers are supported. When makefiles are submitted as part of a package,
they tend to get outdated.
Moreover, creating a makefile that works for a diverse range of compilers
is difficult.

The makefiles created by this script have two hooks for customization.
If the directory
where the makefile is created contains a directory named {\tt include},%
\index{include directory@{\tt include} directory!local}
that
directory will be on the header search path before any other files. This
provides a means to override header files%
\ccIndexSubitem{header files}{overriding}.
Furthermore, the makefiles in the
test suite (created with the {\tt -t} option), contain the variable
{\tt EXTRA\_FLAGS}.\ccIndexSubitem{\tt makefile}{test suite}%
\index{extra_flags variable@{\tt EXTRA\_FLAGS} variable}
This variable can be set, {\em e.g.}, as an environment variable in
{\tt cgal\_test}, to add {\tt -I} or {\tt -D} options.
\ccIndexSubitemEnd{\tt makefile}{creating}
\index{cgal_create_makefile script@{\tt cgal\_create\_makefile} script|)}

\section{{\tt cgal\_create\_cmake\_script}}
\label{sec:cgal_create_cmake_script}
\index{cgal_create_cmake_script script@{\tt cgal\_create\_cmake\_script} script|(}
\ccIndexSubitemBegin{\tt cmake script}{creating}

The shell script
\ccAnchor{https://gforge.inria.fr/plugins/scmsvn/viewcvs.php/trunk/Scripts/scripts/cgal_create_cmake_script?root=cgal&view=markup}
{{\tt cgal\_create\_cmake\_script}} creates a \cgal\ cmake script, that is, a {\tt CMakeLists.txt} file,
in the current working directory for configuring a particular \cgal\ application (such as an example, demo or test).

The cmake script will have commands to make an executable from every {\tt .C}
and {\tt .cpp} file which contains the word {\tt main} in the directory.
The following options are available to indicate the kind of cmake script
to create:
\begin{description}
\item[-q]   create a CMake script with Qt support
\end{description}


You should use this script to create a {\tt 'CMakeLists.txt'} for testing before submitting
your packages, but you should {\bf avoid} customizing the {\tt CMakeLists.txt} for your
package and then submitting it. \ccIndexSubitem{\tt 'CMakeLists.txt'}{submitting}
CMake scripts get created automatically when a release is made. This ensures
that the most up-to-date {\tt 'CMakeLists.txt'} is created. Experience has shown
that cmake scripts need to be updated from time to time. 
When cmake scripts are submitted as part of a package, they tend to get outdated.


The {\tt 'CMakeLists.txt'} created by this script has the following properties:

If the directory where the cmake script is created contains a directory named {\tt include},%
\index{include directory@{\tt include} directory!local}
that directory will be on the header search path before any other files. This
provides a means to override header files%
\ccIndexSubitem{header files}{overriding}.

The \cgal\ library is required (must have been already configured) and
cmake must be called with {\tt '-DCGAL\_DIR={\em <path>}'},
where {\em <path>} corresponds to the binary directory of the \cgal\ installation
(where the file 'CGALConfig.cmake' is).

While cmake itself takes care automatically of most compiler and linker flags based
on the target compiler and debug/release configuration, additional flags
might have been specified when building \cgal\ and will be used here
(as defined in 'CGALConfig.cmake'). However, if you
need {\em additional} compiler or linker flags specifically here,
you can define any of the following cmake variables at the command line
when running cmake (via the -D option):

\begin{verbatim}
CGAL_CXX_FLAGS
CGAL_CXX_FLAGS_RELEASE
CGAL_CXX_FLAGS_DEBUG
CGAL_EXE_LINKER_FLAGS
CGAL_EXE_LINKER_FLAGS_RELEASE
CGAL_EXE_LINKER_FLAGS_DEBUG
\end{verbatim}

The \_RELEASE and \_DEBUG variables are {\em appended} to the general variable, so for each
build type, two sets of flags are used. For example: CGAL\_CXX\_FLAGS {\em then} CGAL\_CXX\_FLAGS\_DEBUG 

\ccIndexSubitemEnd{\tt cmake script}{creating}
\index{cgal_create_cmake_script script@{\tt cgal\_create\_cmake\_script} script|)}


\section{{\tt create\_cgal\_test}}
\label{sec:create_cgal_test}
\index{create_cgal_test script@{\tt create\_cgal\_test} script|(}
\index{cgal_test script@{\tt cgal\_test} script|(}

In every subdirectory of {\tt test} there must be a shell script called
{\tt cgal\_test}. This script is called from the {\tt run\_testsuite}%
\index{run_testsuite script@{\tt run\_testsuite} script}
script when the test suite is run. The script
\ccAnchor{https://gforge.inria.fr/plugins/scmsvn/viewcvs.php/trunk/Scripts/developer_scripts/create_cgal_test?root=cgal&view=markup}
{{\tt create\_cgal\_test}}
will create the shell script {\tt cgal\_test} in the current directory.

As is the case with makefiles, this file will be generated automatically for
each subdirectory of {\tt test} if
it is not supplied by the package. This is also the preferred way.
So you should use {\tt create\_cgal\_test} to test your package before
submitting but generally should avoid submitting the file {\tt cgal\_test}.
But sometimes you may want to do something extra in this script ({\em e.g.}, set
the {\tt EXTRA\_FLAGS}\index{extra_flags variable@{\tt EXTRA\_FLAGS} variable}
environment variable that is used in the makefile).
In this case, you can run {\tt create\_cgal\_test} yourself and edit the result.
The generated file contains a header that lists the requirements a
{\tt cgal\_test} program should fulfill. These are also listed in
Section~\ref{sec:test_subdirectory} with the description of the
{\tt cgal\_test} script.

Files which are considered by {{\tt create\_cgal\_test}} are those with
{\tt .C} or {\tt .cpp} extension, and which content match the word {\tt main}.
This way, no attempt is made at linking programs which are made of several
object files.

%\begin{itemize}
%\item For every target two one-line messages are written to the file
%      {\tt error.txt}\in
%      The first one indicates if the compilation was successful,
%the second one indicates if the execution was successful.
%If one of the two was not successful, the line should start with 'ERROR:'
%\item
%Running the script should not require any user interaction
%\item
%The script should clean up object files and executables
%\end{itemize}
\index{cgal_test script@{\tt cgal\_test} script|)}
\index{create_cgal_test script@{\tt create\_cgal\_test} script|)}

\section{{\tt create\_cgal\_test\_with\_cmake}}
\label{sec:create_cgal_test_with_cmake}
\index{create_cgal_test_with_cmake script@{\tt create\_cgal\_test\_with\_cmake} script|(}
\index{cgal_test_with_cmake script@{\tt cgal\_test\_with\_cmake} script|(}

In every subdirectory of {\tt test} there must be a shell script called
{\tt cgal\_test\_with\_cmake}. This script is called from the {\tt run\_testsuite\_with\_cmake}%
\index{run_testsuite script@{\tt run\_testsuite\_with\_cmake} script}
script when the test suite is run. The script
\ccAnchor{https://gforge.inria.fr/plugins/scmsvn/viewcvs.php/trunk/Scripts/developer_scripts/create_cgal_test_with_cmake?root=cgal&view=markup}
{{\tt create\_cgal\_test\_with\_cmake}}
will create the shell script {\tt cgal\_test\_with\_cmake} in the current directory.

As is the case with cmake scripts, this file will be generated automatically 
for each subdirectory of {\tt test} if
it is not supplied by the package. This is also the preferred way, so you should
use {\tt create\_cgal\_test\_with\_cmake} to test your package before
submitting but generally should avoid submitting the file {\tt cgal\_test\_with\_cmake}.
The generated file contains a header that lists the requirements a
{\tt cgal\_test\_with\_cmake} program should fulfill. These are also listed in
Section~\ref{sec:test_subdirectory} with the description of the
{\tt cgal\_test\_with\_cmake} script.

Files which are considered by {{\tt create\_cgal\_test\_with\_cmake}} are those with
{\tt .c} or {\tt .cpp} extension, and which content match the word {\tt main}.
This way, no attempt is made at linking programs which are made of several
object files.

The generated script calls {\tt cmake} with the following definitions
\begin{verbatim}
-DCGAL_DIR=${CGAL_DIR}
-DCGAL_CXX_FLAGS=${TESTSUITE_CXXFLAGS} 
-DCGAL_EXE_LINKER_FLAGS=${TESTSUITE_LDFLAGS}
-DCMAKE_BUILD_TYPE=NOTFOUND
\end{verbatim}

The environment variable {\tt CGAL\_DIR } is {\em required} and must contain the path
to the binary directory of the \cgal\ installation to use (the testsuite defines 
this automatically), while the environment variables {\tt TESTSUITE\_CXXFLAGS and 
TESTSUITE\_LDFLAGS} are optional and are used to {\em add} flags which have not
been used when building the library. These TESTSUITE variables are
kept for backward compatibility with the non-cmake testsuite (the preferred way is to define all
the flags when building \cgal\ rather than using these).

{\tt CMAKE\_BUILD\_TYPE} is set to {\tt NOTFOUND} in order to use the same
build type specified when building \cgal\ (as defined in {\tt CGALConfig.cmake}).

\index{cgal_test_with_cmake script@{\tt cgal\_test\_with\_cmake} script|)}
\index{create_cgal_test_with_cmake script@{\tt create\_cgal\_test\_with\_cmake} script|)}

\section{{\tt autotest\_cgal}}
\label{sec:autotest_cgal}
\index{autotest_cgal script@{\tt autotest\_cgal} script|(}
\ccIndexSubitem{test suite}{internal release}

The shell script {\tt autotest\_cgal} is used to run automated test suites for
the internal releases of the library. The script takes no command-line
argument, but it is configurable using a {\tt .autocgalrc} file stored
in {\tt \$HOME}.
It is meant to be run regularly by a cron job run by the testers.

This script allows you to run the testsuite on multiple hosts (remotely or
locally) and multiple compiler-platforms. It is also possible to specify how
many processors the host has and the script will use this information to run
the testsuite process on several processors at the same time. By default, the
number of processors assigned to every host is one.

In a couple of words, the script first downloads a file named {\tt LATEST}
that contains the current release file name. It compares it with the file {\tt
RELEASE\_NR} in the {\tt \$CGAL\_ROOT} directory and if it is different it
starts the testsuite process : it downloads the internal release, unzips,
untars, copies the configuration files, and starts the testsuite. When
everything is done, it puts the results on some ftp server.

\paragraph{How to set up your local testing} ~

The first step is to create a directory where you will store the releases.
This directory is known in the script as {\tt \$CGAL\_ROOT}. By default
{\tt \$CGAL\_ROOT} is the directory where you put the script {\tt
autotest\_cgal}, but you may change it in {\tt .autocgalrc}.

The next step is to download an internal release of your choice, say {\tt
CGAL-3.1-I-xx}, and install it on the various platforms you want it to be
installed using the usual procedure with the {\tt install\_cgal} script.
This will create the configuration files in the directory {\tt
CGAL-3.1-I-xx/config/install/}.

Then, create a symbolic link to this release using {\tt ln -s CGAL-3.1-I-xx
CGAL-I}. This link will be updated by {\tt autotest\_cgal} to point to the
last installed release.  You may remove older releases at some point.

The script uses {\tt wget} to download the release. The different options you
may pass to {\tt wget} you should put in the {\tt WGET} variable in {\tt
.autocgalrc}. By default, {\tt WGET=''wget''}. We noticed that you must use
a recent version of {\tt wget} (1.9.1 is fine, but 1.8.2 is not). You must
also create a file in your {\tt HOME} called {\tt .wgetrc} (alternatively,
it is also possible to use another file by setting the {\tt WGETRC} variable),
that contains the following lines:
\begin{verbatim}
--http-user=member1
--http-passwd=xxxxxxx
\end{verbatim}

Alternatively, you can use {\tt curl} instead of {\tt wget}.  In order to
do so, you need to add {\tt USE\_CURL=''y''} to your {\tt .autocgalrc} file.
{\tt curl} is then also used as a replacement for {\tt ftp} for uploading the
test results.
You also have to add the following line in a file called {\tt HOME/.curlrc}:
\begin{verbatim}
--user member1:xxxxxxx
\end{verbatim}

The next step is to specify the name of the hosts. To do that, you
must define the variable \texttt{BUILD\_HOSTS} in the file {\tt
  .autocgalrc}. For every host $h$ listed in \texttt{BUILD\_HOSTS} you
must also specify the variable \texttt{COMPILERS\_$h$} as a list of
OS-compiler descriptors for which the testsuite is to be run on $h$.

Optionally, you can also specify a variable \texttt{BUILD\_ON\_$h$} as
a list of OS-compiler descriptors for which the \cgal\ libraries are
to be built on $h$. If \texttt{BUILD\_ON\_$h$} is not defined, it
defaults to the value of \texttt{COMPILERS\_$h$}. For obvious reasons,
it is a good idea to keep the compilers in \texttt{COMPILERS\_$h$} a
subset of the compilers listed in \texttt{BUILD\_ON\_$h$}. Setting
\texttt{BUILD\_ON\_$h$} to \texttt{all}, invokes the install script
with \texttt{--rebuild-all} and, therefore, builds \cgal\ using all
compilers for which a matching \texttt{config/install} file is found.

\noindent Here is an example:
\begingroup\small
\begin{verbatim}
BUILD_HOSTS="papillon electra winmachine localhost"
COMPILERS_papillon="mips_IRIX64-6.5_CC-n32-7.30 mips_IRIX-6.5_g++-fsquangle-2.95.2"
COMPILERS_electra="sparc_SunOS-5.6_g++-2.95.2"
BUILD_ON_electra="sparc_SunOS-5.6_g++-2.95.2 sparc_SunOS-5.6_CC-5.80"
COMPILERS_winmachine="i686_CYGWINNT-5.0-1.3.22_CL.EXE-1300"
COMPILERS_localhost="i686_Linux-2.4.17_g++-3.4.0"
PROCESSORS_papillon="3" 
BUILD_ON_papillon="all"
\end{verbatim}\endgroup
You should take those names from the configuration files mentioned
earlier. The {\tt PROCESSORS\_hostname} must be set if you have more
than one processor on that host and of course if you want to give all
of them to the testsuite. If you want to run the testsuite locally and
not remotely, name the host as {\tt localhost} and the script will run
the testsuite locally for that host.

\paragraph{List of configurable variables} ~

{\tt MYSHELL} is a variable that must be defined in {\tt .autocgalrc},
otherwise the script will not run.  You can use it to pass environment
variables along to remote hosts.  Here is an example of {\tt MYSHELL}
variable :
\begin{verbatim}
MYSHELL="TERM=vt100 PATH=$PATH:/bin:/usr/local/bin:/usr/ccs/bin:/opt/SUNWspro/bin \
QTDIR=/usr/local/qt2 PARASOFT=/usr/local/parasoft /usr/local/bin/zsh -c\"
\end{verbatim}

{\tt CGAL\_URL} is the URL where internal releases are available.
The {\tt LATEST} file is comming from the same location. If this will change,
you may change either {\tt CGAL\_URL}, or {\tt LATEST\_LOCATION}
in {\tt .autocgalrc}.

{\tt TAR}, {\tt GZIP}, {\tt GUNZIP} are the variables for compression and
decompression tools.  They are defaulted to {\tt tar}, {\tt gzip}, {\tt
gunzip} found in {\tt \$PATH}.

{\tt SENDMAIL} has the default value {\tt ''mail''}.

{\tt CGAL\_TESTER} has the default value {\tt `whoami`}.  It is used to
identify the tester.  You should specify a kind of login name for this
variable.

{\tt CGAL\_TESTER\_NAME} has the default value {\tt `whoami`}.  It is used to
identify the tester.  You should specify your full name for this variable.

{\tt CGAL\_TESTER\_ADDRESS} has the default value {\tt `whoami`}.  It is used
to identify the tester.  You should specify your email address for this
variable.

{\tt MAIL\_ADDRESS} has no value by default. In case you want to
set it in {\tt .autocgalrc}, the script will send an additional email to
everyone mentioned in this variable.

{\tt LOGS\_DIR} has the default value {\tt \$CGAL\_ROOT/AUTOTEST\_LOGS}.  This
is used to keep local log files.

{\tt CONSOLE\_OUTPUT} has the default value ``y''. If you want that the script
 also shows messages to the console, the value is ``y'' otherwise the value
should be ``''.

{\tt TEST\_DIR\_ROOT} specifies where the test-suite will be copied before
being run.  For example, this can be set to \ccc{/tmp}, instead of the default
which is {\tt \$CGAL}.  This directory can be local to the testing machine.

{\tt USE\_CURL} specifies if {\tt curl} should be used as a replacement for
{\tt wget} and {\tt ftp}.  Set it to {\tt ''y''} to use {\tt curl}.

{\tt FTP\_OPTS} specifies the options for {\tt ftp}   On Linux systems 
it should be {\tt ''-p -v -n''} (the default), on cygwin it should be {\tt ''-v -n''}.

{\tt NICE\_OPTIONS} specifies the command line options to pass to the
{\tt nice} command, which is used to prevent the test-suite from keeping
all CPU time for itself.  The default value is {\tt ''-19''}.

{\tt ULIMIT\_OPTIONS} specifies the command line options to pass to the
{\tt ulimit} command, which is used to prevent the test-suite from using
various system ressources.  It can be used to help killing looping programs.
For example, specifying {\tt ''-c 0 -t 10800 -v 2000000''} will prevent
the creation of dumped core files, will stop processes after 3 hours,
and will kill them if they reach 2GB of memory.
The default value is empty (no limit).

\index{.autocgalrc configuration file@{\tt .autocgalrc} configuration file|)}
\index{autotest_cgal script@{\tt autotest\_cgal} script|)}

\section{{\tt autotest\_cgal\_with\_cmake}}
\label{sec:autotest_cgal_with_cmake}
\index{autotest_cgal_with_cmake script@{\tt autotest\_cgal\_with\_cmake} script|(}
\ccIndexSubitem{test suite}{internal release}

The shell script {\tt autotest\_cgal\_with\_cmake} is used to run automated test suites for
the internal releases of the library. The script need no command-line
arguments, and it is configurable using a {\tt .autocgalrc} file stored
in {\tt \$HOME}.
It is meant to be run regularly by a cron job run by the testers.

This script allows you to run the testsuite on multiple hosts (remotely or
locally) and multiple compilers/platforms. It is also possible to specify how
many processors the host has and the script will use this information to run
the testsuite process on several processors at the same time. By default, the
number of processors assigned to every host is one.

In a couple of words, the script first downloads a file named {\tt LATEST}
that contains the current release file name. It compares it with the file {\tt
RELEASE\_NR} in the {\tt \$CGAL\_ROOT} directory and if it is different it
starts the testsuite process : it downloads the internal release, unzips,
untars, copies the configuration files, and starts the testsuite. When
everything is done, it puts the results on some ftp server.

\paragraph{How to set up your local testing} ~

The first step is to create a directory where you will store the releases.
This directory is known in the script as {\tt \$CGAL\_ROOT}. By default
{\tt \$CGAL\_ROOT} is the directory where you put the script {\tt
autotest\_cgal\_with\_cmake}, but you may change it in {\tt .autocgalrc}.

The next step is to download an internal release of your choice, say {\tt
CGAL-3.1-I-xx}, and unzip then untar it under {\tt \$CGAL\_ROOT}.
This release will serve as a {\em fixed reference release} for configuring
and building each current release to test from now on.

This internal release is used as a reference
which defines the configurations to test (it is not itself tested), 
thus is better to rename it accordingly, say as {\tt CGAL-I-REF}.

The next step is to create a new directory for each wanted configuration 
(architecture+platform+compiler)
to test under the directory {\tt \$CGAL\_ROOT/CGAL-I-REF/cmake/platforms}.
Each directory in there, called {\em configuration folder}, will contain the testsuite 
for that configuration and its name will identify the configuration 
in the test results.

Now cd into each such configuration folder and configure \cgal\ using cmake
(either the command line or the GUI). With the command-line cmake,
use the -D option to define cmake variables and -G
to define a generator if the default is not right for you.


The cmake variables {\tt WITH\_CGALCORE, WITH\_CGALimageIO, WITH\_CGALPDB and WITH\_CGALQt}
are used to enable or disable those \cgal\ components. These are all ON by default.
You should you define them with OFF if any of those components do not work in your platform. 
For {\tt these and only these} cmake variables you can define them as environment variables
rather than cmake variables.

The cmake variable {\tt CMAKE\_BUILD\_TYPE} is used to specify a {\tt 'Debug'} or {\tt 'Release'}
configuration. For the testsuite, you should always define this variable
since the default varies on different generators (and use only Debug or Release
since other values are not currently supported)

CMake itself takes care automatically of most compiler and linker flags
via the following cmake variables:

\begin{verbatim}
CMAKE_CXX_FLAGS
CMAKE_CXX_FLAGS_RELEASE
CMAKE_CXX_FLAGS_DEBUG
CMAKE_EXE_LINKER_FLAGS
CMAKE_EXE_LINKER_FLAGS_RELEASE
CMAKE_EXE_LINKER_FLAGS_DEBUG
\end{verbatim}

The \_RELEASE and \_DEBUG variables are {\em appended} to the general variable, so for each
build type, two sets of flags are used. For example: CMAKE\_CXX\_FLAGS {\em then} CMAKE\_CXX\_FLAGS\_DEBUG 

You can define any of these variables on the command-line (with the -D switch) or the GUI (CMakeSetup|ccmake),
but doing so {\em overrides} the values that cmake would automatically compute.

If you just want to {\em add} flags, you can define any of the following variables instead:

\begin{verbatim}
CGAL_CXX_FLAGS
CGAL_CXX_FLAGS_RELEASE
CGAL_CXX_FLAGS_DEBUG
CGAL_EXE_LINKER_FLAGS
CGAL_EXE_LINKER_FLAGS_RELEASE
CGAL_EXE_LINKER_FLAGS_DEBUG
\end{verbatim}

which are named with CGAL rather than CMAKE.

CMake has trouble parsing in the command line variable definitions that contain the '=' sign in the value, thus,
you cannot add a flag like: {\tt -DCGAL\_CXX\_FLAGS\_RELEASE='-std=c++0x'} . On the other hand, cmake uses
the {\em environment} variable CXXFLAGS to initialize CMAKE\_CXX\_FLAGS, so you can use that in this case.

The cmake variable {\tt CMAKE\_CXX\_COMPILER} can be used to specify the full path of the C++ compiler to use.
Unlike most cmake variables, this one is handled specially by cmake, thus, while manually defining it
works fine when building the reference release for the testsuite, its value is not propagated
to the releases being tested (recall that at this point we are manually building the reference release
which the testsuite uses to automatically build and test the others). Therefore, if you need
to specify the compiler (because cmake autodetects the wrong one), you need to define the
{\em environment} variable CXX.


The following example illustrates how to configure and build the reference release.
Notice the ../../.. path to the \cgal\ sources from the platform directory (where cmake is invoked).

\begin{verbatim}
export CXX=<some compiler not detected by cmake>
export CXXFLAGS='-std=c++0x'
export WITH_CGALimageIO=OFF 

cmake -DWITH_CGALPDB=OFF -DCMAKE_BUILD_TYPE=Release ../../..

make
\end{verbatim}

You can create here a shell script {\em specifically} named {\tt 'setup'} in case you need the test script
to automatically do anything for this particular configuration, such as setting up 
environment variables as in the example above. The contents of such a file, if it exists, are copied verbatim 
into the start of the temporary build and test scripts created on each configuration folder. This allows
you to bootstrap the process as needed.

Make sure to fix any problems configuring or building this reference release before starting the automated testsuite.

Once the reference release is ready, define a variable named
{\tt REFERENCE\_PLATFORMS\_DIR} with the full path to the {\tt /cmake/platforms/}
directory of the reference release, for example:
{\tt \$CGAL\_ROOT/CGAL-I-REF/cmake/platforms}
in the file {\tt .autocgalrc}.

The next step is to specify the name of the hosts. To do that, you
must define the variable \texttt{BUILD\_HOSTS} in {\tt .autocgalrc}. 

For every host $h$ listed in \texttt{BUILD\_HOSTS} you
must also specify the variable \texttt{BUILD\_ON\_$h$} as a list of
configuration names for which the \cgal\ libraries are
to be built on $h$. For each name listed in here, the testsuite script 
will create a directory under the current platforms directory
(i.e. {\tt \$CGAL\_ROOT/CGAL-3.1-I-abc/cmake/platforms} ), unless it already exists.

If any of the variables \texttt{BUILD\_ON\_$h$}
has the value 'all' then the platforms directory structure of the reference
release ({\tt \$REFERENCE\_PLATFORMS\_DIR}) is replicated
under the current platforms directory. \footnote{This 'all' value should only be used when
 the testsuite is run on a single localhost, otherwise, the testsuite script won't be able to
properly distribute each platform folder to its corresponding host.}

Similarly, for every host $h$ listed in \texttt{BUILD\_HOSTS} you
must also specify the variable \texttt{COMPILERS\_$h$} as a list of
configuration names for which the testsuite is to be run on $h$
(this must be a subset of the names specified in \texttt{BUILD\_ON\_$h$}).
You can specify only \texttt{COMPILERS\_$h$} instead of both \texttt{BUILD\_ON\_$h$}
and \texttt{COMPILERS\_$h$} if they share the same value.

\noindent Here is an example setting in {\tt .autocgalrc}:

\begingroup\small
\begin{verbatim}
REFERENCE_PLATFORMS_DIR="~/CGAL_autotest/CGAL-I-REF/cmake/platforms"
BUILD_HOSTS="papillon electra winmachine localhost"
COMPILERS_papillon="mips_IRIX64-6.5_CC-n32-7.30 mips_IRIX-6.5_g++-fsquangle-2.95.2"
COMPILERS_electra="sparc_SunOS-5.6_g++-2.95.2"
BUILD_ON_electra="sparc_SunOS-5.6_g++-2.95.2 sparc_SunOS-5.6_CC-5.80"
COMPILERS_winmachine="i686_CYGWINNT-5.0-1.3.22_CL.EXE-1300"
COMPILERS_localhost="i686_Linux-2.4.17_g++-3.4.0"
PROCESSORS_papillon="3" 
\end{verbatim}\endgroup

The {\tt PROCESSORS\_hostname} must be set if you have more
than one processor on that host and of course if you want to give all
of them to the testsuite. If you want to run the testsuite locally and
not remotely, name the host as {\tt localhost} and the script will run
the testsuite locally for that host.

The script copies the entire {\tt /test } subdirectory of the release being tested
into each configuration folder to test at, thus, all executables, temporaries
and results are local to that configuration. When the scripts finishes testing 
a configuration, the local {\tt /test } subdirectory is deleted.

The script uses {\tt wget} to download the release to test. The different options you
may pass to {\tt wget} you should put in the {\tt WGET} variable in {\tt
.autocgalrc}. By default, {\tt WGET=''wget''}. We noticed that you must use
a recent version of {\tt wget} (1.9.1 is fine, but 1.8.2 is not). You must
also create a file in your {\tt HOME} called {\tt .wgetrc} (alternatively,
it is also possible to use another file by setting the {\tt WGETRC} variable),
that contains the following lines:
\begin{verbatim}
--http-user=member1
--http-passwd=xxxxxxx
\end{verbatim}

Alternatively, you can use {\tt curl} instead of {\tt wget}.  In order to
do so, you need to add {\tt USE\_CURL=''y''} to your {\tt .autocgalrc} file.
{\tt curl} is then also used as a replacement for {\tt ftp} for uploading the
test results.
You also have to add the following line in a file called {\tt HOME/.curlrc}:
\begin{verbatim}
--user member1:xxxxxxx
\end{verbatim}

Once the latest release has been downloaded, unzipped and untared, 
say under {\tt \$CGAL\_ROOT/CGAL-3.4-I-abc}, the testsuites creates
a symbolic link to it named {\tt \$CGAL\_ROOT/CGAL-I}. From now on,
the release being tested is located under {\tt CGAL-I}.

For each directory under {\tt \$CGAL\_ROOT/CGAL-I/cmake/platforms}, 
if a directory of the name name exist in the reference release 
(i.e. under {\tt \$CGAL\_ROOT/CGAL-I-REF/cmake/platforms}),
the files {\tt CMakeCache.txt} and {\tt setup} are copied
from the reference release (if they exist). 

\paragraph{Command line options for the initial set up} ~

{\tt autotest\_cgal\_with\_cmake} is meant to be run unattended by a cron job. 
However, in order to simplify the initial set up some command line options are available:

\begin{itemize}
   \item {\tt -c} Uses an already untared internal release under the
                  symbolic link {\tt 'CGAL-I'} instead of
                  downloading and untaring a new one. You can use this option
                  to {\em resume} immediately the test suite process in case it
                  failed before.

   \item {\tt -n} Skips the testing phase, finishing after the libraries has been built.
                  You can use this option to verify that the mechanism that uses the
                  reference release to build the current release with the exact same
                  settings works fine.

   \item {\tt -l} Do not upload the results to the server.
                  You can use this option to avoid uploading incomplete results until
                  the testsuite process works correctly in your system.
\end{itemize}

\paragraph{List of miscellaneous configurable variables} ~

{\tt MYSHELL} is a variable that may be defined in {\tt .autocgalrc}
to pass environment variables along to remote hosts. Here is an example of {\tt MYSHELL}
variable :
\begin{verbatim}
MYSHELL="TERM=vt100 PATH=$PATH:/bin:/usr/local/bin:/usr/ccs/bin:/opt/SUNWspro/bin \
QTDIR=/usr/local/qt2 PARASOFT=/usr/local/parasoft /usr/local/bin/zsh -c\"
\end{verbatim}

{\tt CGAL\_URL} is the URL where internal releases are available.
The {\tt LATEST} file is comming from the same location. If this will change,
you may change either {\tt CGAL\_URL}, or {\tt LATEST\_LOCATION}
in {\tt .autocgalrc}.

{\tt TAR}, {\tt GZIP}, {\tt GUNZIP} are the variables for compression and
decompression tools.  They are defaulted to {\tt tar}, {\tt gzip}, {\tt
gunzip} found in {\tt \$PATH}.

{\tt SENDMAIL} has the default value {\tt ''mail''}.

{\tt CGAL\_TESTER} has the default value {\tt `whoami`}.  It is used to
identify the tester.  You should specify a kind of login name for this
variable.

{\tt CGAL\_TESTER\_NAME} has the default value {\tt `whoami`}.  It is used to
identify the tester.  You should specify your full name for this variable.

{\tt CGAL\_TESTER\_ADDRESS} has the default value {\tt `whoami`}.  It is used
to identify the tester.  You should specify your email address for this
variable.

{\tt MAIL\_ADDRESS} has no value by default. In case you want to
set it in {\tt .autocgalrc}, the script will send an additional email to
everyone mentioned in this variable.

{\tt LOGS\_DIR} has the default value {\tt \$CGAL\_ROOT/AUTOTEST\_LOGS}.  This
is used to keep local log files.

{\tt CONSOLE\_OUTPUT} has the default value ``y''. If you want that the script
 also shows messages to the console, the value is ``y'' otherwise the value
should be ``''.

{\tt USE\_CURL} specifies if {\tt curl} should be used as a replacement for
{\tt wget} and {\tt ftp}.  Set it to {\tt ''y''} to use {\tt curl}.

{\tt FTP\_OPTS} specifies the options for {\tt ftp}   On Linux systems 
it should be {\tt ''-p -v -n''} (the default), on cygwin it should be {\tt ''-v -n''}.

{\tt NICE\_OPTIONS} specifies the command line options to pass to the
{\tt nice} command, which is used to prevent the test-suite from keeping
all CPU time for itself.  The default value is {\tt ''-19''}.

{\tt ULIMIT\_OPTIONS} specifies the command line options to pass to the
{\tt ulimit} command, which is used to prevent the test-suite from using
various system ressources.  It can be used to help killing looping programs.
For example, specifying {\tt ''-c 0 -t 10800 -v 2000000''} will prevent
the creation of dumped core files, will stop processes after 3 hours,
and will kill them if they reach 2GB of memory.
The default value is empty (no limit).

\paragraph{Testing with Visual Studio on cygwin} ~

In order to test with Visual Studio you need to use cygwin and set up
the environment for the command line compiler. This can be done
by setting up the VC command line tools in the {\tt 'setup'} script
that is used to bootstrap the build and test process, as explained before.
Merely executing the {\tt 'vcvars32.bat'} that comes with VC does not work 
since the variables in there will be defined only in the environment for the batch 
file and not in the environment of the building/testing script (this is why
the contents of the 'setup' script are copied into the build/test script 
instead of 'setup' being just executed from there)

Furthermore, within the {\tt 'setup'} script, the following must be
considered: 

The variables {\tt INCLUDE, LIB and LIBPATH} will be used by the Visual C++ compiler
{\em directly}, that is, without the path translation that cygwin usually performs.
Thus, the values for these variables must be a verbatim copy of the values defined in
the {\tt 'vcvars32.bat'} of your Visual Studio installation.

On the other hand, the {\tt PATH} variable will be used by cygwin itself to locate the
components of the command line tools (cl.exe, link.exe, etc.), thus, each Windows
path specified in the PATH definition on {\tt 'vcvars32.bat'} must be converted to a
POSIX path and properly appended to the cygwin PATH variable.

Below is a sample 'setup' script for Visual C++ 9.0:

\begin{verbatim}
export INCLUDE='C:\Program Files\Microsoft Visual Studio 9.0\VC\ATLMFC\INCLUDE;C:\Program Files\Microsoft Visual Studio 9.0\VC\INCLUDE;C:\Program Files\Microsoft Visual Studio 8\VC\PlatformSDK\include;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\include;c:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\include\'

export LIB='C:\Program Files\Microsoft Visual Studio 9.0\VC\ATLMFC\LIB;C:\Program Files\Microsoft Visual Studio 9.0\VC\LIB;C:\Program Files\Microsoft Visual Studio 8\VC\PlatformSDK\lib;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib;c:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Lib\'

export LIBPATH='C:\Program Files\Microsoft Visual Studio 9.0\VC\ATLMFC\LIB;C:\Program Files\Microsoft Visual Studio 9.0\VC\LIB'

export PATH='/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/Common7/IDE':'/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/VC/BIN':'/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/Common7/Tools':'/cygdrive/c
/Program Files/Microsoft Visual Studio 9.0/Common7/Tools/bin':'/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/VC/VCPackages':'/cygdrive/c/Program Files/Microsoft Visual Studio 8/VC/PlatformSDK/bin':'/cygdrive/c/Program Files/Microsoft Visual Studio 8/SDK/v2.0/bin':$PATH

\end{verbatim}


\index{.autocgalrc configuration file@{\tt .autocgalrc} configuration file|)}
\index{autotest_cgal_with_cmake script@{\tt autotest\_cgal\_with\_cmake} script|)}

\section{{\tt check\_licenses}}
\label{sec:check_licenses}
\index{check_licenses script@{\tt check\_licenses} script|(}

This script can be used to check all files in an internal or external release
for proper license notices. It reports all files without a proper notice.
Observe that the check is fairly simple, we just grep through the files
looking for a fixed string. Additionally, there might be provisions in the
top-level LICENSE file that are not taken into account by this script.

Note that there might be license errors that are not detected by this script.
For example, we do not check that files under LGPL and QPL are not mixed in
one library.

\ccIndexMainItemEnd{tools}
