Skip to main content

Configuring your Programming Environment

We will use CMake, a cross-platform, open-source make system. This will allow us to compile the same code on Linux, MacOS, and Windows. Our homeworks will use CGAL and Qt5 libraries, which allow us to write interesting and resource-intensive programs and create visualizations using the graphics hardware available on our computer. You'll also need a C++ compiler and git version control.

Our first goal will be to run a few CGAL provided demos and examples to confirm our system is correctly installed & configured.

Note that fighting through the installation & compilation of the various graphics libraries on a specific OS/hardware can be frustrating. Since installation can take a while, make sure you have a good network connection and your computer has a fully charged battery (even better, plug your laptop into wall power). Don't close the laptop lid or let your computer suspend/sleep during installation. These interruptions may lead to installation failures and you might need to uninstall and re-install to fix the failures.

Use Google to search any errors messages or and please ask for help on the Discussion Forum if you are stuck. Please let the instructor know (by email or through the Discussion Forum) if there are errors/updates to any of the information below. Also, please share any additional installation/compilation instructions you have for your specific environment. And if you catch any portability bugs in the code while working on the homework let us know so we can update the provided files.

Install CMake

  • http://www.cmake.org/cmake/resources/software.html

  • Important Note: You may need to upgrade the version of CMake manually (downloading and installing from zip or building from source) if the default version offered by the package manager for your OS is insufficient.

    To check what version you currently have installed, open a terminal and type: 

          cmake --version

    The current version on MacOS 13.2.1 (Apple M2) is CMake 3.25.2.
    The current version on Windows 11 (Version 21H2) is CMake 3.27.4.

  • We do not recommend using Cygwin for any part of this work. If you do have Cygwin on your system, the Windows CMake should be on the path ahead of Cygwin CMake.

Install git

Install CGAL & Qt5

Follow the instructions in the documentation for your specific operating system on this page:
CGAL - the Computational Geometry Algorithms Library.

Important Note: CGAL 5.6 is the current version of CGAL. We'll need CGAL version 5.3.1 or higher in order to use the current examples and documentation. Older versions use a different CMake build configuration and may be incompatible. As above, you may need to upgrade the version of CGAL manually (downloading and installing from zip or building from source) if the default version offered by the package manager for your OS is not at least 5.3.1.

Additional Notes for installing on MacOS

  • Installation via brew worked ok on MacOS 13.2.1 (Apple M2).

  • To check what version of CGAL you currently have installed on MacOS, type: 

          brew info cgal

  • Which should print something like: 

          cgal: stable 5.6 (bottled)
      Computational Geometry Algorithms Library

  • Note: If you see warning messages when it is installing qt@5, you may have both qt and qt@5 installed. You may need to uninstall qt: 

          brew uninstall qt

Additional Notes for installing on Linux

NOTE: Your help updating the Linux specific instructions is welcome on the Discussion Forum.

  • To check what version of CGAL you currently have installed on Linux, type: 

          dpkg -l libcgal-dev

    Which should output something similar to: 

          Desired=Unknown/Install/Remove/Purge/Hold
      | Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
      |/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
      ||/ Name              Version      Architecture Description
      +++-=================-============-============-==========================================================
      ii  libcgal-dev:amd64 5.4-1        amd64        C++ library for computational geometry (development files)

Additional Notes for installing on Windows

NOTE: Your help updating the Windows specific instructions is welcome on the Discussion Forum.

  • The instructions assume you have already downloaded and installed a Visual Studio compiler for C++.

    It is free to download the "Visual Studio Community 2022 IDE" and specify you will be doing "Desktop Development with C++"

    We do not recommend you attempt installation in a partially emulated environment like Cygwin or WSL - Windows Subsystem for Linux - Ubuntu on Windows.

  • Make a directory for this class, we'll assume it's called YOUR_DIRECTORY_FOR_CLASS.

    NOTE: We recommend that you not have any spaces in the full path name. Some students have encountered bugs in the installation process if this path included a space.

    Go to a "Visual Studio x64 Native Tools" command shell. Note: Don't use a WSL or Cygwin terminal. Don't use a simple CMD shell. Don't use a cross compile shell.

    Type these commands: 

          cd YOUR_DIRECTORY_FOR_CLASS
      git clone https://github.com/microsoft/vcpkg
      cd vcpkg
      .\bootstrap-vcpkg.bat
      .\vcpkg.exe install yasm-tool:x86-windows
      .\vcpkg.exe install cgal:x64-windows
      .\vcpkg.exe install [cgal]qt5:x64-windows --recurse

    Optional: use this command to install all of qt5 (will take longer): 

          .\vcpkg.exe install qt5:x64-windows

    Alternatively: uses these commands to install the 32 bit versions: 

          .\vcpkg.exe install cgal
      .\vcpkg.exe install [cgal]qt5 --recurse

  • To check what version of CGAL you currently have installed on Windows, use Windows explorer file search to locate a file named CGALConfigVersion.cmake. The path may be: 

          YOUR_DIRECTORY_FOR_CLASS/vcpkg/installed/x64-windows/share/cgal/CGALConfigVersion.cmake

    View the contents of that file, it should specify the version at the top, for example: 

          set(CGAL_MAJOR_VERSION 5)
      set(CGAL_MINOR_VERSION 3)
      set(CGAL_BUGFIX_VERSION 1)

Download and run the CGAL examples & demos

  • Download the CGAL Examples and Demos from: https://github.com/CGAL/cgal/releases/download/v5.6/CGAL-5.6-examples.tar.xz

    Untar these files and save them on your computer in your class directory, which we assume is named YOUR_DIRECTORY_FOR_CLASS.

  • Locate the example or demo you wish to run. Note, most (but not all!) of the 'examples' use CGAL but not Qt, and most of the 'demos' use both CGAL and Qt. Below we will target the Polygon example, specifically the draw_polygon example, which uses both CGAL and Qt. Compiling and running other examples and demos and your homework for this course should use the same workflow.

  • Note: In the examples below we will create and use a separate build directory for configuring (using CMake) and building the program (running the compiler). This process creates alot of temporary files (CmakeCache.txt, cmake_install.cmake, etc.) and directories (CMakeFiles, etc.), so it's good to keep this clutter separated from your source code. We could have src and build directories next to each other (what we did in the Advanced Computer Graphics course). Or we could just have a build directory inside of the source code directory (what we will suggest below).

    Separating the source code from the compilation/build directory is also a good software development strategy for version control (e.g. git). You should generally only "check in" your source code in the src or parent directory and do not check in any OS/platform-specific compilation files in the build. To do a clean build from scratch (necessary if you are modifying the installation or configuration) you can simply delete and recreate the build subdirectory.

Instructions for building & running on MacOS or Linux

  • Open up a terminal/shell and cd into the directory for the desired example or demo. Type: 

          cd YOUR_DIRECTORY_FOR_CLASS/CGAL-5.6/examples/Polygon
      ls

    Confirm that you see the CMakeLists.txt and source code for this example in this directory.

  • Make a build directory for the configuration and build files.... 

          mkdir build
      cd build

  • Then run CMake giving it the relative path to the source code directory. In this workflow, just the parent directory .. For example: 

          cmake ..

    If that does not sucessfully configure the project, you may need to specify the full path to Qt. For example: 

          cmake -DQt5_DIR=/usr/local/opt/qt5/lib/cmake/Qt5 ..

  • Now build the program: 

          make

    Your executable will be in the current directory. Confirm you see it by typing ls.

  • Run the program, and pass arguments and data files from other directories as necessary. 

          ./draw_polygon

Instructions for building & running on Windows

NOTE: Your help updating the Windows specific instructions is welcome on the Discussion Forum.

  • Go to a "Visual Studio x64 Native Tools" command shell and type: 

          cd MY_CLASS_DIRECTORY_PATH\CGAL-5.6\examples\Polygon
      dir

    Confirm that you are inside of the directory with the source code for a specific example. You should see a file named CMakeLists.txt. You should also see some source code and maybe input files or subdirectories, depending on the example.

  • Let's make a build directory where the various cmake configuration, cache, and compilation files will be generated. We'll do compilation in that subdirectory and point at the parent directory which contains the CMakeLists.txt file and the source code. 

          mkdir build
      cd build

  • Then configure cmake, passing in the parent directory .., which contains the source code and type: NOTE: Replace "Visual Studio 17" (a.k.a. 2022) with your actual version if you have something else. 

          cmake -G"Visual Studio 17" -A x64 -DCMAKE_TOOLCHAIN_FILE=YOUR_SPECIFIC_CLASS_DIRECTORY_PATH/vcpkg/scripts/buildsystems/vcpkg.cmake ..

    Alternatively: to build the 32 bit version (omitting the -A x64 option) 

          cmake -G"Visual Studio 17" -DCMAKE_TOOLCHAIN_FILE=YOUR_SPECIFIC_CLASS_DIRECTORY_PATH/vcpkg/scripts/buildsystems/vcpkg.cmake ..

    NOTE: If you have an error about not being able to find FindCGAL.cmake.
    Use Windows file explorer to find the location of the FindCGAL.cmake and then specify the location of that file using the -CGAL_DIR option. If you are compiling for 64 bit, make sure that file path includes x64-windows. Or if you are compiling for 32 bit, make sure that file path includes x86-windows. For example: 

          cmake -G"Visual Studio 17" -DCMAKE_TOOLCHAIN_FILE=YOUR_SPECIFIC_CLASS_DIRECTORY_PATH/vcpkg/scripts/buildsystems/vcpkg.cmake -DCGAL_DIR="YOUR_SPECIFIC_DIRECTORY_PATH\cvpkg\installed\x86-windows\share\cgal" ..

  • Make or build the program: 

          cmake --build .

  • And then finally, run the program: 

          Debug\draw_polygon.exe