Chapter 4
Directory Structure for Packages

In order for code, demos, documentation, 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 maintainer, changes.txt and description.txt are obligatory. 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:

      +--- 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

include/CGAL

contains the .h files for the package.

src

contains the .C files (if any) for the package.

test

contains the test suite code for the package. See Section 4.1 for a detailed description.

doc_tex

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 4.2 for a detailed description of this subdirectory. See Chapter 2 for guidelines for producing the documentation.

examples

contains the example programs for the package. See Section 4.3 for a detailed description of this subdirectory.

demo

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 4.4 for a more detailed description of this subdirectory.

auxiliary

contains auxiliary software for CGAL. For instance, GMP goes here. The average package won't have this directory.

scripts

contains scripts that are of interest to CGAL users.

developer_scripts

contains scripts that are of interest to CGAL developers. This directory is included in internal releases only, not in public releases.

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:

2 Feb 2004 Sylvain Pion
- Fix a memory-leak in file.h.
- Optimized function A::f().

description.txt

should give a very short description of the contents of the package.

dont_submit

specifies files and directories that are to be excluded from the release, for example:

TODO
include/CGAL/my_internal_file.h
Benchmark

long_description.txt

may be added with more detailed information about the submission.

maintainer

should be used to names the maintainers of the package. The file should have for each maintainer a line with the following format:

name $$<email address$$>

For example:

Susan Hert $$<hert@mpi-sb.mpg.de$$>
Sylvain Pion $$<Sylvain.Pion@sophia.inria.fr$$>

4.1   test subdirectory

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 17.

      test/<testdir>
               +--- data/
               |
               +--- include/
               |
               |- cgal_test
               |
               |- makefile
               |
               |- *.C
               |
               |- *.cin

data/

is a subdirectory that contains local data files for the test suite.

include/

is a subdirectory that contains local include files for the test suite.

cgal_test

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 strongly discouraged.

For testing purposes, such a script can be created using the create_cgal_test script (Section 5.5).

makefile

is the makefile for the test programs. It is created automatically, just like cgal_test. Submitting it is 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 cgal_create_makefile with the argument -t (Section 5.4).

*.C

source code for the test programs.

When a test program runs correctly, it should return the value zero, or, more precisely, the value std::EXIT_WITH_SUCCESS defined in <cstdlib>. Test programs may not be graphical and they may not require any user interaction.

*.cin

files containing command-line input for test programs. These files are necessary for only those programs that require command-line input (which can usually be avoided). If a file program.cin is present in the test directory, then, when the test suite is run, program will be executed using the command

        ./program < program.cin
        

advanced

Custom cgal_test script. In special cases, you may want to provided a custom cgal_test script to fit special needs. The script should rely on four environment variables:

$CGAL_MAKEFILE

(an included makefile, which must include the full path name!!)

$PLATFORM

(the extension of this makefile, that will be used as an extension to the output files),

$TESTSUITE_CXXFLAGS

(additional compiler flags)

$TESTSUITE_LDFLAGS

(additional linker flags)

The latter two flags must be passed to the makefile and they should precede all other compiler and linker flags. The script then performs all tests using the makefile $CGAL_MAKEFILE.

To indicate whether the tests are successful or not, the script writes two one-line messages to a file called error.txt for each target. If something goes wrong during compilation or during execution, an error message is written that starts with the keyword ERROR:; otherwise a message indicating successful compilation or execution is written to this file. Running the script 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 make clean).

Custom makefile. In special cases, you may want to provided a custom makefile to fit special needs. Use the two variables $TESTSUITE_CXXFLAGS and $TESTSUITE_LDFLAGS as the first compiler and linker flags, respectively.

advanced

4.2   doc_tex subdirectory

As described in Chapter 2, 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>_ref . 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 2.4.), but there must be a file called main.tex in both the user and reference manual directories that inputs all the other files for that manual part. (Note: You should use the \input command and NOT the \include command to input other source files in this file, and they have to include their files using relative paths starting in the doc_tex directory.)

For example, the optimisation package of the basic library can have the following documentation.

      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))

main.tex

must contain one chapter. It must NOT contain a preamble (so no documentclass, usepackage, \begin{document} or \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 file, and include those files in main.tex using the \input macro.

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.

*.tex

- the source files for the Users' and Reference Manual that are input by main.tex

*.((ps)|(eps))

- the PostScript pictures included in the PostScript documentation.

*.pdf

- the PDF pictures included in the PDF documentation.

*.((gif)|(jpg)|(png))

- the raster images included in the HTML documentation.

Historical Notes. Once upon a time a file called 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 latex_to_html converter to find and copy the included raster images automatically. Also the cgal.bib files are not used anymore. They are replaced by a common file doc_tex/Manual/cgal_manual.bib in the Manual package.

4.3   examples subdirectory

Example programs (Chapter 19) for a package should be placed in a subdirectory of the directory examples. The subdirectory name, <exampledir>, will usually correspond to the package name, but this is not a requirement. To make sure that the examples will be tested , a directory with examples should be submitted in exactly the same way as a test directory (Section 4.1).

The structure of an example directory should be as follows:

      examples/<exampledir>
                   +--- data/
                   |
                   +--- include/
                   |
                   |- README
                   |
                   |- cgal_test
                   |
                   |- makefile
                   |
                   |- *.C

The file 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.

4.4   demo subdirectory

The demo directory (Chapter 19) contains programs with graphical interfaces or programs requiring user input. These programs will be compiled but not run by the test suite. The structure of this directory should be as follows:

      demo/<demodir>
            +--- data/
            |
            +--- include/
            |
            |- README
            |
            |- makefile
            |
            |- *.C

The file README should contain information about what the program does, and how to compile it (i.e., what graphical libraries are needed, etc.). Note that, in contrast to example programs and test suite programs, for demo programs is it necessary to submit a makefile since different demos will require different libraries and thus the makefiles for these programs will be somewhat dissimilar.

4.5   Requirements and recommendations

Requirements:

• The directory structure outlined here must be followed exactly.

Recommendations:

• Do not submit makefiles for example programs and test suite programs.
• Do not submit the script cgal_test used to compile and test your test suite programs.