% =============================================================================
% 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>
% -----------------------------------------------------------------------------
% $Revision$
% $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
      |
      |- 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 of this 
       subdirectory.
  \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,
       and other things. The average package won't have this directory.
  \item[{\tt scripts}]\index{scripts directory@{\tt scripts} directory}
       contains scripts that are useful for users of CGAL.
  \item[{\tt developer\_scripts}]\index{developers_scripts directory@{\tt developers\_scripts} directory}
       contains scripts that are useful for
       developers of CGAL. This directory is included only in internal
       releases, not in public releases.
  \item[\ccAnchor{example/changes.txt}{{\tt changes.txt}}]%
       \ccIndexMainItem{\tt changes.txt}
       should be used to document important changes between 
       subsequent versions. Each entry in this file should include
       the date it was committed and the name of the commiter, as well as
       a one line description of the change (most recent entries at the top),
       in the following format, for 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 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}

The structure of the directory that contains the test suite files for 
a package should be as follows: 

\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. It will be created automatically, so usually there
	is no need to submit it. (Submitting it is {\bf discouraged}.)
	It 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}
                 (an additional compiler flag) 
            \item[{\tt \$TESTSUITE\_LDFLAGS}] 
                 \index{TESTSUITE_LDFLAGS variable@{\tt TESTSUITE\_LDFLAGS} variable}
                 (an additional linker flag) 
        \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 should then
        perform all tests using the makefile \verb|$CGAL_MAKEFILE|. 

        To indicate whether the tests are successful or not, the script should 
        write 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 
        should be written that starts with the keyword {\tt ERROR:}; otherwise
        a message indicating successful compilation or execution should be
        written to this file. Running the script {\tt cgal\_test} should not 
        require any user interaction and the script should clean up after 
        itself by removing object files and executables (usually by using the
        command {\tt make clean}).

        This 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}. {\em Submitting it is 
        {\bf discouraged} even more strongly}, because it is quite difficult 
        to produce a makefile that works correctly on all supported platforms.
        The makefile should 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.  The makefile can be created using the script
        {\tt create\_makefile}%
        \index{create_makefile script@{\tt create\_makefile} script} 
        with the argument {\tt -t} 
        (Section~\ref{sec:create_makefile}).
   \item[{\tt *.C}] source code for the test programs.
        \ccIndexSubitem{source files}{test suite}

        Whan 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} 
\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
currently divided into six separate manuals.  This division is reflected
in the structure of the {\tt doc\_tex} directory, which contains the 
documentation source files: 
\begin{verbatim}
      doc_tex
           +--- installation/
           |
           +--- kernel/
           |
           +--- basic/
           |
           +--- support/
           |
           +--- use_of_stl/
\end{verbatim}

The {\tt basic/} and {\tt support/} directories each contain subdirectories
that correspond to the packages documented in these manuals.  Contained in these
subdirectories are the files required for producing a package's contributions
to the reference manual and users' manual. 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.)  

For example, the optimisation package of 
the basic library can have the following documentation. 
\begin{verbatim}
      doc_tex/basic/Optimisation
                          |- main.tex
                          |
                          |- *.tex
                          |
                          |- *.eps
                          |
                          |- *.gif
                          |
                          |- *.html
                          |
                          |- htmlfiles
                          |
                          |- cgal.bib
                          |
      doc_tex/basic/Optimisation_ref/
                          |- main.tex
                          |
                          |- *.tex
                          |
                          |- *.eps
                          |
                          |- *.gif
                          |
                          |- *.html
                          |
                          |- htmlfiles
                          |
                          |- cgal.bib
\end{verbatim}

\begin{description}
 \item[\ccAnchor{example/doc_tex/basic/Package/main_tex}{{\tt main.tex}}]%
      \ccIndexMainItem{\tt main.tex}\ccIndexSubitem{users' manual}{\tt main.tex}
      must contain one or more chapters. It must NOT 
      contain a preamble (so no {\tt documentclass}, {\tt usepackage}, 
      \verb|\begin{document}| or \verb|\end{document}| commands). 
      Until the new manual style is used, this file should also input the
      {\tt main.tex} file for the reference manual pages for this package.
 \item[{\tt *.tex}] -- the source files for the Users' Manual that are input
      by {\tt main.tex} 
 \item[{\tt *.eps}] -- the PostScript pictures included in the documentation
 \item[{\tt *.gif}] -- the corresponding {\tt gif} figures for the HTML 
      documentation
 \item[{\tt *.html}] -- auxiliary HTML files ({\em i.e.}, other than those
      generated by {\tt cc\_manual\_to\_html}) that are used in the HTML 
      documentation.
 \item[\ccAnchor{example/doc_tex/basic/Package/htmlfiles}{{\tt htmlfiles}}]%
      \index{htmlfiles file@{\tt htmlfiles} file}%
      -- a list of auxiliary files ({\em e.g.} the {\tt .gif} and {\tt .html}
      files) required for the HTML documentation.  Each file name should be
      on a separate line in this file.  When the manual is created, these 
      files will be copied to the directory containing the HTML manuals.
 \item[{\tt cgal.bib}]\index{cgal_bib@{\tt cgal.bib}} -- a list of citations
      for items {\bf not found} in the 
      \ccAnchor{http://www.cs.uu.nl/usr/cgi-bin/bib-search/geom}{{\tt geombib}}
      data base.  Citations from this database will be
      resolved automatically when the manual is created. 
 \item[{\tt Optimisation\_ref/}] -- directory containing the source files
      for the reference manual pages for this package. 
 \item[\ccAnchor{example/doc_tex/basic/Package_ref/main_tex}{{\tt Optimisation\_ref/main.tex}}]
      \ccIndexMainItem{\tt main.tex}\ccIndexSubitem{reference manual}{\tt main.tex}%
       -- the file that inputs the source files for the reference manual pages,
      with the same restrictions as above. 
 \item[{\tt Optimisation\_ref/*.tex}] -- the source files for the reference
      manual, with each item documented in a separate file.
 \item[{\tt Optimisation\_ref/*.eps}, {\tt Optimisation\_ref/*.gif}] -- 
      same as above.
 \item[{\tt Optimisation\_ref/htmlfiles}] -- same as above.
\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
                   |
                   |- 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}

}
