From 3ef2dbe91576c40d45fe5f835ae6b1c7fe9b3afc Mon Sep 17 00:00:00 2001 From: Maxime Gimeno Date: Tue, 29 Jun 2021 13:16:42 +0200 Subject: [PATCH 1/2] Add the drop of the support of CGAL not header-only in CHANGES and update the doc about configuration and installation. --- .../Documentation/advanced/Installation.txt | 103 ++++++++---------- Installation/CHANGES.md | 3 + 2 files changed, 46 insertions(+), 60 deletions(-) diff --git a/Documentation/doc/Documentation/advanced/Installation.txt b/Documentation/doc/Documentation/advanced/Installation.txt index 58892d81597..416f975dc13 100644 --- a/Documentation/doc/Documentation/advanced/Installation.txt +++ b/Documentation/doc/Documentation/advanced/Installation.txt @@ -1,29 +1,29 @@ /*! -\page installation Building %CGAL libraries (non header-only mode) +\page installation Installing %CGAL libraries \cgalAutoToc \cgalAdvancedBegin -Since \cgal version 5.0, \cgal is header-only be default, which means +Since \cgal version 5.0, \cgal is header-only, which means that there is no need to compile \cgal or its libraries before it can be used. -This page is for advanced users that have a good reason to still use the old way. +This page is for advanced users that either want to install CGAL on their system, or want to build the examples, +tests and demos that are shipped in a git branch, for example. If this is not your case, head over back to the page \ref general_intro. \cgalAdvancedEnd -This page is a step-by-step description of how to configure, build, and (optionally) install \cgal -in case you do not wish to use the - now enabled by default - header-only mode of \cgal. +This page is a step-by-step description of how to configure and install \cgal, and (optionally) +build examples, tests and demos. It is assumed that you have downloaded a source archive of \cgal, and are using Linux or macOS. \section installation_idealworld Quick Installation -Ideally, compiling and installing \cgal, as well as compiling some examples shipped by \cgal is as simple as: +Ideally, installing \cgal, as well as compiling some examples shipped by \cgal is as simple as: cd $HOME/CGAL-\cgalReleaseNumber mkdir build cd build - cmake -DCGAL_HEADER_ONLY=OFF -DCMAKE_BUILD_TYPE=Release .. # configure CGAL - make # build CGAL + cmake .. # configure CGAL make install # install CGAL cd examples/Triangulation_2 # go to an example directory cmake -DCGAL_DIR=$CMAKE_INSTALLED_PREFIX/lib/CGAL -DCMAKE_BUILD_TYPE=Release . # configure the examples @@ -34,12 +34,11 @@ This is what this page is about. \section installation_configwithcmake Configuring CGAL with CMake -Before building \cgal, or anything using \cgal, you have to choose the compiler/linker, -set compiler and linker flags, specify which -third-party libraries you want to use and where they can be found, and -which \cgal libraries you want to build. Gathering +Before building anything using \cgal, you have to choose the compiler/linker, +set compiler and linker flags and specify which +third-party libraries you want to use and where they can be found. Gathering all this information is called configuration. -The end of the process is marked by the generation of a makefile that you can use to build \cgal. +The end of the process is marked by the generation of a makefile that you can use to install \cgal. CMake maintains configuration parameters in so-called cmake variables. Some of the CMake variables represent user choices, such as `CMAKE_BUILD_TYPE`, while others @@ -51,25 +50,19 @@ and finally the configuration and build processes. \subsection seclibraries CGAL Libraries -\cgal is split into four libraries. During configuration, you can select the libraries that -you would like to build by setting a CMake variable of the form WITH_. By default all -are switched `ON`. All activated libraries are to be built after configuration. - -Note that some libraries have specific dependencies in addition to the essential ones. See the page +\cgal has some optional components. During configuration, you can select the components that +you would like to use by setting a CMake variable of the form WITH_. By default all +are switched `ON`, but some have specific dependencies in addition to the essential ones, so if you don't +need those, don't hesitate to switch theim OFF. +See the page \ref secessential3rdpartysoftware for more information. -| Library | CMake Variable | Functionality | Dependencies | +| Component | CMake Variable | Functionality | Dependencies | | :-------- | :------------- | :------------ | :----------- | | \cgal | none | Main library | \gmp, \mpfr, \boost (headers) | -| `CGAL_Core` | `WITH_CGAL_Core` | The %CORE library for algebraic numbers.\cgalFootnote{CGAL_Core is not part of \cgal, but a custom version of the \core library distributed by \cgal for the user convenience and it has it's own license.} | \gmp and \mpfr | | `CGAL_ImageIO` | `WITH_CGAL_ImageIO` | Utilities to read and write image files | \zlib, \vtk (optional) | | `CGAL_Qt5` | `WITH_CGAL_Qt5` | `QGraphicsView` support for \qt5-based demos | \qt5 | -Shared libraries, also called dynamic-link libraries, are built by default -(`.so` on Linux, `.dylib` on macOS). You -can choose to produce static libraries instead, by setting the CMake -variable `BUILD_SHARED_LIBS` to `FALSE`. - \subsection installation_examples CGAL Examples and Demos \cgal is distributed with a large collection of examples and demos. By default, these are not configured along with @@ -84,7 +77,7 @@ might need these \cgal-libraries and thus their dependencies. See the page \subsection installation_debugrelease Debug vs. Release -The CMake variable `CMAKE_BUILD_TYPE` indicates how to build the libraries. +The CMake variable `CMAKE_BUILD_TYPE` indicates how to build the executables. It accepts the values `Debug` or `Release`. Note that the default value is `Debug`, since it is default value in `CMake`. If you do not plan on debugging, it is important to set the variable to `Release` for performance reasons. @@ -96,9 +89,8 @@ from within the IDE in this environment. There are many more variables that can be used during configuration. The most important ones are: @@ -145,9 +137,6 @@ Providing information and pressing *Configure* goes on until all entries are grayed. You are now ready to press *Generate*. Once this is done, you can quit `cmake-gui`. -Since you intend to build CGAL libraries, you should also ensure that the variable -`CGAL_HEADER_ONLY` has not been set. - If you do not need to debug, you should set the variable `CMAKE_BUILD_TYPE` to `Release`. \subsection installation_configuring_cmd Configuring CGAL with the cmake Command-Line Tool @@ -184,7 +173,7 @@ building of a program using \cgal, see Section \ref installation_buildprogram. \section seccmakeoutofsource Multiple Builds -While you can choose between release or debug builds, and shared or static libraries, +While you can choose between release or debug builds, it is not possible to generate different variants during a single configuration. You need to run CMake in a different directory for each variant you are interested in, each with its own selection of configuration parameters. @@ -208,38 +197,23 @@ You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/build/d cd CGAL-\cgalReleaseNumber/build/release cmake -DCMAKE_BUILD_TYPE=Release ../.. -\section secbuilding Building CGAL + +\subsection ssec_installation_build_ex_demos Building Examples and Demos + +Let's assume that you have turned on the configuration of examples +(`-DWITH_examples=ON`) and/or demos (`-DWITH_demos=ON`). The results of a successful configuration are build files that control the build step. The nature of the build files depends on the generator used during configuration, but in all cases they -contain several targets, one per library, and a default global target corresponding -to all the libraries. +contain several targets, one per executable, and a default global target corresponding +to all of them (called `examples` and/or `demos`). For example, in a \unix-like environment the default generator produces makefiles. You can use the `make` command-line tool for the succeeding build step as follows: - # build all the selected libraries at once - make + # build all the selected examples at once + make examples -The resulting libraries are placed in the subdirectory `lib` under `` -(which is `CGAL-\cgalReleaseNumber` in case you run an in-source-configuration). - -\cgalAdvancedBegin -The build files produced by CMake are autoconfigured. That -is, if you change any of the dependencies, the build step -automatically goes all the way back to the configuration step. This -way, once the target has been configured the very first time by -invoking cmake, you don't necessarily need to invoke `cmake` -again. Rebuilding will call itself `cmake` and re-generate the -build file whenever needed. -\cgalAdvancedEnd - -\subsection ssec_installation_build_ex_demos Building Examples and Demos - -If you have turned on the configuration of examples -(`-DWITH_examples=ON`) and/or demos (`-DWITH_demos=ON`), there will be additional -targets named `examples` and `demos`, plus one target for -each example and each demo in the build files. None of these targets are included by default, so you need to build them explicitly after the \cgal libraries have been successfully built. The targets `examples` and `demos` include themselves all the targets @@ -259,6 +233,15 @@ If you are interested in the demos or examples of just a particular module, you When using `UNIX Makefiles`, you can find out the exact name of the example or demo target of a particular package by typing `make help | grep `. +\cgalAdvancedBegin +The build files produced by CMake are autoconfigured. That +is, if you change any of the dependencies, the build step +automatically goes all the way back to the configuration step. This +way, once the target has been configured the very first time by +invoking cmake, you don't necessarily need to invoke `cmake` +again. Rebuilding will call itself `cmake` and re-generate the +build file whenever needed. +\cgalAdvancedEnd \section secinstalling Installing CGAL On many platforms, library pieces such as headers, docs and binaries @@ -266,10 +249,10 @@ are expected to be placed in specific locations. A typical example being `/usr/include` and `/usr/lib`. The process of placing or copying the library elements into its standard location is sometimes referred to as Installation and it is a -postprocessing step after the build step. +postprocessing step after the configuration step. CMake carries out the installation by producing a build target named install. -Assuming you have successfully configured and built \cgal as demonstrated in the previous sections, +Assuming you have successfully configured \cgal as demonstrated in the previous sections, the installation simply amounts to: # install CGAL @@ -283,7 +266,7 @@ variable explicitly at the configuration time and not when executing the \cgalAdvancedEnd The file `CGALConfig.cmake` is installed by default in -`$CMAKE_INSTALLED_PREFIX/lib/``CGAL-\cgalReleaseNumber`. +`$CMAKE_INSTALLED_PREFIX/lib/cmake/CGAL`. \section installation_buildprogram Building a Program using CGAL @@ -305,7 +288,7 @@ the process of configuring a user's program called `your_program.cpp` amounts to In order to configure a program, you need to indicate the location of the \cgal configuration file in the CMake variable `CGAL_DIR` (as shown in the example above). -If you have installed \cgal, `CGAL_DIR` must afterwards be set to `$CMAKE_INSTALLED_PREFIX/lib/CGAL`. +If you have installed \cgal, `CGAL_DIR` must afterwards be set to `$CMAKE_INSTALLED_PREFIX/lib/cmake/CGAL`. The variable `CGAL_DIR` can also be an environment variable, but setting it manually makes particular sense if you have multiple out-of-source builds of \cgal as in Section \ref seccmakeoutofsource. diff --git a/Installation/CHANGES.md b/Installation/CHANGES.md index 216493431f7..71899f9ca11 100644 --- a/Installation/CHANGES.md +++ b/Installation/CHANGES.md @@ -6,6 +6,9 @@ Release History Release date: July 2021 +### General changes +- The support for the compiled version of CGAL is dropped. Only the header-only version is supported. + ### [Quadtrees, Octrees, and Orthtrees](https://doc.cgal.org/5.3/Manual/packages.html#PkgOrthtree) (new package) - This package implements a tree data structure in which each node encloses a hypercubic section From 83cff06d12d203ec87448a8672449548ac1334c8 Mon Sep 17 00:00:00 2001 From: Maxime Gimeno Date: Tue, 29 Jun 2021 13:45:41 +0200 Subject: [PATCH 2/2] more update --- Documentation/doc/Documentation/Getting_started.txt | 2 +- Documentation/doc/Documentation/Third_party.txt | 2 +- .../doc/Documentation/advanced/Configuration_variables.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/doc/Documentation/Getting_started.txt b/Documentation/doc/Documentation/Getting_started.txt index 522dfa212d8..71d5f9b9e7a 100644 --- a/Documentation/doc/Documentation/Getting_started.txt +++ b/Documentation/doc/Documentation/Getting_started.txt @@ -16,7 +16,7 @@ The following pages cover advanced installation options: - \subpage configurationvariables gives information about which CMake variables can be used to help resolve missing dependencies while using the cmake command line tool. -- \subpage installation describes the deprecated process of configuring and building \cgal. +- \subpage installation describes the process of configuring and installing \cgal. The following pages cover the structure of the manual and general information about \cgal: diff --git a/Documentation/doc/Documentation/Third_party.txt b/Documentation/doc/Documentation/Third_party.txt index 0f062e1f6a6..2da77c838ce 100644 --- a/Documentation/doc/Documentation/Third_party.txt +++ b/Documentation/doc/Documentation/Third_party.txt @@ -28,7 +28,7 @@ Older versions of the above listed compilers might work, but no guarantee is pro In order to configure and build the \cgal examples, demos, or libraries, you need CMake, a cross-platform "makefile generator". -This manual explains only the features of CMake which are needed in order to build \cgal. +This manual explains only the features of CMake which are needed in order to use \cgal. Please refer to the CMake documentation for further details. diff --git a/Documentation/doc/Documentation/advanced/Configuration_variables.txt b/Documentation/doc/Documentation/advanced/Configuration_variables.txt index 16a111ca562..cf7911b21e4 100644 --- a/Documentation/doc/Documentation/advanced/Configuration_variables.txt +++ b/Documentation/doc/Documentation/advanced/Configuration_variables.txt @@ -19,7 +19,7 @@ summarized below are CMake variables. \subsection installation_component_selection Component Selection The following boolean variables indicate which \cgal components to -configure and build. Their values can be ON or OFF. +configure and/or build. Their values can be ON or OFF. | Variable | %Default Value |