There are a number of tools that automate some of the tedious and error-prone tasks that are unavoidable when developing for CGAL. Most of these scripts can be in at least two places.
The shell script create_assertions.sh generates assertion header files. The command
create_assertions.sh minkowskicreates a file minkowski_assertions.h. This file is usually placed in directory include/CGAL and included in files that implement the minkowski package. The file contains several macros for adding checks (preconditions, postconditions, etc.) that can be switched on or off with compile flags. You can read more about the use of these package-level checks in Section 9.3.
CGAL source files should not contain line directives, even if they are made with the help of a literate programming tool like funnelweb. The script remove_line_directives can be used to remove lines starting with #line.
According to standard C++, when you include a header from the standard C library in the modern way (so, #include <cmath> instead of #include <math.h>), the C functions should be in the namespace std. Not all compilers conform to this. That's why CGAL has a macro, CGAL_CLIB_STD, that is set to std (for a conforming compiler) or to the empty string (for a non-conforming compiler). This macro should be prepended to all calls of functions from the C library. So, you should call CGAL_CLIB_STD::sin(x), not std::sin(x) or sin(x).
The perl script rename_clib_calls does this prepending. The script is idempotent, so applying it twice in a row does no harm. The script is not perfect, though. Especially, it recognizes complete words, but it does not discriminate between a function call and a variable or a word in a comment. You should check the differences of the modified file with the original file (which will be saved, with a .bak extension), for example with diff or xdiff.
Before using this script, you should edit the first line. This line states where your perl interpreter is located. The command which perl can help you to find out what to put there.
The shell script cgal_create_makefile creates a CGAL makefile in the current working directory. The makefile will have rules to make an executable from every .C file in the directory. The following options are available to indicate the kind of makefile to create:
You should use this script to create makefiles for testing before submitting your packages, but you should avoid customizing the makefile for your package and then submitting the makefiles for your test suite and example programs. Makefiles get created automatically when a release is made. This ensures that the most up-to-date makefiles are created. Experience has shown that makefiles need to be updated from time to time, especially if new compilers are supported. When makefiles are submitted as part of a package, they tend to get outdated. Moreover, creating a makefile that works for a diverse range of compilers is difficult.
The makefiles created by this script have two hooks for customization. If the directory where the makefile is created contains a directory named include, that directory will be on the header search path before any other files. This provides a means to override header files . Furthermore, the makefiles in the test suite (created with the -t option), contain the variable EXTRA_FLAGS. This variable can be set, e.g., as an environment variable in cgal_test, to add -I or -D options.
In every subdirectory of test there must be a shell script called cgal_test. This script is called from the run_testsuite script when the test suite is run. The script create_cgal_test will create the shell script cgal_test in the current directory.
As is the case with makefiles, this file will be generated automatically for each subdirectory of test if it is not supplied by the package. This is also the preferred way. So you should use create_cgal_test to test your package before submitting but generally should avoid submitting the file cgal_test. But sometimes you may want to do something extra in this script (e.g., set the EXTRA_FLAGS environment variable that is used in the makefile). In this case, you can run create_cgal_test yourself and edit the result. The generated file contains a header that lists the requirements a cgal_test program should fulfill. These are also listed in Section 4.1 with the description of the cgal_test script.
The shell script autotest_cgal is used to run automated test suites for the internal releases of the library. The script takes no command-line argument, but it is configurable using a .autocgalrc file stored in $HOME. It is meant to be run regularly by a cron job run by the testers.
This script allows you to run the testsuite on multiple hosts (remotely or locally) and multiple compiler-platforms. It is also possible to specify how many processors the host has and the script will use this information to run the testsuite process on several processors at the same time. By default, the number of processors assigned to every host is one.
In a couple of words, the script first downloads a file named LATEST that contains the current release file name. It compares it with the file RELEASE_NR in the $CGAL_ROOT directory and if it is different it starts the testsuite process : it downloads the internal release, unzips, untars, copies the configuration files, and starts the testsuite. When everything is done, it puts the results on some ftp server.
How to set up your local testing
The first step is to create a directory where you will store the releases. This directory is known in the script as $CGAL_ROOT. By default $CGAL_ROOT is the directory where you put the script autotest_cgal, but you may change it in .autocgalrc.
The next step is to download an internal release of your choice, say CGAL-3.1-I-xx, and install it on the various platforms you want it to be installed using the usual procedure with the install_cgal script. This will create the configuration files in the directory CGAL-3.1-I-xx/config/install/.
Then, create a symbolic link to this release using ln -s CGAL-3.1-I-xx CGAL-I. This link will be updated by autotest_cgal to point to the last installed release. You may remove older releases at some point.
The script uses wget to download the release. The different options you may pass to wget you should put in the WGET variable in .autocgalrc. By default, WGET=''wget''. We noticed that you must use a recent version of wget (1.9.1 is fine, but 1.8.2 is not). You must also create a file in your HOME called .wgetrc (alternatively, it is also possible to use another file by setting the WGETRC variable), that contains the following lines:
--http-user=member1 --http-passwd=xxxxxxx
Alternatively, you can use curl instead of wget. In order to do so, you need to add USE_CURL=''y'' to your .autocgalrc file. curl is then also used as a replacement for ftp for uploading the test results. You also have to add the following line in a file called HOME/.curlrc:
--user member1:xxxxxxx
The next step is to specify the name of the hosts. To do that, you must define the variable BUILD_HOSTS in the file .autocgalrc. For every host listed in BUILD_HOSTS you must also specify the variable COMPILERS_ as a list of OS-compiler descriptors for which the testsuite is to be run on .
Optionally, you can also specify a variable BUILD_ON_ as a list of OS-compiler descriptors for which the CGAL libraries are to be built on . If BUILD_ON_ is not defined, it defaults to the value of COMPILERS_. For obvious reasons, it is a good idea to keep the compilers in COMPILERS_ a subset of the compilers listed in BUILD_ON_. Setting BUILD_ON_ to all, invokes the install script with -rebuild-all and, therefore, builds CGAL using all compilers for which a matching config/install file is found.
Here is an example:
BUILD_HOSTS="papillon electra winmachine localhost"
COMPILERS_papillon="mips_IRIX64-6.5_CC-n32-7.30 mips_IRIX-6.5_g++-fsquangle-2.95.2"
COMPILERS_electra="sparc_SunOS-5.6_g++-2.95.2"
BUILD_ON_electra="sparc_SunOS-5.6_g++-2.95.2 sparc_SunOS-5.6_CC-5.80"
COMPILERS_winmachine="i686_CYGWINNT-5.0-1.3.22_CL.EXE-1300"
COMPILERS_localhost="i686_Linux-2.4.17_g++-3.4.0"
PROCESSORS_papillon="3"
BUILD_ON_papillon="all"
You should take those names from the configuration files mentioned
earlier. The PROCESSORS_hostname must be set if you have more
than one processor on that host and of course if you want to give all
of them to the testsuite. If you want to run the testsuite locally and
not remotely, name the host as localhost and the script will run
the testsuite locally for that host.
List of configurable variables
MYSHELL is a variable that must be defined in .autocgalrc, otherwise the script will not run. You can use it to pass environment variables along to remote hosts. Here is an example of MYSHELL variable :
MYSHELL="TERM=vt100 PATH=$PATH:/bin:/usr/local/bin:/usr/ccs/bin:/opt/SUNWspro/bin \ QTDIR=/usr/local/qt2 PARASOFT=/usr/local/parasoft /usr/local/bin/zsh -c\"
CGAL_URL is the URL where internal releases are available. The LATEST file is comming from the same location. If this will change, you may change either CGAL_URL, or LATEST_LOCATION in .autocgalrc.
TAR, GZIP, GUNZIP are the variables for compression and decompression tools. They are defaulted to tar, gzip, gunzip found in $PATH.
SENDMAIL has the default value ''mail''.
CGAL_TESTER has the default value `whoami`. It is used to identify the tester. You should specify a kind of login name for this variable.
CGAL_TESTER_NAME has the default value `whoami`. It is used to identify the tester. You should specify your full name for this variable.
CGAL_TESTER_ADDRESS has the default value `whoami`. It is used to identify the tester. You should specify your email address for this variable.
MAIL_ADDRESS has no value by default. In case you want to set it in .autocgalrc, the script will send an additional email to everyone mentioned in this variable.
LOGS_DIR has the default value $CGAL_ROOT/AUTOTEST_LOGS. This is used to keep local log files.
CONSOLE_OUTPUT has the default value ``y''. If you want that the script also shows messages to the console, the value is ``y'' otherwise the value should be ``''.
TEST_DIR_ROOT specifies where the test-suite will be copied before being run. For example, this can be set to /tmp, instead of the default which is $CGAL. This directory can be local to the testing machine.
USE_CURL specifies if curl should be used as a replacement for wget and ftp. Set it to ''y'' to use curl.
NICE_OPTIONS specifies the command line options to pass to the nice command, which is used to prevent the test-suite from keeping all CPU time for itself. The default value is ''-19''.
The perl script create_internal_module is used to generate independent modules from CGAL packages. This script was adapted from the script create_internal_release that is used to build CGAL internal releases. It generates modules from CGAL SVN packages.
To see a short list of possible parameters you may want to set, just run the script with no arguments.
You must have the packages you want to include in the module in one directory. You must create one file modules that contains the packages list that will go into the module itself.
Here is an example of using the script:
$ ./create_internal_module -a /cygdrive/d/CGALSVN -p modules -m Triangulation_module -s /cygdrive/d/CGALSVN/Scripts/scripts/ -r CGAL-3.1-I-76 -n 1003001076
The -a parameter is used to specify the directory that contains the packages. The -p parameter is used to specify the file containing the packages list. The -m parameter is used to specify the name of the module. If there is no m parameter, the default module name is NEW_MODULE. The parameter -r is used to specify the module version. The parameter -n is used to specify the module version number. If you don't use the -n parameter, the version number will be taken from the module version. The module version and version number will be used in the files version.h and version.tex. The -s parameter is used to specify the directory containing the scripts cgal_create_makefile, and all the other scripts that CGAL made public for users. This is not the package Scripts, but the scripts directory in the Scripts package.
You must have wininst package in the same directory with Scripts package because the script is looking for C2vcproj script used to generate the projects in examples for VC++.
The script also generates the makefiles in examples, which was done also by the mother script create_internal_release. This is done only if there is no makefile called makefile in the directory. The script behavior concerning the src dir of the module is as follows:
- when there is a src dir in the module it generates the makefile_lib file that is the makefile to build the CGAL library (only for the C files in the src dir).
- when there is no src directory it simply does nothing.
For the moment the script does not produce the tar.gz version of the module, this will be done in the future if it will be required.
This script is used to trigger the previous script create_internal_module. It looks in the $MODULES_DIRECTORY directory for all the files containing the packages list that should generate the module. For example if the $MODULES_DIRECTORY is ``Modules'', than it looks in the Modules directory for all the files. Each file in this directory represents a module to be created, the name of the file becoming the name of the module. Each file contains a list of packages, one package per line.
For each file in Modules directory, for each package enumerated in the file, it checks out or updates the package in the $SVNDIR. $SVNDIR represents the directory where you store the packages. It is the same as the ``All packages dir'' from the previous script.
Once the update process is done, it calls create_internal_module script with the right parameters.
The version and version number are preset and the way to determine those will be changed in the near future. I am just looking for the best way to do it.
This script can be used to check all files in an internal or external release for proper license notices. It reports all files without a proper notice. Observe that the check is fairly simple, we just grep through the files looking for a fixed string. Additionally, there might be provisions in the top-level LICENSE file that are not taken into account by this script.
Note that there might be license errors that are not detected by this script. For example, we do not check that files under LGPL and QPL are not mixed in one library.