From e6eb4812ebe57dd7a5caa2de895fb4484e8a43ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Fri, 25 Oct 2019 14:05:15 +0200 Subject: [PATCH] Misc Installation Documentation Updates --- .../doc/Documentation/Getting_started.txt | 11 +- Documentation/doc/Documentation/Usage.txt | 18 +-- .../Documentation/advanced/Installation.txt | 149 ++++++------------ Documentation/doc/Documentation/windows.txt | 125 +++++++-------- README.md | 2 +- 5 files changed, 120 insertions(+), 185 deletions(-) diff --git a/Documentation/doc/Documentation/Getting_started.txt b/Documentation/doc/Documentation/Getting_started.txt index 1c39617f5f8..b4759c28f95 100644 --- a/Documentation/doc/Documentation/Getting_started.txt +++ b/Documentation/doc/Documentation/Getting_started.txt @@ -1,19 +1,18 @@ /*! \page general_intro Getting Started with %CGAL -- \subpage usage Using \cgal on Unix +- \subpage usage -- \subpage windows Using \cgal on Windows +- \subpage windows -- \subpage thirdparty lists required and optional third party libraries. +- \subpage thirdparty gives information (supported versions, download links) of the required and optional third party libraries. - \subpage manual gives an idea of where you should look for documentation. - \subpage preliminaries lists how to control inlining, thread safety, code deprecation, checking of pre- and postconditions, and how to alter the failure behavior. Once you are familiar with building your programs with \cgal and how the documentation is structured, -you can head over to the \ref tutorials for a hand-in-hand introduction to \cgal data structures -and algorithms, or directly to the package(s) that interest you the \ref packages. Each package -contains simple examples of the various functionalities of the package. +you can head over to the \ref tutorials for a gentle introduction to \cgal, or directly to the package(s) +that interest you the \ref packages. Each package contains simple examples of the various functionalities of the package. */ diff --git a/Documentation/doc/Documentation/Usage.txt b/Documentation/doc/Documentation/Usage.txt index a15d2dde432..54ecb3c7814 100644 --- a/Documentation/doc/Documentation/Usage.txt +++ b/Documentation/doc/Documentation/Usage.txt @@ -1,5 +1,5 @@ /*! -\page usage Using %CGAL on UNIX +\page usage Using %CGAL on Linux and macOS \cgalAutoToc Since \cgal version 5.0, \cgal is header-only be default, which means @@ -9,8 +9,8 @@ However, some dependencies of \cgal might still need to be installed. \section usage_introduction Quick Start: Compiling a Program using CGAL Assuming that you have obtained \cgal through one of the package managers offering \cgal on your platform -(see Section \ref secgettingcgal), compiling \cgal examples -is as simple as: +(see Section \ref secgettingcgal), you can download \cgal examples here +and the compilation of an example is as simple as: cd $HOME/CGAL-\cgalReleaseNumber/examples/Triangulation_2 # go to an example directory cmake -DCMAKE_BUILD_TYPE=Release . # configure the examples @@ -19,7 +19,7 @@ is as simple as: Compiling your own program is similar: cd /path/to/your/program - cgal_create_CMakeLists -s executable + cgal_create_CMakeLists -s your_program cmake -DCMAKE_BUILD_TYPE=Release . make @@ -55,7 +55,7 @@ and must be downloaded here. On most operating systems, package managers offer \cgal and its essential third party dependencies. -On `macOS`, we recommend using of Homebrew in the following way: +On macOS, we recommend using of Homebrew in the following way: brew install cgal @@ -101,8 +101,8 @@ The directory `include/CGAL/OpenNL` contains a distribution of the which provides solvers for sparse linear systems, especially designed for the Computer Graphics community. \sc{OpenNL} is not part of \cgal and has its own license. -The only documentation shipped within \cgal sources is the present -installation manual. The \cgal manual can be accessed online at +The only documentation shipped within \cgal sources is the present manual. +The \cgal manual can also be accessed online at `https://doc.cgal.org` or downloaded separately at `https://github.com/CGAL/cgal/releases`. @@ -190,10 +190,10 @@ for all shipped examples and demos of \cgal. For other programs, CMake can also and build user programs, but one has to provide the corresponding `CMakeLists.txt`. This script can be generated either manually, or with the help of a shell-script, see Section \ref devman_create_cgal_CMakeLists. Using this shell-script, -the process of configuring a user's program called `executable.cpp` amounts to: +the process of configuring a user's program called `your_program.cpp` amounts to: cd /path/to/your/program - cgal_create_CMakeLists -s executable + cgal_create_CMakeLists -s your_program cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -CMAKE_BUILD_TYPE=Release . Note that the script `cgal_create_CMakeLists` creates a very coarse `CMakeLists.txt` file which diff --git a/Documentation/doc/Documentation/advanced/Installation.txt b/Documentation/doc/Documentation/advanced/Installation.txt index cf6d2679b62..6afd8618d1b 100644 --- a/Documentation/doc/Documentation/advanced/Installation.txt +++ b/Documentation/doc/Documentation/advanced/Installation.txt @@ -1,27 +1,31 @@ /*! -\page installation Installation +\page installation Building %CGAL libraries (non header-only mode) \cgalAutoToc Since \cgal version 5.0, \cgal is header-only be default, which means -that there is no need to compile and install anything before it can be used. -However, the dependencies of \cgal might still need to be installed. +that there is no need to compile \cgal or its libraries before it can be used. -This page is a step-by-step description of how to configure, build, and install \cgal +This page is for advanced users that have a good reason to still use the old way. +If this is not your case, head over back to the page \ref general_intro. + +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. -It is also possible to install \cgal using package managers on some operating systems, -see Section \ref secspecificinstall. + +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: cd $HOME/CGAL-\cgalReleaseNumber - cmake -DCMAKE_BUILD_TYPE=Release . # configure CGAL - make # build CGAL - make install # install CGAL - cd examples/Triangulation_2 # go to an example directory - cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber -DCMAKE_BUILD_TYPE=Release . # configure the examples - make # build the examples + mkdir build + cd build + cmake -DCMAKE_BUILD_TYPE=Release .. # configure CGAL + make # build CGAL + make install # install CGAL + cd examples/Triangulation_2 # go to an example directory + cmake -DCGAL_DIR=$HOME/CGAL-\cgalReleaseNumber/build -DCMAKE_BUILD_TYPE=Release . # configure the examples + make # build the examples In a less ideal world, you might have to install some required tools and third-party libraries. This is what this page is about. @@ -33,8 +37,7 @@ 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 all this information is called configuration. -The end of the process is marked by the generation of a makefile or a -Visual \cpp solution and project file 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 build \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 @@ -61,7 +64,7 @@ Note that some libraries have specific dependencies in addition to the essential | `CGAL_Qt5` | `WITH_CGAL_Qt5` | `QGraphicsView` support for \sc{Qt}5-based demos | \sc{Qt}5 | Shared libraries, also called dynamic-link libraries, are built by default -(`.dll` on Windows, `.so` on Linux, `.dylib` on MacOS). You +(`.so` on Linux, `.dylib` on macOS). You can choose to produce static libraries instead, by setting the CMake variable `BUILD_SHARED_LIBS` to `FALSE`. @@ -123,21 +126,21 @@ The simplest way to start the configuration process is to run the graphical user interface of CMake, `cmake-gui`. You must pass as argument the root directory of \cgal. For example: - cd CGAL-\cgalReleaseNumber - cmake-gui . # Notice the dot to indicate the current directory + cd CGAL-\cgalReleaseNumber/build + cmake-gui .. # The two dots indicate the parent directory -After `cmake-gui` opens, press 'Configure'. +After `cmake-gui` opens, press *Configure*. A dialog will pop up and you will have to choose what shall be generated. -After you have made your choice and pressed 'Finish', you will see +After you have made your choice and pressed *Finish*, you will see the output of configuration tests in the lower portion of the application. When these tests are done, you will see many -red entries in the upper portion of the application. Just ignore them and press 'Configure'. +red entries in the upper portion of the application. Just ignore them and press *Configure*. By now CMake should have found many libraries and have initialized variables. If you still find red entries, you have to provide the necessary information. This typically happens if you have installed software at non-standard locations. -Providing information and pressing 'Configure' goes on until -all entries are grayed. You are now ready to press 'Generate'. Once this is +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`. \subsection installation_configuring_cmd Configuring CGAL with the cmake Command-Line Tool @@ -148,8 +151,8 @@ The command line tool `cmake` accepts CMake variables as arguments of the form ` in the example above, but this is only useful if you already know which variables need to be explicitly defined. For example: - cd CGAL-\cgalReleaseNumber - cmake . # Notice the dot to indicate the current directory + cd CGAL-\cgalReleaseNumber/build + cmake .. The configuration process not only determines the location of the required dependencies, it also dynamically generates a `compiler_config.h` file, which encodes the properties of your system and a special file named @@ -172,13 +175,13 @@ for installation). This file contains the definitions of several CMake variables that summarize the configuration of \cgal and will be essential during the configuration and building of a program using \cgal, see Section \ref installation_buildprogram. -\section seccmakeoutofsource Multiple Variants of Makefiles (Out-of-Source Builds) +\section seccmakeoutofsource Multiple Builds While you can choose between release or debug builds, and shared or static libraries, 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. -CMake stores the resulting makefiles and project files, along with several temporary and auxiliary files such +CMake stores the resulting makefiles, along with several temporary and auxiliary files such as the variables cache, in the directory where it is executed, called `CMAKE_BINARY_DIR`, but it takes the source files and configuration scripts from `CMAKE_SOURCE_DIR`. @@ -187,16 +190,16 @@ The binary and source directories do not need to be the same. Thus, you can conf distinct directory for each configuration and by running CMake from there. This is known in CMake terminology as out-of-source configuration, as opposite to an in-source configuration, as showed in the previous sections. -You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/cmake/platforms/debug` and -`CGAL-\cgalReleaseNumber``/cmake/platforms/release` for two configurations, respectively: +You can, for example, generate subdirectories `CGAL-\cgalReleaseNumber``/build/debug` and +`CGAL-\cgalReleaseNumber``/build/release` for two configurations, respectively: - mkdir CGAL-\cgalReleaseNumber/cmake/platforms/debug - cd CGAL-\cgalReleaseNumber/cmake/platforms/debug - cmake -DCMAKE_BUILD_TYPE=Debug ../../.. + mkdir CGAL-\cgalReleaseNumber/build/debug + cd CGAL-\cgalReleaseNumber/build/debug + cmake -DCMAKE_BUILD_TYPE=Debug ../.. - mkdir CGAL-\cgalReleaseNumber/cmake/platforms/release - cd CGAL-\cgalReleaseNumber/cmake/platforms/release - cmake -DCMAKE_BUILD_TYPE=Release ../../.. + mkdir CGAL-\cgalReleaseNumber/build/release + cd CGAL-\cgalReleaseNumber/build/release + cmake -DCMAKE_BUILD_TYPE=Release ../.. \section secbuilding Building CGAL @@ -205,9 +208,8 @@ The nature of the build files depends on the generator used during configuration contain several targets, one per library, and a default global target corresponding to all the libraries. -For example, in a \sc{Unix}-like environment the default generator produces -makefiles. You can use the `make` command-line tool for the -succeeding build step as follows: +For example, in a \sc{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 @@ -215,20 +217,6 @@ succeeding build step as follows: The resulting libraries are placed in the subdirectory `lib` under `` (which is `CGAL-\cgalReleaseNumber` in case you run an in-source-configuration). -With generators other than `UNIX Makefiles`, the resulting build files -are solution and project files which should be launched in an \sc{Ide}, -such as Visual Studio or KDevelop3. They will contain the targets described -above, which you can manually build as with any other solution/project within your \sc{Ide}. - -Alternatively, you can build it with the command line version of the -\sc{Visual Studio Ide}: - - devenv CGAL.sln /Build Debug - -The "Debug" argument is needed because CMake creates solution files for -all four configurations, and you need to explicitly choose one when building -(the other choices are `Release`, `RelWithDebInfo`, and `MinSizeRel`). - \cgalAdvancedBegin The build files produced by CMake are autoconfigured. That is, if you change any of the dependencies, the build step @@ -236,9 +224,7 @@ 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. Keep this in mind if you configure \cgal -for the Visual Studio IDE since a build could then change the -solution/project file in-place and VS will prompt you to reload it. +build file whenever needed. \cgalAdvancedEnd \subsection ssec_installation_build_ex_demos Building Examples and Demos @@ -270,26 +256,22 @@ of a particular package by typing `make help | grep `. On many platforms, library pieces such as headers, docs and binaries are expected to be placed in specific locations. A typical example -being `/usr/include` and `/usr/lib` on \sc{Unix}-like -operating systems or `C:/Program Files/` on Windows. The process +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. 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, -the installation simply amounts (in a \sc{Unix}-like environment) to: +the installation simply amounts to: # install CGAL make install -If you use a generator that produces IDE files (for Visual Studio for instance), there will be an optional -`INSTALL` project, which you will be able to "build" to execute the installation step. - \cgalAdvancedBegin The files are copied into a directory tree relative to the installation directory determined by the -CMake variable `CMAKE_INSTALL_PREFIX`. This variable defaults to `/usr/local` under \sc{Unix}-like operating systems -and `C:\Program Files` under Windows. If you want to install to a different location, you must override that CMake +CMake variable `CMAKE_INSTALL_PREFIX`. This variable defaults to `/usr/local` under \sc{Unix}-like operating systems. +If you want to install to a different location, you must override that CMake variable explicitly at the configuration time and not when executing the install step. \cgalAdvancedEnd @@ -307,51 +289,18 @@ For other programs, CMake can also be used to configure and build user programs, but one has to provide the corresponding `CMakeLists.txt`. This script can be generated either manually, or with the help of a shell-script, see Section \ref devman_create_cgal_CMakeLists. Using this shell-script, -the process of configuring a user's program called `executable.cpp` amounts to: +the process of configuring a user's program called `your_program.cpp` amounts to: cd /path/to/your/program - cgal_create_CMakeLists -s executable + cgal_create_CMakeLists -s your_program cmake -DCGAL_DIR=XXXXXX -CMAKE_BUILD_TYPE=Release . make -In order to configure a program, you need to indicate the location of the configuration file -in the CMake variable `CGAL_DIR` (as indicated in the example above). +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`. The variable `CGAL_DIR` can also be an environment variable, but setting it manually makes particular sense -if having multiple out-of-source builds of \cgal as in Section \ref seccmakeoutofsource. - -\section secspecificinstall OS Specific Installation - -Some operating systems with package managers offer \cgal and its -essential third party software through the manager, -for instance, Mac OS X or some Linux distribution (e.g. Debian). -For Windows, an installer is provided. - -\subsection sseccgalmacosxe CGAL on macOS - -The \cgal project recommends the use of Homebrew, in the following way: - - brew install cgal - -\subsection sseccgaldebian CGAL on Linux - -For instance in Debian/Ubuntu, use apt-get in the following way: - - sudo apt-get install libcgal-dev - -To get the demos, use: - - sudo apt-get install libcgal-demo - -For other distributions, please consult your respective package manager documentation. - -\subsection sseccgalwindows CGAL on Windows - -You can download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download/windows.html. -It is a self extracting executable that installs the \cgal source, and that allows you -to select and download some precompiled third party libraries. However, you will need to compile -the library using your favorite compiler. -A tutorial is provided on how to proceed with Microsoft Visual Studio. +if you have multiple out-of-source builds of \cgal as in Section \ref seccmakeoutofsource. */ diff --git a/Documentation/doc/Documentation/windows.txt b/Documentation/doc/Documentation/windows.txt index 3df201b6470..cc01f5df6cc 100644 --- a/Documentation/doc/Documentation/windows.txt +++ b/Documentation/doc/Documentation/windows.txt @@ -1,5 +1,5 @@ /*! -\page windows Installing %CGAL for Visual C++ on Windows +\page windows Using %CGAL on Windows (with Visual C++) \cgalAutoToc \cgal is a library that has mandatory dependencies that must be first installed: @@ -19,20 +19,18 @@ you will want to use the \cgal Installer. We explain the two approaches in the next two sections. -\section sec-installing-with-vcpkg Installing CGAL with the Vcpkg library manager +\section sec-installing-with-vcpkg Installing CGAL with the Vcpkg Library Manager \subsection ssec-vcpk-install-vcpk Installing Vcpkg The first step is to clone or download `vcpkg` from https://github.com/microsoft/vcpkg. -\code{.sh} - C:\dev> git clone https://github.com/microsoft/vcpkg - C:\dev> cd vcpkg - C:\dev\vcpkg> .\bootstrap-vcpkg.bat -\endcode + C:\dev> git clone https://github.com/microsoft/vcpkg + C:\dev> cd vcpkg + C:\dev\vcpkg> .\bootstrap-vcpkg.bat -\subsection ssec-vcpk-install-cgal Installing with Vcpkg +\subsection ssec-vcpk-install-cgal Installing CGAL with Vcpkg By default `vcpkg` installs for 32 bit binaries and will use the latest version of Visual C++ installed on your machine. If you develop 64 bit software you must @@ -44,9 +42,7 @@ of `vcpkg` if you want to compile for an older version of a compiler. You are now ready to install \cgal: -\code{.sh} - C:\dev\vcpkg> ./vcpkg.exe install cgal -\endcode + C:\dev\vcpkg> ./vcpkg.exe install cgal This will take several minutes as it downloads \mpir (a fork of \gmp), \mpfr, all boost header files, and it will compile \mpir and \mpfr, as well @@ -56,7 +52,6 @@ subdirectory `C:\dev\vcpkg\installed\x64-windows`. Note that \cgal is a header-only library, and there are therefore no `lib` or `dll` files for \cgal. - \subsection ssec-vcpkg-compile-example Compiling an Example In this section we show how to compile a program that uses \cgal. @@ -77,13 +72,12 @@ Gathering all this information is called *configuration* and we use *CMake* as c The end of the process is marked by the generation of a Visual \cpp solution and a project file that you can use to build your program. -\code{.sh} - C:\Users\Me\CGAL-5.0> cd examples\Triangulation_2 - C:\Users\Me\CGAL-5.0\examples\Triangulation_2> mkdir build - C:\Users\Me\CGAL-5.0\examples\Triangulation_2> cd build - C:\Users\Me\CGAL-5.0\examples\Triangulation_2\build> cmake-gui .. # cmake-gui is the graphical interface for cmake, which we recommend to use -\endcode + C:\Users\Me\CGAL-\cgalReleaseNumber> cd examples\Triangulation_2 + C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2> mkdir build + C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2> cd build + C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build> cmake-gui .. +The command `cmake-gui` launches the graphical interface for `cmake`. When you hit the *Configure* button, you must:
  • specify the *Generator* (e.g., Visual Studio 16 2019),
    • @@ -96,31 +90,24 @@ You will see entries for where header files and libraries are taken from. \subsubsection sssect-vcpkg-additional-dependencies Additional Dependencies -Some \cgal packages also have additional dependencies. During the configuration -of the above examples, you may have observed the following message: +Some \cgal packages also have additional dependencies. For example, during the configuration process +above, you may have observed the following message: -\code{.sh} - NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled -\endcode + NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled \cgal is a library of algorithms and data structures and as such does not depend on `Qt`. However, one of the examples in the Triangulation_2 package does require `Qt` for visualization purposes. If you already have `Qt` installed, you can simply fill in the requested CMake variables and paths. Otherwise, you can also install it using `vcpkg`: -\code{.sh} - C:\dev\vcpkg> .\vcpkg.exe install qt5 -\endcode + C:\dev\vcpkg> ./vcpkg.exe install qt5 Remember to specify `--triplet` or the related environment variable in case you target 64-bit applications. As Qt5 is modular and as the \cgal examples and demos use only some of these modules you can save download and compilation time by specifying an *installation option*: -\code{.sh} - C:\dev\vcpkg> ./vcpkg.exe install cgal [qt] -\endcode - + C:\dev\vcpkg> ./vcpkg.exe install cgal [qt] In both cases, when you start `cmake-gui` again and hit the *Configure* button, the CMake variables and paths concerning Qt should now be filled. @@ -139,44 +126,44 @@ the location of third-party software. \subsubsection sssect-vcpkg-compilation Compilation of an Example -Hit the *Generate* button, and you will find the file `Triangulation_2_examples.sln` -in the directory `C:\Users\Me\CGAL-5.0\examples\Triangulation_2\build`. +Once the configuration process is successful, hit the *Generate* button, +and you will find the file `Triangulation_2_examples.sln` +in the directory `C:\Users\Me\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build`. Double-click it to open it. There is one project per `.cpp` file in the directory. Compile them all, or just the one you are interested in. -\subsection subsect-vpckg-my-code Configuring and Compiling My Code Using CGAL +\subsection subsect-vpckg-my-code Configuring and Compiling Your Code Using CGAL Configuring and compiling your own code is practically the same as for \cgal examples if you use `cmake`. Running `cmake` (or `cmake-gui`) requires a `CMakeLists.txt` file. This file is automatically provided for all examples and demos of \cgal. For your own programs, you are advised to look at the `CMakeLists.txt` files in the example -folder of the package that you are using to learn how to specify \cgal and additional third party +folder of the package(s) that you are using to learn how to specify \cgal and additional third party dependencies. \section install-with-installer Installing with the CGAL Installer You can download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download/windows.html. -It is a self extracting executable that downloads the \cgal header files, and optionally the source code of the +It is a self-extracting executable that downloads the \cgal header files, and optionally the source code of the examples and demos. Additionally, it can download precompiled versions of \gmp and \mpfr. \subsection ssect-installer-boost Installing Boost -Binary versions of `Boost` are available on SourceForge. - +`Boost` is a mandatory dependency of \cgal. Binary versions of `Boost` are available on +SourceForge. The `Boost` installers install both `Boost` headers and precompiled libraries. Please note that the \cgal project is not responsible for the files provided on this website. When \cgal \cgalReleaseNumber was released, the latest version of `Boost` was 1.71. +A typical installation of `Boost` would consist of the following steps:
    • Download and run the file boost_1_71_0-msvc-XX.Y-64.exe (where XX.Y = 14.0 for VC 2015, XX.Y = 14.1 for 2017, XX.Y = 14.2 for VC 2019).
    • Extract the files to a new directory, e.g. `c:\dev\libboost_1_71_0`.
    • Set the following two environment variables to point respectively to the path of the libraries and the headers - -\code{.sh} - BOOST_LIBRARYDIR=C:\dev\libboost_1_71_0\lib64-msvc-XX.Y - BOOST_INCLUDEDIR=C:\dev\libboost_1_71_0 -\endcode - +
        +
      • `BOOST_LIBRARYDIR = C:\dev\libboost_1_71_0\lib64-msvc-XX.Y`
        • +
      • `BOOST_INCLUDEDIR = C:\dev\libboost_1_71_0`
        • +
      as this will help `cmake` to find Boost.
    • Add the path to the Boost `dlls` (`C:\dev\libboost_1_71_0\lib64-msvc-XX.Y`) files to the `PATH` environment variable.
    @@ -186,15 +173,15 @@ as this will help `cmake` to find Boost. Download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download/windows.html. It is a self extracting executable that downloads the \cgal header files, and optionally the source code of the -examples and demos. Additionally, it can download the precompiled versions of \gmp and \mpfr. You must -specify if yoy want the 32 or the 64 bit versions of these two libraries. +examples and demos. Additionally, it can download the precompiled versions of \gmp and \mpfr. You must +specify if you want the 32 or the 64 bit versions of these two libraries. -\cgal being a header-only library, there is no need to compile it. Set the environment variable `CGAL_DIR` to `C:\dev\CGAL-5.0`, -as this will help `cmake` to find \cgal. +Setting the environment variable `CGAL_DIR` to `C:\dev\CGAL-\cgalReleaseNumber` is a good idea +to help `cmake` to find \cgal during the configuration process, detailed in the next section. \subsection ssect-installer-compile-example Compiling an Example -We assume you have downloaded the examples with the \cgal Installer. +We assume that you have downloaded the examples with the \cgal Installer. Before building 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. @@ -205,14 +192,13 @@ download it). The end of the process is marked by the generation of a Visual \cpp solution and a project file that you can use to build your program. -\code{.sh} - C:\dev\CGAL-5.0> cd examples\Triangulation_2 - C:\dev\CGAL-5.0\examples\Triangulation_2> mkdir build - C:\dev\CGAL-5.0\examples\Triangulation_2> cd build - C:\dev\CGAL-5.0\examples\Triangulation_2\build> cmake-gui .. # cmake-gui is the graphical interface for cmake, which we recommend to use -\endcode + C:\dev\CGAL-\cgalReleaseNumber> cd examples\Triangulation_2 + C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2> mkdir build + C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2> cd build + C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build> cmake-gui .. -When you hit the *Configure* button you must: +The command `cmake-gui` launches the graphical interface for `cmake`. +When you hit the *Configure* button, you must:
    • Specify the *Generator*, e.g., Visual Studio 16 2019), and
    • specify an *Optional Platform* (`x64` in case you want to create 64 bit binaries).
      • @@ -222,16 +208,15 @@ You will see entries for where header files and libraries are taken from. \subsubsection ssect-installer-additional-dependencies Additional Dependencies -Individual \cgal packages may also have additional dependencies. During the configuration -of the above examples, you may have observed the following message: +Some \cgal packages also have additional dependencies. For example, during the configuration process +above, you may have observed the following message: -\code{.sh} - NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled -\endcode + NOTICE: The example draw_triangulation_2 requires Qt and will not be compiled \cgal is a library of algorithms and data structures and as such does -not depend on Qt. However, one of the examples does for visualization purposes only. Either you -have Qt installed and you can fill in the requested CMake variables, or we install it now. +not depend on `Qt`. However, one of the examples does for visualization purposes only. Either you +have Qt installed and you can fill in the requested CMake variables, or you must install it. +A typical `Qt` installation would consist of the following steps:
      • @@ -242,10 +227,11 @@ Download and install the Qt library for open source development package for your as this will help `cmake` to find Qt.
      • Add the bin directory of Qt, e.g. add `C:\dev\Qt\Qt5.13.1\msvcXXXX_YY\bin` to `PATH`, where `XXXX_YY` is something like `vc2017_64`. To avoid any conflict with another dll with the same name from another folder, add this path as the first in the list.
        • -
      • When you start `cmake-gui` again and hit the *Configure* button, -the CMake variables concerning Qt should now be filled.
      +Once you have installed `Qt`, the CMake variables concerning `Qt` should now be filled when you +press *Configure* in the \cgal directory. + You must follow a similar process for other dependencies (see page \ref thirdparty for information on supported versions of third party libraries as well as download links) and fill the missing information within the `CMake` interface until configuration is successful (no more red lines indicating @@ -259,10 +245,11 @@ the location of third-party software. \subsubsection sssect-installer-compilation Compilation of an Example -Hit the *Generate* button, and you will find the file `Triangulation_2_examples.sln` -in the directory `C:\dev\CGAL-5.0\examples\Triangulation_2\build`. -Double click in order to open it. You will see one project per `.cpp` file. -Compile them all or just the one you are interested in. +Once the configuration process is successful, hit the *Generate* button, +and you will find the file `Triangulation_2_examples.sln` +in the directory `C:\dev\CGAL-\cgalReleaseNumber\examples\Triangulation_2\build`. +Double-click it in order to open it. You will see one project per `.cpp` file. +Compile them all, or just the one you are interested in. \subsection subsect-installer-my-code Configuring and Compiling My Code Using CGAL @@ -270,7 +257,7 @@ Configuring and compiling your own code is practically the same as for \cgal exa if you use `cmake`. Running `cmake` (or `cmake-gui`) requires a `CMakeLists.txt` file. This file is automatically provided for all examples and demos of \cgal. For your own programs, you are advised to look at the `CMakeLists.txt` files in the example -folder of the package that you are using to learn how to specify \cgal and additional third party +folder of the package(s) that you are using to learn how to specify \cgal and additional third party dependencies. \section install-with-tarball Installing from the Source Archive diff --git a/README.md b/README.md index 2f816f729cb..0166c3f78ae 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Getting Started with CGAL ========================= **Since version 5.0, CGAL is a header-only library, meaning that -it is no longer needed to build or install CGAL before it can be used.** +it is no longer needed to build CGAL libraries before it can be used.** Head over to the [CGAL manual](https://doc.cgal.org/latest/Manual/general_intro.html) for usage guides and tutorials that will get you started smoothly.