songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

import of the wiki

Sebastien Loriot 2016-09-09 13:08:09 +02:00
parent cd2d7d0cda
commit 1cccfa9254
37 changed files with 6177 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
Git-transport.png Normal file

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

229
Guidelines/Branch-Build.md Normal file

@ -0,0 +1,229 @@
<!--TOC-->
# Table of Contents
* [Building CGAL Libraries and Executables based on CGAL](#building-cgal-libraries-and-executables-based-on-cgal)
* [Example](#example)
* [Branch Build of CGAL](#branch-build-of-cgal)
* [Preamble: Options for `cmake`](#preamble-options-for-cmake)
* [Building locally to the working copy](#building-locally-to-the-working-copy)
* [Using a single version of CGAL](#using-a-single-version-of-cgal)
* [Using multiple versions of CGAL](#using-multiple-versions-of-cgal)
* [Building Adam's demo](#building-adam's-demo)
* [No installation required](#no-installation-required)
<!--TOC-->
## Building CGAL Libraries and Executables based on CGAL
Internal releases of CGAL are created every night and distributed in
forms of tarballs. They reflect the current status of the branch `integration`
with all branches of candidate features merged into it; see
[Testsuite](Developing-Features-with-Git#integrating-the-feature-branch-and-adding-it-to-the-testsuite)
for details. You can obtain a public or an internal distribution of CGAL
and build it using the [distribution build procedure](http://doc.cgal.org/latest/Manual/installation.html),
in particular if your goal is to build executables. However, as
developer, building CGAL using the branch build presented here is
recommended. It keeps the build-sources attached to the [Source Code Management](Source-Code-Management-with-Git). A
developer, let's call her Jenny, can build CGAL from [any branch](Source-Code-Management-with-Git#branches)
accessible through a proper SCM client. This way Jenny can modify CGAL
sources and test them without disturbing other developers and without
disturbance from other developers, and at the same time keep (modified)
CGAL sources in sync with an SCM repository and in turn with other
developers. This documentation mainly discusses how to generate Unix
Makefiles with CMake; however other generators are supported by CMake,
too. In general, it is also advised to be familiar with the
[distribution build procedure](http://doc.cgal.org/latest/Manual/installation.html),
as the branch-build only selects another path to the main
`CMakeLists.txt` file (i.e., picks it "from a branch" instead of "from a
distribution").
## Example
Assume that Jenny wants to try the new cool feature developed by Adam
about coloring 2D triangulations. Adam is developing his feature in the
branch `Triangulation_2-coloring-adam`. Jenny got a working copy of
`next` (or of a different branch, e.g., any of her feature branches),
e.g., by calling
``` {.bash}
> cd /path/to/my/cgal_repository/
> git checkout Triangulation_2-coloring-adam
> git branch
master
* Triangulation_2-coloring-adam
...
```
**Jenny aims to compile a demo in that branch using the headers from the
branch and the CGAL libraries built from the sources contained in the
branch.** Learn next how Jenny does it.
## Branch Build of CGAL
Jenny has many options to use the *branch build* to build CGAL and then
compile some examples. The build is categorized either as in-source or
out-source. The former means that generated directories, generated
files, and the sources are placed side by side. The latter means that
generated directories and files are placed under a completely different
directory, which, for example, can be removed when not needed without
any impact on the sources. Among the different options, the in-source
option is, while possible, less typical. Thus, it is not described here.
Jenny can choose among three typical use-cases. Each case has advantages
and disadvantages, and the preferred choice depends on how Jenny's daily
work looks like.
### Preamble: Options for `cmake`
All three have in common that Jenny might enhance the calls to `cmake`
with platform-specific options or other flags as switching on or off
components of CGAL, e.g.,
``` {.bash}
-DWITH_CGAL_Core=ON -DWITH_CGAL_Qt5=ON -DWITH_CGAL_ImageIO=ON -DWITH_examples=OFF -DWITH_demos=OFF
```
or configuring external libraries, e.g.,
``` {.bash}
-DWITH_MPFI=ON -DWITH_RS=ON -DWITH_LEDA=ON -DLEDA_CXX_FLAGS=-ffriend-injection -DLEDA_INCLUDE_DIR=$EXACUS_LEDA/incl/ -DLEDA_LIBRARIES=$EXACUS_LEDA/libleda.so -DLEDA_LINKER_FLAGS=-lX11
```
or any other option valid for `cmake`, e.g.
``` {.bash}
-DCMAKE_BUILD_TYPE=Debug
```
All possible options and external libraries can be found in the
[Installation manual](http://doc.cgal.org/latest/Manual/installation.html#title22).
So, assume next that Jenny knows the options according to her platform
and liking when calling `cmake`. For simplicity, these options are not
mentioned in the next examples.
Those options can also be set using the CMake GUI `cmake-gui`.
### Building locally to the working copy
Jenny can set `$CGAL_DIR` to `/path/to/my/cgal_repository/build`. It
couples the sources and the build closer while still having an
out-of-source-build.
``` {.bash}
> mkdir /path/to/my/cgal_repository/build
> cd /path/to/my/cgal_repository/build
> cmake ..
> make
> export CGAL_DIR=/path/to/my/cgal_repository/build
```
### Using a single version of CGAL
For many packages there is no trace of the package code in the CGAL
library objects, as the entire code of the packages resides only in
header files. As a matter of fact, the library objects themselves are
very thin and thus building CGAL is a quick process and the generated
library objects consume little space. In many cases it is sufficient to
maintain a single version of CGAL at any time, for example, when only a
single feature is developed, when several features are developed in
parallel but the different corresponding branches can share a common
version of CGAL, or when several features are developed in a single
working directory and the corresponding branches are switched rarely. In
such cases the environment variable <CGAL_DIR>, which points to the
build target directory, is set once and never changes.
Assume that Jenny would like to build CGAL from her local
repositorylocated at `/path/to/my/cgal_repository` and place the result
of the build in `~/CGAL/build`. She issue the following commands:
``` {.bash}
> export CGAL_DIR=$HOME/CGAL/build
> cd $CGAL_DIR
> cmake /path/to/my/cgal_repository
> make
```
### Using multiple versions of CGAL
In this setup, Jenny develops several features and often switches
between the corresponding branches in repository. She would like to keep
a build version of CGAL for each of the features she is developing.
Thus, for a branch `Triangulation_2-colored-adam` she builds CGAL in
`~/CGAL/builds/Triangulation_2-colored-adam`.
``` {.bash}
> mkdir ~/CGAL/builds/Triangulation_2-colored-adam
> cd ~/CGAL/builds/Triangulation_2-colored-adam
> cmake /path/to/my/cgal_repository
> make
> export CGAL_DIR=~/CGAL/builds/Triangulation_2-colored-adam
```
In such a setup she probably keeps a build of CGAL for each branch:
``` {.bash}
> ls ~/CGAL/builds
Convex_hull_4-jenny
Convex_hull_2-make_it_faster-jenny
```
Jenny only has to set `$CGAL_DIR` to the build she wants to use before
building a demo
``` {.bash}
> export CGAL_DIR=~/CGAL/builds/Convex_hull_2-make_it_faster-jenny
```
## Building Adam's demo
Now with properly set `$CGAL_DIR` it's time for Jenny to build a demo
contained from another branch in the local repository:
``` {.bash}
> cd /path/to/my/cgal_repository/Triangulation_2/demo/Triangulation_2/
> git branch
master
* Triangulation_2-coloring-adam
...
> ls
CMakeLists.txt colored_t2.cpp
```
It might be required to generate the file `CMakeLists.txt`. This can be
done with the script [`cgal_create_cmake_script`](Scripts#cgal_create_cmake_script-same-as-cgal_create_cmakelists)
found in `/path/to/my/cgal/Scripts/scripts/`. Then call:
``` {.bash}
> cmake .
> make
> ./colored_t2
```
'''The important fact is that all headers are taken from the working copy
that have been used while building CGAL in the current `$CGAL_DIR`.
Remarks on this:
- A build may be outdated after an include/dir has been deleted,
switched or even updated. This might lead to compile problems (link
with outdated version). Thus, it is recommended to build CGAL after
each update, switch, merge of a branch (in particular if directories
have been added/deleted, or cpp files have been added, deleted or
altered).
- There is currently no warning that a build does not match the
branch. However, a little experience helps to be aware of this
problem.
- It might be possible to add such a warning (work in progress).
Finally, she's happy about Adam's cute pictures.
## No installation required
When you install CGAL (using `make install`), you copy all generated
library-objects and header files from the branch to a predefined
directory, `CMAKE_INSTALLATION_PREFIX`. Then, if you want to use the
installed version, you need to set
`$CGAL_DIR=$CMAKE_INSTALLATION_PREFIX` accordingly, thereby detaching
the installed files from the branch and loosing the connection to the
source-code management system. For most purposes there is no need to
install CGAL.

345
Guidelines/Concurrency-in-CGAL.md Normal file

@ -0,0 +1,345 @@
<!--TOC-->
# Table of Contents
* [Which library?](#which-library)
* [License](#license)
* [Guidelines for developers](#guidelines-for-developers)
* [Changes in the CMake process](#changes-in-the-cmake-process)
* [Which mechanism to enable or disable parallelism](#which-mechanism-to-enable-or-disable-parallelism)
* [Advanced TBB configuration](#advanced-tbb-configuration)
<!--TOC-->
## Which library?
[Intel TBB](https://www.threadingbuildingblocks.org/) is the library
which is used for parallel programming in CGAL. It provides thread
support, atomic operations, task-based parallelism support, concurrent
containers and high-level tools (scalable memory allocators, parallel
sorts, etc.)
Intel TBB is designed and optimized for task-based programming. Several
layers are available.
- For simple cases, it provides a high-level API (`parallel_for`,
`parallel_do`, etc.).
- For more complex cases, the developer has access to tasks and can
control the task-scheduler behavior.
- And if the user wants even more control, threads can be created and
managed "by hand".
If one combines several algorithms/packages which use Intel TBB for
task-based programming, the number of threads used by each component is
automatically adjusted so that the total number of threads matches the
number of available hardware threads.
As a result, we **strongly suggest** that developers use **Intel TBB**
instead of any other library, at least for thread-related features. For
other features such as atomics, thread-local storage or locks, C++11
could be used as an alternative in the future when CGAL officially
supports C++11, since it can be safely mixed with Intel TBB. Note that
Intel TBB's API is very close to C++11 for those features.
Nevertheless, if one needs another library for a good reason, we don't
strictly forbid it as long as it is thoroughly documented and as long as
it provides control on the number of threads used. But the developer
must know that, doing so, it prevents its algorithm to be easily
nested/mixed with other parallel algorithms. For this reason, this
choice will have to appear and to be justified in the feature
submission, and the reviewers are allowed to challenge it.
## License
TBB is dual-licensed: GPLv2 with the libstdC++ Runtime Exception or
commercial COM license ([see here](https://www.threadingbuildingblocks.org/Licensing) and
[here](http://www.threadingbuildingblocks.org/faq/10)).
## Guidelines for developers
For developers who are new to TBB, we recommend to visit the
[TBB documentation page](https://www.threadingbuildingblocks.org/documentation) and read:
- *User guide*: learn how to use Intel TBB, with examples and code
samples. It goes through the main features of TBB. A must-read.
- *Design Patterns*: a cookbook of common parallel design patterns and
how to implement them in TBB. You will probably find here a useful
recipe to get inspiration.
- *Reference Manual*.
- And don’t forget the codes samples which come with TBB.
Here is a quick checklist of TBB key features that a developer should
know:
- High-level TBB mechanisms (parallel\_for, parallel\_do)
- Parallel containers (concurrent\_vector, concurrent\_queue...), with
a special attention to operations which are concurrently callable
(e.g. concurrent\_vector::push\_back) and operations which are not
(e.g. concurrent\_vector::clear)
- Mutual exclusion (different kind of mutexes) and its pathologies
(e.g. deadlocks).
- [More advanced] Atomics, TBB task-scheduler
Note that TBB provides concurrency-optimized allocators. We advice the
developers to [try them](https://software.intel.com/en-us/node/506094).
## Changes in the CMake process
In order to easily link with TBB, we provide a FindTBB CMake module.
Thus, the developer of a demo/example/test using parallel code needs to
add the following lines *after* `include(${CGAL_USE_FILE})` in the
`CMakeLists.txt` file:
``` {.bash}
# Activate concurrency?
option(ACTIVATE_CONCURRENCY
"Enable concurrency"
ON)
if( ACTIVATE_CONCURRENCY )
find_package( TBB REQUIRED )
if( TBB_FOUND )
include(${TBB_USE_FILE})
target_link_libraries(the_target ${TBB_LIBRARIES})
endif()
endif()
```
Note: If you are using `create_single_source_cgal_program`, replace
the `target_link_libraries` call by:
``` {.bash}
list(APPEND CGAL_3RD_PARTY_LIBRARIES ${TBB_LIBRARIES})
```
Remarks:
- External users using headers with concurrency-enabled code also have
to ensure to give the right parameters to the compiler.
- In case we go for CTest, tests there can have properties: PROCESSORS
and RUN\_SERIAL, which should be set when testing parallized code.
## Which mechanism to enable or disable parallelism
When CMake finds TBB and links it to the program, the
`CGAL_LINKED_WITH_TBB` macro is defined. To use the parallel version of
an algorithm, two conditions must be fulfilled:
- `CGAL_LINKED_WITH_TBB` is defined
- The user requests the parallel version (see below to know how)
If one of these conditions is not true, the package must automatically
fall back on the sequential version.
Note that we need to keep a sequential version (i.e. we don't want to
rely on TBB to automatically fall back on a sequential version) for
several reasons:
- One should be able to build CGAL without TBB installed
- We don't want a hard dependency to TBB
- The automatic TBB fallback won't probably be as fast as a true
sequential code (but you may not notice the difference)
**Tag dispatching** must be used to allow the user to enable/disable
concurrency. Compared to macros (\#ifdef), it allows to use sequential
and parallel versions in the same application. Several techniques are
available for this, and the developer can choose whatever is best in his
case:
- Tag dispatching by **Type** or by **Instance**.
- Non-type template parameters (`bool`, `enum`…)
In `<CGAL/tags.h>`, two tags are defined: Sequential\_tag and
Parallel\_tag.
``` {.cpp}
struct Sequential_tag {};
struct Parallel_tag : public Sequential_tag {};
```
The developers should use them (and no other custom tag) in order to
keep a good consistency among packages.
Here are a few code samples showing different ways to use tag
dispatching. These examples are just here as a "quick-start guide" and
are not exhaustive, there may be more complex scenarii involving tag
dispatching. Please note that we combine "`#ifdef CGAL_LINKED_WITH_TBB`"
and tag dispatching to test both conditions. As long as
`CGAL_LINKED_WITH_TBB` is defined, both sequential and parallel versions
can be used in the same program, depending on the tag used.
**By Type**
``` {.cpp}
// Default: sequential
template <typename Concurrency_tag = Sequential_tag >
class Foo
{
public:
void Bar() { std::cout << "Hello sequential world" << std::endl; }
};
#ifdef CGAL_LINKED_WITH_TBB
// Parallel
template <>
class Foo<Parallel_tag>
{
public:
void Bar() { std::cout << "Hello parallel world" << std::endl; }
};
#endif // CGAL_LINKED_WITH_TBB
int main(void)
{
Foo<> f1; // Sequential_tag is used by default
Foo<Parallel_tag> f2;
f1.Bar(); // Calls the sequential version
f2.Bar(); // Calls the parallel version
return 0;
}
```
Note: If the developer is using custom tags inherited from
Parallel\_tag, he must provide one specialization by tag.
**By Instance**
``` {.cpp}
// Default: sequential
template <typename Concurrency_tag = Sequential_tag >
class Foo
{
protected:
void Bar_dispatch(Sequential_tag)
{
std::cout << "Hello sequential world" << std::endl;
}
#ifdef CGAL_LINKED_WITH_TBB
void Bar_dispatch(Parallel_tag)
{
std::cout << "Hello parallel world" << std::endl;
}
#endif //CGAL_LINKED_WITH_TBB
public:
void Bar()
{
#ifdef CGAL_LINKED_WITH_TBB
Bar_dispatch(Concurrency_tag());
#else //!CGAL_LINKED_WITH_TBB
// If TBB is not available, we fall back on the sequential function
Bar_dispatch(Sequential_tag());
#endif //CGAL_LINKED_WITH_TBB
}
};
int main(void)
{
Foo<> f1; // Sequential_tag is used by default
Foo<Parallel_tag> f2;
f1.Bar(); // Calls the sequential version
f2.Bar(); // Calls the parallel version
return 0;
}
```
**Using is\_convertible**
Note that it makes it possible to have some inheritage amongst tags.
``` {.cpp}
// Default: sequential
template <typename Concurrency_tag = Sequential_tag>
class Foo
{
public:
void Bar()
{
#ifdef CGAL_LINKED_WITH_TBB
// Parallel
if (boost::is_convertible<Concurrency_tag, Parallel_tag>::value)
{
std::cout << "Hello parallel world" << std::endl;
}
// Sequential
else
#endif // CGAL_LINKED_WITH_TBB
{
std::cout << "Hello sequential world" << std::endl;
}
}
};
int main(void)
{
Foo<> f1; // Sequential_tag is used by default
Foo<Parallel_tag> f2;
f1.Bar(); // Calls the sequential version
f2.Bar(); // Calls the parallel version
return 0;
}
```
**Using non-type template parameters**
``` {.cpp}
// Default: sequential
template <bool Is_parallel = false>
class Foo
{
public:
void Bar()
{
#ifdef CGAL_LINKED_WITH_TBB
// Parallel
if (Is_parallel)
{
std::cout << "Hello parallel world" << std::endl;
}
// Sequential
else
#endif // CGAL_LINKED_WITH_TBB
{
std::cout << "Hello sequential world" << std::endl;
}
}
};
int main(void)
{
Foo<> f1; // Is_parallel = false by default
Foo<true> f2;
f1.Bar(); // Calls the sequential version
f2.Bar(); // Calls the parallel version
return 0;
}
```
Note: this is for internal use only. Documented classes must use
Sequential\_tag/Parallel\_tag.
Of course, more advanced techniques may be used – e.g.: specialized base
classes to provide different member variables.
## Advanced TBB configuration
An advanced user may want to specify the number of threads used by TBB.
This control is provided by the [`tbb::task_scheduler_init` class](https://software.intel.com/en-us/node/506294).
TBB automatically creates a task scheduler the first time that a thread
uses task scheduling services and destroys it when the last such thread
exits. Instead, an instance of task\_scheduler\_init might be manually
created by the user to control, among other things, the number of
threads used by the task scheduler. Here is an example:
` {`\
`   tbb::task_scheduler_init tsi(6); // 6 threads`\
`   run_parallel_algo1(); // Uses 6 threads`\
` }`\
` {`\
`   tbb::task_scheduler_init tsi(12); // 12 threads`\
`   run_parallel_algo2(); // Uses 12 threads`\
` }`
See [Intel documentation](https://software.intel.com/en-us/node/506294)
for more information.

293
Guidelines/Directory-Structure-for-Packages.md Normal file

@ -0,0 +1,293 @@
<!--TOC-->
# Table of Contents
* [Directory structure](#directory-structure)
* [Obligatory](#obligatory)
* [`test` subdirectory](#test-subdirectory)
* [`examples` subdirectory](#examples-subdirectory)
* [`demo` subdirectory](#demo-subdirectory)
* [`benchmark` subdirectory](#benchmark-subdirectory)
* [Requirements and recommendations](#requirements-and-recommendations)
<!--TOC-->
## 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](#obligatory).
Submissions should not contain files in other places than described
here. It is possible to have some under SCM, but they need to be listed
in the `dont_submit` file to avoid being submitted. 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:
```
+--- dont_submit
|
+--- 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
```
- `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](#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](Documentation-Guidelines)
for a detailed description of this subdirectory.
- `examples/`
contains the example programs for the package. See Section
[`examples` subdirectory](#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. See Section [`demo` subdirectory](#demo-subdirectory) for a more detailed
description of this subdirectory.
- `benchmark/`
contains the benchmark programs for the package. See Section
[`benchmark` subdirectory](#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.
- `dont_submit`
specifies files and directories that are to be excluded from the
release, for example:
- `TODO`
- `include/CGAL/my_internal_file.h`
- `benchmark/`
### 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 `<jenny@mpi-sb.mpg.de>
 Adam Smithee `<adam.smith@inria.fr>
```
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.
### `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](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.
- `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](Scripts#create_cgal_test_with_cmake)).
- `CMakeLists.txt`
is the CMake configuration file for the test programs. It is
created automatically, just like `cgal_test`. Submitting it is
**strongly discouraged**, and the only reason for submitting one is
when the automatic generation script cannot produce a working CMake
configuration file. Such a `CMakeLists.txt` can be created using the
script `cgal_create_cmake_script` with the argument `-t` (see
[here](Scripts#cgal_create_cmake_script-same-as-cgal_create_cmakelists)).
- `*.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](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](#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.
### `demo` subdirectory
The `demo` directory (see [Examples and Demo
Programs](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. 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.
## Requirements and recommendations
Requirements:
- The directory structure outlined here must be followed exactly.
Recommendations:
- Do not submit `CMakeLists.txt`s for example programs and test suite
programs.
- Do not submit the script `cgal_test` used to compile and test your
test suite programs.

274
Guidelines/Doxygen_specification/Building-the-Documentation.md Normal file

@ -0,0 +1,274 @@
<!--TOC-->
# Table of Contents
* [Getting and Installing the Tools](#getting-and-installing-the-tools)
* [doxygen](#doxygen)
* [Syntax Highlighting](#syntax-highlighting)
* [MathJax](#mathjax)
* [Building The Documentation](#building-the-documentation)
* [Building Only a Single Package](#building-only-a-single-package)
* [Looking at the Result](#looking-at-the-result)
* [Html output postprocessing: `html_output_post_processing.py`](#html-output-postprocessing-html_output_post_processingpy)
* [Getting it to work on Windows](#getting-it-to-work-on-windows)
* [Testing the Documentation](#testing-the-documentation)
* [Releasing the Documentation](#releasing-the-documentation)
* [Changing things](#changing-things)
* [PDF Output](#pdf-output)
* [Using Doxygen](#using-doxygen)
* [Alternative (linux,windows)](#alternative-linuxwindows)
<!--TOC-->
## Getting and Installing the Tools
For building the CGAL documentation we use two tools. in the following
documentation, we use `/path/to/branch` to refer to the path where you
have a checkout of your git branch on your disk.
### doxygen
`doxygen` generates documentation for individual CGAL packages.
We currently added a few features and fixes to doxygen, which we
communicate to the author to get them included upstream. The official
documentation is built with this patched version while all the
patches are not integrated in the official release. If you want you can
try it, (but this is not needed to build a correct version of your
documentation). See `https://github.com/CGAL/doxygen`. A windows
executable is available [here](doxygen-1.8.4-patched.gz)
- doxygen 1.8.11 (+1.8.12) generates an incomplete website: the treeview is missing.
Maybe our hackery is incompatible? Also too many things are exported in
tags. Only two consecutive runs doxygen can be done. After that the tag
files must be deleted to avoid many warnings.
- doxygen 1.8.10 generates an incomplete website: the treeview is missing.
- doxygen 1.8.8 gives a segmentation fault.
- doxygen 1.8.5 has a bug and cannot build correctly the target `BGL_doc`
after some tag files exists (it will fill the memory before crashing).
The only remaining extra patch correspond to this bug report: [`502d15f`](https://bugzilla.gnome.org/show_bug.cgi?id=684978) Bug 684978 - `EXTRACT_ALL` creates superfluous detail sections. See also this [PR](https://github.com/doxygen/doxygen/pull/452).
There is also the current [bug report](https://bugzilla.gnome.org/show_bug.cgi?id=770973)
about a blocking issue found in the 1.8.12 version.
#### Syntax Highlighting
- Microsoft provides a
[plugin](https://visualstudiogallery.msdn.microsoft.com/11a30c1c-593b-4399-a702-f23a56dd8548)
for Visual Studio for syntax highlighting.
- On Emacs there is [doxymacs](http://doxymacs.sourceforge.net/).
### MathJax
MathJax is required to be installed if you need to have typeset formulas
without an internet connection.
- get MathJax:
`git clone git://github.com/mathjax/MathJax.git /path/to/MathJax`
- to configure the documentation to build with your local MathJax,
change the CMake variable `CGAL_DOC_MATHJAX_LOCATION` to point to
your locale MathJax
<b>Note:</b>
- For alternative methods to get MathJax see
[here](https://docs.mathjax.org/en/latest/installation.html).
- You have the possibility to disable MathJax and use fixed size
bitmap by setting `USE_MATHJAX = NO` in the config file
`/path/to/branch/Documentation/BaseDoxyfile.in`.
## Building The Documentation
To build the documentation on Unix:
``` {.bash}
cd /path/to/cgal/build/dir
cmake -DBUILD_DOC:BOOL=ON /path/to/cgal/ # if not already done
make doc
```
If `make` does not find target "doc", it is probably because your
branch is too old. Try: `make Documentation_doc`.
To build the documentation with Visual Studio build the `doc` target in
Visual Studio.
With a self-built Doxygen, or with Doxygen from MacPorts
(`/opt/local/bin/doxygen`) you will probably need to adjust the CMake
variable `DOXYGEN_EXECUTABLE` to point to the right location.
After that, a single run suffices.
This will generate the output for each package and a master package with
the Introduction, Preliminaries, and Installation manuals and a complete
index.
### Building Only a Single Package
Often you only want to work on one package and building the whole
documentation would take longer than you would like. To do this:
``` {.bash}
# in /path/to/cgal/build/dir
make My_package_doc
```
in Visual Studio build the target `My_package_doc`.
Doing this requires that the `doc` target has been built twice before.
In case you are working on a new package, make sure that you followed
the steps discussed
[here](Writing-Documentation#new-packages-and-doxygen-configuration).
### Looking at the Result
The result will be stored in `/path/to/cgal/build/dir/doc_output/`. The
main entry point is:
`/path/to/cgal/build/dir/doc_output/Manual/index.html`. The
documentation of a respective package can be found under
`/path/to/cgal/build/dir/doc_output/My_package/index.html`.
### Html output postprocessing: `html_output_post_processing.py`
The postprocessing of the html output is triggered by building the
target <b>`doc_with_postprocessing`</b>:
``` {.bash}
# in /path/to/cgal/build/dir
make doc_with_postprocessing
```
Internally, the script `html_output_post_processing.py` is used to do
some output cleaning in the html output of doxygen. This script:
- turns specific classes into concepts.
- performs some scrubbing of the documentation to remove duplicate
files, small glitches and the like.
- uses special icons in `Concept and class list` pages
- numbers the figures using CGAL doxygen macros
This script requires at least Python 2 and the library
[PyQuery](http://pypi.python.org/pypi/pyquery), and
[python-lxml](http://lxml.de/installation.html) v2.3.2 (or higher). To
check which python executable is used, you can check in your
`CMakeCache.txt` the value of `PYTHON_EXECUTABLE`.
Note that [pip](http://www.pip-installer.org/en/latest/) is a solution
to install python dependencies on machine you do not administrate.
#### Getting it to work on Windows
Getting the postprocessing working on Windows we didn't check with `pip`
yet, but we used `easy_install` instead.
- *The recommended way to install setuptools on Windows is to download
`ez_setup.py` and run it. The script will download the appropriate
.egg file and install it for you.*
[1](https://pypi.python.org/pypi/setuptools#windows)
[2](https://bootstrap.pypa.io/ez_setup.py)
- Install the C++ libraries `libxml` and `libxslt`. As written on
[3](http://www.xmlsoft.org/downloads.html) Igor Zlatkovic is now the
maintainer of the Windows port, he provides binaries.
[4](http://www.zlatkovic.com/libxml.en.html)
- Add in `PATH` `C:\Python27`, `C:\Python27\Scripts`, and the `bin`
directory of `libxml/libxslt`
- In a `cmd.exe`
- run `easy_install lxml==2.3` to install the python bindings of
libxml (the version is fixed to `2.3` as it is broken for the
latest version)
- run `easy_install pyquery` to install the pyquery package
To check everything is fine, you can run in a `cmd`
``` {.bash}
> python
>>> import lxml
>>> import pyquery
```
### Testing the Documentation
To create a small HTML overview detailing errors and warnings when
building the documentation use:
``` {.bash}
cd /path/to/cgal/build/dir
cmake -DBUILD_DOC:BOOL=ON -DCGAL_DOC_CREATE_LOGS:BOOL=TRUE /path/to/cgal/
make doc_and_publish_testsuite
```
### Releasing the Documentation
Use
`cmake -DBUILD_DOC:BOOL=ON -DCGAL_DOC_RELEASE:BOOL=TRUE .. -DCGAL_DOC_MATHJAX_LOCATION:STRING=../../MathJax `
if you intend to make public the documentation.
- The flag `CGAL_DOC_RELEASE` removes TODO-list, bug-list,...
- The path related to MathJax indicates the relative location from a
package directory (for example <http://doc.cgal.org/4.3/Kernel_23/>,
or `doc_output/Manual` in your local build) to a local MathJax
checkout on the server. This is required in particular when using
`https`. Modern browsers protect users by disabling any `http` (like
MathJax CDN) included in a `https` page.
### Changing things
The file `Documentation/Customizations.txt` contains a detailed list of
the customizations that are applied to doxygen. It should be maintained
if things are changed.
### PDF Output
Please note that the pdf output is not yet bug-free and largely a work
in progress.
#### Using Doxygen
In case you want the PDF output of your package:
1. in `Documentation/BaseDoxyfile.in` set the option `GENERATE_LATEX`
to `YES`
2. build targets as before
3. `cd doc_output/Package_name/latex`
4. `make`
Please note that the pdf output is not yet bug-free and largely a work
in progress.
#### Alternative (linux,windows)
Another option is to use the html to create a pdf.
Open in a new firefox window the user manual and the classified ref man.
Open in different tabs, all the pages you want to print.
You can then use the [firefox extension "Print pages to PDF"](https://addons.mozilla.org/fr/firefox/addon/print-pages-to-pdf/)
to print all the tabs into one pdf. In the preferences of that firefox
extension, make sure that the checkbox `PrintMedia` of the [tab `Pdf (webpage)->Styling`](http://printpdf.pf-control.de/index.php/en/styling/articles/styleing-preferences.html)
is checked. That option instructs the extension to print using the CSS
style dedicated to "print" media (in Doxygen, that tweaks several
things, and particularly the navigation box is hidden).
An example of the result can be found
[here](https://cgal.geometryfactory.com/CGAL/Members/wiki-images/1/17/Deformation-man-v3.pdf).
- Issue with MathJax Formulas:
- There are issues with missing MathJax formulas on some machines
and we have not figured the reason for this yet.
- Solution 1: disable MathJax globally or in your package. Just
modifying `PackageName/doc/PackageName/Doxyfile.in`, i.e.,
adding line
```
Don't commit this change
USE_MATHJAX = NO
```
- Solution 2: Ask somebody else to print for you and get the nicer
formulas.

5
Guidelines/Doxygen_specification/Documentation-Guidelines.md Normal file

@ -0,0 +1,5 @@
[Writing Documentation](Writing-Documentation) : How to write Documentation for `CGAL` and a list of Doxygen resources
[Building the Documentation](Building-the-Documentation) : How to build the Documentation and the involved tools
[Doxygen FAQ](Doxygen-FAQ) : Common issues and guidelines for using Doxygen

116
Guidelines/Doxygen_specification/Doxygen-FAQ.md Normal file

@ -0,0 +1,116 @@
<!--TOC-->
# Table of Contents
* [Linkage](#linkage)
* [Placing images in specific ways](#placing-images-in-specific-ways)
* [ccVar](#ccvar)
* [Groups](#groups)
* [Words in mathmode](#words-in-mathmode)
* [Mixing dummy headers and real documentation](#mixing-dummy-headers-and-real-documentation)
* [Deprecation](#deprecation)
<!--TOC-->
## Linkage
Doxygen uses different ways to link to link symbol names to
documentation pages. Understanding
[auto-linking](http://www.stack.nl/~dimitri/doxygen/autolink.html) saves
a lot of trouble when adapting documentation.
One main difference to the old tools is the way doxygen links to nested
types. In CGAL, a link to nested type would usually be
`\ccc{Foo<Bar>::Nested}` whereas doxygen requires the link to be
`` `Foo::Nested` `` or just `Foo::Nested`.
**Problem**
<br>&nbsp;&nbsp; Missing link for `\cgalHasModel`.<br>
**Solution**
<br>&nbsp;&nbsp; the type has to be backquoted, and the class must be prefixed with `CGAL::` as concepts are not in a namespace.
**Problem**
<br>&nbsp;&nbsp; Missing link to a symbol from another package.
<br>
**Solution**
<br>&nbsp;&nbsp; Add a package dependency in the file Package/doc/Package/dependencies and run `cmake .` before running `make doc_with_postprocessing`
**Problem**
<br>&nbsp;&nbsp; A text like ``A call to `make_surface_mesh(c2t3,surface, criteria, tag)` does...`` does not create a link when you write `` `make_surface_mesh(c2t3,surface, criteria, tag)` ``.
<br>
**Solution**
<br>&nbsp;&nbsp; Use `\link \endlink` and write: ``A call to \link make_surface\_mesh() `make_surface_mesh(c2t3,surface, criteria, tag)` \endlink does...`` instead, because the linking mechanism accepts only empty `()` or the exact API.
**Problem**
<br>&nbsp;&nbsp; How to get a link to a type obtained with a `typedef`?
<br>
**Solution**
<br>&nbsp;&nbsp; backquotes are enough for classes and functions, but such types you have to use `\link \endlink` and write: `` \link CGAL::Tag_true `Tag_true` \endlink ``. Note that there are no backquotes for the link, but backquotes so that what follows the link is typeset like code.
**Problem**
<br>&nbsp;&nbsp; My sentence "Object oriented programming is....." generates a link to the page of `CGAL::Object`. How to get rid of this link?
<br>
**Solution**
<br>&nbsp;&nbsp; Put a `%` in front of the word that you don't want to link. This also works in backquoted text. ``In a polyhedron you call `e->%next()` to get to the next edge ...``
## Placing images in specific ways
**Problem**
<br>&nbsp;&nbsp; I have special requirements how my images should be placed (e.g. next to each other or in-line).
<br>
**Solution**
<br>&nbsp;&nbsp; Use the raw commands of the targeted output mode directly protected by [latexonly](http://www.stack.nl/~dimitri/doxygen/commands.html#cmdlatexonly) and [htmlonly](http://www.stack.nl/~dimitri/doxygen/commands.html#cmdhtmlonly). Sometimes it is easier to combine two images into a single one with some image manipulation tools and just use that instead.
## ccVar
**Problem**
<br>&nbsp;&nbsp; The old CGAL manual tool let you define a variable name for an instance of the class you document, and the member function documentation was presented as a call applied to this variable. This allowed to use the variable name inside the method documentation.
<br>
**Solution**
<br>&nbsp;&nbsp; Using doxygen, you have to write "this object" or `*this`, or introduce an object name that you use consistently in the documentation.
## Groups
**Problem**
<br>&nbsp;&nbsp; `\ingroup` does not work
<br>
**Solution**
<br>&nbsp;&nbsp; Did you forget to `\defgroup` or does the name not match?
**Problem**
<br>&nbsp;&nbsp; I have several `\defgroup` spread over different files. How to get them listed in alphabetical order in the navigation panel?
<br>
**Solution**
<br>&nbsp;&nbsp; Change them to `\addtogroup` and put the `\defgroup` in one central file in the right order.
## Words in mathmode
**Problem**
<br>&nbsp;&nbsp; Words like "\$coefficient(..)\$" in mathmode are ugly.
<br>
**Solution**
<br>&nbsp;&nbsp; Use `$\mathrm{coefficient}(..)\$"`. The previous `latex2html` converter was relatively sloppy with mathmode. Switching to MathJax revealed the problem. The previously generated pdf version of the manual had the problem as well, but it went unnoticed.
## Mixing dummy headers and real documentation
If you want to add a new class and write the documentation in-source
directly to a package, you will need to add the file directly to the
input. In order to make doxygen aware these files should be processed,
you should update the `INPUT` field in the file `Doxyfile.in` of
the package.
**Example:**
```
INPUT += ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/boost/graph/Euler_operations.h \
${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/boost/graph/Helpers.h
```
## Deprecation
As described in the
[Coding](Developing-Features-with-Git#coding)
section, use the Doxygen macro `\deprecated` to deprecate a class. The
deprecation should be done consistently in the source code file.

8
Guidelines/Doxygen_specification/Standalone-Problems.md Normal file

@ -0,0 +1,8 @@
## List of possible/actual problems with the standalone version of the documentation
* Examples are titled `File <package_name>/<filename.cpp>` instead of the actual path, `<package_name>/examples/<package_name>`
* Figure names have to be corrected by hand since output is not filtered through `html_output_post_processing.py` like html is.
* A small text is prepended to the Class Index for all packages that reads "Here is the list of all concepts and classes of this package. Classes are inside the namespace CGAL. Concepts are in the global namespace". What exactly does the last sentence mean - especially since Concepts are not `C++` entities.
* The Reference Manual is included as a chapter titled "Module Documentation". This is a bit strange because the authors are re-included here while they have already been mentioned in the first chapter.
* A chapter titled "Example Documentation" is included in the end. I'm not sure this is useful, since all examples and their code have all been included in the previous chapters, so it's just repeating information.
* The underscore in `Is Model` and `Has Model` has been removed.

1005
Guidelines/Doxygen_specification/Writing-Documentation.md Normal file

File diff suppressed because it is too large Load Diff

4
Guidelines/Doxygen_specification/_Footer.md Normal file

@ -0,0 +1,4 @@
[Home](Home) >
[Guidelines](Guidelines) >
[Doxygen Guidelines](Documentation-Guidelines)

4
Guidelines/Doxygen_specification/_Sidebar.md Normal file

@ -0,0 +1,4 @@
[Home](Home) > <br>
[Guidelines](Guidelines) > <br>
[Doxygen Guidelines](Documentation-Guidelines)

169
Guidelines/Examples-and-Demo-Programs.md Normal file

@ -0,0 +1,169 @@
<!--TOC-->
# Table of Contents
* [Introduction](#introduction)
* [Coding conventions](#coding-conventions)
* [The Programs](#the-programs)
* [Create `CMakeLists.txt`](#create-cmakeliststxt)
* [Including programs in documentation](#including-programs-in-documentation)
* [Demo programs on the web](#demo-programs-on-the-web)
<!--TOC-->
## Introduction
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
sec:examples\_subdirectory 4.3 and sec:demo\_subdirectory 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.
**Requirements**:
- Follow the [coding conventions](http://doc.cgal.org/latest/Manual/devman_code_format.html)
(see the [section below](#coding-conventions) for a
summary).
- 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.
## 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](http://doc.cgal.org/latest/Manual/devman_code_format.html)
and good programming practice in these programs. In particular:
- Do **not** use the statements
```
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 example, you should have simply:
``` {.cpp}
#include <CGAL/Cartesian.h>
```
instead of:
``` {.cpp}
#include <CGAL/config.h>
#include <CGAL/Cartesian.h>
#include <CGAL/Point_2.h>
#include <CGAL/Triangle_2.h>
#include <CGAL/Segment_3.h>
```
- 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
``` {.cpp}
typedef CGAL::Cartesian<double>     Kernel;
```
instead of
``` {.cpp}
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.
## 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](http://doc.cgal.org/latest/Generator/)
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.
## Create `CMakeLists.txt`
Each directory containing examples or a demo (or tests) needs a
`CMakeLists.txt` file. There is a script `cgal_create_CMakeLists`.
(The previous script `cgal_create_cmake_script`
does not support all use-cases and is going to become deprecated soon.)
The file `CMakeLists.txt` also ensures that depending optional
third-party libraries are configured for the demo/examples. Say a
directory requires MPFI, then `CMakeLists.txt` must have been altered
accordingly. There are three ways to do so:
1. call the script accordingly: `cgal_create_CMakeLists -c MPFI`
2. replace `find_package(CGAL)` by `find_package(CGAL COMPONENTS MPFI)`
(not deleting existing components)
3. add `find_package(MPFI)` and `include(${MPFI_USE_FILE})` to
`CMakeLists.txt`.
For the demo/example, all three are equivalent. It is to be discussed
which option is the preferred one for CGAL demos and examples (and
tests); in particular for components (like MPFI/RS) that activate
additional code in CGAL's header files, and thus must be (pre)configured
with CGAL (i.e. when and where are `CGAL_USE_<lib>` flags set - config
of CGAL, config of example?).
## 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.
Please make sure that your example programs do not have too long lines,
this can overflow in the output.
## Demo programs on the web
Demo programs for some packages are accessible from the [package overview](http://doc.cgal.org/latest/Manual/packages.html)
web page. For each demo on the page, we have a precompiled executable
for the Windows platform.
If a specific package has a demo that should be linked in the [package overview](http://doc.cgal.org/latest/Manual/packages.html)
web page, then the header in `<package>/doc/<package>/PackageDescription.txt` should be updated to include a `\cgalPkgDemo{}` line.
For details see [this page](Writing-Documentation#packagedescriptiontxt).
for each demo of the package. Please discuss with [@lrineau](https://github.com/lrineau) to agree on the name
`<name_of_the_demo>.zip` of the zip file, so that the automatic scripts
that create the zip files are updated.

35
Guidelines/Guidelines.md Normal file

@ -0,0 +1,35 @@
## Guidelines
These guides are meant to be a resource for developers who
wish to contribute to the CGAL library either by designing new packages
or maintaining or enhancing existing ones. They are organized roughly in
the order in which a developer will need the information in order to
produce a package for the library. New developers should also read
[Information for new developers](Information-for-New-Developers)
and the [public developer manual](http://doc.cgal.org/latest/Manual/dev_manual.html).
1. [ Source Code Management with Git](Source-Code-Management-with-Git)
- [ A Quick Start Guide to Git for CGAL](Quick-Start)
- [ Developing Features with Git](Developing-Features-with-Git)
- [ FAQ about Git](Git-FAQ)
- [ Migration from `scm.cgal.org` to GitHub](Migration-to-Github)
2. [ Building](Branch-Build) (libraries, demos, or executables based on CGAL)
3. [ Package Directory-Structure](Directory-Structure-for-Packages)
4. [ Libraries](Libraries) (how to add or modify a CGAL library)
5. [ Shared-memory parallelism](Concurrency-in-CGAL)
6. [ Package Documentation using Doxygen](Documentation-Guidelines)
- [ Writing Documentation](Writing-Documentation)
- [ Building the Documentation](Building-the-Documentation)
- [ Doxygen FAQ](Doxygen-FAQ)
7. [ Testing](Testing)
8. [ Scripts](Scripts) (for performing routine tasks)
9. [ Examples and Demo Programs](Examples-and-Demo-Programs)
10. [ Submitting new features](Submission)
11. [ The CGAL web site](Website)
## Technical background information
1. [ Infrastructure](Infrastructure)
2. [ Making Releases](Making-Releases)

20
Guidelines/Infrastructure.md Normal file

@ -0,0 +1,20 @@
Here is a list of our servers:
## Web server `www.cgal.org`
See [Website](Website)
## `cgal.geometryfactory.com` - GeometryFactory
This server administrated by [@lrineau](https://github.com/lrineau) currently handles the following
services:
- <http://cgal.geometryfactory.com/CGAL/Members/Releases/>: the daily
internal releases creation
- <http://cgal.geometryfactory.com/CGAL/testsuite/>: the
testsuite results collection pages,
- <http://cgal.geometryfactory.com/CGAL/Manual_doxygen_test/>:
the manual testsuite, using Doxygen,
- <http://cgal.geometryfactory.com/CGAL/Members/wiki/>: the internal developer
wiki.

298
Guidelines/Libraries.md Normal file

@ -0,0 +1,298 @@
<!--TOC-->
# Table of Contents
* [Altering the libraries](#altering-the-libraries)
* [Remark for Qt5](#remark-for-qt5)
* [Adding a library](#adding-a-library)
* [Layout of directories and files](#layout-of-directories-and-files)
* [The `CMakeLists.txt` of the new library](#the-cmakeliststxt-of-the-new-library)
* [Additions to `CGALConfig.cmake`](#additions-to-cgalconfigcmake)
* [Build](#build)
* [Remark](#remark)
* [Support for Windows DLL, and ELF visibility](#support-for-windows-dll-and-elf-visibility)
* [Definition of the export macro](#definition-of-the-export-macro)
* [Use of the export macro](#use-of-the-export-macro)
* [Test of the visibility feature with GNU/g++](#test-of-the-visibility-feature-with-gnug)
<!--TOC-->
## Altering the libraries
In order to compile and build CGAL's libraries
`CGAL, CGAL_Core, CGAL_ImageIO, CGAL_Qt5` from the packages of
a branch, the branch-build collects all sources that are required to
build by calling
` ls */src/CGAL<name-of-the-library>/*.cpp`
on the parent of the branch. That is, `*` is replaced by all packages
contained in branch. More detailed: The source files of a library can
spread over various packages. Though, for most libraries, only a single
package collects all source files.
Jenny can alter or extend a library by simply modifying or adding a
`.cpp` file in `<whateverpackage>/src/CGAL<name-of-the-library>/`. If
the modifications of the library need new third-party libraries support,
then the `CMakeLists.txt` of the library (located in a package as
`*/src/CGAL<<name-of-the-library>/CMakeLists.txt`) needs to be adapted.
### Remark for Qt5
Building the Qt5 library also needs to call `qtmoc` for some
files. Also this task is half-automated: To support the 'qtmoc', Jenny
is required to add a file to each package that contributes sources to
`CGAL_Qt5`, respectively. Such a file should be located in
`<whateverpackage>/src/CGALQt5/` and needs to a have unique filename
over all packages, because of flattening of packages during release
creation. A recommended choice is `<name-of-package>.qtmoc.cmake`. The
file's content gives commands needed to run `qtmoc` for files related to
the package. For instance, the file `GraphicsView.qtmoc.cmake` looks:
```
# moc files that are compiled directly as cpp files
qt5_wrap_cpp(mocfiles ../../include/CGAL/Qt/GraphicsViewNavigation.h
../../include/CGAL/Qt/DemosMainWindow.h
../../include/CGAL/Qt/GraphicsItem.h
../../include/CGAL/Qt/GraphicsViewInput.h)
# qrc files (resources files, that contain icons, at least)
qt5_add_resources ( RESOURCE_FILES ../../demo/resources/CGAL.qrc ../../demo/icons/Input.qrc ../../demo/icons/File.qrc ../../demo/icons/Triangulation_2.qrc)
```
Modifying this example should suffice for most of Jenny's use cases.
## Adding a library
<span style="color:orange">Disclaimer: This is an initial version of
this section. There are plans to improve the handling of libraries in
CGAL in a more automatic way with CMake. For now the following steps are
known, though slight modifications of the steps should be expected. Note
that adding a library is a very seldom task as a CGAL developer.</span>
### Layout of directories and files
Suppose Jenny wants to add a new component library to CGAL, e.g., to
speed up parallel computations. She chooses the new library to be called
`CGAL_Parallel`. The new development takes place in a new package (with
some subdirectories)
```
> mkdir Parallel
> mkdir -p Parallel/package_info/Parallel
> mkdir -p Parallel/src/CGALParallel
```
She adds the proper information in the directory
`Parallel/package_info/Parallel`. The sources of the new library have to
be put under `Parallel/src/CGALParallel`. The naming of this directory
`CGALParallel` is crucial. The new library will be named
`CGAL_Parallel`, that is the name of the directory where the prefix
`CGAL` has been replaced by `CGAL_`.
### The `CMakeLists.txt` of the new library
In order to include the new library to the build-process she adds a
`CMakeLists.txt` file the same directory.
The simplest `CMakeLists.txt` is a single call to the CMake macro
**`build_cgal_library`**:
` build_cgal_library(CGAL_Parallel CGALParallel "")`
The macro `build_cgal_library` declares a new library to CMake, using
`add_library`. It does extra work for name-mangling support on Windows,
and set the VERSION and SOVERSION properties of the library. Here are
the arguments of the macro:
- The first argument is the name of the library.
- The second argument is the name of the directory, under `src/` that
contains the .cpp files of the library.
- The third argument may list extra files to be included in the build,
here an empty list.
Usually, the new library needs third-party libraries, and for that
reason the
`CMakeLists.txt<code> is usually more complicated. See e.g. <code>CGALimageIO/src/CGALImageIO/CMakeLists.txt`.
### Additions to `CGALConfig.cmake`
Jenny also has to announce the new library with the help of CGAL's
configurations file. To do so she alters two template files: First she
adds to `Installation/cmake/modules/CGALConfig_binary.cmake.in` (for the
CGAL in out-of-source-build):
```
set(WITH_CGAL_Parallel "@WITH_CGAL_Parallel@")
 
set(CGAL_Parallel_LIBRARY "@CGAL_Parallel_LIBRARY@")
set(CGAL_Parallel_3RD_PARTY_INCLUDE_DIRS   "@CGAL_Parallel_3RD_PARTY_INCLUDE_DIRS@" )
set(CGAL_Parallel_3RD_PARTY_DEFINITIONS    "@CGAL_Parallel_3RD_PARTY_DEFINITIONS@" )
set(CGAL_Parallel_3RD_PARTY_LIBRARIES_DIRS "@CGAL_Parallel_3RD_PARTY_LIBRARIES_DIRS@" )
set(CGAL_Parallel_3RD_PARTY_LIBRARIES      "@CGAL_Parallel_3RD_PARTY_LIBRARIES@" )`
```
and similarly adds the following lines to
` Installation/cmake/modules/CGALConfig_install.cmake.in` (for installed
CGAL):
```
set(WITH_CGAL_Parallel "@WITH_CGAL_Parallel@")
set(CGAL_Parallel_LIBRARY "@CMAKE_INSTALL_PREFIX@/@CGAL_INSTALL_LIB_DIR@/@CGAL_Parallel_LIBRARY_NAME@")
set(CGAL_Parallel_3RD_PARTY_INCLUDE_DIRS   "@CGAL_Parallel_3RD_PARTY_INCLUDE_DIRS@" )
set(CGAL_Parallel_3RD_PARTY_DEFINITIONS    "@CGAL_Parallel_3RD_PARTY_DEFINITIONS@" )
set(CGAL_Parallel_3RD_PARTY_LIBRARIES_DIRS "@CGAL_Parallel_3RD_PARTY_LIBRARIES_DIRS@" )
set(CGAL_Parallel_3RD_PARTY_LIBRARIES      "@CGAL_Parallel_3RD_PARTY_LIBRARIES@" )`
```
Lines like:
```
set(CGAL_Parallel_USE_ZLIB                  "@CGAL_Parallel_USE_ZLIB@" )
```
might be required, too. And if, then in both files.
### Build
Then, after calling
```
> cmake ~/CGAL/workingcopy
> make
```
she will find the library `CGAL_Parallel` compiled from the sources in
`*/src/CGALParallel` in the `lib` directory of her build-path.
### Remark
- The sources for the library can be spread over several packages, as
indicated by the `*` in `*/src/CGALParallel`. However, only one of
the packages is allowed to have the corresponding `CMakeLists.txt`
file. It is recommended not to spread the files too much; it is best
if all source files of one library are parts of one package.
## Support for Windows DLL, and ELF visibility
On Windows, shared libraries are called DLLs (dynamic-link library). The
implementation of DLLs differs from the implementation of shared
libraries on other systems by the way public symbols are exported from a
DLL and imported into an application (see [the Visual Studio reference
about DLLs](http://msdn.microsoft.com/en-us/library/1ez7dh12.aspx)). For
that reason, when one creates a library that can be compiled as shared
library, all the classes or symbols that must be accessible from outside
the library need to use special macros to declare symbols to export.
*Note that private functions or private data members of a class can be a
symbol that must be export, if the class contains inline public
functions that uses those internal symbols*.
### Definition of the export macro
First you need to create a file `include/CGAL/export/Parallel.h`, to
define the macros:
``` {.cpp}
// Copyright (c) 2011 GeometryFactory (France). All rights reserved.
//
// This file is part of CGAL (www.cgal.org); you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public License as
// published by the Free Software Foundation; either version 3 of the License,
// or (at your option) any later version.
//
// Licensees holding a valid commercial license may use this file in
// accordance with the commercial license agreement provided with the software.
//
// This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
// WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
//
// $URL$
// $Id$
//
//
// Author(s) : Laurent Rineau
#ifndef CGAL_PARALLEL_EXPORT_H
#define CGAL_PARALLEL_EXPORT_H
#include <CGAL/config.h>
#include <CGAL/export/helpers.h>
#if defined(CGAL_BUILD_SHARED_LIBS)
# if defined(CGAL_Parallel_EXPORTS) // defined by CMake or in cpp files of the dll
# define CGAL_PARALLEL_EXPORT CGAL_DLL_EXPORT
# define CGAL_PARALLEL_EXPIMP_TEMPLATE
# else // not CGAL_Parallel_EXPORTS
# define CGAL_PARALLEL_EXPORT CGAL_DLL_IMPORT
# define CGAL_PARALLEL_EXPIMP_TEMPLATE extern
# endif // not CGAL_PARALLEL_EXPORTS
#else // not CGAL_BUILD_SHARED_LIBS
# define CGAL_PARALLEL_EXPORT
# define CGAL_PARALLEL_EXPIMP_TEMPLATE
#endif // not CGAL_BUILD_SHARED_LIBS
#endif // CGAL_PARALLEL_EXPORT_H
```
You can copy, for example, the file
`GraphicsView/include/CGAL/export/Qt.h`, and adapt it. Note that the
macro `CGAL_Parallel_EXPORTS` used at line 28 is defined by the build
system generated by CMake. The name of that macro is
`''<libname>''_EXPORTS`: as here the library is named CGAL\_Parallel,
the macro is named `CGAL_Parallel_EXPORTS` (attention to the case).
The important macro that is defined by this file is:
`CGAL_PARALLEL_EXPORT` (all uppercase to respect the naming convention
of macros in CGAL).
### Use of the export macro
The export macro must be used in the header file that corresponds to the
.cpp file build in the library.
More precisely, the export macro must be inserted in the **declaration**
of any:
- class that has parts of its implementation defined in a .cpp file in
the library,
- free function that has its definition in a .cpp file,
- global variable that is declared in a header file but initialized in
a .cpp file.
Example:
``` {.cpp}
// Do not forget to include the header that defines the export macros
#include <CGAL/export/Parallel.h>
// for a non-inline and non-template function:
CGAL_PARALLEL_EXPORT int parallel_do_overlap(Bbox_3, Bbox_3);
// for a non-template class that has part of its
// implementation in a .cpp file of the library:
class CGAL_PARALLEL_EXPORT Foobar {
int private_stuff;
public:
Foobar();
void parallel_compute(Something input);
};
```
Note that at line 9, the export macro is inserted between the `class`
and the name of the class.
You must not insert export macro in the **definition** of a symbol: it
means that .cpp files should not contain uses of export macros.
See also:
- <http://gcc.gnu.org/wiki/Visibility>
### Test of the visibility feature with GNU/g++
You can add `-fvisibility-ms-compat` to the `CMAKE_CXX_FLAGS` to check
the visibility feature with a non-Windows compiler. That works with:
- llvm/clang,
- the Linux version of the Intel compiler,
- g++ versions 4.0 and after.

22
Guidelines/Making-Releases.md Normal file

@ -0,0 +1,22 @@
## Internal Releases
Internal releases are currently created daily from a script run at
GeometryFactory. This script packages together the current versions of
all packages into a tar file and publish a tarball at
<http://cgal.geometryfactory.com/CGAL/Members/Releases/>. People
responsible for running the test suite can pick it up automatically
using the [`autotest_cgal`](Scripts#autotest_cgal) script.
## Public Releases
A public release can be created from an internal release by following
the steps detailed in the `README` file in the package `Release` in the
SCM repository. This file describes how to create the code, the
documentation and the updated web pages for a new release.
Each public release is tagged in the [`cgal`](https://github.com/CGAL/cgal)
repository with a tag in the following format
`releases/CGAL-N`, where `N` is the release
number. There is also a branch created for each release
with the name `releases/CGAL-N-branch`, where `N` is the release number as
before. This facilitates the creation of bug fix releases.

656
Guidelines/Scripts.md Normal file

@ -0,0 +1,656 @@
<!--TOC-->
# Table of Contents
* [` cgal_create_cmake_script` (same as `cgal_create_CMakeLists`)](#cgal_create_cmake_script-same-as-cgal_create_cmakelists)
* [`cgal_create_package_dir.py`](#cgal_create_package_dirpy)
* [`create_assertions.sh`](#create_assertionssh)
* [`check_licenses`](#check_licenses)
* [`create_new_release`](#create_new_release)
* [`create_cgal_test_with_cmake`](#create_cgal_test_with_cmake)
* [`autotest_cgal_with_cmake`](#autotest_cgal_with_cmake)
* [`autotest_cgal`](#autotest_cgal)
* [How to set up your local testing](#how-to-set-up-your-local-testing)
* [Command line options for the initial set up](#command-line-options-for-the-initial-set-up)
* [Sending results](#sending-results)
* [List of miscellaneous configurable variables](#list-of-miscellaneous-configurable-variables)
* [Testing with Visual Studio on cygwin](#testing-with-visual-studio-on-cygwin)
* [`add_toc_to_github_wiki_page.py`](#add_toc_to_github_wiki_pagepy)
<!--TOC-->
There are a number of tools that automate some of the tedious and
error-prone tasks that are unavoidable when developing for CGAL. We
distinguish
- scripts for users located in `Package/scripts`, most of them in
`Scripts/scripts` and
- scripts for developers located in `Package/developer_scripts`,
typically `Scripts/developer_scripts`.
They are available in any branch of CGAL, thus the developer Jenny adds
the directories she needs the most (typically the two from the `Scripts`
package to her `PATH` variable.
```
PATH=$HOME/CGAL/workingcopy/Scripts/scripts:$HOME/CGAL/workingcopy/Scripts/developer_scripts:$PATH
```
## ` cgal_create_cmake_script` (same as `cgal_create_CMakeLists`)
The shell script `cgal_create_cmake_script`
creates a CGAL cmake script, that is, a ` CMakeLists.txt` file, in the
current working directory for configuring a particular CGAL application
(such as an example, demo or test).
The cmake script will have commands to make an executable from every
`.C` and `.cpp` file which contains the word `main` in the directory.
The following options are available to indicate the kind of cmake script
to create:
The `CMakeLists.txt` created by this script has the following
properties:
If the directory where the cmake script 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.
The CGAL library is required (must have been already configured) and
cmake must be called with `-DCGAL_DIR=''<path>''`, where *<path>*
corresponds to the binary directory of the CGAL installation (where the
file `CGALConfig.cmake` is).
While cmake itself takes care automatically of most compiler and linker
flags based on the target compiler and debug/release configuration,
additional flags might have been specified when building CGAL and will
be used here (as defined in `CGALConfig.cmake`). However, if you need
*additional* compiler or linker flags specifically here, you can define
any of the following cmake variables at the command line when running
cmake (via the -D option):
- ` CGAL_CXX_FLAGS`
- ` CGAL_CXX_FLAGS_RELEASE`
- ` CGAL_CXX_FLAGS_DEBUG`
- ` CGAL_EXE_LINKER_FLAGS`
- ` CGAL_EXE_LINKER_FLAGS_RELEASE`
- ` CGAL_EXE_LINKER_FLAGS_DEBUG`
The `_RELEASE` and `_DEBUG` variables are *appended* to the general
variable, so for each build type, two sets of flags are used. For
example: `CGAL_CXX_FLAGS` *then* `CGAL_CXX_FLAGS_DEBUG`
## `cgal_create_package_dir.py`
This python script creates the directory structure for a new package,
according to the [package directory structure guidelines](Directory-Structure-for-Packages).
This script is provided so that the writer of a new package does not
have to build the structure from scratch. The command
```
cgal_create_package_dir.py Minkowski_sum_2
```
creates the structure of the new package in the current directory, in a
single directory named `Minkowski_sum_2`. The command
```
cgal_create_package_dir.py Minkowski_sum_2 creation_path
```
creates the single directory with the structure under the given
`creation_path`.
The structure and the files created are just a template and inspection
by the package writer is required. The package writer might decide to
even delete some files or directories created by the script. See the
[package directory structure guidelines](Directory-Structure-for-Packages) for
more details.
Package-specific assertions are not created. If you want to create
package-specific assertions, use the `create_assertions.sh` script.
## `create_assertions.sh`
This shell script generates assertion header files, to be used for
[invariant/pre-/post-condition checks on package level](http://doc.cgal.org/latest/Manual/devman_checks.html).
The command
```
create_assertions.sh Minkowski_sum_2
```
creates a file `Minkowski_sum_2_assertions.h`
This file is usually placed in directory `include/CGAL` and included in
files that implement the `Minkowsk_sum_2` package. The file contains
several macros for adding checks (preconditions, postconditions, etc.)
that can be switched on or off with compile flags, and can be used in
the following fashion:
```
#include <CGAL/optimisation_assertions.h>
void optimisation_foo( int i)
{
  CGAL_Minkowski_sum_2_precondition_msg( i == 42, "Only 42 allowed!");
  // ...
}
```
The documentation of your new package has to name the term chosen to be
part of the package-specific macros in order to enable the user to
selectively turn off and on the checks of your package. For example, in
the documentation of the package you should find a sentence similar to
the following:
```
The code of this package uses the term `MINKOWSKI_SUM_2` for the
checks; e.g., setting the compile time flag
`CGAL_MINKOWSKI_SUM_2_NO_PRECONDITIONS` switches off
precondition checking in the Minkowski sum code.
```
## `check_licenses`
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 GPL are
not mixed in one library.
That script does not work on SCM branches. It needs a CGAL release.
## `create_new_release`
The script `create_new_release`
builds a tarball of CGAL from a branch of a Git non-bare repository The
command ` create_new_release ` creates a directory ` tmp ` which
contains the tarball, as well as its public and SRPM versions.
This script takes as argument the root of a Git repository (checked out
to a certain branch TODO @LR: Or is there a way to specify the branch?)
and it default to `master`. It also supports the following options:
- `--rpm` create SRPM files as well
- `--public` create a public version as well
- `--do-it` (reserved to the release manager) moves it on the web
server, tags...
- `--do-not-tag` option that allows to create a new release with
`--do-it` without creating the tag.
## `create_cgal_test_with_cmake`
In every subdirectory of ` test` there must be a shell script called
` cgal_test_with_cmake`. This script is called from the
` run_testsuite_with_cmake` script when the test suite is run. The
script ` create_cgal_test_with_cmake`
will create the shell script ` cgal_test_with_cmake` in the current
directory.
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_with_cmake` to test your package before submitting
but generally should avoid submitting the file ` cgal_test_with_cmake`.
The generated file contains a header that lists the requirements a
` cgal_test_with_cmake` program should fulfill.
Files which are considered by ` create_cgal_test_with_cmake` are those
with ` .c` or ` .cpp` extension, and which content match the word
` main`. This way, no attempt is made at linking programs which are made
of several object files.
The generated script calls ` cmake` with the following definitions
` -DCGAL_DIR=${CGAL_DIR}`\
` -DCGAL_CXX_FLAGS=${TESTSUITE_CXXFLAGS} `\
` -DCGAL_EXE_LINKER_FLAGS=${TESTSUITE_LDFLAGS}`\
` -DCMAKE_BUILD_TYPE=NOTFOUND`
The environment variable ` CGAL_DIR` is *required* and must contain the
path to the binary directory of the CGAL installation to use (the
testsuite defines this automatically), while the environment variables
` TESTSUITE_CXXFLAGS` and `TESTSUITE_LDFLAGS` are optional and are used
to *add* flags which have not been used when building the library. These
TESTSUITE variables are kept for backward compatibility with the
non-cmake testsuite (the preferred way is to define all the flags when
building CGAL rather than using these).
` CMAKE_BUILD_TYPE` is set to ` NOTFOUND` in order to use the same build
type specified when building CGAL (as defined in ` CGALConfig.cmake`).
## `autotest_cgal_with_cmake`
That script has been renamed `autotest_cgal` and a wrapper script is
kept for compatibility with existing setups.
## `autotest_cgal`
The shell script ` autotest_cgal` is used to run automated test suites
for the internal releases of the library. The script need no
command-line arguments, and 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 compilers/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-4.2-Ic-xx`, and unzip then untar it under ` $CGAL_ROOT`. This
release will serve as a *fixed reference release* for configuring and
building each current release to test from now on.
This internal release is used as a reference which defines the
configurations to test (it is not itself tested), thus is better to
rename it accordingly, say as ` CGAL-I-REF`.
The next step is to create a new directory for each wanted configuration
(architecture+platform+compiler) to test under the directory
` $CGAL_ROOT/CGAL-I-REF/cmake/platforms`. Each directory in there,
called *configuration folder*, will contain the testsuite for that
configuration and its name will identify the configuration in the test
results.
Now cd into each such configuration folder and configure CGAL using
cmake (either the command line or the GUI). With the command-line cmake,
use the -D option to define cmake variables and -G to define a generator
if the default is not right for you.
The cmake variables
` WITH_CGAL_Core, WITH_CGAL_ImageIO and WITHD_CGAL_Qt5
are used to enable or disable those CGAL components. These are all ON by
default. You should you define them with OFF if any of those components
do not work in your platform. For *these and only these* cmake variables
you can define them as environment variables rather than cmake
variables.
The cmake variable ` CMAKE_BUILD_TYPE` is used to specify a ` Debug` or
`Release` configuration. For the testsuite, you should always define
this variable since the default varies on different generators (and use
only Debug or Release since other values are not currently supported)
CMake itself takes care automatically of most compiler and linker flags
via the following cmake variables:
- `CMAKE_CXX_FLAGS`
- `CMAKE_CXX_FLAGS_RELEASE`
- `CMAKE_CXX_FLAGS_DEBUG`
- `CMAKE_EXE_LINKER_FLAGS`
- `CMAKE_EXE_LINKER_FLAGS_RELEASE`
- `CMAKE_EXE_LINKER_FLAGS_DEBUG`
The `_RELEASE` and `_DEBUG` variables are *appended* to the general
variable, so for each build type, two sets of flags are used. For
example: `CMAKE_CXX_FLAGS` *then* `CMAKE_CXX_FLAGS_DEBUG`.
You can define any of these variables on the command-line (with the -D
switch) or the GUI (CMakeSetup|ccmake), but doing so *overrides* the
values that cmake would automatically compute.
If you just want to *add* flags, you can define any of the following
variables instead:
- `CMAKE_CXX_FLAGS`
- `CMAKE_CXX_FLAGS_RELEASE`
- `CMAKE_CXX_FLAGS_DEBUG`
- `CMAKE_EXE_LINKER_FLAGS`
- `CMAKE_EXE_LINKER_FLAGS_RELEASE`
- `CMAKE_EXE_LINKER_FLAGS_DEBUG`
which are named with `CGAL` rather than `CMAKE`.
CMake has trouble parsing in the command line variable definitions that
contain the '=' sign in the value, thus, you cannot add a flag like:
`-DCGAL_CXX_FLAGS_RELEASE=' -std=c++11 '` . On the other hand, cmake
uses the *environment* variable `CXXFLAGS` to initialize
`CMAKE_CXX_FLAGS`, so you can use that in this case.
The cmake variable `CMAKE_CXX_COMPILER` can be used to specify the full
path of the C++ compiler to use. Unlike most cmake variables, this one
is handled specially by cmake, thus, while manually defining it works
fine when building the reference release for the testsuite, its value is
not propagated to the releases being tested (recall that at this point
we are manually building the reference release which the testsuite uses
to automatically build and test the others). Therefore, if you need to
specify the compiler (because cmake autodetects the wrong one), you need
to define the *environment* variable `CXX`.
The following example illustrates how to configure and build the
reference release. Notice the ../../.. path to the CGAL sources from the
platform directory (where cmake is invoked).
```
export CXX=`<some compiler not detected by cmake>
export CXXFLAGS='-std=c++11'`
export WITH_CGAL_ImageIO=OFF `
cmake -DWITH_CGAL_Core=OFF -DCMAKE_BUILD_TYPE=Release ../../..
make`
```
You can create here a shell script *specifically* named `setup` in
case you need the test script to automatically do anything for this
particular configuration, such as setting up environment variables as in
the example above. The contents of such a file, if it exists, are copied
verbatim into the start of the temporary build and test scripts created
on each configuration folder. This allows you to bootstrap the process
as needed.
Make sure to fix any problems configuring or building this reference
release before starting the automated testsuite.
Once the reference release is ready, define a variable named
`REFERENCE_PLATFORMS_DIR` with the full path to the `/cmake/platforms/`
directory of the reference release, for example:
`$CGAL_ROOT/CGAL-I-REF/cmake/platforms` in the file `.autocgalrc`.
The next step is to specify the name of the hosts. To do that, you must
define the variable `BUILD_HOSTS` in `.autocgalrc`.
For every host *h* listed in `BUILD_HOSTS` you must also specify the
variable `BUILD_ON_`*h* as a list of configuration names for which the
CGAL libraries are to be built on *h*. For each name listed in here, the
testsuite script will create a directory under the current platforms
directory (i.e. ` $CGAL_ROOT/CGAL-4.2-I-abc/cmake/platforms`), unless it
already exists.
If any of the variables `BUILD_ON_`*h* has the value 'all' then the
platforms directory structure of the reference release
(`$REFERENCE_PLATFORMS_DIR`) is replicated under the current platforms
directory. <small>This 'all' value should only be used when the
testsuite is run on a single localhost, otherwise, the testsuite script
won't be able to properly distribute each platform folder to its
corresponding host.</small>
Similarly, for every host *h* listed in `BUILD_HOSTS` you must also
specify the variable `COMPILERS_`*h* as a list of configuration names
for which the testsuite is to be run on \$h\$ (this must be a subset of
the names specified in `BUILD_ON_`*h*). You can specify only
`COMPILERS_`*h* instead of both `BUILD_ON_`*h* and `COMPILERS_`*h* if
they share the same value.
Here is an example setting in `.autocgalrc`:
```
REFERENCE_PLATFORMS_DIR="~/CGAL_autotest/CGAL-I-REF/cmake/platforms"
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"
```
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.
The script copies the entire `/test` subdirectory of the release being
tested into each configuration folder to test at, thus, all executables,
temporaries and results are local to that configuration. When the
scripts finishes testing a configuration, the local `/test` subdirectory
is deleted.
The script uses `wget` to download the release to test. 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=username
--http-passwd=password
```
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 {\\tt
HOME/.curlrc}:
```
 --user username:password
```
Once the latest release has been downloaded, unzipped and untared, say
under `$CGAL_ROOT/CGAL-4.9-I-abc`, the testsuites creates a symbolic
link to it named `$CGAL_ROOT/CGAL-I`. From now on, the release being
tested is located under `CGAL-I`.
For each directory under `$CGAL_ROOT/CGAL-I/cmake/platforms`, if a
directory of the name name exist in the reference release (i.e. under
`$CGAL_ROOT/CGAL-I-REF/cmake/platforms`), the files `CMakeCache.txt` and
`setup` are copied from the reference release (if they exist).
### Command line options for the initial set up
` autotest_cgal` is meant to be run unattended by a cron job. However,
in order to simplify the initial set up some command line options are
available:
- ` -c` Uses an already untared internal release under the symbolic
link ` CGAL-I` instead of downloading and untaring a new one. You
can use this option to *resume* immediately the test suite process
in case it failed before.
- ` -n` Skips the testing phase, finishing after the libraries has
been built. You can use this option to verify that the mechanism
that uses the reference release to build the current release with
the exact same settings works fine.
- ` -l` Do not upload the results to the server. You can use this
option to avoid uploading incomplete results until the testsuite
process works correctly in your system.
### Sending results
Unless you use the ` -l` option, the script will attempt to send result
using ` scp` (secured-copy, a tool from the SSH suite) to the
GeometryFactory server ` cgal.geometryfactory.com}` You must declare
yourself as a tester to Laurent Rineau, and send him the public part of
your ssh key. Usually, that is the file ` $HOME.ssh/id_rsa.pub`, or
`$HOME/.ssh/id_dsa.pub`.
After that, you can test that the sending works, by typing:
```
ssh cgaltest@cgal.geometryfactory.com
```
If the result is something like:
```
Last login: Thu July 14 12:03:18 1789 from 1.1.1.1
CentOS release 5.3 (Final)
Linux cgal.geometryfactory.com 2.6.28.4-xxxx-std-ipv6-32 #4 SMP Wed Sep 9 22:08:40 UTC 2009 i686 i686 i386 GNU/Linux
server    : 39891
ip        : 91.121.110.28
ip        : 91.121.110.28
hostname  : cgal.geometryfactory.com
```
then the test is successful (you will need to interrupt SSH with
Ctrl+C). If instead you get something like:
` Permission denied (publickey,gssapi-with-mic).`
then contact [@lrineau](https://github.com/lrineau).
### List of miscellaneous configurable variables
- `MYSHELL` is a variable that may be defined in `.autocgalrc` 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 coming 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 `' '`.
`USE_CURL` specifies if `curl` should be used as a replacement for
`wget` and `ftp`. Set it to `y` to use `curl`.
`FTP_OPTS` specifies the options for `ftp`. On Linux systems it should
be `-p -v -n` (the default), on cygwin it should be `-v -n`.
`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' '`.
`ULIMIT_OPTIONS` specifies the command line options to pass to the
`ulimit` command, which is used to prevent the test-suite from using
various system ressources. It can be used to help killing looping
programs. For example, specifying `-c 0 -t 10800 -v 2000000` will
prevent the creation of dumped core files, will stop processes after 3
hours, and will kill them if they reach 2GB of memory. The default value
is empty (no limit).
### Testing with Visual Studio on cygwin
In order to test with Visual Studio you need to use Cygwin and set up
the environment for the command line compiler.
In Cygwin, install at least the following packages:
- procmail (for the lockfile utility),
- wget,
- ca-certificates,
- make (called only once at the start of the test suite),
- diffutils (for the cmp utility),
- openssh (for scp).
Content of the \~/.wgetrc file:
```
--http-user=username
--http-passwd=password
ca_directory = /usr/ssl/certs
```
The setup of the environment can be done by setting up the VC command
line tools in the `setup` script that is used to bootstrap the build
and test process, as explained before. Merely executing the
`vcvars32.bat` that comes with VC does not work since the variables in
there will be defined only in the environment for the batch file and not
in the environment of the building/testing script (this is why the
contents of the 'setup' script are copied into the build/test script
instead of `setup` being just executed from there)
Furthermore, within the `setup` script, the following must be
considered:
The variables `INCLUDE, LIB` and `LIBPATH` will be used by the Visual
C++ compiler *directly*, that is, without the path translation that
cygwin usually performs. Thus, the values for these variables must be a
verbatim copy of the values defined in the `vcvars32.bat` of your
Visual Studio installation.
On the other hand, the `PATH` variable will be used by cygwin itself to
locate the components of the command line tools (cl.exe, link.exe,
etc.), thus, each Windows path specified in the PATH definition on
`vcvars32.bat` must be converted to a POSIX path and properly appended
to the cygwin PATH variable.
Below is a sample 'setup' script for Visual C++ 9.0:
```
export INCLUDE='C:\Program Files\Microsoft Visual Studio 9.0\VC\ATLMFC\INCLUDE;
C:\Program Files\Microsoft Visual Studio 9.0\VC\INCLUDE;C:\Program Files\Microsoft Visual Studio 8\VC\PlatformSDK\include;
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\include;c:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\include\'
export LIB='C:\Program Files\Microsoft Visual Studio 9.0\VC\ATLMFC\LIB;C:\Program Files\Microsoft Visual Studio 9.0\VC\LIB;
C:\Program Files\Microsoft Visual Studio 8\VC\PlatformSDK\lib;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib;
c:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Lib\'
export LIBPATH='C:\Program Files\Microsoft Visual Studio 9.0\VC\ATLMFC\LIB;C:\Program Files\Microsoft Visual Studio 9.0\VC\LIB'
export PATH='/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/Common7/IDE':
'/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/VC/BIN':
'/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/Common7/Tools':
'/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/Common7/Tools/bin':
'/cygdrive/c/Program Files/Microsoft Visual Studio 9.0/VC/VCPackages':
'/cygdrive/c/Program Files/Microsoft Visual Studio 8/VC/PlatformSDK/bin':
'/cygdrive/c/Program Files/Microsoft Visual Studio 8/SDK/v2.0/bin':$PATH
```
## `add_toc_to_github_wiki_page.py`
This script can be used to generate or update the table of contents (TOC)
of a wiki page in github. The script is compatible with `python` 2 and 3.
The script expects as input the name of the file to process.
In order for the script to generate a TOC, the file first line must be
`<!--TOC-->`. Then another line must also be `<!--TOC-->`. The generated
TOC will be put between these lines (thus allowing to update an already
existing TOC).
The only sections processed are those created with the `#` keyword.
`h1` sections are not allowed, that is the first section level must be `##`.
Here is an example of a wiki page for which a TOC will be generated
```
<!--TOC-->
<!--TOC-->
## Section 1
### Subsection 1
blabla
## Section 2
blabla
```
To apply the script to all the files you can use for example the following
command:
```
find . -name '*.md' -exec python add_toc_to_github_wiki_page.py {} \;
```

559
Guidelines/Source_code_management/Developing-Features-with-Git.md Normal file

@ -0,0 +1,559 @@
<!--TOC-->
# Table of Contents
* [Opening a feature branch](#opening-a-feature-branch)
* [Coding](#coding)
* [Synchronizing the feature branch](#synchronizing-the-feature-branch)
* [Integrating the feature branch and adding it to the testsuite](#integrating-the-feature-branch-and-adding-it-to-the-testsuite)
* [Merging the feature branch to master](#merging-the-feature-branch-to-master)
* [Closing the feature branch](#closing-the-feature-branch)
* [Problem with end-of-line encoding in a feature branch](#problem-with-end-of-line-encoding-in-a-feature-branch)
* [How to develop several features in parallel](#how-to-develop-several-features-in-parallel)
* [How to work on a different branch?](#how-to-work-on-a-different-branch)
* [Which branch Jenny is currently working on?](#which-branch-jenny-is-currently-working-on)
* [Building after switching/updating](#building-after-switchingupdating)
* [How to use another feature in own feature branch](#how-to-use-another-feature-in-own-feature-branch)
* [Developing and committing to several orthogonal feature branches](#developing-and-committing-to-several-orthogonal-feature-branches)
* [Sharing your branches with the outside](#sharing-your-branches-with-the-outside)
<!--TOC-->
Any change to the existing code of CGAL, such as the introduction of a
new function or functor in an existing file, the fixing of a bug in a
package, or the refactoring of some code in various packages, is
classified either as a feature or as a bug fix. Features must be
reviewed by the Editorial Board. The development of a feature should
follow a certain procedure described in this page. However, it is
encouraged to follow the same procedure also for the development of
demos or fixing non-trivial bugs, even though both are not needed to be
reviewed. One advantage, for example, is that such code can be tested as
part of the testsuite in the same way that features are. A bug is
non-trivial if its fix is "beyond a typo". Trivial bugs can be fixed
directly on the `master` branch.
A new feature must be developed in a dedicated branch called the
<i>feature branch</i>. This branch is cloned from the `master` branch.
The feature branch, just as the `master` branch, supports the
[branch-build](Branch-Build), which allows the
building of CGAL from the sources in their package structure. This is
advantageous especially in cases where new features alter the generated
library objects. Once the development of a feature is complete, the
branch with all the modifications is merged back into `master`. The
release manager clones `master` to create the branch for upcoming public
release a short period before the release. This way new features end up
in the upcoming release.
The following assumes that 1) you are familiar with CGAL's SCM-layout
and which branches exists, as described in
[the guidelines](Source-Code-Management-with-Git),
2) you have cloned the remote Git repository, and 3) took a crash course
on git commands (our
[Quickstart](Quick-Start)),
or for example: [1](http://git.or.cz/course/svn.html) (which also
compares with SVN) or [2](http://cworth.org/hgbook-git/tour/) (from
Section 2.4 onwards), as **this documentation is not a general
introduction to GIT. It will only list the most important use-cases for
developing code in CGAL using Git as SCM.**
This page discusses the case of adding a package. The same steps
similarly apply for adding a demo/example or non-trivial bug-fixes. At
the beginning Jenny enters her local Git repository.
```
> cd /path/to/my/cgal\_repository
```
## Opening a feature branch
Assume that Jenny would like to develop a new package named
`Kinetic_arrangement_2`.
First, following the [quick start](Quick-Start)
Jenny creates her own feature branch (based on the master branch).
Following the [naming recommendations](Naming-Recommendations),
Jenny calls the branch `Kinetic_arrangement_2-jenny`.
``` {.bash}
git checkout -b Kinetic_arrangement_2-jenny --no-track cgal/master
```
This is a local branch, and not visible to anyone besides Jenny until
the first call to the `git push` command (see below).
Note: if you already have made a ["pull
request"](Source-Code-Management-with-Git#pull-request),
your local repository has a remote branch named `mine/master`. That
branch is useless. It is a leftover of the fork. Unless you have
regularly merged `cgal/master` into it, `cgal/mine` branch is probably
obsolete.
## Coding
Now, Jenny can implement the package. She is iterating the following
commands until the package is implemented.
``` {.bash}
> mkdir Kinetic_arrangement_2
# [hack boom bang]
# Rebuild CGAL with branch-build to include the package in the build system
# Use `git add Kinetic_arrangement_2/path/to/file.cpp` to add new files to the source code management.
> git add <all-new-relevant-files>
> git commit <files>
```
This opens an editor to enter the commit message. Please use the
[established format](Source-Code-Management-with-Git#commit-messages)
for Git repositories.
If she wants to share the new feature with others, or have a back-up,
she can push the new commits to the remote repository:
``` {.bash}
> git push -u cgal-dev Kinetic_arrangement_2-jenny
```
Now her branch is visible to everyone with access to the remote
*cgal-dev*. Once the first push of the branch has been done, the
following ones no longer need the `-u cgal-dev` option, and are done
simply with
``` {.bash}
> git push
```
Otherwise, she could postpone this step until major progress took place.
Note: There are techniques (not explained here) to combine several small
commits into one bigger.
**To deprecate** something, she should make modifications in the code
and in the documentation. \* In the .h code-file she wants to deprecate,
she should add the following :
```
#define CGAL_DEPRECATED_HEADER "<CGAL/old_header_file.h>"
#define CGAL_REPLACEMENT_HEADER "<CGAL/new_header_file.h>"
#include <CGAL/internal/deprecation_warning.h>
```
- In the .h file that contains the documentation, in the description
of the class she should add :
```
\deprecated This class is deprecated since N.M. The class `New_class` should be used
instead.
```
**Once the package is ready** she submits the documentation of the
package to the editorial board. She gets some feedback and improves the
package according to the review.
## Synchronizing the feature branch
In contrast to SVN, we now have an **integration** branch that is used
to integrate new features to the recent development that took place on
`master` and by the nightly testsuite. Thus, Jenny delays the
integration until her feature has been accepted.
To remember: In order to avoid unnecessary dependencies and to keep the
shape of history simple, Jenny follows the procedure of section
["My branch is really old. I would like to update it to get latest update from master."](Git-FAQ#my-branch-is-really-old-i-would-like-to-update-it-to-get-latest-update-from-master)
of [our Git FAQ](Git-FAQ) to update her feature branch.
<b>Under no circumstance Jenny merges master into her feature branch</b>.
## Integrating the feature branch and adding it to the testsuite
Once Jenny got the feature accepted by CGAL's Editorial Board, she gains
the right and obligation to test her feature on various platforms and to
ensure the interoperability with other parts of the library. The
[Testing](Testing) chapter explains how to test
code.
Note that on Saturday nights, the internal releases are usually created
from `master` only. That means that the Saturdays versions of the
`integration` branch are not tested.
Before merging her branch to `integration`, Jenny has to shortly
describe the changes she is making to CGAL in the file
`Installation/changes.html` and commit it.
``` {.bash}
# be sure to have a checkout of the right branch
> git checkout Kinetic_arrangement_2-jenny # commit changes.html
> git commit
# then push this commit to the branch Kinetic_arrangement_2-jenny
> git push
```
**Be careful** that the following commands will erase, in your working
directory, all *non-committed* modifications to files tracked by Git.
The following command:
``` {.bash}
> git status
```
must display either `nothing to commit (working directory clean)` or
`nothing added to commit but untracked files present`, but not a list
of files under a section `Changes not staged for commit:`. If you have
uncommited changes to tracked files, you must commit your changes to a
branch, or save them using the `git stash` command.
The inclusion of her feature branch to the testsuite takes place in the
`integration` branch (which she gets as any other branch with
`git checkout -b integration cgal-dev/integration`), and needs a few
steps:
``` {.bash}
# update the local copies of the remote branches cgal-dev/*
> git fetch cgal-dev
## update the 'integration' branch, in two steps ##
# First: checkout of the branch
> git checkout integration
# That Git command might displays such a warning:
Switched to branch 'integration'
Your branch and 'cgal-dev/integration' have diverged,
and have 1 and 31 different commit(s) each, respectively.
# Or the following message:
Switched to branch 'integration'
Your branch is ahead of 'cgal-dev/integration' by 285 commits.
(use "git push" to publish your local commits)
# Second: one forces the update of the branch, that way:
> git reset --hard cgal-dev/integration
# now, Jenny merges her own feature branch
> git merge --no-ff --no-commit Kinetic_arrangement_2-jenny
# --no-ff keeps the branch visible in the history
# --no-commit does the merge but does not commit it.
# You can thus look at the diff and see if all went as expected.
```
The merge can only be aborted with an **empty** commit message! If you
leave the editor *without* saving, the commit message is **not** empty.
At this point, Jenny has to check the integrity of the merge:
- solve conflicts (hints might be given in
[3](http://public.kitware.com/Wiki/Git/Workflow/Topic/Conflicts#Topic-to-Topic)
and
[4](http://public.kitware.com/Wiki/Git/Workflow/Topic/Conflicts#Resolution_Topic).
Note that they use `next` while we name this branch `integration`)
- build, test, and verify...
Then, she commits locally and pushes the integration onto the remote
location:
``` {.bash}
> git commit
# the commit message is already filled with the merge message.
# push updates 'integration' onto the remote location
> git push
```
If the push is rejected because the update is not fast-forward, that
means that another developer has pushed to the same branch between the
`git reset --hard` and the push. That situation can be fixed with a pull
of the remote updates, and then a new push attempt:
``` {.bash}
> git pull
> git push
```
Please do not use `git rebase` or `git pull --rebase` in the
`integration` branch.
If Jenny modifies again her feature branch the same day after the merge
in `integration`, she can restart the same procedure to merge again the
feature branch in `integration`. Only the new commits will be considered
by Git.
Notice that a snapshot of the integration branch is taken every day
exactly at 21:00 CEST (local time in France: UTC/GMT + 1 hour + Daylight
saving time when applicable) and the integration branch is reset to
reflect the master branch immediately after.
Finally, Jenny waits for the results reported on [the test results web
page](https://cgal.geometryfactory.com/CGAL/Members/testsuite/) on the
following day (assuming that she completed the steps above before the
snapshot was taken). She can click on the *y/w/n/r* symbols in the table
to see for which commit the test suite was run. If the testsuite is
green, her feature can be merged into the `master` branch upon approval
of the release manager (see [below](#merging-the-feature-branch-to-master)).
If not green, note that `integration` gets thrown away and is reset to
the content of `master` each day, during the daily internal release
creation. As a consequence, if one day Jenny merges her branch into
`integration` so that it is tested during the night, and if the tests
were not fully successful, Jenny will have to remerge again the branch
into `integration` the day after (i.e. redoing the steps above). Anyway,
if the tests were not fully successful (e.g. the feature did not work
correctly on all platforms), she has to modify something in her code and
remerge into `integration`. This strategy shows Jenny that she is
responsible to get her feature properly tested and if successful to
quickly merge into in the stable `master` branch.
In order to check previous runs of the testsuite, the Git repository
will keep a sort of "cyclic backup" of all branches that were tested
during the last week, as branches:
- `testsuite-Monday`
- `testsuite-Tuesday`
- and so on (seven such branches)
## Merging the feature branch to master
Once a feature branch has been successfully tested
([went through integration](#integrating-the-feature-branch-and-adding-it-to-the-testsuite)),
then Jenny can ask her branch to be merged into master by opening a
[Pull Request](Source-Code-Management-with-Git#pull-request).
## Closing the feature branch
At the end of the reintegration Jenny removes her feature branch, which
has reached the end of its life-time with the merge into `master`.
``` {.bash}
# change to the master-branch
> git checkout master
# delete the local branch
> git branch -d Kinetic_arrangement_2-jenny
# delete the branch on cgal-dev
> git push cgal-dev --delete Kinetic_arrangement_2-jenny
```
Remarks:
- If the last command does not work because your version of
Git does not know `git push --delete`, then you can use the old syntax:
"`git push cgal-dev :Kinetic_arrangement_2-jenny`".
- Removing the local branch is actually not a requirement. What happens in your own
repository is your responsibility.
- Once a branch is merged into
another, even if all the references to the branch has been removed, the
branch itself still exist in the history of the branch where it has been
merged. Thus, it is possible to revive old feature branches, using for
example [the procedure described on the Kitware wiki](http://public.kitware.com/Wiki/Git/Workflow/Topic#Old_Topic).
## Problem with end-of-line encoding in a feature branch
The CGAL repository used to include a few files with `crlf`, and
`crlfcr` end-of-line encoding. These have been fixed in master by
updating the .gitattributes (`6b43b44e642a560cf63f6dac3438298cbd3f4de4`)
and problematic files (`1adf441b18227f2e064abe59173a6fb7a6e48d65` and
`7d20531b1def82fe7f8bcc1bb557c3a350b23270`). In your feature branch
created before those fixes, it might happen that you need to modify the
re-encoded files. In order to avoid a problem while merging your branch
to master, it is advised to do the following:
``` {.bash}
# stash current work
> git stash
# update the .gitattributes
> git cherry-pick -x 6b43b44e642a560cf63f6dac3438298cbd3f4de4
# resolve the conflict by accepting the new version
# -x write the picked hash to the commit message, -ff tries a fast-forward
> git add .gitattributes
> git commit
# force re-encoding of eol
> rm .git/index
> git reset
> git commit -a -m "Convert all CRLF files to LF"
# then pop the stash to retrieve the modifications you have stashed
> git stash pop
```
(An alternative to be checked could be to set
`git config merge.renormalize true` as written in this thread
[5](http://stackoverflow.com/questions/861995/is-it-possible-for-git-merge-to-ignore-line-ending-differences)
## How to develop several features in parallel
### How to work on a different branch?
Assume Jenny is developing several features in different branches. With
Git it is very easy to deal with different (local) branches. Before she
checks out another branch, she ensures that her workspace has no
modifications, that is, `git status` reports no alterations. If there
are, she either commits them to her local repository (see above) or
*stash* them onto a stack (not explained here).
To checkout her feature branch `Convex_hull_2-make_it_faster-jenny` she
uses the following command:
``` {.bash}
> git checkout Convex_hull_2-make_it_faster-jenny
```
**NOTE: In contrast to SVN, Jenny is not required to be in the root of
the branch to switch them.** Git-commands likes `status` or `checkout`
can be called in any subdirectory and still work on the whole branch.
Future commits from that working copy will be made to the branch
`Convex_hull_2-make_it_faster-jenny` (until the next use of
`git checkout ` command).
Then, she can continue developing the new feature and commit changes
into the right branch. If she adds a new package, a new
[branch-build](Branch-Build) may be required to
include the new package in CGAL.
### Which branch Jenny is currently working on?
When Jenny develops more than one feature in several feature branches
she may frequently checkout various branches. If at any point Jenny is
uncertain which feature branch is currently checked out she can issue
the following command:
``` {.bash}
> git branch Kinetic_arrangement_2-jenny
```
At this point, the repository's workspace contains a full checkout of
CGAL, with all the packages, representing the current state of a branch.
Some shells can be extended to give the branch name in the prompt. See,
e.g., [6](http://aaroncrane.co.uk/2009/03/git_branch_prompt/)
(untested). Ask a search engine if you want to have this gimmick. There
is also tab-completion for branch names available.
### Building after switching/updating
For now, it is compulsory to
[rebuild](Branch-Build) CGAL each time a working
copy either is switched from one branch to another or if the branch is
simply updated.
Remarks:
- In fact, rebuilding CGAL is '''only needed if a cpp file has
been added, removed or altered or include dirs have been added or
deleted ''' during the switch/update
- As CGAL mainly consists of
header files, actual rebuilds are often not needed.
- For the same
reason, it is actually not a big harm to rebuild, as this is done within
less than a minute.
- There is a chance that in the future a
warning/error is reported if build and working copy do not match.
**Comment:** Jenny can also maintain [several working directories](Git-FAQ#What_if_I_want_to_work_on_multiple_branches_in_parallel.3F)
in parallel from one repository. This is recommended if switching
branches happens quite often. On the other hand, Git encourages to often
commit (to the local repository, while pushes to the central repository
can be less often), and such a single checkout should usually not be
dirty (and even if: `git stash` offers a nice way to temporarily clean
up - and to get it *dirty* again.
## How to use another feature in own feature branch
At some point Jenny notices that she needs, in her branch
`Convex_hull_2-make_it_faster-jenny`, a feature that has been
implemented by Adam in the `STL_extension-new_iterator-adam` branch. It
is required that Adam's feature is already integrated. Then, Jenny has
to revive his feature branch and merge it into her branch; she never
merges the branches `integration`, `master` or `maint` into her feature
branch! We follow roughly the ideas in
[7](http://public.kitware.com/Wiki/Git/Workflow/Topic#Dependent_Topic)
with details from
[8](http://public.kitware.com/Wiki/Git/Workflow/Topic/Conflicts#Topic-to-Topic)
and
[9](http://public.kitware.com/Wiki/Git/Workflow/Topic/Conflicts#Resolution_Topic)
(note that their `next` is our `integration` branch):
``` {.bash}
# update the local copies of the remote branches cgal-dev/* &gt; git fetch cgal-dev
```
Use
``` {.bash}
> git log --first-parent cgal-dev/integration
```
to find the merge-commit for Adam's feature. The commit message gives
you the name of Adam's branch. The second parent of the commit (see the
message) is the end of Adam's feature branch, say 0a398e5. Next Jenny
creates a branch from this commit
``` {.bash}
> git branch STL_extension-new_iterator-adam 0a398e5
```
Now Jenny can merge that branch into her feature branch
``` {.bash}
> git checkout Convex_hull_2-make_it_faster-jenny
> git merge STL_extension-new_iterator-adam
# resolved conflicts!
# and delete Adam's revived branch
> git branch -d STL_extension-new_iterator-adam
```
This way, only Adam's feature is merged into Jenny's branch, while all
other new features on `integration` are excluded. Thus Jenny's feature
has no dependencies to those features. Furthermore there is a crisp
commit message for the merge "Merge branch
'STL\_extension-new\_iterator-adam' into 'Mesh\_3-jenny'" which is much
more appealing than the merge for the whole `integration` branch.
Downside: Jenny's feature is now dependent on Adam's.
## Developing and committing to several orthogonal feature branches
There are scenarios where Jenny wants to compile programs with sources
from several branches, like
- preparing some experiments for a paper
- providing a demo or a web service with experimental code (e.g. for
reviewers of papers)
There are two ways:
- Checkout [several
branches](Git-FAQ#What_if_I_want_to_work_on_multiple_branches_in_parallel.3F)
and tweak `CMakeLists.txt` of your executable to collect the right
includes from several checkouts.
- Create a new local branch
`Combined-jenny` and merge all relevant feature branches into it:
`git merge branchA branchB [... branchG]`
The former feels more dirty and less *gitty*. The latter has the
problems that commits are expected on the individual feature branches
and in contrast to `Combined-jenny`. In the following Jenny decides for
the second way. Her rationale is to submit the features indepently! But
she is aware of the fact that this is only recommended if her commits
are rather orthogonal across the branches (e.g. adding GPU support to an
algebraic kernel in one branch, and implementing a new point location in
arrangements in another branch). As soon as a commit in one branch
requires a commit in the other (e.g. a change in the interface) the
following method is not recommended.
[Combining orthogonal feature branches](#developing-and-committing-to-several-orthogonal-feature-branches)
## Sharing your branches with the outside
If Jenny wants to share a branch with a person who does not have access to
`cgal-dev`, she has two solutions:
* The branch is not sensitive and
can be made public: she can push it into her own `cgal` fork (`mine`).
The procedure is the same as when she prepares a ["pull request"](Source-Code-Management-with-Git#pull-request).
* The branch is sensitive and cannot be made public yet: If not already
done, create a fork of the repository `private-fork` by visiting
[<https://www.github.com/CGAL/private-fork>](https://www.github.com/CGAL/private-fork)
and clicking on the <i>fork</i> button. she can now visit
[<https://www.github.com/jenny/private-fork>](https://www.github.com/jenny/private-fork),
click on <i>Settings</i> and add <i>Collaborators</i> to which she wants
to give access to the private repository. She has to update her git
config to add this new repository as a remote:
```
> git remote add private-mine git@github.com:jenny/private-fork.git #assuming your GitHub ID is jenny
> git fetch private-mine
```
Then pushing a branch `Pkg-modif-jenny` can be done using:
```
> git checkout Pkg-modif-jenny # switch to the branch from cgal-dev you want to share
> git push mine Pkg-modif-jenny # public option
> git push private-mine Pkg-modif-jenny # private option
```
Note that if Adam or Jenny did a modification that (s)he pushed into cgal-dev, when
ready the other remotes can be updated by simply pushing the branch into them.

246
Guidelines/Source_code_management/Git-FAQ.md Normal file

@ -0,0 +1,246 @@
<!--TOC-->
# Table of Contents
* [Which clients?](#which-clients)
* [How much space do I need on my disk?](#how-much-space-do-i-need-on-my-disk)
* [How can I see which branch I am on?](#how-can-i-see-which-branch-i-am-on)
* [What if I want to work on multiple branches in parallel?](#what-if-i-want-to-work-on-multiple-branches-in-parallel)
* [How to remove old branches that are already merged](#how-to-remove-old-branches-that-are-already-merged)
* [How can I disable/change the pager used by some git commands?](#how-can-i-disablechange-the-pager-used-by-some-git-commands)
* [How can Git ignore files globally?](#how-can-git-ignore-files-globally)
* [How to create aliases for Git commands?](#how-to-create-aliases-for-git-commands)
* [How to search for the commits of a certain author?](#how-to-search-for-the-commits-of-a-certain-author)
* [My branch is really old. I would like to update it to get latest update from master.](#my-branch-is-really-old-i-would-like-to-update-it-to-get-latest-update-from-master)
* [Simpler alternative if your have not shared your branch with others](#simpler-alternative-if-your-have-not-shared-your-branch-with-others)
* [I want to rename a local branch, without renaming the upstream branch (in cgal-dev)](#i-want-to-rename-a-local-branch-without-renaming-the-upstream-branch-in-cgal-dev)
* [I see remote branches in my repository that have been removed on the server. How do I update my local clone?](#i-see-remote-branches-in-my-repository-that-have-been-removed-on-the-server-how-do-i-update-my-local-clone)
<!--TOC-->
We here collect questions already raised on the cgal-dev mailing list or
stated below.
Note that the Git project already has a huge FAQ:
<https://git.wiki.kernel.org/index.php/GitFaq>
## Which clients?
On Linux/Mac OS git comes as command line tool. Please refer to your
package manager to install it. You can also install git from sources
(http://www.git-scm.org/downloads). For windows there is also a command
line (http://code.google.com/p/msysgit/)
There are also many GUI available, **for instance**
- Windows: TortoiseGit (which is similar to TortoiseSVN), SmartGit,
GitEye
- Mac OSX: Sourcetree, Tower, SmartGit, GitEye
... and many others. Please explore the web (eg here
<http://git-scm.com/downloads/guis>) to find your preferred one.
## How much space do I need on my disk?
With `git clone <url>` you receive a full repository with all branches
as existing on the server. In addition the branch `master` will be
checked out. A clone of `cgal.git` needs about 0.75 GB.
A clone of `cgal-web.git` also needs about 0.75 GB.
## How can I see which branch I am on?
``` {.bash}
git branch
```
displays all the local branches, and display a '\*' in front of the
current branch.
The first line of the 'status' command also displays the branch:
``` {.bash}
git status
```
There is also a shell prompt, see
<http://nuclearsquid.com/writings/git-new-workdir/>
## What if I want to work on multiple branches in parallel?
If you are working on several branches at a time and for several reasons
you don't want to switch all the time, Bash (or git-shell) users can use
the script `git-new-workdir` on the
[https://github.com/git/git/tree/master/contrib/workdir git
repository](https://github.com/git/git/tree/master/contrib/workdir git repository).
It's creating a copy of the repo but the git config files are not
duplicated (they are symlinked).
``` {.bash}
git clone cgal cgal-other
```
create another local clone (with hardlinks even very fastly). However,
it extends the tree of git repositories by one more child. There is
``` {.bash}
git new-workdir <repo>
<dir>
```
that does not come with all distributions, but check
<http://nuclearsquid.com/writings/git-new-workdir/> how to get it.
Suppose that your cgal clone is in `/home/jenny/CGAL/Git/cgal` do:
``` {.bash}
> cd /home/jenny/CGAL/Git/
> git-new-workdir cgal"ng"A
```
**Recommendation:** Jenny can add as third parameter the name of the
branch you want to checkout. It looks convenient to name the new working
directory as the branch, that is:
``` {.bash}
> git-new-workdir cgal Convex_hull_3-make_it_faster-jenny Convex_hull_3-make_it_faster
```
**Note for Windows users:** `git-new-workdir` needs symbolic links. Do
not try to use it on Windows unless you only use git.exe from Cygwin.
Git.exe from msysgit or Tortoize will not work with such a working
directory.
We also discuss (for advanced users) [how to combine several orthogonal features in one branch](Developing-Features-with-Git#developing-and-committing-to-several-orthogonal-feature-branches)
## How to remove old branches that are already merged
The command `git branch --merged cgal/master` lists all local branches
that are already merged into `cgal/master`. (Note that `integration` and
`master` are usually seen as merged into `master`.) The following
command remove all such branches, but `integration` and `master`:
``` {.bash}
git branch --merged cgal/master | grep -vE 'master|integration' | xargs -n 1 git branch -d<br />
```
(adaptation from [a StackOverflow answer](http://stackoverflow.com/a/6127884/1728537))
## How can I disable/change the pager used by some git commands?
git sends the output of some commands to a pager (like `less` or
`more`). If you don't like that, e.g., because the used pager does not
understand the escape sequences for colors, the pager can be disabled or
changed with the command
``` {.bash}
git config --global core.pager cat
```
`cat` effectively disables paging. A different pager can be set by
supplying the command name there.
## How can Git ignore files globally?
See this nice
[tutorial](https://help.github.com/articles/ignoring-files)
## How to create aliases for Git commands?
See that page: <https://git.wiki.kernel.org/index.php/Aliases>
## How to search for the commits of a certain author?
``` {.bash}
> git log -p --author="Jenny";
```
## My branch is really old. I would like to update it to get latest update from master.
Assuming you are currently working on a branch called
`my-ancient-feature`.
``` {.bash}
git branch -m my-ancient-feature my-ancient-feature-old
# Rename your branch to a temporary name.
# Please use the same name with an -old suffix, because that temporary name
# will be seen in the commit log message later.
git fetch cgal
git checkout -b my-ancient-feature --no-track cgal/master
# Creates a branch from master with the same old name and switch to it.
# The --no-track option is in order to avoid accidental pushes to master.
# It tells git that the new branch must not track
# the remote branch cgal/master
git merge --no-commit my-ancient-feature-old
# Merge the old branch into the newly created one.
# Then resolve conflicts, if there are any. You can also review the changes
# made by the merge with the following command:
git diff --staged
# Once you resolved everything, you can commit that merge:
git commit
# Now you are ready to specify the -u cgal-dev option
# which is needed because the branch, even if it has the same name as before,
# is a new branch that does not track any remote branch.
# (If your branch is an old GSoC branch that you want to keep in the dedicated
# cgal-public-dev.git repository, then replace "cgal-dev" by "cgal-public-dev", in the following command.)
git push -u cgal-dev my-ancient-feature
# That update is a regular fast-forward push, that other developers will be able
# to pull without issues.
# note -u is equivalent to --set-upstream
# Then delete your old local branch
git branch -D my-ancient-feature-old
```
Note that if you have a [special working directory for this branch](#what-if-i-want-to-work-on-multiple-branches-in-parallel),
you will need to erase it and recreate it.
### Simpler alternative if your have not shared your branch with others
If your branch hasn't been shared with others (e.g. push it to a remote
or you are absolutely sure that no one has done any work based on your
branch) you can forgo the above procedure and rebase your branch from an
updated master. Rebasing is the process of replaying your commits on top
of an updated upstream.
This should not be done if you simply intend to merge your branch to
master because it hides the actual integration changes that would
usually be represented by the differences of the merge commit.
``` {.bash}
# switch to your ancient feature
git checkout my-ancient-feature
git rebase cgal/master
# follow the instructions of the output of rebase, fix conflicts
```
Be warned that, if you use `git-rebase` while other developers also work
on the same branch, their next `git-pull` will show a *lot* of
conflicts!
## I want to rename a local branch, without renaming the upstream branch (in cgal-dev)
Just do:
``` {.bash}
git branch -m <oldname> <newname>
```
## I see remote branches in my repository that have been removed on the server. How do I update my local clone?
``` {.bash}
git fetch -p
```
will do the job
If you have more than one remote, you can add the option `--all` to
apply it to all of them.
``` {.bash}
git fetch --all -p
```

121
Guidelines/Source_code_management/Migration-to-Github.md Normal file

@ -0,0 +1,121 @@
<!--TOC-->
# Table of Contents
* [Create a GitHub account](#create-a-github-account)
* [Migration Procedure for Regular Developers](#migration-procedure-for-regular-developers)
* [Migration Procedure for Student Developers](#migration-procedure-for-student-developers)
* [Migration Procedure for Web Developers](#migration-procedure-for-web-developers)
* [New procedure to merge a branch into master](#new-procedure-to-merge-a-branch-into-master)
<!--TOC-->
Since the 5th of March 2015, the Git repositories of the CGAL project
are hosted on GitHub.
## Create a GitHub account
The first step is to create a GitHub account [as described here](Information-for-New-Developers#creating-a-GitHub-account).
## Migration Procedure for Regular Developers
We describe here the procedure to migrate a repository that was using
`ssh://git@scm.cgal.org/var/git/cgal.git` as url for the *origin* remote
and `ssh://gsoc@scm.cgal.org/var/git/cgal-gsoc.git` as url for the
*gsoc* remote. If you have only one remote choose the correct one
(`cgal-public-dev` if you are a student or `cgal-dev` if you are a
*regular* developer).
Rename your *origin* remote to *cgal-dev* and update its url:
``` {.bash}
cd ~/CGAL/git/cgal #where your git clone is locate on your disk git remote rename origin cgal-dev git remote set-head cgal-dev integration git remote set-url cgal-dev git@github.com:CGAL/cgal-dev.git git fetch --all --prune
```
Rename your *gsoc* to *cgal-public-dev* and update its url:
``` {.bash}
git remote rename gsoc cgal-public-dev git remote set-url cgal-public-dev git@github.com:CGAL/cgal-public-dev.git
```
Master is no longer writable for regular developers. You need to setup a
new remote to access it:
``` {.bash}
git remote add cgal git@github.com:CGAL/cgal.git
```
and set the tracking branch of your local master branch:
``` {.bash}
git fetch cgal git branch --set-upstream-to=cgal/master master # for git &lt; 1.8: git branch --set-upstream master cgal/master
```
The command `git remote -v` should now show the following:
```{.bash}
$ git remote -v
cgal git@github.com:CGAL/cgal.git (fetch)
cgal git@github.com:CGAL/cgal.git (push)
cgal-dev git@github.com:CGAL/cgal-dev.git (fetch)
cgal-dev git@github.com:CGAL/cgal-dev.git (push)
cgal-public-dev git@github.com:CGAL/cgal-public-dev.git (fetch)
cgal-public-dev git@github.com:CGAL/cgal-public-dev.git (push)
```
You can now fetch all the remotes at once with:
``` {.bash}
git fetch --all
```
## Migration Procedure for Student Developers
Rename your *origin* to *cgal-public-dev* and update its url:
``` {.bash}
cd ~/CGAL/git/cgal #where your git clone is locate on your disk git remote rename origin cgal-public-dev git remote set-head cgal-public-dev -d git remote set-url cgal-public-dev git@github.com:CGAL/cgal-public-dev.git git fetch --all --prune
```
Master is not writable. You need to setup a new remote to access it:
``` {.bash}
git remote add cgal git@github.com:CGAL/cgal.git
```
and set the tracking branch of your local master branch:
``` {.bash}
git fetch cgal git branch --set-upstream-to=cgal/master master # for git &lt; 1.8: git branch --set-upstream master cgal/master
```
The command git remote -v should now show the following:
``` {.bash}
$ git remote -v
cgal git@github.com:CGAL/cgal.git (fetch)
cgal git@github.com:CGAL/cgal.git (push)
cgal-dev git@github.com:CGAL/cgal-dev.git (fetch)
cgal-dev git@github.com:CGAL/cgal-dev.git (push)
cgal-public-dev git@github.com:CGAL/cgal-public-dev.git (fetch)
cgal-public-dev git@github.com:CGAL/cgal-public-dev.git (push)
```
You can now fetch the two remotes at once with:
``` {.bash}
git fetch --all
```
## Migration Procedure for Web Developers
Rename your *origin* to *cgal-web* and update its url:
``` {.bash}
cd ~/CGAL/git/cgal #where your git clone is locate on your disk git remote rename origin cgal-web git remote set-url cgal-web git@github.com:CGAL/cgal-web.git
```
Verify all is good:
``` {.bash}
git fetch --all
```
## New procedure to merge a branch into master
We now use [pull requests](Source-Code-Management-with-Git#pull-request).

36
Guidelines/Source_code_management/Naming-Recommendations.md Normal file

@ -0,0 +1,36 @@
## Naming recommendation for feature branches
The name should be made of four optional strings separated by dashes:
1. A common identifier used as prefix (e.g., gsoc2014) if applicable.
2. The name of a significant package involved (an existing or a new
one) if applicable.
3. The name of the single component added or modified (e.g., class,
function, concept, or enum) if applicable, or a description of the
changes to see. Maybe prefixed with "fix" if it's a bugfix.
4. The login username of the main developer or the name of a group
(e.g., geometrica, vegas, mpi, eth, gf or forth) if applicable.
Examples:
- Assume Jenny would like to develop a fast implementation of the 2D
convex hull, the recommended name would be:
`Convex_hull_2-make_it_faster-jenny`
- Sandeep is a GSoC student in 2014. He works on the plane-sweep code
in the Arrangement\_on\_surface\_2 package. The recommended name is:
`gsoc2014-Arrangement_on_surface_2-plane_sweep-sandeep`
- Adam is fixing a bug in the Mesh\_3 package. The recommended name is
`Mesh_3-fix_point_at_infinity-adam`
Notice that you will need to enter these names in places where you may
not have automatic name-completion. For example, if you are involved in
the development of several new features developed in different branches,
you may need to switch between the different branches often. Switching
between branches is a common routine for you that you would like to
facilitate. For GIT there exists tab completion of branch names and many
programs with GUIs.

395
Guidelines/Source_code_management/Quick-Start.md Normal file

@ -0,0 +1,395 @@
<!--TOC-->
# Table of Contents
* [Obtain Git repository](#obtain-git-repository)
* [General Setup](#general-setup)
* [Additional Setup for Adding Another Remote](#additional-setup-for-adding-another-remote)
* [Status](#status)
* [New feature branch](#new-feature-branch)
* [Switching branches](#switching-branches)
* [Other branches](#other-branches)
* [diff/log](#difflog)
* [Revert last commit](#revert-last-commit)
* [Comparing Branches](#comparing-branches)
* [Branch completion](#branch-completion)
<!--TOC-->
This guide gives a quick introduction to using Git with `CGAL`.
Beyond, it is valuable to read more "getting started" information at
[Git - SVN Crash Course](http://git-scm.com/course/svn.html). There is
also plenty of nice documentation on the web, e.g. the [Git community
Book](http://book.git-scm.com/). Some fundamental concepts are nicely
explained
[here](http://eagain.net/articles/git-for-computer-scientists/), and,
about Git and Tortoise Git [there (nice course notes, in
french)](http://marc.chevaldonne.free.fr/ens_rech/Csharp_XML_GI_2010_2011_files/Quick%20Guide%20Git%20TortoiseGit.pdf).
In the following commands of the command-line client of Git (`git` on
Linux/Mac OS, `git.exe` on Windows cygwin) are given. They naturally
translate to GUI-guided actions. Intuitive GUIs exists. For instance,
for **Windows** (TortoiseGit, which is similar to TortoiseSVN, or
[GitExtensions](http://gitextensions.github.io/), that integrate
into Visual Studio) and **Mac OSX** (Sourcetree) or **both** (SmartGit)
- and many others. Feel free to explore the web and choose a GUI to your
preference and wallet (or stay with the command-line client). Cloning,
branching, committing, merging is equivalent (or even simpler) in GUIs.
Please refer to tutorials on the web how to install them (e.g. for
[TortoiseGit](http://robertgreiner.com/2010/02/getting-started-with-git-and-tortoisegit-on-windows/)).
See also our [FAQ](Git-FAQ#which-clients).
Beyond the following, and for reference reasons, check the
[http://byte.kde.org/\~zrusin/git/git-cheat-sheet-medium.png Git Cheat Sheet](http://byte.kde.org/~zrusin/git/git-cheat-sheet-medium.png Git Cheat Sheet)
## Obtain Git repository
### General Setup
Jenny has Git installed. Next Jenny needs to set **once** some basic
variables. She uses the following commands (while replacing personal
information!):
``` {.bash}
# required variables
> git config --global user.name "Jenny Doe"
> git config --global user.email "jenny.doe@example.com"
# useful variables
## pretty
> git config --global color.branch auto
> git config --global color.diff auto
> git config --global color.interactive auto
> git config --global color.status auto
## religious statement about editor preference
> git config --global core.editor "emacs"
```
`git config --global` stores the values for these variables in a Jenny's
`.gitconfig` file.
Now Jenny is ready to get her own local repository by **cloning** the
remote repository on our server:
``` {.bash}
> git clone -o cgal-dev git@github.com:CGAL/cgal-dev.git my_cgal_folder #If you are NOT a CGAL student
> # or
> git clone -o cgal-public-dev git@github.com:CGAL/cgal-public-dev.git my_cgal_folder #If you are a CGAL student
```
Master and release branches are not writable by regular developers.
Jenny needs to add another remote and add a local master branch:
``` {.bash}
> cd my_cgal_folder
> git remote add cgal git@github.com:CGAL/cgal.git
> git fetch --all
> git checkout -b master cgal/master
```
The local repository is a full clone of the remote repository which
includes all branches and tags, and is stored in very efficient
compressed fashion. Its size is about 850 MB. Cloning also checks out
the integration branch.
At this point we also *strongly recommend* to run
``` {.bash}
> cd my_cgal_folder
> ./Scripts/developer_scripts/cgal_git_update_hooks_for_client
```
which installs a pre-commit hook to Jenny's local repository (Windows
users: there is a git-bash in the context menu of Git in which you can
run the script). The hook gives you *early alerts* for commit that will
be rejected by the central repo when you try to push your changes to it.
With
``` {.bash}
> git branch
* master # the star marks the current branch
integration
```
Jenny sees on which branch she is currently working on. Here she is
working on the **local** `master`:
``` {.bash}
> ls
AABB_tree
Algebraic_foundations
Algebraic_kernel_d
...
iostream
kdtree
wininst
```
### Additional Setup for Adding Another Remote
You can add another remote like this:
``` {.bash}
# go into your cgal git repository folder and then
> git remote add cgal-public-dev git@github.com:CGAL/cgal-public-dev.git
# After that
> git fetch cgal-public-dev
#brings in all branches from the cgal-public-dev repository.
> git branch -a
#will show the branches:
remotes/cgal-public-dev/hooks-for-clients
remotes/cgal-public-dev/hooks-on-server
remotes/cgal-public-dev/gsoc2013-XXXX-student
#Starting to work on such a branch works as for branches on "cgal-dev" - see the guidelines, and replace "cgal-dev" with "cgal-public-dev" - or add "cgal-public-dev" to pushes
git push cgal-public-dev gsoc2013-XXXX-student
#If you want to push a branch from gsoc to the main repository, use
git push cgal-dev gsoc2013-XXXX-student
```
## Status
To check the status of the current branch she uses
``` {.bash}
> git status
# On branch master
nothing to commit (working directory clean)
```
`git status` also shows the status of all files (modified, staged,
deleted, etc) in the repository - no matter whether Jenny is the root
level of the repository or in a subdirectory.
## New feature branch
In order to start a feature development she comes up with a name for a
branch following our <b>[naming conventions](Naming-Recommendations)</b>,
here `Mesh_9-jenny`, and then uses
``` {.bash}
> git checkout -b Mesh_9-jenny --no-track cgal/master
Switched to a new branch 'Mesh_9-jenny'
> git branch
master
* Mesh_9-jenny
```
This command creates a local branch `Mesh_9-jenny` from the master
branch and checks it out. It is shorthand for:
``` {.bash}
> git checkout master
> git branch Mesh_9-jenny
> git checkout Mesh_9-jenny
```
Next, Jenny can alter files and commit changes and check the status
again with `git status`. Before commiting she uses
``` {.bash}
> git add [myfiles.hpp]
> git commit
[Mesh_9-jenny 6341737c37db] Message
1 file changed, 1 insertion(+)
```
`git add` to *add* a file to the index (list of files scheduled for next
commit), while `commit` really executes the commitment (of all indexed
files - in the version they have been added to the index!)
'''Remarks: ''' \* Note that every "commit" is only done to the
**local** repository. It stores all previous and new commit information.
\* Each commit *gets assigned a SHA-1 hash* (a cryptographically
tamper-proof signature of your file contents), here
`6341737c37dbcd932e6646eac2347d9402f12b07`. For convenience these hashes
can be abbreviated with the first chars only (seven is usually
sufficient to uniquely identify a commit). It is also mentioned to which
branch Jenny has committed (here "Mesh\_9-jenny"). \* In case you want
to *abort* the commit, you just don't write a **commit message**!
The next step is synchronize the local changes with the remote location.
In order to avoid wrong pushes to `master` Jenny adds this to her
configuration
``` {.bash}
> git config --add push.default simple
# In even older Git version (<1.7.11) 'simple' must be replaced with 'current' or 'tracking' (for even older versions)
```
This refuses a push if the local and remote branchnames do not match
(check whether other repositories also need this option - or whether you
want to add it to you global `.gitconfig` - can be done by adding
`--global` option). Though this should now happen if she **initially
pushes with** the `-u` flag. Jenny sends the branch onto the remote
repository she cloned from ("cgal-dev"):
``` {.bash}
> git push -u cgal-dev Mesh_9-jenny
```
Let's explain this in more detail: The `push` mirrors the local branch
`Mesh_9-jenny` into the remote repository "cgal-dev". This way her
branch becomes available to everybody with access to the "cgal-dev"
repository - and her commits get also backup'ed in the remote location.
The `-u` option not only publishes the branch on the remote, but also
sets it as a *tracking branch* of her local branch. Every future
``` {.bash}
> git push
```
will publish her local changes onto *cgal-dev*.
## Switching branches
Jenny now has two local branches, she is in Mesh\_9-jenny and she can
switch back to master with
``` {.bash}
> git checkout master
```
## Other branches
By using
``` {.bash}
> git branch -a
* Mesh_9-jenny
master
remotes/cgal/master
remotes/cgal-dev/Mesh_9-jenny
remotes/cgal-dev/Kernel-rewrite_functors-adam
```
can see a list of all local branches and all branches on the configured
*remotes*.
If Jenny wants to work on one of those remote branches she uses
``` {.bash}
> git checkout -b Kernel-rewrite_functors-adam cgal-dev/Kernel-rewrite_functors-adam
```
That command creates a *local* branch named
`Kernel-rewrite_functors-adam` as a copy of the current state of the
*remote* branch `cgal-dev/Kernel-rewrite_functors-adam`. Be careful that
the branch name appears twice: after `-b`, and after `cgal-dev/`. The
branch name after `-b` is actually a free name you can choose, where as
`cgal-dev/some_name` refers to an existing referenced branch on the
remote repository `cgal-dev`.
Again she alters files:
``` {.bash}
> git add [otherfiles.hpp]
> git commit
```
And finally she pushes her changes back to the remote location.
As some Git versions (e.g. 1.7.9.5) set no default upstream branch for
push, Jenny adds this to her configuration
``` {.bash}
> git config --add push.default simple
# In even older Git version 'simple' must be replaced with 'current' or 'tracking' (for even older versions)
```
If this is set (or the Git version is new enough) the following suffice
to push changes to `cgal-dev`
``` {.bash}
> git push
```
Note that here the tracking of the upstream branch
`cgal-dev/Kernel-rewrite_functors-adam` is correct, thus a `git push`
suffices.
In order to update her branch from the remote repository, Jenny gets the
changes into her local repository with:
``` {.bash}
> git fetch
> git merge
```
We refer Jenny for full details on how to work with branches to [the
section on how to use branching in Git for code
development](Developing-Features-with-Git#how-to-develop-several-features-in-parallel).
## diff/log
`git log` is used to inspect the revision history of a file, repository
or branch.
``` {.bash}
> git log # plain log of current repository
> git log --follow -- filename # file history, including before renames
> git log -p # add diffs
> git log --since=2.weeks # commits of the last 2 weeks
```
`git diff` is used to inspect the changes between commits
``` {.bash}
> git diff # the difference between the working copy and the index
> git diff --cached # the difference between the index and the last commit
> git diff HEAD HEAD^ --stat # the changed files between the last commit and the commit that came before
> git diff HEAD HEAD^ -- my_file.h # same as above, but just for my_file.h
> git diff master..my_branch # diff between master and my_branch
```
## Revert last commit
There are several scenarios: \* the bad commit wasn't pushed yet \* the
bad commit was already pushed to a remote \* the commit is not really
that bad, wasn't pushed yet and can be fixed easily
In the first case `git reset --hard HEAD^` resets your repository to the
commit just before the last one. All changes in the last commit will be
lost.
In the second case, `git revert commit_name` followed by a `git push` is
one of the less intrusive options. It will create a new commit that
reverts the old one.
In the third option `git commit --amend` can be used to modify the
current HEAD commit. This is useful if something has been forgotten in
the last commit.
## Comparing Branches
Sometimes it is useful to see if a branch is actually a subset of
another, e.g. if all commits of a local branch have been pushed to the
remote.
``` {.bash}
> git log cgal-dev/my_branch..my_branch
# if empty, everything is pushed
```
Similarily,
``` {.bash}
> git log --branches --not --remotes
```
will show all commits on local branches that are not present on remote
branches. The options `--decorate --graph` can be added to decorate the
result of the `git log` command with the name of the branches involved,
and the drawing (in ASCII) of the graph of commits.
The above commands are also useful to check if a release branch is a
subset of an integration branch and which commits are still candidates
to be picked.
## Branch completion
The Bash completion system offers completion for branches and prompt
modifications (to display current branch in prompt). Google is your
friend.

407
Guidelines/Source_code_management/Source-Code-Management-with-Git.md Normal file

@ -0,0 +1,407 @@
<!--TOC-->
# Table of Contents
* [History](#history)
* [Git Repository Layout](#git-repository-layout)
* [Branches](#branches)
* [Feature branches](#feature-branches)
* [Utility branches](#utility-branches)
* [Tags and Release Branches](#tags-and-release-branches)
* [Working with Git](#working-with-git)
* [Workflow](#workflow)
* [Guidelines](#guidelines)
* [Pull request](#pull-request)
* [Update a pull-request](#update-a-pull-request)
* [Bug-fix branch](#bug-fix-branch)
* [Commit Messages](#commit-messages)
* [Branch-build](#branch-build)
* [Post-commit mails](#post-commit-mails)
* [Special files in or not in the repository](#special-files-in-or-not-in-the-repository)
* [Git: Working with the local and the remote repository](#git-working-with-the-local-and-the-remote-repository)
* [Further Directions](#further-directions)
* [Commitment](#commitment)
* [Resources](#resources)
<!--TOC-->
## History
CGAL's code is maintained by a **Source Control Management** system. It
keeps track of the complete history of changes of a set of source files.
When several people work on the same project, using a Source Control
Management system becomes vital. At the beginning, CVS was used. At some
point CVS was replaced by the popular SVN (Subversion). This document
describes the current iteration, where Git is enabled as a new version
control system that has better support for branching and also allows
decentralized repositories. As each developer holds a local repository,
branching in Git is much faster.
## Git Repository Layout
Any Git repository for CGAL, in particular your local one, contains
various branches. A branch represents a version of CGAL, that is a set
of source, header and documentation files needed to
[build](Branch-Build) a version of CGAL. Each
branch contains `CMakeLists.txt` file that serves as anchor for
building, and a set of subfolders, so called *packages* (packages have
their own [certain
structure](Directory-Structure-for-Packages)).
Most packages implement a data structure or an algorithm for CGAL (e.g.,
`Convex_hull_2`, or `Triangulation_3`); however some packages serve
special needs:
- Installation - meta-files and CMake-support
- Maintenance - infrastructural support
- Core, CGALimageIO, Qt_widget, GraphicsView - component libraries
- Scripts - scripts to simplify developer's and user's work
- Testsuite - infrastructure for testsuite
- MacOSX - support for writing demos for Mac OS X
- Documentation - infrastructure for CGAL's manual
- LEDA - interfacing external libraries
- STL_Extension - extensions to the standard template library
- Stream_support - support for iostreams
A branch of CGAL can contain a stable release or a forthcoming release,
a stable version with a collection of new features for the upcoming
release or an extension of a stable version with single new feature
under development; a branch can also exist for adding demos and
examples, or to fix non-trivial bugs. The development of any new code
(except for trivial bugfixes) must be carried out in a dedicated branch
referred to as a *feature-branch* (see [Developing features with branches](Developing-Features-with-Git)
for more details). Development in one branch can happen without
disturbing development in any other branch. A feature branch has a
limited life-time. Upon acceptance and successful integration and
testing of a new feature, the new code in the feature branch can be
integrated into a branch that collects all features for the upcoming
release, referred to as the `master` branch. Once this integration is
complete the feature branch will be removed. Small bug fixes that are
absolutely harmless are committed directly to `master` (though it is
very easy to do this on a feature branch, as its creation is a question
of seconds). A detailed description of the various branches follows:
### Branches
Note that, in contrast to SVN, a Git repository does not organize
branches in a tree. All branches exist next to each other. Each Git
repository (remote or local) contains the following (types of) branches.
We propose a layout that uses three different main branches for
development (ordered by stability):
master : This branch collects all features accepted and successfully integrated for the upcoming release. Changes to this branch are merges of tested, mature feature branches or merges of very small bug-fix branches.
integration : The integration branch represents the current ongoing development in CGAL and the test-suite is run from this branch. If the work in a feature branch is completed it is [merged into this branch and tested](Developing-Features-with-Git#integrating-the-feature-branch-and-adding-it-to-the-testsuite)
along with a separate branch for each feature and tags for specific
releases..
#### Feature branches
A feature branch is used for a single new feature that is under
development, such as a new package, a new function, or some kind of
optimization. A feature branch starts as a clone of `master`, that is
`master` is its *parent*. When Jenny intends to develop a new feature,
she creates the branch. A feature branch ceases to exist upon its
successful reintegration into `master`, which takes place after
acceptance of the feature by CGAL's Editorial Board and a successful
integration and test period - in particular, after invitation of the
Release Manager.
Larger bug-fixes, demos, or examples have to be developed in branches
and follow the same integration process even though those don't need to
follow the Guidelines for Features or Small Features and the approval
process.
Developers must follow the rules for [features](https://cgal.geometryfactory.com/CGAL/Members/wiki/Features) and
[small features](https://cgal.geometryfactory.com/CGAL/Members/wiki/Features/Small_Features)
and the [naming recommendations for feature branches](Naming-Recommendations).
#### Utility branches
A set of branches is maintained for things that are not immediately
related to the CGAL source repository. For now the only two candidates
are Debian packaging information and git-hook scripts. Such branches
should not be created lightly and often a separate repository is more
appropriate.
#### Tags and Release Branches
Tags of the form `X.Y.Z` denote releases of CGAL. If a release has to be
maintained even after new feature release (e.g. `3.9.1 -> 3.9.2`, while
the current release is `4.0`) this is done in a branch with the name
`maint-X.Y.(Z-1)`. Other tags are possible to be added; this is not
expected to happen often.
## Working with Git
[Quick Start](Quick-Start)
### Workflow
The main goal of the proposed workflow is to maintain a clean, easy to
understand history of the CGAL repository. General feature development
follows a few general steps. The specific commands to execute those
steps and descriptions are explained in
[Developing features with branches](Developing-Features-with-Git).
1. To develop a feature, a branch of the current master is created.
See:
[Opening a feature branch](Developing-Features-with-Git#opening-a-feature-branch)
2. When the development is finished and the feature is accepted the
branch is merged into `integration`.
[Integrating the feature branch and adding it to the testsuite](Developing-Features-with-Git#integrating-the-feature-branch-and-adding-it-to-the-testsuite)
3. After the branch has spent some time in integration and all
necessary adjustments have been made to integrate it successfully,
the feature branch (not `integration`) can be merged into the
`master` branch through a [pull request](#pull-request).
#### Guidelines
- Integration commit should happen in the feature branch, not in the
integration branch. That is, changes that are required to
successfully merge a feature into a stable branch, should be first
committed to the feature branch before merging the feature branch
into the stable branch (and not: first merge and then commit fixes
that are further needed to resolve conflicts) - merges of features
become conflict free this way.
### Pull request
A pull request is a request to merge a feature branch or a bug-fix
branch into master. In order to submit a pull request you need to have
your own fork of the cgal repository. If you don't already have one, go
to <https://github.com> and log in. Then go to
<https://github.com/CGAL/cgal> and click on the *Fork* button in the
upper right part of the page. You need to add another remote (*mine*) in
your git clone:
``` {.bash}
> git remote add mine git@github.com:jenny/cgal.git #assuming your GitHub ID is jenny
> git fetch mine
```
If I want to merge a feature branch from *cgal-dev* or
*cgal-public-dev*, I need to push that branch into *mine*:
``` {.bash}
> git push mine AABB_tree-dimension_2-jenny
```
Then go to your local fork (https://github.com/jenny/cgal), select the
branch `AABB_tree-dimension_2-jenny` and click on the green button left
to the branch selection box. You'll be asked to add a comment describing
what your merge is about. This should contain:
- the reference of the (small) feature corresponding to the branch, if
there is one,
- or the fact that the branch is a bug-fix, if that is the case,
- the internal release number in which the branch was last
successfully tested (if not a trivial fix).
**Note:** *please* use clickable links to the feature pages, and to the
test result page, to ease the job of the Release Manager.
If your pull request is accepted, you'll receive an email from github
and the branch will be removed from your local fork.
Finally, you can update the [features](https://cgal.geometryfactory.com/CGAL/Members/wiki/Features) or [small
features](https://cgal.geometryfactory.com/CGAL/Members/wiki/Features/Small_Features) table indicating that your
feature has been merged into `master`. To do so, move the feature line
from the table "Proposed features" to the table "Accepted/Integrated
into CGAL-x.y" below. This includes, in particular, mentioning the link
to the pull request.
If your feature branch was shared in `cgal-dev` or `cgal-public-dev`, do
not forget to remove it from there once the pull request is accepted:
``` {.bash}
> git push ''<repo>''--delete AABB_tree-dimension_2-jenny
```
where *<repo>* is `cgal-dev` or `cgal-public-dev`.
For more information about pull requests, refer to the official
documentation: <https://help.github.com/articles/about-pull-requests/>
#### Update a pull-request
If during the tests for integration, you need to update something in the
branch, then the pull-request is updated as soon as you push your branch
(with the modifications) in `mine` again:
``` {.bash}
> git push mine AABB_tree-dimension_2-jenny
```
#### Bug-fix branch
If you want to create a short term bug-fix branch, it is sufficient to
create it locally, push it in your *mine* remote, do a pull request and
then forget about it. The Release Manager will deal with the
pull-request and then remove the branch from your *mine* remote.
``` {.bash}
> git checkout -b AABB_tree-bug_fix-jenny --no-track cgal/master
# edit files, use git-add and git-commit to create a commit with the modifications, then:
> git push mine AABB_tree-bug_fix-jenny
# and then create the pull-request in the web interface
```
### Commit Messages
Use the following format for commit messages:
```
<max 79 characters short description>\n
\n
<long description, 79 chars per line>
\n
```
An example from the Git project (commit 2b34e486bc):
```
pack-objects: Fix compilation with NO_PTHREADS
It looks like commit 99fb6e04 (pack-objects: convert to use
parse_options(), 2012-02-01) moved the #ifdef NO_PTHREADS around but
hasn't noticed that the 'arg' variable no longer is available.
```
Git commands like log, shortlog, etc support this format and make use of
the short description. Please stick to the format. At some point a push
hook might be installed that will reject pushes containing
non-conforming commit messages.
### Branch-build
CGAL can be built from a branch directly, i.e., there is no need to
create an internal release. The developer Jenny can build the CGAL
libraries from the branch she is currently working on. The [branch build
has its own wiki page](Branch-Build).
### Post-commit mails
After each pushed commit, an automatic mail is sent to the
`cgal-dev-commits@inria.fr` mailing-list which records the log message
as well as the URLs to the corresponding diffs. Maintainers and
developers can subscribe to it in order to check what gets committed to
their packages.
### Special files in or not in the repository
- Do not put automatically generated files into the repository.
- Files and directories in the repository that you don't want to be
included in releases (e.g., literate programming web files) can be
listed with their names in a file called `dont_submit` (at the top
of a package, see
[Directory Structure for Packages](Directory-Structure-for-Packages)).
- The following files are always excluded from releases: `TODO`,
`todo`, `TODO.txt`, `todo.txt`, `TO_DO`, `Doxyfile` and `*.dxy` (as
as long Doxygen is not officially supported). more generally, you
can have a look at the file
`Maintenance/release_building/global_dont_submit` for the full list
of files or file patterns that are ignored globally during the
creation of release tarballs.
## Git: Working with the local and the remote repository
Git is essentially demanding and build on branches. This section gives a
high-level explanation of Git concepts. It is no replacement for reading
introductory materials.
The following picture is taken from
[1](http://tiebing.blogspot.com/2010/12/git-data-transport-commands.html).
It illustrates the connection between the local workspace, local index,
local repository and a remote repository. For now you can assume, for
simplicity, that the *remote repository* is located on a remote
filesystem. The *single* difference is that one is on a remote location,
the other is on a local file systems.
![](Git-transport.png "Git-transport.png")
To understand the figure, you **first concentrate on its left part**,
that is, forget about the remote repository for a minute. We are faced
with the workspace, the index and the (local) repository. Please observe
that this setup basically matches the situation of a (local)
SVN-repository with a checkout working copy:
- The workspace represents all files belonging to a certain branch
that can be **checkout**.
- Files can be scheduled for **addition** to the (local) repository
...
- ... and finally **committed**.
- Updates from the (local) repository can be **pulled** into the
workspace (assuming that someone else alters a branch in the - local
- repository, we will see what "someone" means).
- And finally modifications of the workspace can be compared against
the repository. This **diff** shows changes that can be committed to
the (local) repository.
- Similarly to SVN, and not depicted in the figure, one can **merge**
one branch of the repository into another branch. And, similarly
again, merge conflicts must be resolved.
We now focus on the **right part of the figure**, which mainly adds two
operations:
- All changes *committed* to the local repository only can be
**pushed** into the remote repository. Typically the current branch
is pushed, but there is also the `--all` option. This is the main
difference to the SVN setup, where no "local repository" exists.
That is, Git throws the local repository into the picture!
- The local repository will be updated with the changes from the
remote directory by **fetching**. A call to fetch updates the local
repository from all remote branches.
- A fetch constitutes the before-mentioned alterations of the local
repository by *someone*. It updates one or several local branches.
Then, these changes were pulled from a local branch into an checkout
workspace.
- To short-cut these two steps, the branch in the workspace can also
directly be updated from a remote repository as indicated with the
**pull** arrow that is originating from the remote repository.
- There are many, many, many more Git-commands.
Analogy to SVN:
- commit becomes two-phase: first commit to the local repository, then
a push to the remote location
- update becomes two-phase: first fetch from remote location, then
merge changes to local branch (there is a shortcut to do both in one
step: pull)
Remarks:
- Note that the changes in a Git repository are organized as directed
acyclic graph (DAG), where a node represent a certain change that is
identified by a hash (replacing revision numbers).
- **push** and **fetch** simply update the remote (push) or the local
graph (fetch) accordingly. Be aware that **pull**, the direct
counterpart to **push**, also updates the workspace (i.e., apply
changes to the checkout files).
## Further Directions
Git enables some further developments that can be considered:
- Code review
- Continuous integration
- publicly mirror specific parts of the SCM tree
## Commitment
- CGAL developers learn a new architecture that requires slightly
changed commands.
- In contrast to central repository, local repositories are not
backed-up through server maintenance. To backup your work, push your
branches onto the central remote repository, or **mirror** your
local repository - either on any network file system of your choice,
or in a private directory on CGAL's scm-server.
## Resources
- [SO Definitive
Guide](http://stackoverflow.com/questions/315911/git-for-beginners-the-definitive-practical-guide)
- [Official Git Page](http://git-scm.com/)
- [learn.github (with Videos for the
Lazy)](http://learn.github.com/p/intro.html)

3
Guidelines/Source_code_management/_Footer.md Normal file

@ -0,0 +1,3 @@
[Home](Home) >
[Guidelines](Guidelines) >
[Source Code Management with Git](Source-Code-Management-with-Git)

3
Guidelines/Source_code_management/_Sidebar.md Normal file

@ -0,0 +1,3 @@
[Home](Home) > <br>
[Guidelines](Guidelines) > <br>
[Source Code Management with Git](Source-Code-Management-with-Git)

8
Guidelines/Submission.md Normal file

@ -0,0 +1,8 @@
Whether you produce library code, demos, documentation or something
else, and when you have been invited as a [CGAL developer](http://www.cgal.org/project_rules.html#developers), if you want your work to become part of CGAL, you'll have to submit it in
the form of a page in the *internal CGAL wiki* on [Features](https://cgal.geometryfactory.com/CGAL/Members/wiki/Features) or on
[Small Features](https://cgal.geometryfactory.com/CGAL/Members/wiki/Features/Small_Features) (please
follow the template given there), and announce it by email to the
[editorial board mailing list](Mailing-Lists).
Please carefully read the [submission and review](http://www.cgal.org/review_process_rules.html).

450
Guidelines/Testing.md Normal file

@ -0,0 +1,450 @@
<!--TOC-->
# Table of Contents
* [Introduction](#introduction)
* [Test suite directory](#test-suite-directory)
* [Test suite input](#test-suite-input)
* [Data files](#data-files)
* [`*.cin` files](#*cin-files)
* [`*.cmd` files](#*cmd-files)
* [Command-line arguments](#command-line-arguments)
* [Running the test suite](#running-the-test-suite)
* [Files generated by the test suite](#files-generated-by-the-test-suite)
* [Test suite results](#test-suite-results)
* [Running the testsuite locally on a single package](#running-the-testsuite-locally-on-a-single-package)
* [Running the test suite on a branch](#running-the-test-suite-on-a-branch)
* [Custom test script](#custom-test-script)
* [Using the code coverage tool gcov](#using-the-code-coverage-tool-gcov)
* [CMake](#cmake)
<!--TOC-->
## Introduction
The CGAL test suite is a way to test the compilation and execution of
CGAL programs automatically (i.e., without user interaction) on a number
of different platforms. A platform in this context refers to a
combination of an operating system, a compiler, and a set of flags
provided in the compilation command-line. Examples of the latter are
'`-g`' for compiling with g++ in the so-called debug mode, and
'`-O2 -DNDEBUG`' for compiling with g++ in the so-called release mode.
Developers should, naturally, thoroughly test their code on their own
development platform(s) *before* committing it. The test suite is not
intended for initial testing of code, and it serves mainly as a way to
test on additional platforms not available to the developer.
The **test suite helps** the developer(s) of a package to
- detect compilation problems on the various platforms,
- detect runtime problems, and
- check the correctness of the algorithms in the package
**Requirements**:
- Test your code thoroughly *before* committing it.
- Obey the directory structure detailed in [this
subsection](Directory-Structure-for-Packages#test-subdirectory).
- Check the test suite results for your package regularly.
**Recommendations**:
- Cover the complete code of the package; every (member) function
should be called at least once (see [ this
section](#Using_the_code_coverage_tool_gcov) for a
description of a tool you can use to test code coverage).
- Use more than one instantiation of templated functions or classes.
- A lot of classes in CGAL can be parametrized by traits classes, so
that they are usable with different kernels. In such cases more than
one kernel should be used for testing.
- Recall that the CGAL checks, such as `CGAL_precondition` and
`CGAL_postcondition` are disabled by the `CGAL_NDEBUG` macro, which
is set when the flag '`-DNDEBUG`' appears on the compilation
command-line; see [CGAL Developer Manual](http://doc.cgal.org/latest/Manual/devman_checks.html). Thus,
in the test-suite code itself you should use `assert` and not
`CGAL_assertion` if you want the check to persist when your test is
run in a mode where `CGAL_assertion` is disabled (but `assert` is
not). Naturally, it is encouraged to use pre- and postcondition
checks wherever it is possible in the tested code.
- Not contain a makefile unless it needs to do something very special
to compile or link. If you find you want to do something very
special in your makefile, think long and hard about whether it's
really necessary or not. See also [this
section](#Custom_makefile).
- Not contain the script `cgal_test_with_cmake`. In the special case
it has to, see [this section](#custom-test-script).
## Test suite directory
The test suite is located in the directory test/ of the [internal
releases](https://cgal.geometryfactory.com/CGAL/Members/Releases/) (see
also [this wiki page](Internal-Releases) on the creation of
internal releases). The test/ directory is not part of external
releases. It contains:
- a script `run_testsuite_with_cmake` that is (not surprisingly) used
to run the test suite.
- a subdirectory for every package included in the internal release.
These subdirectories are created from the test/ directories of the
packages by copying the source, include, and input files from these
directories and adding makefiles and `cgal_test_with_cmake` scripts
where needed. See [this subsection](Directory-Structure-for-Packages#test-subdirectory)
for more information about the proper structure of the `test/`
directory for a package.
- a subdirectory with a name that ends in `_Examples/` for every
package that was submitted with an examples directory.
- a subdirectory with a name that ends in `_Demo/` for every package
that was submitted with a demo directory.
The test suite will attempt to compile all the programs in the
subdirectories of test/ and to run all except the demo programs (which
usually require user interaction) by using the `cgal_test_with_cmake`
scripts (Sections [`test` subdirectory](Directory-Structure-for-Packages#test-subdirectory)
and
[`create_cgal_test`](Scripts#create_cgal_test_with_cmake))
and will save the results in files in the package subdirectories.
Even if a program fails to compile or run, the test suite will continue.
## Test suite input
Input to programs in the test suite can be supplied in three different
ways:
### Data files
The data files in the data/ directory: As described in Section
[`test` subdirectory](Directory-Structure-for-Packages#test-subdirectory),
a package's `test/` directory may contain a subdirectory `data/` that
contains input files for the test programs.
### `*.cin` files
If a test program program.cpp requires input from standard input (i.e.,
cin), you should put a file called program.cin in the test directory.
The test suite will then execute the program using the command
`./program < program.cin`
### `*.cmd` files
If a test program program.cpp requires input from the command line
(i.e., `-f` `*.off` ), you should put a file called program.cmd in the test
directory. For each line in `program.cmd`, the testsuite will then
execute the program with the full line as arguments.
### Command-line arguments
Command-line arguments should be supplied in the `cgal_test_with_cmake`
script: You are discouraged from using this option to give input values
to your programs since it requires you to edit and submit a
`cgal_test_with_cmake` script; see
[`create_cgal_test`](Scripts#create_cgal_test_with_cmake).
However, if a test program program.cpp absolutely requires command-line
parameters, you should do the following. Use
`create_cgal_test_with_cmake` to create the script
`cgal_test_with_cmake`. This file contains an entry of the form
```
compile_and_run program
```
Just put the command-line parameters for your program at the end of this
line:
```
compile_and_run program  arg1 arg2 ..
```
The test suite will then execute the program using the command
```
./program <arg1> <arg2> ...
```
## Running the test suite
The test suite is run using the `run_testsuite_with_cmake` script that
is distributed with every internal release in the test/ directory. There
are several ways you can customize this script to meet you needs:
- Add additional compiler and linker flags by setting the variables
`TESTSUITE_CXXFLAGS` and `TESTSUITE_LDFLAGS` at the top of the
script. These variables are prepended to `CXX_FLAGS` and `LDFLAGS`,
respectively, in the test suite makefiles. So, for example, if you
have a directory experimental/include/CGAL containing new or
experimental CGAL files, you can do the following:
`TESTSUITE_CXXFLAGS="-Iexperimental/include"` and in this way test
with your new files without overwriting the originals.
- Export additional environment variables by adding lines to the
`run_testsuite_with_cmake` script. As an example, we demonstrate how
to export the `LD_LIBRARY_PATH`.
- Add the line `LD_LIBRARY_PATH=<your library path>` to the
script.
- Append `LD_LIBRARY_PATH` to the line
`export PLATFORM CGAL_MAKEFILE TESTSUITE_CXXFLAGS TESTSUITE_LDFLAGS`
in the script. After this, the programs from the test suite will
be run using the `LD_LIBRARY_PATH` that was specified in step 1.
- Run the test suite on more than one platform by adding a line at the
bottom of the script of the form
`run_testsuite_with_cmake <include makefile>` for every platform
that you wish to test. Just substitute for `<include makefile>` the
appropriate include makefiles that were generated during
installation (don't forget to use the full path name for the
makefile). By default, the last line in the file is
`run_testsuite_with_cmake $CGAL_MAKEFILE` so you need not make any
changes if you run the testsuite on only one platform and have set
the `CGAL_MAKEFILE` environment variable properly.
After these steps you are ready to run the test suite. It can be run in
two different ways:
```
./run_testsuite_with_cmake
```
The test suite will run the tests from all test directories. This may
take a considerable amount of time.
```
./run_testsuite_with_cmake <dir1> <dir2> ...
```
The test suite will run only the test programs in the test directories
`<dir1> <dir2> ...`
To run an entire CGAL test suite automatically, including downloading of
an internal release, configuration, and installation of the library, you
can use the `autotest_cgal` script described in Section
[`autotest_cgal`](Scripts#autotest_cgal).
## Files generated by the test suite
The testsuite will generate the following output files:
- `<testdir>/ErrorOutput_<platform>` This file contains two lines for
every program that was tested on platform <platform> in the test
directory <testdir>. The first line tells if the compilation was
successful and the second line tells if the execution was successful
(i.e., the program returned the value 0) (see Section [`test`](Directory-Structure-for-Packages#test-subdirectory)
for more details).
- `<testdir>/ProgramOutput.<program>.<platform>` This file contains the
console output from the test program `<program.cpp>` run on platform
`<platform>`.
- `<testdir>/CompilerOutput_<platform>` This file contains the compiler
output from platform `<platform>` for all programs.
- `error.txt` This is just a concatenation of all the `ErrorOutput` files
that were generated during the last run of the test suite.
## Test suite results
The results of test suites run on the various supported or
soon-to-be-supported platforms are posted on the
[test suite results](http://cgal.geometryfactory.com/CGAL/Members/testsuite/) page.
The results of the tests are presented in a table (`y` = success, `w` =
warning, `n` = failure, `r` = a requirement is not found).
`r` triggers on the text found in the output of cmake or a testprogram.
The regular expression is
`NOTICE: .*(need|require|incompatible).*and.*will not be`
## Running the testsuite locally on a single package
Before merging into integration it is good style to run the testsuite of
the package you worked on. Here is what you need:
- A shell such as bash (install Cygwin, when you are on Windows)
- *optional:* put `Scripts/scripts` and `Scripts/developer_scripts` on
your `PATH` environment variable. Alternatively, you can call the
scripts mentioned below using their full path or a relative path
- define the environment variable `CGAL_DIR`. It should be the
directory where you built CGAL.
- *optional:* define the environment variables for Boost, GMP, and any
optional third party lib, e.g. Eigen.
- *On Windows:* define the environment variable `MAKE_CMD` (put the
line `export MAKE_CMD=nmake` in your `$HOME/.bashrc` for VC++)
- *On Windows:* define the environment variable `CMAKE_GENERATOR` (put
the line `export CMAKE_GENERATOR='-GNMake Makefiles'` in your
`$HOME/.bashrc` for VC++)
- go in the directory you want to test
- Run `cgal_create_CMakeLists` (or
`../../../Scripts/scripts/cgal_create_CMakeLists`) in case there is
not yet a file `CMakeLists.txt`
- Run `create_cgal_test_with_cmake` in case there is not yet a file
`cgal_test_with_cmake`
- Run `cgal_test_with_cmake`. This should run CMake, compile and run,
and you can see what happened in the generated file `error.txt`.
## Running the test suite on a branch
Note that this section will probably be soon updated to take into
account running a testsuite on a *branch-build* branch.
We describe here how to proceed to the testing of a full copy of
`master` or `integration` (or the original), by first creating a flat
*release*.
The creation of the flat release is done using the script
`create_internal_release` located in the directory `developer_scripts`
of the package `Scripts`. Running the script with no argument will give
the complete usage of this script. We only describe one way of using it.
The prerequisite is to have a checkout of `master` or `integration` In
the example, it will be located in `~/Git/cgal/`.
First one creates goes into a directory where the flat release will be
created.
` > cd /tmp`
Then the script `create_internal_release` is ran
```
 >  create_internal_release -r CGAL-I-FOO -a ~/Git/cgal/
```
The directory `CGAL-I-FOO` now contains the flat release of the branch
in `~/Git/cgal/`. Then you need to compile this flat release and set
`CGAL_DIR` accordingly. Refer to the installation manual of CGAL to do
this.
To run the test-suite simply do:
```
> cd CGAL-I-FOO/test
> ./run_testsuite_with_cmake
```
and wait for the results to be written in the file `error.txt`, or
follow the instructions given in [Running the
test-suite](#Running_the_test_suite).
## Custom test script
In special cases, you may want to provided a custom
`cgal_test_with_cmake` 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_with_cmake` 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`).
## Using the code coverage tool gcov
The tool `gcov` can be used together with the GNU C++ compiler to test
for code coverage in your programs and may be helpful when you create
your CGAL test suite programs. You can find a complete guide to this
tool in the [GNU on-line
documentation](http://gcc.gnu.org/onlinedocs/gcc-2.95.2/gcc_6.html). If
you want to use the code coverage tool `gcov`, you have to compile your
programs with the option `--coverage`. This generates a file called
your\_program.gcda. Then you run the program, which generates a file
your\_program.gcno. Finally, you can run `gcov your_program.cpp`. This
will generate a number of files with the ending `.gcov` which contain
annotated source code. View it in a text editor. Here is a simple
example:
```
#include<iostream>
using namespace std;
void fu(int val)
{
int w,v=0;
if (val==0) {
cout << "val == 0!\n";
for(w=0;w<100;w++) v=v+w;
}
else {
cout << "val != 0!\n";
for(w=0;w<10;w++) v=v+w;
}
cout << "v:" << v << "\n";
}
int main()
{
fu(0);
return 0;
}
```
First you have to compile the example program test.cpp with the special
option. Then you have to execute it, and, after this, `gcov` can be
used.
```
g++ --coverage -o test test.cpp
test
gcov test.cpp
```
`gcov` will create a file `test.cpp.gcov` containing the following output
(or very similar):
```
#include<iostream>
using namespace std;
void fu(int val)
1 {
1 int w,v=0;
1 if (val==0) {
1 cout << "val == 0!\n";
1 for(w=0;w<100;w++) v=v+w;
}
###### else {
###### cout << "val != 0!\n";
###### for(w=0;w<10;w++) v=v+w;
}
1 cout << "v:" << v << "\n";
}
int main()
1 {
1 fu(0);
1 return 0;
}
```
The lines that were not executed will be marked with `######`, so you
will see what should be added in the (CGAL) test suite programs. When
doing multiple runs of your program, keep in mind that the execution
numbers per line will be accumulated in the gcno file, so delete it if
you want to reset them.
### CMake
When using CMake, to pass the `--coverage` flag both to the compiler and
to the linker, use a command like this:
```
cmake -DCGAL_DONT_OVERRIDE_CMAKE_FLAGS=TRUE -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_EXE_LINKER_FLAGS="--coverage"
```
Then `make` and run your program/test. The .gcda and .gcno files are
created within the directory CMakeFiles/<executable>.dir/ relative to
your project path, which is why you have to invoke gcov like this:
```
gcov <executable>.cpp -o CMakeFiles/<executable>.dir/<executable>.cpp.gcno
```
Within CGAL, it is often useful to pass the additional `-p` option to
gcov to preserve the source files' full paths.

287
Guidelines/Website.md Normal file

@ -0,0 +1,287 @@
<!--TOC-->
# Table of Contents
* [Web site](#web-site)
* [Content](#content)
* [Regular Tasks](#regular-tasks)
* [Using Git to maintain the web pages](#using-git-to-maintain-the-web-pages)
* [Hints about Jekyll](#hints-about-jekyll)
* [Required Tools](#required-tools)
* [Looking at the website locally](#looking-at-the-website-locally)
* [How to create a new post?](#how-to-create-a-new-post)
* [How to create a new page?](#how-to-create-a-new-page)
* [How to publish?](#how-to-publish)
* [Notes from @bo0ts on cgal-develop, April 1st, 2015](#notes-from-@bo0ts-on-cgal-develop-april-1st-2015)
* [Hosting](#hosting)
* [Access statistics](#access-statistics)
* [Releases download statistics](#releases-download-statistics)
* [`firstname.lastname@cgal.org`](#firstnamelastname@cgalorg)
* [Wiki](#wiki)
<!--TOC-->
## Web site
### Content
- Our webpages are <http://www.cgal.org>
- The Editorial Board is responsible for the content. The upload is
done automatically as soon as the `master` or `upcoming` branches
are updated. Developers in the team
[cgal-web-editors](https://github.com/orgs/CGAL/teams/cgal-web-editors)
and members of the editorial board have write access the the
cgal-web repository. [Regular
developers](https://github.com/orgs/CGAL/teams/developers) have read
access only, thus an edit should be done using a pull request.
- Of course, issues can be submitted if you find any problems with the
web site.
#### Regular Tasks
Some aspects of the web pages need constant attention to keep them
up-to-date. If you can please do the necessary updates yourself, or
notify the Editorial Board if you know about updates. This is relevant
in particular for the following web pages:
- The News section on <http://www.cgal.org>
- People involved in the project <http://www.cgal.org/people.html>
(also observe that the Board Manager, the Release Manager, and the
Review Manager are subject to change from time to time).
- Updates for the work in progress page
(http://www.cgal.org/in\_progress.html): work that is finished and
thus no longer in progress must be removed, and new work must be
added.
- Publications related to CGAL appear at
<http://www.cgal.org/bibliography.html>, which is currently
maintained by [@moniqueteillaud](https://www.github.com/moniqueteillaud)
- Projects using CGAL <http://www.cgal.org/projects.html>
- Events listed on <http://www.cgal.org/events.html>
- *(This item is not so clear, to be updated)* Demo programs to be
included in the package overview
<http://www.cgal.org/Manual/latest/doc_html/cgal_manual/packages.html>.
See the Developers manual for how to submit these.
### Using Git to maintain the web pages
Clone the repository
``` {.bash}
> git clone -o cgal-web git@github.com:CGAL/cgal-web.git
```
If already done
``` {.bash}
> git pull
```
updates your current branch from the server. It's recommended not to
have local modifications when doing so.
Adding a new file
``` {.bash}
> git add <file>
```
Committing a file to your local repository
``` {.bash}
> git commit <file>
```
Next task is to send the updates to the server. In order to avoid pushes
in all branches use `git` (\>= 2.0.0) (where the default is to only push
the current branch) or add this to your configuration
``` {.bash}
> git config --add push.default simple
# In even older Git version (<1.7.11) 'simple' must be replaced with 'current' or 'tracking' (for even older versions)
```
This refuses a push if the local and remote branchnames do not match
(check whether other repositories also need this option - or whether you
want to add it to you global `.gitconfig` - can be done by adding
`--global` option). Next you send the branch onto the remote repository
she cloned from ("origin"):
``` {.bash}
> git push
```
Actually, the change of the default push strategy is more important when
you are working on local branches other than `master`, see below.
You can also create a local branch to test some changes:
``` {.bash}
> git checkout -b NewDesign master
```
then you add/modify/commit files in the local "NewDesign" branch. Browse
the files locally to see your changes.
Once you're happy:
``` {.bash}
> git checkout master
> git merge NewDesign
## resolve conflicts
> git push
```
The last commands updates the server again.
If needed, usually to prepare a release, we have
<http://upcoming.cgal.org>
``` {.bash}
> git checkout -b upcoming cgal-web/upcoming
## make sure upcoming and master are the same
> git merge master
## resolve conflicts
> git merge NewDesign
## resolve conflicts
```
and finally
``` {.bash}
> git push
```
### Hints about Jekyll
#### Required Tools
- Install Ruby
- Linux: check your package manager
- Windows
- Note: you should run everything in cmd.exe and not a cygwin
shell.
- go to <http://rubyinstaller.org/downloads/> and download
RubyInstaller 2.0.0 and the appropriate Development Kit
- execute RubyInstaller (check "Add to Path")
- unzip Development Kit somewhere
- in \`cmd.exe\`:
```
cd C:\path_to_devkit
ruby dk.rb init
ruby dk.rb install
```
- Install jekyll: \`gem install jekyll\`
- If download error, try \`gem install jekyll --source
<http://rubygems.org>\`
#### Looking at the website locally
```
# get the required tools
cd /path/to/cgal/web
jekyll serve --watch
# point browser at [http://localhost:4000](http://localhost:4000)
```
#### How to create a new post?
```
cd /path/to/cgal/web
rake post title="My Title" [date="2014-02-24"]
```
#### How to create a new page?
` cd /path/to/cgal/web`\
` rake page name="my_page.html"`
#### How to publish?
- Using Push (if you are in the team
[cgal-web-editors](https://github.com/orgs/CGAL/teams/cgal-web-editors))
- Push your changes to the `master` branch.
```
 git push origin your_branch:master
```
- Using Pull Request (otherwise)
- Push your branch to your own repository and create a pull
request to the \`master\` branch.
After a few minutes (sometimes hours), you will see the content here:
<http://www.cgal.org>
Another way to test the website online without perturbing cgal.org (if
you cannot test it locally, for example) is to push to the \`gh-pages\`
branch and watch the result here: <http://cgal.github.io/cgal-web/>
#### Notes from @bo0ts on cgal-develop, April 1st, 2015
There are only two short commands: `rake post` and `rake page`. They
are documented here:
<http://jekyllbootstrap.com/usage/jekyll-quick-start.html#toc_7>
A quick explanation: there are posts, drafts, and pages.
Pages are the sites with a fixes address, like software.html or
index.html. They contain not reusable contents and can be placed
anywhere in the repository hierarchy besides folders prefixed with `_`.
Posts are stored in the `_posts` directory, they have a date, tags, and a
category. A release announcement, for example, is a post. Exhaustive
documentation about posts is here: <http://jekyllrb.com/docs/posts/>
Drafts are posts without a date which are not published by the automated
tools, but you can see them locally. They are stored in the `_drafts`
directory. Exhaustive documentation about drafts is here:
<http://jekyllrb.com/docs/drafts/>
In general, <http://jekyllrb.com> contains a lot of helpful information.
### Hosting
**Update:** this has changed. See [Staging Area/Servers/Migration to
OVH](Staging Area/Servers/Migration to OVH). [@lrineau](https://github.com/lrineau) is responsible for the web site,
now, with [@sloriot](https://github.com/sloriot) as backup.
### Access statistics
CGAL Editors can access the statistics for <http://www.cgal.org/> and
<http://doc.cgal.org/> at the following address:
<https://logs.ovh.net/cgal.org/>
That page is protected by a login/password. The login is "editor", and
the password is the usual password for the pages protected for CGAL
editors. Be careful that the login is not exactly the usual login.
### Releases download statistics
For each new release of CGAL, the tarballs and the Windows `.exe` installer
are now uploaded to GitHub, as "assets".
See https://github.com/CGAL/cgal/releases
The download statistics can be seen at:
http://www.somsubhra.com/github-release-stats/?username=CGAL&repository=cgal
## `firstname.lastname@cgal.org`
Since February 2015, GeometryFactory handles the service of email
redirections `firstname.lastname@cgal.org`, using the OVH
infrastructure. Changes to the configuration should be communicated to
[@lrineau](https://github.com/lrineau) (or [@sloriot](https://github.com/sloriot)) when [@lrineau](https://github.com/lrineau) is not available).
*For the administrators:* *The settings are in the [OVH Manager](https://www.ovh.com/manager),
select "cgal.org" in the list of
products in the left bar, then the "Emails" tab, then in the buttons on
the right, use "Gestion des redirections" ("Manage redirections" in
English).*
## Wiki
The wiki is hosted at
<http://cgal.geometryfactory.com/CGAL/Members/wiki/> .
It is administrated at GF by [@lrineau](https://github.com/lrineau).

2
Guidelines/_Footer.md Normal file

@ -0,0 +1,2 @@
[Home](Home) >
[Guidelines](Guidelines)

2
Guidelines/_Sidebar.md Normal file

@ -0,0 +1,2 @@
[Home](Home) > <br>
[Guidelines](Guidelines)

5
Home.md

@ -1 +1,4 @@
Welcome to the cgal wiki!
Welcome to the cgal-dev wiki!
* [Guidelines](Guidelines)
* [Informations for New Developers](Information-for-New-Developers)

88
Information-for-New-Developers.md Normal file

@ -0,0 +1,88 @@
<!--TOC-->
# Table of Contents
* [Creating a GitHub account](#creating-a-github-account)
* [Setting up your development environment](#setting-up-your-development-environment)
* [Important Resources](#important-resources)
* [Stay in contact](#stay-in-contact)
<!--TOC-->
Once your mentor has introduced you on the [CGAL Editorial Board mailing list](Mailing-Lists), and once the [CGAL Editorial Board](http://www.cgal.org/people.html) has approved your participation in the CGAL project as a [CGAL developer](http://www.cgal.org/project_rules.html#developers), then you should follow the following guidelines.
## Creating a GitHub account
- Visit <https://github.com/join> and then, choose **Free** as the
personal plan (while you are free to pay if you want).
- You should receive an email to *verify* that the email address
provided is valid.
- Add your first name and last name and complete your profile at
<https://github.com/settings/profile>
- Add all email addresses you have ever used (for statistics) at
<https://github.com/settings/emails> and, optionally, check the box
*Keep my email address private*.
- Set up your SSH keys: <https://github.com/settings/ssh> (see
[here](http://help.github.com/key-setup-redirect) for help)
- **Recommended** Set up the 2-factor authentication
<https://github.com/settings/security> (if you don't set it you'll
be contacted by an admin of CGAL to ask you why).
- Configure notifications at
<https://github.com/settings/notifications>
Once done, send an email with your Github ID to [@sloriot](https://github.com/sloriot) who will
add you to the list of members of the CGAL organization, so that you can
see the private repositories.
**<span style="color:red">Note that each developer with SCM access has
the power to modify all source files for the time being. This does not
entitle you to exploit this. You are expected to be very cautious if you
change anything under the version control system.</span>**
## Setting up your development environment
**<span style="color: red; ">BEFORE YOU START ANY CODING BE SURE TO SET
UP CGAL IN EXACTLY THIS WAY:</span>**
- Uninstall any old CGAL Installation (if you installed CGAL through a package manager, use it to uninstall it again, if you installed CGAL from a tarball, you need to remove it manually)
- Install all dependencies
- on Arch Linux: `pacman -S cmake qt5 gmp mpfi mpfr boost zlib mesa glu eigen`, you can get `qglviewer` from AUR
- on Mac OS X, use brew (`brew install --only-dependencies cgal`) or macports
- on Windows things are more [delicate](https://www.cgal.org/windows_installation.html) (TODO other link?)
- Clone your repository (if you're CGAL *student* clone `cgal-public-dev`)
- cloning cgal-dev: ` git clone git@github.com:CGAL/cgal-dev.git`
- or cloning cgal-public-dev: ` git clone git@github.com:CGAL/cgal-public-dev.git`
- add read-only branches: ` git remote add cgal git@github.com:CGAL/cgal.git`
- Set `CGAL_DIR` persistently to a directory where you intend to build CGAL
- UNIX environment: Add `export CGAL_DIR=path/to/cgal/build` to `~/.profile` or your shell configuration file. Refer to your systems documentation for more specific information.
- [Build CGAL from the repository](Branch-Build#using-a-single-version-of-cgal)
## Important Resources
There is a lot of information in the wiki. Some pages that every
developer should read are:
- The [public Developers' Manual](http://doc.cgal.org/latest/Manual/dev_manual.html)
(especially the [*Getting Started* section](http://doc.cgal.org/latest/Manual/general_intro.html))
- Our [Guidelines](Guidelines) and in particular
- [Source Code Management](Source-Code-Management-with-Git) and
its subpages
- [Package directory structure](Directory-Structure-for-Packages)
- [Package documentation](Documentation-Guidelines)
## Stay in contact
- Please introduce yourself on your **user page** of the *internal* wiki (click on your user
name at the top of every wiki page when logged in), and provide your
e-mail address there as well (remember that that wiki is not
publicly accessible).
- Have a look at our [mailing lists](Mailing-Lists). The
developers mainly communicate via *cgal-develop* (with restricted
access only for [CGAL developers](http://www.cgal.org/project_rules.html#developers)), but you might want to also
subscribe to the public (high-traffic) *cgal-discuss* and/or
(low-traffic) *cgal-announce*.
- We meet in person on *CGAL developer meetings*, which take place roughly each six
months. We try to distribute the meetings between several institutes
affiliated to CGAL. They are announced via *cgal-develop* and on the internal
wiki.

29
Internal-Releases.md Normal file

@ -0,0 +1,29 @@
Every day, at 9pm, Paris local time, which is either CET (winter) or
CEST (summer), a new internal release is created. The branch that is
tested by the internal release is not always the same.
**Note that most of the test results are published the following day.**
## Summary
Internal releases are published every night. The day of week in the
following table indicates the day of the creation of the internal
release, and thus the beginning of CGAL testsuite process. Usually you
have a look at the results **the following day**.
Day | Tested branches
----------| ----------------
Monday | `integration`
Tuesday | `integration`
Wednesday | `integration`
Thursday | `integration`
Friday | `integration`
Saturday | `CGAL-4.9-branch`
Sunday | `master`
-------------------------------
**This page is unfortunately not always updated when the configuration
of the testsuite is changed. Last change:** **2016-09-08**

52
Mailing-Lists.md Normal file

@ -0,0 +1,52 @@
<!--TOC-->
# Table of Contents
* [Public lists](#public-lists)
* [Lists available to CGAL developers](#lists-available-to-cgal-developers)
* [Editorial board list](#editorial-board-list)
<!--TOC-->
## Public lists
See also [Public lists](http://www.cgal.org/mailing_list.html).
- [cgal-discuss@inria.fr](https://sympa.inria.fr/sympa/info/cgal-discuss)
the cgal users discussion list.
[nabble forum interface](http://cgal-discuss.949826.n4.nabble.com/)
(admins: [@sloriot](https://www.github.com/sloriot) and [@moniqueteillaud](https://www.github.com/moniqueteillaud))
- [cgal-announce@inria.fr](https://sympa.inria.fr/sympa/info/cgal-announce)
the mailing lists where announcements related to CGAL are posted.
(admins: [@sloriot](https://www.github.com/sloriot) and [@moniqueteillaud](https://www.github.com/moniqueteillaud))
## Lists available to CGAL developers
admins: sebastien.loriot@cgal.org and monique.teillaud@cgal.org
- [cgal-develop@inria.fr](https://sympa.inria.fr/sympa/info/cgal-develop)
: discussion list for [CGAL developers](http://www.cgal.org/project_rules.html)
- [cgal-dev-commits](https://sympa.inria.fr/sympa/info/cgal-dev-commits):
commits/push to the [cgal-dev](https://github.com/CGAL/cgal-dev)
private repo AND the
[cgal-public-dev](https://github.com/CGAL/cgal-public-dev) public
repo
- (only for editors and a few developers working on the website)
[cgal-web-commits](https://sympa.inria.fr/sympa/info/cgal-web-commits):
commits/push to the [cgal-web](https://github.com/CGAL/cgal-web)
repo
## Editorial board list
The private list of CGAL editorial board
- [cgal-editorial-board@inria.fr](http://sympa.inria.fr/sympa/info/cgal-editorial-board).
Moderated by [@sloriot](https://www.github.com/sloriot) and [@moniqueteillaud](https://www.github.com/moniqueteillaud)
- `info@cgal.org` is the public official mail address of CGAL for
general issues. Its only member is cgal-editorial-board@inria.fr.
Moderated by [@sloriot](https://www.github.com/sloriot) and [@moniqueteillaud](https://www.github.com/moniqueteillaud)

1
_Footer.md Normal file

@ -0,0 +1 @@
[Home](Home)

1
_Sidebar.md Normal file

@ -0,0 +1 @@
[Home](Home)

BIN
doxygen-1.8.4-patched.gz Normal file

Binary file not shown.