Chapter 19
Example 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 4.3 and 4.4 for a description of the directory structure required for example and demo programs, respectively. Note in particular that each directory should contain a README file that explains what the programs do and how one interacts with them.

19.1   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 6) and good programming practice in these programs. In particular:

• Include a comment that gives the name of the file relative to the CGALROOT directory, such as:

           //
           // file : examples/Generator/random_polygon_ex.C
           //
           

• Do not use the commands

           using namespace CGAL;
           using namespace std;
           

  We discourage the use of these as they introduce more names than are necessary and may lead to more conflicts than are necessary.
• As of release 2.3, you can include only the kernel include file (e.g., Cartesian.h or Homogeneous.h) to get all kernel classes as well as the basic.h file. All example and demo programs should do this. For exmaple, you should have simply:

           #include <CGAL/Cartesian.h>
           

  instead of:

           #include <basic.h>
           #include <CGAL/Cartesian.h>
           #include <CGAL/Point_2.h>
           #include <CGAL/Triangle_2.h>
           #include <CGAL/Segment_3.h>
           // etc.
           

• Types should be declared using the following syntax:

           typedef CGAL::Cartesian<double>     Kernel;
           typedef Kernel::Point_2             Point_2;
           typedef Kernel::Triangle_3          Triangle_3;
           

  instead of this syntax:

           typedef CGAL::Cartesian<double>     Kernel;
           typedef Point_2<Kernel>             Point_2;
           typedef Triangle_3<Kernel>          Triangle_3;
           

  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

           typedef CGAL::Cartesian<double>     Kernel;
           

  instead of

           typedef CGAL::Cartesian<double>     R; // for representation
           

  This also reflects the new design, where the kernel classes are kernels containing objects and predicates not just representation classes for the objects.

19.2   The Programs

The following guidelines should be followed to the greatest extent possible when writing the example and demo programs.

• Provide simple programs with which a beginner can get started.
• Provide more involved programs that illustrate the power of the software.
• 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 randomly generated or user-generated data. This illustrates confidence in the software (and can also build confidence by highlighting bugs).
• Take some care to design a good interface to the program; the packaging of a product does make a difference.

19.3   Including programs in documentation

All programs included in the documentation should be included in either the examples or the demo directory to ensure that:

(a)
the programs will be included in the test suite and
(b)
the user can more easily use the example program

The reverse statement, that all programs in the examples and 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.

19.4   Demo programs on the web

We maintain a page of demo programs on the CGAL web site . For each demo on the page, we have a screen shot of the demo in action, a link to the source code, and 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:

1. Compile the demo and create a screen shot (as a .gif or .jpg file) and then create a smaller version of this (approx $$235 × 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: <program>_[big|small].[gif|jpg], where $$<prog_name$$> is the name of the program from which the screen shots were made (an nice menmonic name like alpha_shapes_2 or hull_of_int_points_2).

2. Create the .exe file for use under Windows (probably with the Borland compiler with optimization flags turned on)
3. gzip the .exe file
4. Package these together with the source code using the following structure:

             images/demo/<program>_big.[gif|jpg]
             demo/<program>.exe
             demo/<subdir>/<program>.C
         

   where <subdir> is the name of the subdirectory in which the program is (or will be) found in the distribution. <program> should be a name that is self-explanatory (e.g., demo.C is a bad name here).

5. Send the package to the web page maintainer together with a one-paragraph description similar to the ones on the page already.

19.5   Requirements and recommendations

Requirements:

• Follow the coding conventions outlined in Section 19.1.
• Include all example and demo programs from the documentation in the examples or demo directories.

Recommendations:

• Place a demo of your package on the web site.