Assignment 0

Basic setup and knowledge for the course

This is a preparation assigment. It is unmarked and has no deadline, but it will help you to do the following assignments.

The instructions in this assignment will help you to have a working system to compile C++ files with CGAL and other external libraries. It will be useful to hit the ground running in week 2.

1. How to install a nice C++ development environment

There are two or three parts to this:

  1. a C++ compiler, which you absolutely need and is what converts your C++ source code to an executable file that you can run;
  2. an integrated development environment (IDE), which is highly recommended and provides you with a nice text editor for C++ source code and other programming tools, such as debuggers (to find bugs in your code) and profiling tools (to find what makes it slow); and
  3. CMake as a build system, which is also highly recommended and is a layer between the two parts above.

Our recommendation is that you install CLion, CMake and a C++ compiler using the instructions from geogeeks.

If you the above tools don’t work for you and you want some IDE alternatives, Visual Studio is the most popular full featured IDE on Windows, Xcode is the one on Mac and Visual Studio Code is a nice simpler alternative that runs on Windows, Mac and Linux. Note that Visual Studio and Xcode have their own build systems that do not rely on CMake.

2. Test and understand your C++ development environment

After you have installed the tools listed above, we recommend that you test your C++ development environment and make sure that it is working correctly.

If you use the recommended tools, try step 1 of this CLion tutorial. Make sure that your default C++ project builds and runs correctly.

Try to understand what is happenning in the CMakeLists.txt using this page of geogeeks. Also, read this page to understand what your compiler is doing when you tell it to build your project.

If you don’t know C++ or need a refresher, this is a good series of tutorials. Read the tutorials in the section titled Basics of C++ and the ones on Control Structures, Functions and Input/output with files. You don’t need to memorise every single C++ feature in them, but knowing what’s available will help you in the future. Test and modify some of the examples in your own computer.

The same website is also a very good user friendly reference for the C++ standard library data structures, functions and algorithms. For example, if you want to know the member functions of a list or a map.

3. Installing CGAL and other C++ libraries

Your C++ development environment already comes with the C++ standard library, which contains a lot of functionality. However, there’s much, much more that is available in external libraries, which you have to install.

During the course, we will use CGAL, which is a very nice computational geometry library with a lot of features. It is also a relatively complex library to install and use, so installing it now will help you to get it working already and to understand the process of installing libraries more generally.

The simplest way to install CGAL (and similar libraries) depends on your operating system. See the sections below.

3.1. Windows

In our opinion, there are two good ways to install CGAL. Each have their pros and cons. These are:

  1. using vcpkg, Microsoft’s package manager for C++ libraries; or

  2. through the Windows Subsystem for Linux (WSL), which is a feature of Windows that allows you to run a Linux environment inside Windows 10 or later.

vspkg advantages: If you choose to use vcpkg, you’ll use less disk space on your computer (several GBs), use less memory because you won’t need to run a Linux environment at the same time, generally achieve higher performance, and avoid dealing with two different filesystems. vcpkg is also what you should use if you want to use Visual Studio instead of CLion.

WSL advantages If you choose to use WSL, you’ll have access to the easier and less error-prone install processes of CGAL (and other libraries) that are available under Linux, be able to use other nice tools that work better on Linux (e.g. SSH or git clients), generally have access to better support/answers from internet communities, and gain valuable (work) experience using Linux. Also, If you want to take GEO5015: Modelling wind and dispersion in urban environments, you’ll most likely use WSL anyway.

For what is worth, we used to recommend the WSL route in previous years, but vcpkg is getting better and CLion has vcpkg integration now. Both options are fine.

If you want to go the WSL route, install it if you don’t have it already. If you already have it but have WSL 1, we advice that you upgrade to WSL 2. Similarly, if you have it but have an old distribution of Linux, we advice that you upgrade to something like Ubuntu-22.04. Then, follow this tutorial. You can skip the GDAL installation for now, but you should do all of the rest, including the Connect to CLion section.

If you want to go the vcpkg route, have a look at this tutorial to install vcpkg and CGAL. Here is a more detailed tutorial that explains how to link it to CLion step by step.

3.2. Mac

The easiest way is to use Homebrew (recommended), although it’s quite easy to use an alternative like MacPorts or to install them manually (follow the Linux or Unix instructions if there are none for Mac).

An example to install CGAL with Homebrew:

brew install cgal

Note that if you’re using an Apple Silicon (arm64) Mac, the paths used by Homebrew are: /opt/homebrew/include (for headers) and /opt/homebrew/lib (for libraries). If you’re using an Intel (x86-64) Mac, the paths used by Homebrew are: /usr/local/include (for headers) and /usr/local/lib (for libraries). If you’re using CLion, these should be found by CMake. However, if you’re using Xcode you might have to put these manually in your project settings.

3.3. Linux

Use the package manager of your distribution (eg apt in Ubuntu/Debian) or install them manually.

An example to install CGAL with apt:

sudo apt-get install libcgal-dev

4. How to use C++ libraries?

Anything in the standard library works after just including a header in your C++ source code files. For example, if you want to use std::cout and its << operator, you need include iostream:

#include <iostream>

However, if you need to use an external library (eg CGAL), you will first need to add the required paths during compilation and linking. In IDEs (like Visual Studio or Xcode), this is done in the GUI. If you use CMake, this is typically done in your CMakeLists file by first calling a script that finds the library. An example using CGAL:

find_package( CGAL REQUIRED )

The REQUIRED keyword makes CMake generate an error if CGAL is not found. This command sets a number of variables with the required paths. Then, you should set the include path, which for CGAL is done as:

include( ${CGAL_USE_FILE} )

This is a bit non-standard, since for most libraries the include_directories command is used instead. For example, with GDAL it is:

include_directories( ${GDAL_INCLUDE_DIR} )

CGAL is a header-only library (see section below), so nothing else might be necessary. However, some parts of it rely on libraries that do have library files, and so linking to them is also necessary. So, you might have to add a line that looks as follows:

target_link_libraries(your_project_name CGAL::CGAL)

Again, CGAL is a bit non-standard because CGAL::CGAL is hardcoded into the command. Here’s a more typical example with GDAL:

target_link_libraries(your_project_name ${GDAL_LIBRARY} )

Only after those steps, adding the required headers in your .cpp file will work:

#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
4.1. Header-only libraries?

Broadly, there are two kinds of C++ libraries:

  1. The traditional C++ way involves a combination of header files (.h or .hpp) and library files (.lib and .dll files on Windows, .a and .dylib on Mac, .a and .so on Linux). The header files are standard C++ source code files that tell your code what functions are available, whereas the library ones are precompiled files that contain their implementations (i.e. all the functionality).

  2. The more modern C++ way that just puts everything in header files (i.e. header-only libraries). This means that you have to compile them together with your code, which is slower, but computers are fast now and it avoids a lot of issues with distributing library files.

CGAL is header-only, but part of its functionality relies on libraries that are not. In particular, only parts of Boost are header-only, and GMP and MPFR need library files.

4.2. Libraries and dependencies

C++ libraries are often not standalone things. Just like you can include an external library in your code, many C++ libraries depend on other C++ libraries. For instance, most of CGAL requires Boost, GMP and MPFR. Certain CGAL packages require other libraries, such as Eigen or Qt.

If you use a package manager, like Homebrew or apt, these dependencies should be installed automatically with CGAL. If not, you will need to install them manually.

Also note that these libraries’ paths might also need to be set up in your CMakeLists.

5. Testing your C++ with CGAL installation

We recommend that you test your setup with CGAL. This is important because the exact CMake files that will work well for your system can differ from computer to computer based on many factors (like operating system versions and paths)

So, how about using one of the CGAL library examples (eg this one with polygons)? This will be extra useful since CGAL will be used for homework assignment 1.

Acknowledgements

The student assistants of different years have helped us a lot to figure out the best way to install things in different environments. In particular, Özge Tufan contributed most of the WSL instructions and Dimitris Mantas documented the method to use vcpkg with CLion.

[last updated: 2024-02-11 13:01]