cgal/Packages/Developers_manual/tools.tex

% =============================================================================
% The CGAL Developers' Manual
% Chapter: Tools
% -----------------------------------------------------------------------------
% file   : tools.tex
% authors: Geert-Jan Giezeman <geert@cs.uu.nl>
% -----------------------------------------------------------------------------
% $Revision$
% $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{http://cgal.inria.fr/cgi-bin/viewcvs.cgi/CGAL/Packages/Scripts/}{Scripts} on the CVS server%
         \index{CVS server!Scripts package@\texttt{Scripts} package}%
         \begin{ccTexOnly}
        (\path|http://cgal.inria.fr/cgi-bin/viewcvs.cgi/CGAL/Packages/Scripts/|) 
         \end{ccTexOnly}.
\end{itemize}

\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{http://cgal.inria.fr/cgi-bin/viewcvs.cgi/CGAL/Packages/Scripts/developer_scripts/create_assertions.sh}{{\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 remove\_line\_directives}}
\label{sec:remove_line_directives}
\index{remove_line_directives script@{\tt remove\_line\_directives} script}
\ccIndexSubitem{line pragmas}{removing}

\cgal\ source files should not contain line directives, even if they are made
with the help of a literate programming tool like funnelweb.
The script \ccAnchor{http://cgal.inria.fr/cgi-bin/viewcvs.cgi/CGAL/Packages/Scripts/developer_scripts/remove_line_directives}{{\tt remove\_line\_directives}} can be used to remove
lines starting with {\tt \#line}.

\section{{\tt rename\_clib\_calls}}
\label{sec:rename_clib_calls}
\index{rename_clib_calls script@{\tt rename\_clib\_calls} script|(}
\ccIndexSubitemBegin{namespace}{\ccFont std}

According to standard C++, when you include a header from the standard C
library in the modern way (so, \verb+#include <cmath>+ instead of
\verb+#include <math.h>+), the C functions should be in the namespace
{\ccFont std}.
Not all compilers conform to this.
That's why \cgal\ has a macro, CGAL\_CLIB\_STD,%
\index{cgal_clib_std macro@{\tt CGAL\_CLIB\_STD} macro}
that is set to {\ccFont std} (for
a conforming compiler) or to the empty string (for a non-conforming
compiler). This macro should be prepended to all calls of functions from
the C library. So, you should call \ccc{CGAL_CLIB_STD::sin(x)}, not 
\ccc{std::sin(x)} or \ccc{sin(x)}.

The perl script \ccAnchor{http://cgal.inria.fr/cgi-bin/viewcvs.cgi/CGAL/Packages/Scripts/developer_scripts/rename_clib_calls}{{\tt rename\_clib\_calls}}
does this prepending.
The script is idempotent, so applying it twice in a row does no harm.
The script is not perfect, though. Especially, it recognizes complete
words, but it does not discriminate between a function call and a variable
or a word in a comment.
You should check the differences of the modified file with the original
file (which will be saved, with a {\tt .bak} extension), for example with 
{\tt diff} or {\tt xdiff}.

Before using this script, you should edit the first line. This line
states where your perl interpreter is located. The command {\tt which perl}
can help you to find out what to put there.
\ccIndexSubitemEnd{namespace}{\ccFont std}
\index{rename_clib_calls script@{\tt rename\_clib\_calls} script|)}

\section{{\tt create\_makefile}}
\label{sec:create_makefile}
\index{create_makefile script@{\tt create\_makefile} script|(}
\ccIndexSubitemBegin{\tt makefile}{creating}

The shell script \ccAnchor{http://cgal.inria.fr/cgi-bin/viewcvs.cgi/CGAL/Packages/Scripts/scripts/create_makefile}{{\tt create\_makefile}} creates a \cgal\ makefile
in the current working directory.
The makefile will have rules to make an executable from every {\tt .C} 
file 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 makefile for the test suite
\item[-w]   create a makefile with flags for LEDA windows
\item[-g]   create a makefile with flags for GEOWIN
\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{create_makefile script@{\tt create\_makefile} 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{http://cgal.inria.fr/cgi-bin/viewcvs.cgi/CGAL/Packages/Scripts/developer_scripts/create_cgal_test}{{\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.

%\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 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:
\begin{verbatim}
$ cat ~/.wgetrc 
--http-user=member1
--http-passwd=xxxxxxx
\end{verbatim}

The next step is to specify the name of the hosts. To do that, you must define
the variable {\tt \$BUILD\_HOSTS} in the file {\tt .autocgalrc}. For every
host that you define you must also specify the compiler-platform names on that
host.  Here is an example:
\begin{verbatim}
BUILD_HOSTS="papillon electra winmachine localhost"
COMPILERS_papillon="mips_IRIX64-6.5_CC-n32-7.30_LEDA mips_IRIX-6.5_g++-fsquangle-2.95.2_LEDA"
COMPILERS_electra="sparc_SunOS-5.6_g++-2.95.2_LEDA"
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}
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:$HOME/bin/SunOS:/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`}.

{\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 ``''.

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


\ccIndexMainItemEnd{tools}