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

461 lines
19 KiB
TeX
Raw Blame History

% =============================================================================
% 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 ({\tt Sylvain.Pion@sophia.inria.fr}) }
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}, {\tt changes.txt} and {\tt description.txt}
are obligatory.
\index{maintainer file@{\tt maintainer} file}
\ccIndexMainItem{\tt changes.txt}\ccIndexMainItem{\tt description.txt}
Submissions should not contain files in other places than described here.
Packages may be rejected if they do, and the contents won't go into releases.
The directory structure of a submission should be as follows:
\begin{verbatim}
+--- include/CGAL
|
+--- src/
|
+--- test/<testdir>
|
+--- doc_tex/
|
+--- examples/<exampledir>
|
+--- demo/<demodir>
|
+--- auxiliary/
|
+--- scripts/
|
+--- developer_scripts/
|
|- changes.txt
|
|- description.txt
|
|- dont_submit
|
|- 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 .C} files}
contains the {\tt .C} files (if any) for the package.
\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 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 auxiliary}]\index{auxiliary directory@{\tt auxiliary}
directory} contains auxiliary software for CGAL. For
instance, GMP goes here. 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[\ccAnchor{example/changes.txt}{{\tt changes.txt}}]%
\ccIndexMainItem{\tt changes.txt} used to document important
changes between subsequent versions. Each entry must provide the
date of the change and the name of the person who committed it, as
in the following example:
\begin{verse}
2 Feb 2004 Sylvain Pion\\
- Fix a memory-leak in file.h.\\
- Optimized function A::f().
\end{verse}
\item[{\tt description.txt}]%
\ccIndexMainItem{\tt description.txt}
should give a very short description of the contents of the package.
\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 long\_description.txt}]%
\ccIndexMainItem[c]{\tt long_description.txt}
may be added with more detailed information about the submission.
\item[\ccAnchor{example/maintainer}{{\tt maintainer}}]%
\index{maintainer file@{\tt maintainer} file}
should be used to names 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}
\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/
|
|- cgal_test
|
|- makefile
|
|- *.C
|
|- *.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 makefile}]\ccIndexSubitem{\tt makefile}{test suite}
is the makefile for the test programs. It is created
automatically, just like {\tt cgal\_test}. Submitting it is
{\bf discouraged even more strongly}, because it is quite difficult
to produce a makefile that works correctly on all supported platforms.
For testing purposes, such a makefile can be created using the
script
{\tt cgal\_create\_makefile}%
\index{cgal_create_makefile script@{\tt cgal\_create\_makefile} script}
with the argument {\tt -t}
(Section~\ref{sec:cgal_create_makefile}).
\item[{\tt *.C}] 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|std::EXIT_WITH_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}
\begin{ccAdvanced}
\textbf{Custom cgal\_test script.} In special cases, you may want to
provided a custom {\tt cgal\_test} script to fit special needs. The
script should rely on four environment variables:
\begin{description}
\item[{\tt \$CGAL\_MAKEFILE}]%
\index{CGAL_MAKEFILE variable@{\tt CGAL\_MAKEFILE} variable}%
\ccIndexSubitem{\tt makefile}{\cgal}
(an included makefile, which {\bf must} include the full path
name!!)
\item[{\tt \$PLATFORM}]%
\index{PLATFORM variable@{\tt PLATFORM} variable}
(the extension of this makefile, that will
be used as an extension to the output files),
\item[{\tt \$TESTSUITE\_CXXFLAGS}]%
\index{TESTSUITE_CXXFLAGS variable@{\tt TESTSUITE\_CXXFLAGS} variable}
(additional compiler flags)
\item[{\tt \$TESTSUITE\_LDFLAGS}]
\index{TESTSUITE_LDFLAGS variable@{\tt TESTSUITE\_LDFLAGS} variable}
(additional linker flags)
\end{description}
The latter two flags must be passed to the makefile%
\ccIndexSubitem{\tt makefile}{test suite} and they should
precede all other compiler and linker flags. The script then
performs all tests using the makefile \verb|$CGAL_MAKEFILE|.
To indicate whether the tests are successful or not, the
script writes two one-line messages to a file called {\tt
error.txt} \index{error.txt@{\tt error.txt}} for each
target. If something goes wrong during compilation or during
execution, an error message is written that starts with the
keyword {\tt ERROR:}; otherwise a message indicating
successful compilation or execution is written to this file.
Running the script {\tt cgal\_test} must not require any user
interaction and the script cleans up after itself by removing
object files and executables (usually by using the command
{\tt make clean}).
\textbf{Custom makefile.} In special cases, you may want to
provided a custom {\tt makefile} to fit special needs. Use the
two variables \verb|$TESTSUITE_CXXFLAGS|
\index{TESTSUITE_CXXFLAGS variable@{\tt TESTSUITE\_CXXFLAGS}
variable} and \verb|$TESTSUITE_LDFLAGS|
\index{TESTSUITE_LDFLAGS variable@{\tt TESTSUITE\_LDFLAGS}
variable} as the first compiler and linker flags,
respectively.
\end{ccAdvanced}
\ccIndexMainItemEnd{test suite}
\index{test directory@{\tt test} directory|)}
\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
|
+--- *.((ps)|(eps)|(pdf)|(gif)|(jpg)|(png))
doc_tex/Optimisation_ref/
|--- main.tex
|
|--- intro.tex
|
|--- *.tex
|
+--- *.((ps)|(eps)|(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 *.((ps)|(eps))}] -- the PostScript pictures included in
the PostScript documentation.
\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|)}
\textbf{Historical Notes.} Once upon a time a file called
\texttt{htmlfiles} has been used to indicate files (e.g., images) to
be used for the html conversion. This file is no longer needed nor is
it evaluated anymore. The functionality is now provided by an
mechanism in the \texttt{latex\_to\_html} converter to find and copy
the included raster images automatically. Also the \texttt{cgal.bib}
files are not used anymore. They are replaced by a common file
\texttt{doc\_tex/Manual/cgal\_manual.bib} in the \texttt{Manual}
package.
\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
|
|- makefile
|
|- *.C
\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
|
|- makefile
|
|- *.C
\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 programs and test suite
programs, for demo programs is it necessary to submit a {\tt makefile}
\ccIndexSubitem{\tt makefile}{demo programs} since
different demos will require different libraries and thus the makefiles
for these programs will be somewhat dissimilar.
\ccIndexMainItem{demo programs}
\ccIndexSubitemEnd{demo programs}{submitting}
\index{demo directory@{\tt demo} 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 makefile}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}
}
Reference in New Issue View Git Blame Copy Permalink