Directory Structure for Packages

Table of Contents

• Directory structure
  • Obligatory
  • test subdirectory
  • examples subdirectory
  • demo subdirectory
  • benchmark subdirectory
• Shared data directory
• Requirements and recommendations

Name of a Package

Before detailing its structure, we must name the 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 Triangulation_2 for a package dealing with triangulations of points in the plane and Min_ellipse_2, which contains an algorithm that finds the minimal enclosing ellipse of a set of points in the plane. The package names pm and arr are a bit too terse. Planar_map and Arrangement (or Arrangement_2) are better.

Directory structure

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 copyright, description.txt, license.txt and maintainer are obligatory, see below.

A simple way to create such a directory structure is to call the script cgal_create_package_dir.

Submissions should not contain files in other places than described here. Make sure your package does not have any file clashing with any other packages (for example two files named 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:

+--- include/CGAL/
|
+--- src/{CGAL|CGALQt|...}/
|
+--- test/<testdir>/
|
+--- doc/
|
+--- examples/<exampledir>/
|
+--- demo/<demodir>/
|
+--- benchmark/<benchmarkdir>/
|
+--- auxiliary/
|
+--- scripts/
|
+--- developer_scripts/
|
+--- package_info/Package/
                         +- copyright
                         |
                         +- description.txt
                         |
                         +- license.txt
                         |
                         +- long_description.txt
                         |
                         +- maintainer
                         |
                         +- dependencies

• include/CGAL contains the .h files for the package.
• src/ contains the .cpp files (if any) for the package. They are gathered in subdirectories corresponding to each library (be it static or shared).
• test/ contains the test suite code for the package. See Section test subdirectory for a detailed description.
• doc/ 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 the Documentation Guidelines for a detailed description of this subdirectory.
• examples/ contains the example programs for the package. See Section examples subdirectory 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. Demo programs for 2D packages should instead be placed in the GraphicsView/ package. See Section demo subdirectory for a more detailed description of this subdirectory.
• benchmark/ contains the benchmark programs for the package. See Section benchmark subdirectory for a detailed description of this subdirectory.
• auxiliary/ contains auxiliary software for CGAL. For instance, GMP goes here when using the Windows installer. 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.

Obligatory

• package_info/Package/copyright Indicates who is holding the copyright of the package
• package_info/Package/description.txt should give a very short description of the contents of the package.
• package_info/Package/license.txt indicates the license of the package.
• package_info/Package/long_description.txt may be added with more detailed information about the package.
• package_info/Package/maintainer should be used to name the maintainers of the package. The file should have for each maintainer a line with the following format name <email address>. For example:

  Jenny Doe `<[email protected]>
  Adam Smithee `<[email protected]>

• package_info/Package/dependencies lists the CGAL packages whose headers are included by the package.

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 Testing

test/<testdir>/
              +--- data/
              |
              +--- include/
              |
              |- CMakeLists.txt
              |
              |- cgal_test
              |
              |- *.cpp
              |
              |- *.cin

where the directory <testdir> has a name that corresponds to the package name.

• 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. See also this section

• 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 (see here).

• CMakeLists.txt is the CMake configuration file for the test programs. Note that the project name used in CMakeLists.txt must be PKG_Tests. For example, it is project( Triangulation_2_Tests ) for the Triangulation_2 packages. Such a CMakeLists.txt can be created using the script cgal_create_cmake_script with the argument -t (see here).

• *.cpp source code for the test programs. When a test program runs correctly, it should return the value zero, or, more precisely, the value EXIT_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

examples subdirectory

Example programs (see Examples and Demo Programs) 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 test subdirectory).

The structure of an example directory should be as follows:

examples/<exampledir>/
                     +--- data/
                     |
                     +--- include/
                     |
                     |- README
                     |
                     |- cgal_test
                     |
                     |- CMakeLists.txt
                     |
                     |- *.cpp

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.

Note that the project name used in CMakeLists.txt must be PKG_Examples. For example, it is project( Triangulation_2_Examples ) for the Triangulation_2 packages.

demo subdirectory

The demo directory (see Examples and Demo Programs) contains programs with graphical interfaces or programs requiring user input. These programs will be compiled but not run by the test suite.

Note that if 3D packages have their own demo directory, 2D packages have theirs located in GraphicsView/demo/.

The structure of this directory should be as follows:

demo/<demodir>/
              +--- data/
              |
              +--- include/
              |
              |- README
              |
              |- CMakeLists.txt
              |
              |- *.cpp

where <demodir> is a name that corresponds (at least in part) to the package for which it is a demo.

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 and test programs, demo programs more often need to submit a CMakeLists.txt since different demos will require different libraries and thus the CMakeLists.txt for these programs will be somewhat dissimilar.

benchmark subdirectory

Benchmark programs for a package should be placed in a subdirectory of the directory benchmark. The subdirectory name, <benchmarkdir>, will usually correspond to the package name, but this is not a requirement. Benchmark programs are currently not subject to any automatic treatment in the test-suite, although they could evolve into an automatic benchmark-suite at some point. We suggest at directory organization similar to the one of <exampledir>.

Some data sets can be placed under the data subdirectory of <benchmarkdir>, but we recommend that only a small number of small files go there. Extensive benchmarks data sets should probably be gathered elsewhere, so as not to bloat the SCM repository. See also this section.

Shared data directory

Since CGAL 5.4, to avoid the need to duplicate data files amongst example and test directories of packages, the function CGAL::data_file_path() has been introduced. This function appends a prefix to a file so as to point to the data directory at the root of a release or to the Data/data directory of a git branch checkout. At the time these lines are written, the data directory contains meshes, 3D point sets, and 3D images. The rule used for the migration of those files is the following: any such data from an example or a demo directory is moved in the data directory, a data file from a test will be moved only if it is duplicated in several test directories. Any file that is of general interest and that is used in a single test can be moved into the data directory. New categories can be created if relevant (2D polygons, ...).

Requirements and recommendations

Requirements:

• The directory structure outlined here must be followed exactly.

Recommendations:

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