diff --git a/.gitignore b/.gitignore index 2c738d0819a..81287a07cbd 100644 --- a/.gitignore +++ b/.gitignore @@ -1154,3 +1154,4 @@ gmon.* /Polygon/test/Polygon/polytest.pretty /Stream_support/test/Stream_support/CMakeLists.txt /Stream_support/test/Stream_support/cgal_test_with_cmake +/*.html diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000000..d8a39d8de77 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,71 @@ +Building CGAL Libraries From a Branch +===================================== + +Building CGAL using the *branch build* presented here keeps the +build-sources attached to the Git repository. + +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. + +Here is an example of how to build the library in Debug: +``` {.bash} +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 +``` + +Here is an example of how to build the library in Release: +``` {.bash} + > 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 +``` +Note that *no installation is required* to use that version of CGAL once it has been compiled. + +Building a Program Using CGAL +============================= + +To compile a program using CGAL, simply set `CGAL_DIR` to the location +of where you built the library (environment or cmake variable). + +Here is an example of how to build in debug the examples from the 3D Triangulations package: + +``` {.bash} + > cmake -DCGAL_DIR:PATH=/path/to/cgal.git/build/debug /path/to/cgal.git/Triangulation_3/examples/Triangulation_3 + > make +``` + +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} + > 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 +``` + +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). + + diff --git a/Installation/INSTALL b/Installation/INSTALL.md similarity index 78% rename from Installation/INSTALL rename to Installation/INSTALL.md index 70f22546404..89d3b9023ae 100644 --- a/Installation/INSTALL +++ b/Installation/INSTALL.md @@ -1,17 +1,13 @@ -INSTALL -------------------------------------------------------------------------------- - - INTRODUCTION ============ This file describes how to install CGAL. The instructions in this file -are for the most common use cases, and cover the command line tools. +are for the most common use cases, and cover the command line tools. For further information, or in case of problems, please see the detailed installation instructions, which can be found in this distribution in the file ./doc_html/index.html or on the CGAL website -http://www.cgal.org/Manual/latest/doc_html/cgal_manual/Installation/Chapter_main.html +http://doc.cgal.org/latest/Manual/installation.html The documentation of CGAL is available in PDF and HTML formats. It is not bundled with the software but can be downloaded separately @@ -26,8 +22,8 @@ of CGAL (3.5.1, 3.6, and so on). PREREQUISITES ============= -To install CGAL, you need 'cmake' and several third-party libraries. -Some are essential for entire CGAL, some are mandatory for particular +To install CGAL, you need 'cmake' and several third-party libraries. +Some are essential for entire CGAL, some are mandatory for particular CGAL packages, some are only needed for demos. * CMake (>= 2.6.2), the build system used by CGAL @@ -42,7 +38,7 @@ CGAL packages, some are only needed for demos. You need the former if you plan to compile the boost libraries yourself, for example because you target 64 bit applications for XP64 - * Exact Arithmetic + * Exact Arithmetic CGAL combines floating point arithmetic with exact arithmetic, in order to be fast and reliable. CGAL offers support for GMP and MPFR, for LEDA exact number types, as well as a built-in exact number type used when @@ -62,7 +58,7 @@ CGAL packages, some are only needed for demos. - LEDA (>= 6.2) http://www.algorithmic-solutions.com/leda/index.htm - * Visualization + * Visualization Required for most demos - Qt3 (>= 3.3) @@ -83,10 +79,10 @@ CGAL packages, some are only needed for demos. Required by the packages: o Estimation of Local Differential Properties of Point-Sampled Surfaces o Approximation of Ridges and Umbilics on Triangulated Surface Meshes - o Planar Parameterization of Triangulated Surface Meshes - o Surface Reconstruction from Point Sets + o Planar Parameterization of Triangulated Surface Meshes + o Surface Reconstruction from Point Sets http://eigen.tuxfamily.org - + - BLAS, LAPACK, ATLAS Required by the packages (if EIGEN is not available): o Estimation of Local Differential Properties of Point-Sampled Surfaces @@ -98,7 +94,7 @@ CGAL packages, some are only needed for demos. - MPFI Required by the package: o Algebraic Kernel - https://gforge.inria.fr/projects/mpfi/ + https://gforge.inria.fr/projects/mpfi/ (or shipped with RS http://vegas.loria.fr/rs/) - RS (root isolation) @@ -111,10 +107,10 @@ CGAL packages, some are only needed for demos. o Polynomial o Algebraic Kernel http://www.shoup.net/ntl/ - + * Miscellaneous - - zlib + - zlib Optional for the package: o Surface Mesh Generator can read compressed images directly http://www.zlib.net/ @@ -129,24 +125,24 @@ CONFIGURATION ============= To configure CGAL, type - +``` cmake . - +``` in the directory that contains this INSTALL file. You can add several options to this command. The most important ones are - -DCMAKE_INSTALL_PREFIX= installation directory [/usr/local] - -DCMAKE_BUILD_TYPE= build type [Release] - -DBUILD_SHARED_LIBS= shared or static libraries [TRUE] - -DCMAKE_C_COMPILER= C compiler [gcc] - -DCMAKE_CXX_COMPILER= C++ compiler [g++] +* `-DCMAKE_INSTALL_PREFIX=` installation directory [/usr/local] +* `-DCMAKE_BUILD_TYPE=` build type [Release] +* `-DBUILD_SHARED_LIBS=` shared or static libraries [TRUE] +* `-DCMAKE_C_COMPILER=` C compiler [gcc] +* `-DCMAKE_CXX_COMPILER=` C++ compiler [g++] In case you want to add additional compiler and linker flags, you can use - -DCGAL_CXX_FLAGS additional compiler flags - -DCGAL_MODULE_LINKER_FLAGS add. linker flags (static libraries) - -DCGAL_SHARED_LINKER_FLAGS add. linker flags (shared libraries) - -DCGAL_EXE_LINKER_FLAGS add. linker flags (executables) +* `-DCGAL_CXX_FLAGS` additional compiler flags +* `-DCGAL_MODULE_LINKER_FLAGS` add. linker flags (static libraries) +* `-DCGAL_SHARED_LINKER_FLAGS` add. linker flags (shared libraries) +* `-DCGAL_EXE_LINKER_FLAGS` add. linker flags (executables) Variants with the additional suffix "_DEBUG" and "_RELEASE" allow to set separate values for debug and release builds. In case you do not want to add @@ -154,12 +150,12 @@ additional flags, but to override the default flags, replace "CGAL" by "CMAKE" in the variable names above. By default demos and examples are not configured. If you want to configure -them at the same time as the CGAL library, you can use +them at the same time as the CGAL library, you can use - -DWITH_examples=true - -DWITH_demos=true +* `-DWITH_examples=true` +* `-DWITH_demos=true` -Note that CMake maintains a cache name "CMakeCache.txt". If you change options +Note that CMake maintains a cache name `CMakeCache.txt`. If you change options (or your environment changes), it is best to remove that file to avoid problems. @@ -168,28 +164,29 @@ BUILDING ======== To build the CGAL libraries, type - - make (or nmake in a Windows command prompt) - +``` + make +``` +(or nmake in a Windows command prompt). If you want, you can install the CGAL header and libraries. To do so, type - +``` make install - +``` You can build all demos or examples by typing - - make demos or +``` + make demos make examples - +``` If you are interested in the demos or examples of just a particular module, you can build them in the following way: - +``` make -C demo/Alpha_shapes_2 (or: cd demo/Alpha_shapes_2; make) make -C examples/Alpha_shapes_2 (or: cd examples/Alpha_shapes_2; make) - +``` A list of all available make targets can be obtained by - +``` make help - +``` OUT-OF-SOURCE BUILDS ==================== @@ -201,10 +198,10 @@ configurations (debug and release, different compilers, and so on). Using different build directories keeps all the generated files separated for each configuration. -In the following, $CGAL_SRC denotes the directory with the CGAL sources; -$CGAL_BUILD is an arbitrary directory where the generated files will be +In the following, `$CGAL_SRC` denotes the directory with the CGAL sources; +`$CGAL_BUILD` is an arbitrary directory where the generated files will be placed. You can perform an out-of-source build as follows: - +``` mkdir $CGAL_BUILD cd $CGAL_BUILD cmake [options] $CGAL_SRC @@ -212,7 +209,7 @@ placed. You can perform an out-of-source build as follows: make install (if desired) make demos (if desired) make examples (if desired) - -Basically, the only difference is the last parameter of the "cmake" command: -$CGAL_SRC instead of "." . +``` +Basically, the only difference is the last parameter of the `cmake` command: +`$CGAL_SRC` instead of `.` . diff --git a/Installation/README b/Installation/README index cd6af6a22d2..be07977a7c6 100644 --- a/Installation/README +++ b/Installation/README @@ -6,7 +6,7 @@ This distribution of CGAL includes: AUTHORS - current and former authors of CGAL CHANGES - history of changes for the library CMakeLists.txt - main script of the build system - INSTALL - information about the installation process + INSTALL.md - information about the installation process LICENSE - describes the license of CGAL LICENSE.FREE_USE - text of the free use license (see LICENSE file) LICENSE.GPL - text of GPL v3 license diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000000..423220b365e --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,15 @@ +License of CGAL files in the Git repository +=========================================== +The first vector of diffusion of the CGAL sources is the publication of the +source tarballs of CGAL releases, twice a year. The file +[`Installation/LICENSE`](https://github.com/cgal/cgal/blob/master/Installation/LICENSE), in the Git repository, is the file `LICENSE` at the +root of the source tarballs. It describes the license of all the files of +the source tarballs. + +A lot of files in the Git repository are not distributed in the source +tarballs, for examples all the files in the `doc/` and `test/` +sub-directories of CGAL packages. For all those files, unless they have an +explicit license notice, the license is the GNU General Public License (as +published by the Free Software Foundation; either version 3 of the License +or (at your option) any later version). The text of that license can be +found in the file `Installation/LICENSE.GPL`. diff --git a/README.md b/README.md new file mode 100644 index 00000000000..b3a236fd228 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +#![CGAL](Installation/doc_html/images/cgal_2013_grey.png) + +The Computational Geometry Algorithms Library (CGAL) is a C++ library that +aims to provide easy access to efficient and reliable algorithms in +computational geometry. + +CGAL releases +============= +The primary vector of distribution of CGAL are sources tarballs, released +twice a year, announced on [the web site of CGAL](http://www.cgal.org/). +The sources distributed that way can be built using the +[CGAL installation manual](http://doc.cgal.org/latest/Manual/installation.html). + +CGAL Git repository layout +========================== + +The Git repository of CGAL has a different layout from release tarballs. It +contains a `CMakeLists.txt` file that serves as anchor for building, and a +set of subfolders, so called *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 +* `Documentation` - infrastructure for CGAL's manual +* `STL_Extension` - extensions to the standard template library + +Compilation and installation +============================ +The compilation and installation of CGAL from a sources tarball is +described in the +[CGAL installation manual](http://doc.cgal.org/latest/Manual/installation.html) +and in the file [INSTALL.md](Installation/INSTALL.md) that is at the root +of any sources tarball. + +CGAL developers, however, usually compile CGAL directly from a local Git +repository. That kind of compilation is called a *branch build*, and is +described in the file [INSTALL.md](INSTALL.md) that is at the root of the +Git repository. + +License +======= +See the file [LICENSE.md](LICENSE.md). + +More information +================ +* [The CGAL web site](http://www.cgal.org/) +* [Lastest CGAL release documentation pages](http://doc.cgal.org/)