Merge branch 'Doc-Remove_compiled_cgal_compatibility-maxGimeno'

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:
 

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 <a href="https://cmake.org/">CMake</a>, 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 <a href="https://cmake.org/documentation/">CMake documentation</a>
 for further details.
 
@@ -84,7 +84,7 @@ and for multi precision floating point numbers.
 \cgal combines floating point arithmetic with exact arithmetic
 in order to be efficient and reliable. \cgal has a built-in
 number type for that, but \gmp and \mpfr provide a faster
-solution, and we recommend to use them.
+solution, and we recommend using them.
 
 These libraries can be obtained from <A HREF="https://gmplib.org/">`https://gmplib.org/`</A>
 and <A HREF="https://www.mpfr.org/">`https://www.mpfr.org/`</A>.

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   |

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
+This page is a step-by-step description of how to configure and install \cgal, and (optionally)
-in case you do not wish to use the - now enabled by default - header-only mode of \cgal.
+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
+    cmake ..                                                                          # configure CGAL
-    make                                                                              # build 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,
+Before building anything using \cgal, you have to choose the compiler/linker,
-set compiler and linker flags, specify which
+set compiler and linker flags and specify which
-third-party libraries you want to use and where they can be found, and
+third-party libraries you want to use and where they can be found. Gathering
-which \cgal libraries you want to build. Gathering
 all this information is called <I>configuration</I>.
-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 <I>cmake variables</I>. 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
+\cgal has some optional components. During configuration, you can select the components that
-you would like to build by setting a CMake variable of the form <TT>WITH_<library></TT>. By default all
+you would like to use by setting a CMake variable of the form <TT>WITH_<library></TT>. By default all
-are switched `ON`. All activated libraries are to be built after configuration.
+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 them `OFF`.
-Note that some libraries have specific dependencies in addition to the essential ones. See the page
+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 <I>dynamic-link libraries</I>, 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 <B>not</B> 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:
 <ul>
-<li> `CMAKE_INSTALL_PREFIX=<dir>`          installation directory [/usr/local]</li>
+<li> `CMAKE_INSTALL_PREFIX=<dir>`         installation directory [/usr/local]</li>
 <li>`CMAKE_BUILD_TYPE=<Debug|Release>`    build type [Release]</li>
-<li>`BUILD_SHARED_LIBS=<TRUE|FALSE>`      shared or static libraries [TRUE]</li>
 <li>`CMAKE_C_COMPILER=<program>`          C compiler [gcc]</li>
 <li>`CMAKE_CXX_COMPILER=<program>`        C++ compiler [g++]</li>
 </ul>
@@ -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 <I>targets</I>, one per library, and a default global target corresponding
+contain several <I>targets</I>, one per executable, and a default global target corresponding
-to all the libraries.
+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
+    # build all the selected examples at once
-    make
+    make examples
 
-The resulting libraries are placed in the subdirectory `lib` under `<CMAKE_BINARY_DIR>`
-(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
 <I>after</I> 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 <package>`.
 
+\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 <I>Installation</I> 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 <I>install</I>.
-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 <I>at the configuration time</I> 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.

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