From daa8c94c73f50e02a65629b7e5a11981e6af3ea1 Mon Sep 17 00:00:00 2001 From: Sebastien Loriot Date: Thu, 5 Mar 2015 00:44:19 +0100 Subject: [PATCH] Update INSTALL.md --- INSTALL.md | 234 ++++++++++------------------------------------------- 1 file changed, 44 insertions(+), 190 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index cda45534569..d8a39d8de77 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,217 +1,71 @@ -Building CGAL Libraries and Executables based on CGAL -===================================================== +Building CGAL Libraries From a Branch +===================================== Building CGAL using the *branch build* presented here keeps the -build-sources attached to the Git repository. A developer, let's call her -Jenny, can build CGAL from any CGAL branch accessible through a proper -*source code management* (SCM) client, such as Git. +build-sources attached to the Git repository. -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 usual -build procedure 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 -sources tarball"). - -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. +Note that we do not document here what are the dependancies and cmake options that +are needed to configure CGAL as they are already documented in the +[installation manual](http://doc.cgal.org/latest/Manual/installation.html). Branch Build of CGAL ==================== +The cmake script at the root of the repository is the one to use to +build the CGAL library from a branch. It will collect the list of packages +of the branch and will append their include folder to the include path. +This is main noticable difference with a build using a regular *flat* release. -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., - +Here is an example of how to build the library in Debug: ``` {.bash} - -DWITH_CGAL_Core=ON -DWITH_CGAL_Qt3=OFF -DWITH_CGAL_Qt4=ON -DWITH_CGAL_ImageIO=ON -DWITH_examples=OFF -DWITH_demos=OFF +git clone https://github.com/CGAL/cgal.git /path/to/cgal.git +cd /path/to/cgal.git +mkdir -p build/debug +cd build/debug +cmake -DBUILD_TYPE=Debug ../.. +make ``` -or configuring external libraries, e.g., - +Here is an example of how to build the library in Release: ``` {.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). -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 .. + > git clone https://github.com/CGAL/cgal.git /path/to/cgal.git + > cd /path/to/cgal.git + > mkdir -p build/debug + > cd build/debug + > cmake -DBUILD_TYPE=Release ../.. > make - > export CGAL_DIR=/path/to/my/cgal_repository/build ``` +Note that *no installation is required* to use that version of CGAL once it has been compiled. -Using a single version of CGAL ------------------------------- +Building a Program Using 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 , which points to the -build target directory, is set once and never changes. +To compile a program using CGAL, simply set `CGAL_DIR` to the location +of where you built the library (environment or cmake variable). -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: +Here is an example of how to build in debug the examples from the 3D Triangulations package: ``` {.bash} - > export CGAL_DIR=$HOME/CGAL/build - > cd $CGAL_DIR - > cmake /path/to/my/cgal_repository + > cmake -DCGAL_DIR:PATH=/path/to/cgal.git/build/debug /path/to/cgal.git/Triangulation_3/examples/Triangulation_3 > 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`. +If you're trying to build examples or tests that does not already have a `CMakeLists.txt`, you can trigger its creation by calling the script [`cgal_create_cmake_script`](Scripts/scripts/cgal_create_cmake_script) found in `/path/to/cgal.git/Scripts/scripts/` at the root of the example/test directory. Here is an example for the examples of the 2D Triangulation package: ``` {.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 + > cd /path/to/cgal.git/Triangulation_2/examples/Triangulation_2 + > /path/to/cgal.git/Scripts/scripts/cgal_create_cmake_script + > cd - + > cmake -DCGAL_DIR:PATH=/path/to/cgal.git/build/debug /path/to/cgal.git/Triangulation_2/examples/Triangulation_2 + > make ``` -In such a setup she probably keeps a build of CGAL for each branch: +Note If You Switch Between Branches +=================================== +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). -``` {.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/scripts/cgal_create_cmake_script) -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 workingcopy -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.