% =============================================================================
% 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/cvsweb.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/cvsweb.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/cvsweb.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/cvsweb.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/cvsweb.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/cvsweb.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/cvsweb.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.

\section{{\tt cgal\_submit}}
\label{sec:cgal_submit}
\index{cgal_submit script@{\tt cgal\_submit} script|(}
\ccIndexSubitem{packages}{submitting}
\ccIndexSubitem{submitting}{script for}

The shell script \ccAnchor{http://cgal.inria.fr/cgi-bin/cvsweb.cgi/CGAL/Packages/Scripts/developer_scripts/cgal_submit}{\texttt{cgal\_submit}} is used to 
submit packages from the
CVS server.  The script should be run from the working directory of the
package being submitted and takes a single argument, which is the new
version number of the package.  For example:
\begin{verbatim}
   cgal_submit 3.2.1
\end{verbatim}
The script will tag the files of a module
with a tag \texttt{v}$<num>$, where $<num>$ is the version number given
as an argument to the script (3.2.1 in the example above) with all `.'s 
replaced by `\_'s (so \texttt{v3\_2\_1} for the example above).  The files are
also labeled with the tag \texttt{current\_submission}.  The script is 
available in the \texttt{developers\_scripts} directory of each internal 
release.
\index{cgal_submit script@{\tt cgal\_submit} script|)}
 
\section{{\tt autotest\_cgal}}
\label{sec:autotest_cgal}
\index{autotest_cgal script@{\tt autotest\_cgal} script|(}
\ccIndexSubitem{test suite}{internal release}

This shell script \ccAnchor{http://www.cs.inf.ethz.ch/personal/hoffmann/CGAL/mem
bers/autotest_cgal}{{\tt autotest\_cgal}}
is used to run test suites for the internal releases of the library
``automagically''.  The script takes two arguments, which are a
\cgal\ release label (Section~\ref{sec:file_header}) and an email
address of someone to notify about the success or failure of the test suite
run.  For example:
\begin{verbatim}
   autotest_cgal CGAL-2.2-I-3 cgal-submit@cs.uu.nl
\end{verbatim}

The script must be
\ccAnchor{http://www.cs.inf.ethz.ch/personal/hoffmann/CGAL/members/autotest.html
}{customized}
\begin{ccTexOnly}
 (See \path|http://www.cs.inf.ethz/ch/personal/hoffmann/CGAL/members/autotest.html|)
\end{ccTexOnly}
a bit to run on your environment, but
after this it works almost like magic! 
When run, the script will download the indicated internal release of
the library, unpack it, configure things and create the proper makefiles,
build the library, run the test, collect the results and then send mail
notifying the proper authorities ({\em i.e.}, {\tt cgal-submit@cs.uu.nl})
that the test results are available.  
\index{autotest_cgal script@{\tt autotest\_cgal} 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|)}
\ccIndexMainItemEnd{tools}