From 726e530029ce4bc8cc4cbbb4a2c0a8214c74edd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Thu, 24 Oct 2019 16:30:42 +0200 Subject: [PATCH] Update Usage on Linux / Usage on Windows pages --- .../doc/Documentation/Getting_started.txt | 4 +- Documentation/doc/Documentation/Usage.txt | 52 ++---- Documentation/doc/Documentation/windows.txt | 173 ++++++++++-------- 3 files changed, 105 insertions(+), 124 deletions(-) diff --git a/Documentation/doc/Documentation/Getting_started.txt b/Documentation/doc/Documentation/Getting_started.txt index 34128eaa5ee..1c39617f5f8 100644 --- a/Documentation/doc/Documentation/Getting_started.txt +++ b/Documentation/doc/Documentation/Getting_started.txt @@ -1,9 +1,9 @@ /*! \page general_intro Getting Started with %CGAL -- \subpage usage describes how to obtain \cgal and the few steps required to build a program using \cgal. +- \subpage usage Using \cgal on Unix -- \subpage windows blabla +- \subpage windows Using \cgal on Windows - \subpage thirdparty lists required and optional third party libraries. diff --git a/Documentation/doc/Documentation/Usage.txt b/Documentation/doc/Documentation/Usage.txt index 65cff71be5f..a15d2dde432 100644 --- a/Documentation/doc/Documentation/Usage.txt +++ b/Documentation/doc/Documentation/Usage.txt @@ -1,23 +1,21 @@ /*! -\page usage Usage +\page usage Using %CGAL on UNIX \cgalAutoToc Since \cgal version 5.0, \cgal is header-only be default, which means -that there is no need to build or install \cgal before it can be used. +that there is no need to build \cgal before it can be used. 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, which can be downloaded here, +(see Section \ref secgettingcgal), compiling \cgal examples is as simple as: cd $HOME/CGAL-\cgalReleaseNumber/examples/Triangulation_2 # go to an example directory cmake -DCMAKE_BUILD_TYPE=Release . # configure the examples make # build the examples -On Windows, instead of calling `make` simply double-click on the generated solution (`.sln`) to open Visual C++. - Compiling your own program is similar: cd /path/to/your/program @@ -34,10 +32,10 @@ This is what this page is about. Using \cgal requires a few core components to be previously installed: Optional third-party software might be required to build examples and demos shipped with \cgal, @@ -57,34 +55,19 @@ 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 -On Linux distributions such as Debian/Ubuntu/Mint, use `apt-get` in the following way: +On Linux distributions such as `Debian`/`Ubuntu`/`Mint`, use `apt-get` in the following way: sudo apt-get install libcgal-dev -On Windows, we recommand using vcpkg in the following way: - - vcpkg install cgal - -To see how to use libraries installed with vcpkg, -refer to the official documentation. - For other distributions or package manager, please consult your respective documentation. -\subsection sseccgalwindows Using the CGAL Installer 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. - \subsection secusingwebsite Using CGAL Source Archive -You can obtain the \cgal library from +You can also obtain the \cgal library sources directly from https://www.cgal.org/download.html. Once you have downloaded the file `CGAL-\cgalReleaseNumber``.tar.gz` containing the @@ -157,8 +140,7 @@ In the rare event that it has not, the variable `CGAL_DIR` should be set manuall If \cgal has been obtained via other means, `CGAL_DIR` must point to the root directory @@ -237,18 +219,6 @@ You can use the `make` command-line tool for the succeeding build step as follow cd CGAL-\cgalReleaseNumber/examples/Triangulation_2 make # build all the examples of the Triangulation_2 package -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 Release - -The "Release" 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 `Debug`, `RelWithDebInfo`, and `MinSizeRel`). - \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 diff --git a/Documentation/doc/Documentation/windows.txt b/Documentation/doc/Documentation/windows.txt index 2664d64ff4f..ac4c885895f 100644 --- a/Documentation/doc/Documentation/windows.txt +++ b/Documentation/doc/Documentation/windows.txt @@ -18,7 +18,7 @@ and compile it, but from then on `vcpkg` will make your life easier. have installed boost, or you need a specific boost version, and not the latest one, which you would get with `vcpkg`.] -In the next two sections we explain the two approaches. +We explain the two approaches in the next sections. \section sec-installing-with-vcpkg Installing CGAL with the vcpkg Library Manager @@ -34,7 +34,7 @@ The first step is to clone or download `vcpkg` from C:\dev\vcpkg> .\vcpkg integrate install \endcode -The last step requires to run *cmd* with administrator rights. +The last step requires to run `cmd` with administrator rights. \subsection ssec-vcpk-install-cgal Installing CGAL Itself @@ -72,34 +72,34 @@ next compile an example from the 2D Triangulation package. \subsubsection sssec-vcpkg-configuration-example Configuring of an Example -Before building anything using \cgal you have to choose the compiler/linker, set compiler +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. Gathering all this information is called *configuration* and we use CMake as configuration tool -(see Section \ref seccmake for more information on minimal supported versions and where to -download it). +(see Section \ref seccmake for more information on supported versions and where to download it). -The end of the process is marked by the generation of a Visual \cpp solution and -project file that you can use to build your program. +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 .. + 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 -When you hit the *Configure* button you must choose the compiler, -you must *Specify the Generator* (e.g., Visual Studio 16 2019), you must -specify the *Optional Platform* (`x64 in case you want to create 64 bit binaries), -and you must select *Specify toolchain file for cross compilation* -(`C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake`, which you have -to adapt to where you installed `vcpkg` on your machine). -Once the configuration is done, tick *Advanced* and *Grouped* in `cmake-gui`. +When you hit the `Configure` button, you must: + +Once the configuration process is done, tick `Advanced` and `Grouped` in `cmake-gui`. You will see entries for where header files and libraries are taken from. \subsubsection sssect-vcpkg-additional-dependencies Additional Dependencies -Individual \cgal packages may also have additional dependencies. During the configuration +Some \cgal packages also have additional dependencies. During the configuration of the above examples, you may have observed the following message: \code{.sh} @@ -107,66 +107,79 @@ of the above examples, you may have observed the following message: \endcode \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 using `vcpkg`: +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 -Remember to specify `--triplet` or the related environment variable in case you target 64 bit applications. +Remember to specify `--triplet` or the related environment variable in case you target 64-bit applications. -When you start *cmake-gui* again and hit the *Configure* button, -the CMake variables concerning Qt should now be filled. +When you start `cmake-gui` again and hit the `Configure` button, +the CMake variables and paths concerning Qt should now be filled. -Note that not all dependencies are available through the `vcpkg` library manager. -In this case you have to download and install them - -See page \ref configurationvariables et \ref thirdparty +Note that not all optional dependencies are available through the `vcpkg` library manager. +In this case, you must download and install them independently (see page \ref thirdparty +for information on support versions and download links) as well as fill the missing information +within the `CMake` interface until configuration is successful (no more red lines indicating +missing dependencies). +\cgalAdvancedBegin +You may also decide to solve missing dependencies using the `CMake` command line tool (which is not recommended). +If so, the page \ref configurationvariables lists variables which can be used to specify +the location of third-party software. +\cgalAdvancedEnd \subsubsection sssect-vcpkg-compilation Compilation of an Example -Hit the *Generate* button, and you will find the file `Triangulation_2_examples.sln` +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`. -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. - - +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 +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 +dependencies. \section install-with-installer Installing with the 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 -examples and demos. Additionally, it can download the precompiled versions of GMP and Mpfr. +examples and demos. Additionally, it can download precompiled versions of GMP and MPFR. -\subsection ssect-installer-boost Installing boost +\subsection ssect-installer-boost Installing `Boost` -Binary versions of Boost are available on SourceForge. +Binary versions of `Boost` are available on SourceForge. -The installers install both Boost headers and precompiled libraries. -Please note that the \cgal project is not responsible for the files provided on this web site. -When \cgal \cgalReleaseNumber was released, the latest version of boost was 1.71. +The 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. -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). - -Choose to extract the files to a new directory: c:\dev\libboost_1_71_0. - -Set the following two environment variables to point respectively to the path of the libraries and the headers + \subsection ssect-installer-install-cgal Installing CGAL Itself -Download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from https://www.cgal.org/download/windows.html. +Download and run `CGAL-\cgalReleaseNumber``-Setup.exe` from < +a href="https://www.cgal.org/download/windows.html">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. @@ -174,34 +187,34 @@ specify if yoy 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. -\subsection ssect-installer-compile-example Compiling an Example +\subsection ssect-installer-compile-example Compiling an Example We assume you have downloaded the examples with the installer. -Before building anything using \cgal you have to choose the compiler/linker, set compiler +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. Gathering all this information is called *configuration* and we use CMake as configuration tool (see Section \ref seccmake for more information on minimal supported versions and where to download it). -The end of the process is marked by the generation of a Visual \cpp solution and -project file that you can use to build your program. +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 .. + 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 -When you hit the *Configure* button you must choose the compiler, -you must *Specify the Generator* (e.g., Visual Studio 16 2019), you must -specify the *Optional Platform* (`x64 in case you want to create 64 bit binaries). -Once the configuration is done, tick *Advanced* and *Grouped* in `cmake-gui. +When you hit the `Configure` button you must: + +Once the configuration is done, tick `Advanced` and `Grouped` in `cmake-gui. 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 @@ -215,43 +228,41 @@ of the above examples, you may have observed the following message: 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. - + -Add the environment variable `QTDIR` pointing to the place you installed Qt, e.g., `C:\dev\Qt\Qt5.13.1`, -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. - -For other dependencies it will be similar page \ref thirdparty \ref configurationvariables +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). \subsubsection sssect-installer-compilation Compilation of an Example -Hit the *Generate* button, and you will find the file `Triangulation_2_examples.sln` +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. +\subsection subsect-installer-my-code Configuring and Compiling My 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 +dependencies. \section install-with-tarball Installing from the tarball -Instead of the installer you can also download the tarball. The sole difference is that the installer -also downloads the precompiled GMP and Mpfr libraries. - - -\section sect-my-code Configuring and Compiling My Code Using CGAL - -Configuring and compiling your own code is practically the same as for \cgal examples -if you use `cmake`. 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 dependencies. - +Instead of the installer you can also download release tarballs. The sole difference with the installer +procedure is that the installer also downloads precompiled GMP and MPFR libraries. */