mirror of https://github.com/CGAL/cgal
184 lines
8.6 KiB
TeX
184 lines
8.6 KiB
TeX
% =============================================================================
|
|
% The CGAL Developers' Manual
|
|
% Chapter: Tools
|
|
% -----------------------------------------------------------------------------
|
|
% file : tools.tex
|
|
% authors: Geert-Jan Giezeman <geert@cs.uu.nl>
|
|
% -----------------------------------------------------------------------------
|
|
% $Revision$
|
|
% $Date$
|
|
% =============================================================================
|
|
|
|
\chapter{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 automatize some of the tedious and
|
|
error-prone tasks that are unavoidable when developing for \cgal.
|
|
These scripts can be found in several places.
|
|
\begin{itemize}
|
|
\item in every internal release (directory {\tt developer\_scripts} or
|
|
{\tt scripts})
|
|
\item in the package Scripts on the %
|
|
\ccAnchor{http://www.cs.uu.nl/CGAL/Members/Develop/updates/packages.html}{packages page}\begin{ccTexOnly}
|
|
( \path|http://www.cs.uu.nl/CGAL/Members/Develop/updates/packages.html|)
|
|
\end{ccTexOnly}
|
|
\item on the \ccAnchor{http://www.cs.uu.nl/CGAL/Members/Develop/tools/index.html}{scripts page} \begin{ccTexOnly}
|
|
(\path|http://www.cs.uu.nl/CGAL/Members/Develop/tools/index.html|)
|
|
\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://www.cs.uu.nl/CGAL/Members/Develop/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://www.cs.uu.nl/CGAL/Members/Develop/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{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://www.cs.uu.nl/CGAL/Members/Develop/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://www.cs.uu.nl/CGAL/Members/Develop/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|)}
|
|
\ccIndexMainItemEnd{tools}
|