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

Merge branch 'Doc-Remove_compiled_cgal_compatibility-maxGimeno'

This commit is contained in:
Laurent Rineau 2021-06-30 15:29:35 +02:00
parent 01f670e61e 83cff06d12
commit 7a3baf216d
5 changed files with 50 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Documentation/doc/Documentation/Getting_started.txt
View File

@ -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:

4
Documentation/doc/Documentation/Third_party.txt
View File

@ -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>.

2
Documentation/doc/Documentation/advanced/Configuration_variables.txt
View File

@ -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 |

103
Documentation/doc/Documentation/advanced/Installation.txt
View File

@ -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 <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
you would like to build 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.
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 <TT>WITH_<library></TT>. 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 them `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 <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
to all the libraries.
contain several <I>targets</I>, 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 `<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.

3
Installation/CHANGES.md
View File

@ -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