diff --git a/Developers_manual/doc_tex/Developers_manual/addresses.tex b/Developers_manual/doc_tex/Developers_manual/addresses.tex deleted file mode 100644 index f0293ab2c7b..00000000000 --- a/Developers_manual/doc_tex/Developers_manual/addresses.tex +++ /dev/null @@ -1,70 +0,0 @@ -% ============================================================================= -% The CGAL Developers' Manual -% Chapter: Mailing Lists and Addresses -% ----------------------------------------------------------------------------- -% file : addresses.tex -% authors: Susan Hert -% ----------------------------------------------------------------------------- -% $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} diff --git a/Developers_manual/doc_tex/Developers_manual/chapters.tex b/Developers_manual/doc_tex/Developers_manual/chapters.tex index 8c0f9af88a0..b7351e720be 100644 --- a/Developers_manual/doc_tex/Developers_manual/chapters.tex +++ b/Developers_manual/doc_tex/Developers_manual/chapters.tex @@ -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} diff --git a/Developers_manual/doc_tex/Developers_manual/directory_structure.tex b/Developers_manual/doc_tex/Developers_manual/directory_structure.tex deleted file mode 100644 index b086f4c5961..00000000000 --- a/Developers_manual/doc_tex/Developers_manual/directory_structure.tex +++ /dev/null @@ -1,436 +0,0 @@ -% ============================================================================= -% The CGAL Developers' Manual -% Chapter: Directory Structure for Packages -% ----------------------------------------------------------------------------- -% file : directory_structure.tex -% authors: Geert-Jan Giezeman & Susan Hert -% ----------------------------------------------------------------------------- -% $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// - | - +--- doc_tex/ - | - +--- examples// - | - +--- demo// - | - +--- benchmark// - | - +--- 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/ - +--- data/ - | - +--- include/ - | - |- CMakeLists.txt - | - |- cgal_test - | - |- *.cpp - | - |- *.cin -\end{verbatim} -where the directory \verb|| 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||. - 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 $${\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||, 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/ - +--- 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/ - +--- data/ - | - +--- include/ - | - |- README - | - |- CMakeLists.txt - | - |- *.cpp -\end{verbatim} -where \verb|| 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||, 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||. - -Some data sets can be placed under the {\tt data} subdirectory of \verb||, -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} - -} diff --git a/Developers_manual/doc_tex/Developers_manual/examples_and_demos.tex b/Developers_manual/doc_tex/Developers_manual/examples_and_demos.tex deleted file mode 100644 index f26245e699a..00000000000 --- a/Developers_manual/doc_tex/Developers_manual/examples_and_demos.tex +++ /dev/null @@ -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 - \end{verbatim} - instead of: - \begin{verbatim} - #include - #include - #include - #include - #include - // etc. - \end{verbatim} - \item Types should be declared using the following syntax: - \begin{verbatim} - typedef CGAL::Cartesian Kernel; - typedef Kernel::Point_2 Point_2; - typedef Kernel::Triangle_3 Triangle_3; - \end{verbatim} - instead of this syntax: - \begin{verbatim} - typedef CGAL::Cartesian Kernel; - typedef Point_2 Point_2; - typedef Triangle_3 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 Kernel; - \end{verbatim} - instead of - \begin{verbatim} - typedef CGAL::Cartesian 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{_}\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/_big.[gif|jpg] - demo/.exe - demo//.cpp - \end{verbatim} - where \ccc{} is the name of the subdirectory in which the program - is (or will be) found in the distribution. \ccc{} 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} diff --git a/Developers_manual/doc_tex/Developers_manual/submission_process.tex b/Developers_manual/doc_tex/Developers_manual/submission_process.tex index c9e61c5635c..52d3e26bc6e 100644 --- a/Developers_manual/doc_tex/Developers_manual/submission_process.tex +++ b/Developers_manual/doc_tex/Developers_manual/submission_process.tex @@ -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} -%} diff --git a/Developers_manual/doc_tex/Developers_manual/testing.tex b/Developers_manual/doc_tex/Developers_manual/testing.tex deleted file mode 100644 index 92f5af20563..00000000000 --- a/Developers_manual/doc_tex/Developers_manual/testing.tex +++ /dev/null @@ -1,403 +0,0 @@ -% ============================================================================= -% The CGAL Developers' Manual -% Chapter: Testing -% ----------------------------------------------------------------------------- -% file : testing.tex -% authors: Mathair Baeskin -% ----------------------------------------------------------------------------- -% $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 - - 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 - - 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 ... - \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=| - \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 - \end{verbatim} - for every platform that you wish to test. Just substitute for - \verb|| 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 ... -\end{verbatim} - -The test suite will run only the test programs in the test directories -\begin{verbatim} ... \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|/ErrorOutput_| -\index{ErrorOutput files@{\tt ErrorOutput} files} - -This file contains two lines for every program that was tested on -platform \texttt{} in the test directory \texttt{}. -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|/ProgramOutput..| -\index{ProgramOutput files@{\tt ProgramOutput} files} - -This file contains the console output from the test program -\texttt{} run on platform \texttt{}. - -\item \verb|/CompilerOutput_| -\index{CompilerOutput files@{\tt CompilerOutput} files} - -This file contains the compiler output from platform -\texttt{} 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} - -