mirror of https://github.com/CGAL/cgal
817 lines
39 KiB
TeX
817 lines
39 KiB
TeX
% =============================================================================
|
|
% 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}
|