songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

removing old stuff that was commented

This commit is contained in:
Monique Teillaud 2012-05-20 13:23:26 +00:00
parent 4c372fba67
commit 04d1c5f0b4
6 changed files with 1 additions and 1189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
Developers_manual/doc_tex/Developers_manual/addresses.tex
View File

@ -1,70 +0,0 @@
% =============================================================================
% The CGAL Developers' Manual
% Chapter: Mailing Lists and Addresses
% -----------------------------------------------------------------------------
% file : addresses.tex
% authors: Susan Hert <hert@mpi-sb.mpg.de>
% -----------------------------------------------------------------------------
% $Id$
% $Date$
% =============================================================================
\chapter{Mailing Lists and Addresses\label{chap:addresses}}
\ccChapterRelease{Chapter Version: 1.0}
\ccChapterAuthor{Susan Hert ({\tt hert@mpi-sb.mpg.de})}
\ccIndexMainItemBegin{email addresses}
\ccIndexMainItemBegin{mailing lists}
There are a number of mailing lists and email addresses that have been set
up to communicate with various subsets of the \cgal\ community. The
addresses that should be of interest to \cgal\ developers are as follows.
The up-to-date addresses and archives can be found on the web site.
\begin{description}
\item[{\tt cgal-develop}]
\index{cgal_develop mailing list@{\tt cgal-develop} mailing list}
This list is intended for discussing detailed matters
about implementation and development issues. All developers should
subscribe to this list.
\item[\ccAnchor{mailto:cgal-commits@lists.gforge.inria.fr}{{\tt cgal-commits@lists.gforge.inria.fr}}]
\index{cgal-commits mailing list@{\tt cgal-commits} mailing list}
This list is read-only. It collects all automatic mails sent by
the SVN server, one per commit, with the log messages and the URLS
pointing to the corresponding diffs.
Developers can subscribe to this list from
\ccAnchor{https://gforge.inria.fr/mail/?group_id=52}{\cgal\ mailing lists page}.
An \ccAnchor{http://lists.gforge.inria.fr/cgi-bin/mailman/private/cgal-commits}{archive}
of this mailing list is maintained%
\begin{ccTexOnly}
at \nonlinkedpath|http://lists.gforge.inria.fr/cgi-bin/mailman/private/cgal-commits|
\end{ccTexOnly}. To enter this archive, use your email address and InriaGForge
password.
\item[{\tt cgal-discuss}]
\index{cgal-discuss mailing list@{\tt cgal-discuss} mailing list}
Users of \cgal\ post questions and discuss issues
related to \cgal\ on this list. All developers should subscribe to this
list so they can answer questions relevant to their packages and monitor
the input from the users provided here.
\item[{\tt cgal-announce}]
\index{cgal-announce mailing list@{\tt cgal-announce} mailing list}
Announcements of new releases, bug fixes, special courses, etc. are posted
to this list. The list is moderated (meaning every message posted needs
to be approved) to keep the traffic low.
\item[{\tt cgal-editorial-board}]
\index{cgal-editorial-board mailing list@{\tt cgal-editorial-board} mailing list}
This is the email address to which you should
send proposed design specifications (Chapter~\ref{chap:specification})
for approval by the editorial
board (Section~\ref{sec:editorial_board}). Anyone can do that
at any time about any \cgal\ design issues.
\end{description}
The mailing lists at \texttt{lists.gforge.inria.fr} and
\texttt{lists-sop.inria.fr} are currently maintained by
Sylvain Pion, Mariette Yvinec, Monique Teillaud.
\ccIndexMainItemEnd{email addresses}
\ccIndexMainItemEnd{mailing lists}

8
Developers_manual/doc_tex/Developers_manual/chapters.tex
View File

@ -17,7 +17,6 @@
\include{Developers_manual/intro}
\InternalOnly{
\include{Developers_manual/specification}
%\include{Developers_manual/directory_structure}
\include{Developers_manual/tools}
}
\include{Developers_manual/code_format}
@ -31,16 +30,9 @@
\include{Developers_manual/iterators_and_circulators}
\include{Developers_manual/robustness}
\include{Developers_manual/portability}
%\InternalOnly{
%\include{Developers_manual/testing}
%}
\include{Developers_manual/debugging}
%\InternalOnly{
%\include{Developers_manual/examples_and_demos}
%}
\include{Developers_manual/submission_process}
\InternalOnly{
\include{Developers_manual/releases}
%\include{Developers_manual/addresses}
}
\include{Developers_manual/information_sources}

436
Developers_manual/doc_tex/Developers_manual/directory_structure.tex
View File

@ -1,436 +0,0 @@
% =============================================================================
% The CGAL Developers' Manual
% Chapter: Directory Structure for Packages
% -----------------------------------------------------------------------------
% file : directory_structure.tex
% authors: Geert-Jan Giezeman <geert@cs.uu.nl> & Susan Hert <hert@mpi-sb.mpg.de>
% -----------------------------------------------------------------------------
% $Id$
% $Date$
% =============================================================================
\chapter{Directory Structure for Packages\label{chap:directory_structure}}
\ccIndexMainItemBegin{directory structure}
\ccIndexSubitemBegin{submitting}{directory structure for}
\ccChapterRelease{Chapter Version: 1.1}
\ccChapterAuthor{Geert-Jan Giezeman ({\tt geert@cs.uu.nl})\\
Susan Hert ({\tt hert@mpi-sb.mpg.de})\\
Sylvain Pion}
In order for code, demos, documentation, {\em etc.} developed for \cgal\ to
be included in an automated way into the internal (and public) releases of the
library, the files must be organized in a specific directory structure, which
we describe here. We describe the entire directory structure for a package.
Not every package will have all the parts described here. Only the files
{\tt maintainer} and {\tt description.txt}
are obligatory.
\index{maintainer file@{\tt maintainer} file}
\ccIndexMainItem{\tt description.txt}
Submissions should not contain files in other places than described here.
It is possible to have some under SVN, but they need to be listed in the
\ccc{dont_submit} file to avoid being submitted.
Make sure your package does not have any file clashing with any other packages
(for example two files named {\tt simple\_example.cpp} in the example directories of
two different packages will clash in the target names of cmake).
The directory structure of a package named Package should be as follows:
\begin{verbatim}
+--- dont_submit
|
+--- include/CGAL/
|
+--- src/{CGAL|CGALQt|...}/
|
+--- test/<testdir>/
|
+--- doc_tex/
|
+--- examples/<exampledir>/
|
+--- demo/<demodir>/
|
+--- benchmark/<benchmarkdir>/
|
+--- auxiliary/
|
+--- scripts/
|
+--- developer_scripts/
|
+--- package_info/Package/
|
+- description.txt
|
+- long_description.txt
|
+- maintainer
\end{verbatim}
\begin{description}
\item[{\tt include/CGAL}]\index{include/CGAL directory@{\tt include/CGAL} directory}
\index{source\ files!{\tt .h} files}
contains the {\tt .h} files for the package.
\item[{\tt src}]\index{src directory@{\tt src} directory}
\index{source\ files!{\tt .cpp} files}
contains the {\tt .cpp} files (if any) for the package.
They are gathered in subdirectories corresponding to each
library (be it static or shared).
\item[{\tt test}]\index{test directory@{\tt test} directory!for
packages} contains the test suite code for the package. See
Section~\ref{sec:test_subdirectory} for a detailed description.
\item[{\tt doc\_tex}]\index{doc_tex directory@{\tt doc\_tex} directory}
\ccIndexSubitem{source files}{documentation}
contains the documentation for the user and reference manuals.
These are the files used to produce the manuals for public releases and
to run the internal release reference manual test suite.
See Section~\ref{sec:doc_tex_subdirectory} for a detailed description
of this subdirectory.
See Chapter~\ref{chap:specification} for guidelines for producing
the documentation.
\item[{\tt examples}]\index{examples directory@{\tt examples} directory}
contains the example programs for the package.
See Section~\ref{sec:examples_subdirectory} for a detailed
description of this subdirectory.
\item[{\tt demo}]\index{demo directory@{\tt demo} directory}
contains the demo programs for the package.
Contrary to example programs, demo programs are not expected to be
usable on all platforms. Demo programs may depend on platform-specific
software and may require user interaction. They are compiled but not
run in the test suite. See Section~\ref{sec:demo_subdirectory} for a
more detailed description of this subdirectory.
\item[{\tt benchmark}]\index{benchmark directory@{\tt benchmark} directory}
contains the benchmark programs for the package.
See Section~\ref{sec:benchmark_subdirectory} for a detailed
description of this subdirectory.
\item[{\tt auxiliary}]\index{auxiliary directory@{\tt auxiliary}
directory} contains auxiliary software for CGAL. For
instance, GMP goes here when using the Windows installer.
The average package won't have this directory.
\item[{\tt scripts}]\index{scripts directory@{\tt scripts}
directory} contains scripts that are of interest to \cgal\ users.
\item[{\tt developer\_scripts}]\index{developers\_scripts
directory@{\tt developers\_scripts} directory} contains
scripts that are of interest to \cgal\ developers. This directory
is included in internal releases only, not in public releases.
\item[{\tt dont\_submit}]%
\ccIndexMainItem{\tt dont\_submit} specifies files and directories
that are to be excluded from the release, for example:
\begin{verse}
TODO\\
include/CGAL/my\_internal\_file.h\\
benchmark
\end{verse}
\item[{\tt package\_info/Package/description.txt}]%
\ccIndexMainItem{\tt description.txt}
should give a very short description of the contents of the package.
\item[{\tt long\_description.txt}]%
\ccIndexMainItem[c]{\tt package\_info/Package/long\_description.txt}
may be added with more detailed information about the package.
\item[\ccAnchor{maintainer}{{\tt package\_info/Package/maintainer}}]%
\index{maintainer file@{\tt maintainer} file}
should be used to name the maintainers of the package. The file should
have for each maintainer a line with the following format:
\begin{verse}
{\it name} $<${\it email address}$>$\\
\end{verse}
For example:
\begin{verse}
{\it Susan Hert} $<$hert@mpi-sb.mpg.de$>$\\
{\it Sylvain Pion} $<$Sylvain.Pion@sophia.inria.fr$>$\\
\end{verse}
\end{description}
A package has a name, which identifies it. This name should obey the same
rules as for C identifiers: it consists of letters, digits and underscores and
it does not start with a digit. Choose a name that is descriptive, yet not
too long (under 25 characters). If a package deals with objects of a
particular dimension, then use the suffixes \_2, \_3, and \_d, especially if
there exists (or may exist in the future) a package with similar
functionality in different dimensions. Examples of good package names are
\texttt{Triangulation\_2} for a package dealing with triangulations of points
in the plane and \texttt{Min\_ellipse\_2}, which contains an algorithm that
finds the minimal enclosing ellipse of a set of points in the plane. The
package names \texttt{pm} and \texttt{arr} are a bit too terse.
\texttt{Planar\_map} and \texttt{Arrangement} (or
\texttt{Arrangement\_2}) are better.
\section{{\tt test} subdirectory}
\label{sec:test_subdirectory}
\index{test directory@{\tt test} directory|(}
\ccIndexMainItemBegin{test suite}
This directory contains the test suite for the package. Here we just
briefly list the files contained in such a directory. For more
detailed information about testsuites for \cgal\ packages refer to
Chapter~\ref{chap:testing}.
\begin{verbatim}
test/<testdir>
+--- data/
|
+--- include/
|
|- CMakeLists.txt
|
|- cgal_test
|
|- *.cpp
|
|- *.cin
\end{verbatim}
where the directory \verb|<testdir>| has a name that corresponds to the package
name.
\begin{description}
\item[{\tt data/}] is a subdirectory that contains local data files for the
test suite\index{data directory@{\tt data} directory}.
\item[{\tt include/}] is a subdirectory that contains local include files for
the test suite.
\item[{\tt cgal\_test}]\index{cgal_test script@{\tt cgal\_test}
script|(} is the script that will be called when the entire
test suite is run. As this file is created automatically
during the release process, submitting it is error-prone and
thus {\bf strongly discouraged}.
For testing purposes, such a script can be created using the
{\tt create\_cgal\_test}%
\index{create_cgal_test script@{\tt create\_cgal\_test} script}
script (Section~\ref{sec:create_cgal_test}).
\index{cgal_test script@{\tt cgal\_test} script|)}
\item[{\tt CMakeLists.txt}]\ccIndexSubitem{\tt CMakeLists.txt}{test suite}
is the CMake configuration file for the test programs. It is created
automatically, just like {\tt cgal\_test}. Submitting it is
{\bf strongly discouraged}, and the only reason for submitting one is
when the automatic generation script cannot produce a working CMake
configuration file.
Such a {\tt CMakeLists.txt} can be created using the script
{\tt cgal\_create\_cmake\_script}%
\index{cgal_create_cmake_script script@{\tt cgal\_create\_cmake\_script} script}
with the argument {\tt -t}
(Section~\ref{sec:cgal_create_cmake_script}).
\item[{\tt *.cpp}] source code for the test programs.
\ccIndexSubitem{source files}{test suite}
When a test program runs correctly, it should return
\ccIndexSubsubitem{test suite}{program}{return value} the
value zero, or, more precisely, the value \verb|EXIT_SUCCESS|
defined in \verb|<cstdlib>|.
Test programs may not be graphical and they may not require any user
interaction.\ccIndexSubitem{test suite}{program}
\item[{\tt *.cin}] files containing command-line input for
\index{test\ suite!input!from {\tt cin}}
test programs. These files are necessary for only those programs
that require command-line input (which can usually be avoided).
If a file \texttt{program.cin} is
present in the test directory, then, when the test suite is run,
\texttt{program} will be executed using the command
\begin{verbatim}
./program < program.cin
\end{verbatim}
\end{description}
\section{{\tt doc\_tex} subdirectory}
\label{sec:doc_tex_subdirectory}
\index{doc_tex directory@{\tt doc\_tex} directory|(}
\ccIndexSubitemBegin{manuals}{source files}
\ccIndexSubitemBegin{source files}{documentation}
As described in Chapter~\ref{chap:specification}, the \cgal\ documentation is
organized in subdirectories for each package and the different manuals
are assembled from these packages. Contained in these
subdirectories are the files required for producing a package's contributions
to the different reference and users' manuals. The users' manual input
files are located in the package's directory; the reference manual files are
be located in a directory named $<Package>${\tt \_ref}
\index{ref directory@{\tt \_ref} directory}.
For both the users' manual and reference manual parts, the input can be
split into more than one file (In fact, this is necessary for the reference
manual in order to support conversion to HTML;
see Section~\ref{sec:ref_manual}.), but there must be a file called
{\tt main.tex} in both the user and reference manual directories that inputs
all the other files for that manual part.
({\bf Note}: You should use the \verb|\input| command and NOT the
\verb|\include| command to input other source files in this file, and
they have to include their files using relative paths starting in the
\texttt{doc\_tex} directory.)
For example, the optimisation package of
the basic library can have the following documentation.
\begin{verbatim}
doc_tex/Optimisation
|--- main.tex
|
|--- *.tex
|
+--- *.((pdf)|(gif)|(jpg)|(png))
doc_tex/Optimisation_ref/
|--- main.tex
|
|--- intro.tex
|
|--- *.tex
|
+--- *.((pdf)|(gif)|(jpg)|(png))
\end{verbatim}
\begin{description}
\item[{\tt main.tex}]%
\ccIndexMainItem{\tt main.tex}\ccIndexSubitem{users' manual}{\tt
main.tex} must contain one chapter. It must NOT
contain a preamble (so no {\tt documentclass}, {\tt usepackage},
\verb|\begin{document}| or \verb|\end{document}| commands).
If you want more than one chapter in the documentation of this
package you have to put each chapter in its own \LaTeX\ file,
and include those files in \texttt{main.tex} using the \verb|\input|
macro.
\item[{\tt intro.tex}]%
\ccIndexMainItem{\tt intro.tex}%
\ccIndexSubitem{reference manual}{\tt intro.tex}
is not mandatory but common for reference manual chapter. It
contains a brief introduction to the package (one paragraph) and
lists the different concepts, classes, functions, etc. that are
contained in this package in a systematic way.
\item[{\tt *.tex}] -- the source files for the Users' and Reference
Manual that are input by {\tt main.tex}
\item[{\tt *.pdf}] -- the PDF pictures included in
the PDF documentation.
\item[{\tt *.((gif)|(jpg)|(png))}] -- the raster images included in
the HTML documentation.
\end{description}
\ccIndexSubitemEnd{source files}{documentation}
\ccIndexSubitemEnd{manuals}{source files}
\index{doc_tex directory@{\tt doc\_tex} directory|)}
\section{{\tt examples} subdirectory}
\label{sec:examples_subdirectory}
\index{examples directory@{\tt examples} directory|(}
\ccIndexSubitemBegin{example programs}{submitting}
Example programs (Chapter~\ref{chap:examples_and_demos}) for a package should
be placed in a subdirectory of the directory {\tt examples}.
The subdirectory name, \verb|<exampledir>|, will usually correspond to the
package name, but this is not a requirement.
To make sure that the examples will be tested%
\ccIndexSubitem{test suite}{examples in},
a directory with examples
should be submitted in exactly the same way as a test directory
(Section~\ref{sec:test_subdirectory}).
The structure of an example directory should be as follows:
\begin{verbatim}
examples/<exampledir>
+--- data/
|
+--- include/
|
|- README
|
|- cgal_test
|
|- CMakeLists.txt
|
|- *.cpp
\end{verbatim}
\ccIndexSubitem{source files}{examples}
The file {\tt README} should contain information about what the programs do
and how to compile them.
See the rules for a test directory for an explanation of the other files
and subdirectories.
\ccIndexSubitemEnd{example programs}{submitting}
\index{examples directory@{\tt examples} directory|)}
\section{{\tt demo} subdirectory}
\label{sec:demo_subdirectory}
\index{demo directory@{\tt demo} directory|(}
\ccIndexMainItem{demo programs}
\ccIndexSubitemBegin{demo programs}{submitting}
The {\tt demo} directory (Chapter~\ref{chap:examples_and_demos}) contains
programs with graphical interfaces or programs requiring user input. These
programs will be compiled but not run by the test suite.
\ccIndexSubitem{test suite}{demos in}
The structure of this directory should be as follows:
\begin{verbatim}
demo/<demodir>
+--- data/
|
+--- include/
|
|- README
|
|- CMakeLists.txt
|
|- *.cpp
\end{verbatim}
where \verb|<demodir>| is a name that corresponds (at least in part) to
the package for which it is a demo.
\ccIndexSubitem{source files}{demos}
The file {\tt README} should contain information about what the program does,
and how to compile it ({\it i.e.}, what graphical libraries are needed,
{\it etc.}). Note that, in contrast to example and test programs,
demo programs more often need to submit a {\tt CMakeLists.txt}
\ccIndexSubitem{\tt CMakeLists.txt}{demo programs} since
different demos will require different libraries and thus the {\tt CMakeLists.txt}
for these programs will be somewhat dissimilar.
\ccIndexMainItem{demo programs}
\ccIndexSubitemEnd{demo programs}{submitting}
\index{demo directory@{\tt demo} directory|)}
\section{{\tt benchmark} subdirectory}
\label{sec:benchmark_subdirectory}
\index{benchmark directory@{\tt benchmark} directory|(}
\ccIndexSubitemBegin{benchmark programs}{submitting}
Benchmark programs for a package should be placed in a subdirectory of the directory {\tt benchmark}.
The subdirectory name, \verb|<benchmarkdir>|, will usually correspond to the
package name, but this is not a requirement.
Benchmark programs are currently not subject to any automatic treatment in the
test-suite, although they could evolve into an automatic benchmark-suite at
some point. We suggest at directory organization similar to the one of
\verb|<exampledir>|.
Some data sets can be placed under the {\tt data} subdirectory of \verb|<benchmarkdir>|,
but we recommend that only a small number of small files go there. Extensive
benchmarks data sets should probably be gathered elsewhere, so as not to bloat
the SVN server.
\index{benchmark directory@{\tt benchmark} directory|)}
\ccIndexSubitemEnd{submitting}{directory structure for}
\ccIndexMainItemEnd{directory structure}
\InternalOnly{
\section{Requirements and recommendations\label{sec:directories_req_and_rec}}
\noindent
Requirements:
\begin{itemize}
\item The directory structure outlined here must be followed exactly.
\end{itemize}
\noindent
Recommendations:
\begin{itemize}
\item Do not submit {\tt CMakeLists.txt}s for example programs and test suite
programs.
\item Do not submit the script {\tt cgal\_test} used to compile and test
your test suite programs.
\end{itemize}
}

196
Developers_manual/doc_tex/Developers_manual/examples_and_demos.tex
View File

@ -1,196 +0,0 @@
\chapter{Example and Demo Programs\label{chap:examples_and_demos}}
\ccIndexMainItemBegin{example programs}
\ccIndexMainItemBegin{demo programs}
{\HUGE This page is no longer maintained. The content has been moved to
https://cgal.geometryfactory.com/CGAL/Members/wiki/Examples_and_Demo_Programs}
The best way to illustrate the functionality provided by the library
is through programs that users can compile, run, copy and modify to
their hearts' content. Thus every package should contain some of
these programs. In \cgal\ we distinguish between two types of
programs: those that provided graphical output (demos) and those that
do not (examples).
In this chapter we provide guidelines for the development
of these programs and their inclusion in the documentation. See
Sections~\ref{sec:examples_subdirectory} and~\ref{sec:demo_subdirectory}
for a description of the directory structure required for example and
demo programs, respectively. Note in particular that each directory
should contain a \texttt{README} file that explains what the programs do and
how one interacts with them.
\section{Coding conventions\label{sec:ex_and_demo_coding}}
\ccIndexSubitem{example programs}{coding conventions}
\ccIndexSubitem{demo programs}{coding conventions}
Remember that these programs are likely to be a user's first introduction
to the library, so you should be careful to follow our coding conventions
(Chapter~\ref{chap:code_format}) and good programming practice in these
programs. In particular:
\begin{itemize}
\item Do \textbf{not} use the statements
\begin{verbatim}
using namespace CGAL;
using namespace std;
\end{verbatim}
\ccIndexSubitem{\tt using}{in examples and demos}
We discourage the use of these as they introduce more names than
are necessary and may lead to more conflicts than are necessary.
\item As of release 2.3, you can include only the kernel include file
(\eg, \texttt{Cartesian.h} or \texttt{Homogeneous.h}) to get all
kernel classes as well as the \texttt{basic.h} file. All example
and demo programs should do this. For example, you should have
simply:
\begin{verbatim}
#include <CGAL/Cartesian.h>
\end{verbatim}
instead of:
\begin{verbatim}
#include <basic.h>
#include <CGAL/Cartesian.h>
#include <CGAL/Point_2.h>
#include <CGAL/Triangle_2.h>
#include <CGAL/Segment_3.h>
// etc.
\end{verbatim}
\item Types should be declared using the following syntax:
\begin{verbatim}
typedef CGAL::Cartesian<double> Kernel;
typedef Kernel::Point_2 Point_2;
typedef Kernel::Triangle_3 Triangle_3;
\end{verbatim}
instead of this syntax:
\begin{verbatim}
typedef CGAL::Cartesian<double> Kernel;
typedef Point_2<Kernel> Point_2;
typedef Triangle_3<Kernel> Triangle_3;
\end{verbatim}
Although both will work, the former is to be preferred since
it reflects that the types are actually part of the kernel and
also reflects the new (as of release 2.3) kernel design that allows
types to be easily exchanged and adapted.
Note also that the typedef used above is
\begin{verbatim}
typedef CGAL::Cartesian<double> Kernel;
\end{verbatim}
instead of
\begin{verbatim}
typedef CGAL::Cartesian<double> R; // for representation
\end{verbatim}
This also reflects the new design, where the kernel classes are
kernels containing objects and predicates not just representation
classes for the objects.
\end{itemize}
\section{The Programs\label{sec:ex_and_demo_content}}
\ccIndexSubitem{example programs}{content}
\ccIndexSubitem{demo programs}{content}
The following guidelines should be followed to the greatest extent possible
when writing the example and demo programs.
\begin{itemize}
\item Provide simple programs with which a beginner can get started.
\item Provide more involved programs that illustrate the power of the
software.
\item Provide programs that truly exercise the data structure. Though you
may have some canned programs that work on fixed data sets to
illustrate specific things, you should also have one (or more)
programs that work on
\ccAnchor{http://www.cgal.org/Manual/doc_html/support_lib/Generator/Chapter_generators.html}{randomly generated} or user-generated data.
This illustrates confidence in the software (and can also build
confidence by highlighting bugs).
\item Take some care to design a good interface to the program;
the packaging of a product does make a difference.
\end{itemize}
\section{Including programs in documentation\label{sec:programs_in_doc}}
\ccIndexSubitem{example programs}{in manuals}
All programs included in the documentation should be included in either
the \texttt{examples} or the \texttt{demo} directory to ensure that:
\begin{itemize}
\item[(a)] the programs will be included in the test suite and
\item[(b)] the user can more easily use the example program
\end{itemize}
The macro to do this inclusion is \verb|\ccIncludeExampleCode|.
See Chapter~\ref{chap:specification} and the documentation of the
\ccAnchor{http://www.cgal.org/Members/Manual_tools}{Manual tools} for more
details.
The reverse statement, that all programs in the \texttt{examples}
and \texttt{demo} directory should be included in the documentation,
is not necessarily true. Ideally the programs included in the documentation
will be a proper (non-empty) subset of the programs included in the
distribution.
Please make sure that your example programs do not have too lengthy lines
as they are copied verbatim in the manual, which can trigger overflows
in the PDF manual.
\section{Demo programs on the web\label{sec:demos_web_page}}
\ccIndexSubitem{demo programs}{on the web}
Demo programs for some packages are accessible from the
\ccAnchor{http://www.cgal.org/Manual/latest/doc_html/cgal_manual/packages.html}{package overview}
web page \lcTex{ (\path|http://www.cgal.org/Manual/latest/doc\_html/cgal\_manual/packages.html|)}.
For each demo on the page, we have a precompiled executable for the
Windows platform.
If you have other demos you would like to add to the page (and the more
here the better), you should do the following:
\begin{enumerate}
\item Compile the demo and create a screen shot (as a \texttt{.gif} or
\texttt{.jpg} file) and then create a smaller version of this
(approx $235 \times 280$) that can be used as a ``thumbnail''
(admittedly for a rather large thumb) on the page. These names of
the image files should be as follows:
\centerline{\ccc{<program>_}\texttt{[big|small].[gif|jpg]}},
where \textit{$<$prog\_name$>$} is the name of the program from which
the screen shots were made (an nice mnemonic name like
\ccc{alpha_shapes_2} or \ccc{hull_of_int_points_2}).
\item Create the \texttt{.exe} file for use under Windows (probably with the
compiler optimization flags turned on)
\item \texttt{gzip} the \texttt{.exe} file
\item Package these together with the source code using the following structure:
\begin{verbatim}
images/demo/<program>_big.[gif|jpg]
demo/<program>.exe
demo/<subdir>/<program>.cpp
\end{verbatim}
where \ccc{<subdir>} is the name of the subdirectory in which the program
is (or will be) found in the distribution. \ccc{<program>} should be a
name that is self-explanatory (\eg, \texttt{demo.cpp} is a bad name here).
\item Send the package to \ccAnchor{mailto:ameyer@mpi-sb.mpg.de}{the web page
maintainer} together with a one-paragraph description similar to the
ones on the page already.
\end{enumerate}
\InternalOnly{
\section{Requirements and recommendations\label{sec:ex_and_demos_req_and_rec}}
\noindent
Requirements:
\begin{itemize}
\item Follow the coding conventions outlined in
Section~\ref{sec:ex_and_demo_coding}.
\item Include all example and demo programs from the documentation in
the \texttt{examples} or \texttt{demo} directories.
\end{itemize}
\noindent
Recommendations:
\begin{itemize}
\item Place a demo of your package on the web site.
\end{itemize}
}
\ccIndexMainItemEnd{example programs}
\ccIndexMainItemEnd{demo programs}

77
Developers_manual/doc_tex/Developers_manual/submission_process.tex
View File

@ -9,19 +9,7 @@
% $Date$
% =============================================================================
% \InternalOnly{
% \chapter{Submitting Packages\label{chap:submission}}
% \ccChapterRelease{Chapter Version: 1.0}
% \ccChapterAuthor{Geert-Jan Giezeman\\ %({\tt geert@cs.uu.nl})\\
% Susan Hert\\ %({\tt hert@mpi-sb.mpg.de})\\
% Monique Teillaud ({\tt Monique.Teillaud@inria.fr})}
% \section{Editorial board\label{sec:editorial_board}}
% }
%\ExternalOnly{
\chapter{Editorial Board\label{chap:submission}\label{sec:editorial_board}}
%}
\ccIndexMainItemBegin{editorial board}
@ -69,8 +57,7 @@ due to the recommendations of the board.
% However, since it can take some time for the board to process
% submissions, packages that are to become part of the library
% can be submitted
% \InternalOnly{as detailed in
% Section~\ref{sec:electronic_submission}} before approval.
% before approval.
% Inclusion in an internal release does not ensure inclusion in a public
% release.
Only after approval by the board will packages be included in new
@ -78,65 +65,3 @@ public releases and then only if they pass the test suite, of course.
The current list of members of the editorial board can be found on the
\ccAnchor{http://www.cgal.org/people.html}{web site}.
% \InternalOnly{
% \section{Electronic submission\label{sec:electronic_submission}}
% \ccIndexMainItemBegin{submitting}
% Whether you produce library code, demos, documentation or something else,
% if you want it to become part of \cgal, you'll have to submit it in
% the form of a wiki page on the
% \ccAnchor{https://cgal.geometryfactory.com/CGAL/Members/wiki/Features}{Feature page}
% or on the
% \ccAnchor{https://cgal.geometryfactory.com/CGAL/Members/wiki/Features/Small_Features}{Small Features page},
% and announce it by email to the
% \ccAnchor{mailto:cgal-editorial-board@lists-sop.inria.fr}{board}
% \lcTex{(\texttt{cgal-editorial-board@lists-sop.inria.fr})}.
% The package itself has to be a folder under SVN experimental
% packages.
% The directory structure required for a package is described in
% Chapter~\ref{chap:directory_structure}.
%Here we focus on how to submit a package.
% \ccIndexSubitem{naming scheme}{package}
% A package has a name, which identifies it. This name should obey the same
% rules as for C identifiers: it consists of letters, digits and underscores and
% it does not start with a digit. Choose a name that is descriptive, yet not
% too long (under 25 characters). If a package deals with objects of a
% particular dimension, then use the suffixes \_2, \_3, and \_d, especially if
% there exists (or may exist in the future) a package with similar
% functionality in different dimensions. Examples of good package names are
% \texttt{Triangulation\_2} for a package dealing with triangulations of points
% in the plane and \texttt{Min\_ellipse\_2}, which contains an algorithm that
% finds the minimal enclosing ellipse of a set of points in the plane. The
% package names \texttt{pm} and \texttt{arr} are a bit too terse.
% \texttt{Planar\_map} and \texttt{Arrangement} (or
% \texttt{Arrangement\_2}) are better.
% Make sure your package does not have any file clashing with any other packages.
% Please also make sure the information such as the maintainer email adress is
% up to date under the \texttt{package\_info} directory.
% \ccIndexSubitem{submitting}{file for}
% \ccIndexMainItemEnd{submitting}
% Monique: I would just remove this section
% \section{Requirements and recommendations\label{sec:submission_req_and_rec}}
% \noindent
% Requirements:
% \begin{itemize}
% \item Submit specifications to the editorial board.
% \item Obey the directory structure outlined in Chapter~\ref{chap:directory_structure}.
% \end{itemize}
% \noindent
% Recommendations:
% \begin{itemize}
% \item Wait for approval from the editorial board before submitting packages
% for internal releases.
% \end{itemize}
%}

403
Developers_manual/doc_tex/Developers_manual/testing.tex
View File

@ -1,403 +0,0 @@
% =============================================================================
% The CGAL Developers' Manual
% Chapter: Testing
% -----------------------------------------------------------------------------
% file : testing.tex
% authors: Mathair Baeskin <baeskin@infsn2.informatik.uni-halle.de>
% -----------------------------------------------------------------------------
% $Id$
% $Date$
% =============================================================================
\chapter{Testing\label{chap:testing}}
\ccChapterRelease{Chapter Version: 1.2}
\ccChapterAuthor{Matthias B\"asken}
\ccChapterAuthor{Yves Brise ({\tt ybrise@inf.ethz.ch})}
\ccIndexMainItemBegin{test suite}
%\section{Introduction}
{\HUGE This page is no longer maintained. The content has been moved to
https://cgal.geometryfactory.com/CGAL/Members/wiki/Testing}
The \cgal\ test suite is a way to test the compilation and execution of \cgal\
programs automatically (\ie, without user interaction) on a number of
different platforms. Developers should, of course, thoroughly test their
code on their own development platform(s) \textbf{before} submitting it.
The test suite serves as a way to test on additional platforms not available
to the developer.
\section{What a test suite for a package should contain\label{sec:whats_in_test_suite}}
The test suite helps the developer(s) of a package to
\begin{itemize}
\item detect compilation problems on the various platforms
\item detect runtime problems
\item check the correctness of the algorithms in the package
\end{itemize}
That does not mean that the test suite is a platform for initial testing of
code. New code should be tested on different platforms by the developer
before submission.
It is strongly recommended for a test suite of a package to
\begin {itemize}
\item Cover the complete code of the package; every (member) function
should be called at least once. (See Section~\ref{sec:gcov} for
a description of a tool you can use to test for code coverage.)
\item Use more than one instantiation of templated functions or classes.
\item A lot of classes in \cgal\ can be parametrized by traits classes, so
that they are usable with different kernels. In such cases more than one
kernel should be used for testing.
\item Use pre- and postcondition checkers wherever it is possible in the
main code. In the test-suite code itself, the macro \ccc{assert}
should be used in place of \ccc{CGAL_assertion} to check
all conditions, since \ccc{assert} is not disabled by \ccc{CGAL_NDEBUG}.
\end {itemize}
\section{Using the code coverage tool \texttt{gcov}}
\label{sec:gcov}
The tool {\tt gcov} can be used together with the GNU C++ compiler to test
for code coverage in your programs and may be helpful when you create your
\cgal\ test suite programs. You can find a complete guide to this tool
in the GNU on-line documentation at
\path|http://gcc.gnu.org/onlinedocs/gcc-2.95.2/gcc_6.html|.
If you want to use the code coverage tool {\tt gcov}, you have to compile
your programs with the options \texttt{-fprofile-arcs} and
\texttt{-ftest-coverage}. This generates a file called
\texttt{your\_program.gcda}. Then you run the program, which generates a file
\texttt{your\_program.gcno}. Finally, you can run \texttt{gcov your\_program.cpp}.
This will generate a number of files with the ending \texttt{.gcov} which contain
human readable information. View it in a text editor.
Here is a simple example:\\
\begin{verbatim}
#include<iostream>
using namespace std;
void fu(int val)
{
int w,v=0;
if (val==0) {
cout << "val == 0!\n";
for(w=0;w<100;w++) v=v+w;
}
else {
cout << "val != 0!\n";
for(w=0;w<10;w++) v=v+w;
}
cout << "v:" << v << "\n";
}
int main()
{
fu(0);
return 0;
}
\end{verbatim}
First you have to compile the example program \texttt{test.cpp} with the special
options. Then you have to execute it, and, after this, \texttt{gcov} can be
used.
\begin{verbatim}
g++ -fprofile-arcs -ftest-coverage -o test test.cpp
test
gcov test.cpp
\end{verbatim}
\texttt{gcov} will create a file \texttt{test.cpp.gcov} containing output
from \texttt{gcov}:
\begin{verbatim}
#include<iostream>
using namespace std;
void fu(int val)
1 {
1 int w,v=0;
1 if (val==0) {
1 cout << "val == 0!\n";
1 for(w=0;w<100;w++) v=v+w;
}
###### else {
###### cout << "val != 0!\n";
###### for(w=0;w<10;w++) v=v+w;
}
1 cout << "v:" << v << "\n";
}
int main()
1 {
1 fu(0);
1 return 0;
}
\end{verbatim}
The lines that were not executed will be marked with \verb|######|,
so you will see what should be added in the (\cgal) test suite programs.
There are a few pitfalls when using CMake and \texttt{gcov} together.
First note, that with CMake you can add compiler flags using the \texttt{CGAL\_CXX\_FLAGS} variable. See the
\ccAnchor{http://www.cgal.org/Manual/latest/doc_html/installation_manual/Chapter_installation_manual.html#Subsection_8.2}{\cgal Installation Manual} to get more information on that. Typing \texttt{make your\_program} to compile your program is straightforward, as is running it. But then, the \texttt{.gcda}
and \texttt{.gcno} are created within the directory \texttt{CMakeFiles/your\_program.dir/} relative to your project path. You first have to copy them to the same folder where \texttt{your\_program.cpp} resides.
If you don't do that, running \texttt{gcov your\_program.cpp} will give an error
message.
\section{Test suite directory\label{sec:test_suite_directory}}
The test suite is located in the directory {\tt test} of the internal
releases of \cgal. This directory is not part of external releases. The
directory {\tt test}\index{test directory@{\tt test} directory!for test suite}
contains:
\begin{itemize}
\item a script {\tt run\_testsuite}
\index{run_testsuite script@{\tt run\_testsuite} script}
that is (not surprisingly) used to run the test suite.
\item a subdirectory for every package included in the internal release.
These subdirectories are created from the {\tt test} directories
of the packages by copying the source, include, and input files from
these directories and adding makefiles and {\tt cgal\_test} scripts
where needed. See Section~\ref{sec:test_subdirectory} for more
information about the proper structure of the {\tt test} directory
for a package.
\index{test directory@{\tt test} directory!for packages}
\item a subdirectory with a name that ends in {\tt \_Examples} for every
package that was submitted with an {\tt examples} directory
(Section~\ref{sec:examples_subdirectory})
\index{examples directory@{\tt examples} directory}
\ccIndexSubitem{test suite}{examples in}
\ccIndexSubitem{example programs}{in test suite}
\item a subdirectory with a name that ends in {\tt \_Demo} for every
package that was submitted with a {\tt demo} directory
(Section~\ref{sec:demo_subdirectory})
\index{demo directory@{\tt demo} directory}
\ccIndexSubitem{test suite}{demos in}
\ccIndexSubitem{demo programs}{in test suite}
\end{itemize}
The test suite will attempt to compile all the programs in the
subdirectories of {\tt test} and to run all except
the demo programs (which usually require user interaction) by using the
{\tt cgal\_test} scripts
(Sections~\ref{sec:test_subdirectory} and~\ref{sec:create_cgal_test})
\index{cgal_test script@{\tt cgal\_test} script}
and will save the results in files in the package subdirectories
(Section~\ref{sec:test_suite_output}).
Even if a program fails to compile or run, the test suite will continue.
\section{Test suite input\label{sec:test_suite_input}}
\ccIndexSubitemBegin{test suite}{input}
Input to programs in the test suite can be supplied in three different
ways:
\begin{description}
\item[data files in the {\tt data} directory]
\index{data directory@{\tt data} directory}
\ccIndexSubsubitem{test suite}{input}{from files}
As described in Section~\ref{sec:test_subdirectory}, a package's
{\tt test} directory may contain a subdirectory {\tt data} that
contains input files for the test programs.
\item[{\tt *.cin} files]
\index{test\ suite!input!from {\tt cin}}
If a test program \texttt{program.cpp} requires input from standard
input (\ie, {\tt cin}), you should put a file called
\texttt{program.cin} in the test directory.
The test suite will then execute the program using the command
\begin{verbatim}
./program < program.cin
\end{verbatim}
\item[command-line arguments supplied in the {\tt cgal\_test} script]
\ccIndexSubsubitem{test suite}{input}{from command-line}
{\em You are discouraged from using this option to give input values
to your programs} since it requires you to edit and submit a
{\tt cgal\_test} script; see Section~\ref{sec:create_cgal_test}.
\index{cgal_test script@{\tt cgal\_test} script}
However, if a test program \texttt{program.cpp} absolutely requires
command-line parameters, you should do the following. Use
\texttt{create\_cgal\_test} to create the script \texttt{cgal\_test}.
This file contains an entry of the form
\begin{verbatim}
compile_and_run program
\end{verbatim}
Just put the command-line
parameters for \texttt{program} at the end of this line:
\begin{verbatim}
compile_and_run program arg1 arg2 ..
\end{verbatim}
The test suite will then execute the program using the command
\begin{verbatim}
./program <arg1> <arg2> ...
\end{verbatim}
\end{description}
\ccIndexSubitemEnd{test suite}{input}
\section{Running the test suite\label{sec:running_test_suite}}
\index{run_testsuite script@{\tt run\_testsuite} script|(}
The test suite is run using the {\tt run\_testsuite} script that is distributed
with every internal release in the {\tt test} directory. There are several
ways you can customize this script to meet you needs:
\begin{itemize}
\item Add additional compiler and linker flags by setting the variables
{\tt TESTSUITE\_CXXFLAGS}%
\index{TESTSUITE_CXXFLAGS variable@{\tt TESTSUITE\_CXXFLAGS} variable}
and {\tt TESTSUITE\_LDFLAGS}
\index{TESTSUITE_LDFLAGS variable@{\tt TESTSUITE\_LDFLAGS} variable}
\ccIndexSubitem{header files}{overriding}
at the top of the
script. These variables are prepended to {\tt CXX\_FLAGS} and
{\tt LDFLAGS}, respectively, in the test suite makefiles. So, for
example, if you have a directory \verb|experimental/include/CGAL|
containing new or experimental \cgal\ files, you can do the following:
\begin{center}
\verb|TESTSUITE_CXXFLAGS="-Iexperimental/include"|
\end{center}
and in this way test with your new files without overwriting
the originals.
\item Export additional environment variables by adding lines to the
\ccIndexSubitem{environment variables}{test suite}
\ccIndexSubitem{test suite}{environment variables}
{\tt run\_testsuite} script. As an example, it will be demonstrated
how to export the {\tt LD\_LIBRARY\_PATH} by editing \texttt{run\_testsuite}.%
\index{LD_LIBRARY_PATH variable@{\tt LD\_LIBRARY\_PATH} variable}
\begin{enumerate}
\item Add the line
\begin{center}
\verb|LD_LIBRARY_PATH=<your library path>|
\end{center}
to the script.
\item Append {\tt LD\_LIBRARY\_PATH} to the line
\begin{center}
\verb|export PLATFORM CGAL_MAKEFILE TESTSUITE_CXXFLAGS TESTSUITE_LDFLAGS|
\end{center}
in the script.
\end{enumerate}
After this, the programs from the test suite will be run using the
{\tt LD\_LIBRARY\_PATH} that was specified in step 1.
\item Run the test suite on more than one platform by adding a line at the
bottom of the script of the form
\begin{verbatim}
run_testsuite <include makefile>
\end{verbatim}
for every platform that you wish to test. Just substitute for
\verb|<include makefile>| the appropriate include makefiles that
were generated during installation. (Don't forgot to use the
full path name for the makefile!) By default, the last line in the
file is
\begin{verbatim}
run_testsuite $CGAL_MAKEFILE
\end{verbatim}
so you need not make any changes if you run the testsuite on only one
platform and have set the {\tt CGAL\_MAKEFILE} environment variable
properly.%
\index{CGAL_MAKEFILE variable@{\tt CGAL\_MAKEFILE} variable!and test suite}
\end{itemize}
After these steps you are ready to run the test suite. It can be run in two
different ways:
\begin{verbatim}
./run_testsuite
\end{verbatim}
The test suite will run the tests from all test directories. This may take a
considerable amount of time.
\begin{verbatim}
./run_testsuite <dir1> <dir2> ...
\end{verbatim}
The test suite will run only the test programs in the test directories
\begin{verbatim}<dir1> <dir2> ... \end{verbatim}
\index{run_testsuite script@{\tt run\_testsuite} script|)}
To run an entire \cgal\ test suite automatically, including downloading of
an internal release, configuration, and installation of the library, you
can use the {\tt autotest\_cgal} script described in
Section~\ref{sec:autotest_cgal}.
\section{Files generated by the test suite\label{sec:test_suite_output}}
\ccIndexSubitemBegin{test suite}{output files}
The testsuite will generate the following output files:
\begin{itemize}
\item \verb|<testdir>/ErrorOutput_<platform>|
\index{ErrorOutput files@{\tt ErrorOutput} files}
This file contains two lines for every program that was tested on
platform \texttt{<platform>} in the test directory \texttt{<testdir>}.
The first line
tells if the compilation was successful and the second line tells if
the execution was successful (\ie, the program returned the value 0).
(See Section~\ref{sec:test_subdirectory} for more details.)
\item \verb|<testdir>/ProgramOutput.<program>.<platform>|
\index{ProgramOutput files@{\tt ProgramOutput} files}
This file contains the console output from the test program
\texttt{<program.cpp>} run on platform \texttt{<platform>}.
\item \verb|<testdir>/CompilerOutput_<platform>|
\index{CompilerOutput files@{\tt CompilerOutput} files}
This file contains the compiler output from platform
\texttt{<platform>} for all programs.
\item \verb|error.txt|
\index{error.txt@{\tt error.txt}}
This is just a concatenation of all the \texttt{ErrorOutput} files that were
generated during the last run of the test suite.
\end{itemize}
\ccIndexSubitemEnd{test suite}{output files}
\section{Test suite results\label{sec:test_suite_results}}
\ccIndexSubitemBegin{test suite}{results}
The results of test suites run on the various supported or soon-to-be-supported
platforms are posted on the
\ccAnchor{http://cgal.geometryfactory.com/CGAL/Members/testsuite/}%
{test suite results}
page
\lcTex{(\path|http://cgal.geometryfactory.com/CGAL/Members/testsuite/|)}.
\ccIndexSubitemEnd{test suite}{results}
\section{Requirements and recommendations\label{sec:testing_req_and_rec}}
\noindent
Requirements:
\begin{itemize}
\item Test your code thoroughly \textbf{before} submitting it.
\item Obey the directory structure detailed in Section~\ref{sec:test_subdirectory}
\item Check the test suite results for your package regularly.
\end{itemize}
\noindent
Recommendations:
\begin{itemize}
\item Write test suite programs that use more than one instantiation of
templated functions and classes, call every member function at least
once, and use more than one kernel.
\item Use pre- and postcondition checkers.
\item Use \texttt{gcov} to test your code for coverage.
\item Don't submit a makefile for your test suite unless you need to do
something very special to compile or link your program. If you find
you want to do something very special in your makefile, think long
and hard about whether it's really necessary or not.
\item Don't submit the script \texttt{cgal\_test} with your package.
\end{itemize}
\ccIndexMainItemEnd{test suite}