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. 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. Use the Google 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.
The instructor needed to manually upgrade to CMake 3.20.2 on Ubuntu 18.04 Linux and CMake 3.22.1 on MacOS 11.5. CMake 3.15.x was sufficient on Windows.

To check what version you currently have installed, type:
```
      cmake --version
    
```
Note: 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 CGAL & Qt5

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

Important Note: We'll need CGAL version 5.3.1 in order to use the current examples and documentation. Older versions use a different CMake build configuration and are 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 5.3.1.

Additional Notes for installing on MacOS

Installation via brew worked ok on MacOS 11.5.
To check what version of CGAL you currently have installed on MacOS, type:
```
      brew info cgal
    
```

Which should print something like:

      cgal: stable 5.3.1 (bottled)
      Computational Geometry Algorithms Library

Additional Notes for installing on Linux

To check what version of CGAL you currently have installed on Linux, type:
```
      locate CGALConfigVersion.cmake 
    
```
Which should return one or more paths to a file with that name. For example:
```
      /usr/local/lib/cmake/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)
    
```

Additional Notes for installing on Windows

The instructions assume you have already downloaded and installed a Visual Studio compiler for 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
    
```
Note, at this point we get an error: "only supported on 'native & !uwp'".
Edit the file vcpkg/ports/yasm-tool/vcpkg.json to remove native &
Now you'll re-run that last command:

    .\vcpkg.exe install yasm-tool:x86-windows

Then continue with these commands:

      .\vcpkg.exe install cgal:x64-windows
      .\vcpkg.exe install cgal[qt]:x64-windows --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.3.1/CGAL-5.3.1-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.3.1/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

Go to a "Visual Studio x64 Native Tools" command shell and type:
```
      cd MY_CLASS_DIRECTORY_PATH\CGAL-5.3.1\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 16" (a.k.a. 2019) with your actual version if you have something else.
```
      cmake -G"Visual Studio 16" -A x64 -DCMAKE_TOOLCHAIN_FILE=YOUR_SPECIFIC_CLASS_DIRECTORY_PATH/vcpkg/scripts/buildsystems/vcpkg.cmake ..
    
```
Make or build the program:
```
      cmake --build .
    
```
And then finally, run the program:
```
      Debug\draw_polygon.exe
    
```