INSTALL

Installation Instructions
*************************

Linux
*****

Install required packages:

$ sudo apt install -y git cmake make build-essential libgl1-mesa-dev freeglut3-dev libpugixml-dev libjsoncpp-dev libboost-test-dev libboost-timer-dev qtbase5-dev qtbase5-dev-tools

Additional packages that you may need, depending on selected cmake options:
$ sudo apt install -y libboost-log-dev libboost-program-options-dev libboost-iostreams-dev libspdlog-dev libfmt-dev

Git
***

The gotools module points to a repository on GitHub:
https://github.com/SINTEF-Geometry/GoTools.git.

GoTools contains three submodules (on GitHub):
GoTools-Data: https://github.com/SINTEF-Geometry/GoTools-Data.git,
SISL: https://github.com/SINTEF-Geometry/SISL.git, and
TTL: https://github.com/SINTEF-Geometry/TTL.git.

To clone the GoTools module, run:

$ git clone https://github.com/SINTEF-Geometry/GoTools.git

Alternatively use ssh:

$ git clone git@github.com:SINTEF-Geometry/GoTools.git

Change to the source directory:

$ cd GoTools

Initialize the submodules:

$ git submodule update --init --recursive

The branch 'master' is the only branch. Any releases will be available as tags.

CMake
*****

This GoTools package uses CMake to generate a Makefile (on Linux and macOS) or MS Visual Studio
project file (on Windows).

Make a build directory in the source directory (or somewhere else):

$ mkdir build
$ cd build

Use cmake to configure (or ccmake for a gui-like experience), enabling OpenMP, referencing the
source folder:

$ cmake -DCMAKE_BUILD_TYPE=Release -DGoTools_ENABLE_OPENMP=ON ..

Build in parallel mode:

$ make -j$(nproc)

Install the project to system directories:

$ sudo make install

Compilers
*********

The code uses certain features of the C++ standard C++14. On Linux this should be compatible with
gcc 5.0 and newer. On Windows this should be compatible with Visual Studio 2019 and newer.

A set of options to control the build can be accessed in CMake (names starting with 'GoTools'). For
example, you can turn on/off building the various modules by checking/unchecking
GoTools_COMPILE_MODULE_<modulename>.

Windows
*********

The code has been tested using Visual Studio 2015, 2019 and 2022, with x64.

Make sure that your installment of Visual Studio includes support for Visual C++. When installing
Visual Studio you should select "Desktop development with C++" from the Workloads options. If you
did not do that then you must launch the Visual Studio installer and select "Modify", then select
"Desktop development with C++". Follow further instructions.

Note that Visual Studio introduced binary compatibility in Visual Studio 2015, allowing the user to
mix binaries built by the VS toolsets v140, v141, v142 and v143 (Visual Studio 2015 and later, with
some specific restrictions). The linker must use a toolset at least as recent as the newest toolset
used by the binaries.

How to edit environment variables:
- Open the settings application.
- Search for env, select: "Edit the system environment variables" (or "Edit environment variables
  for your account" to add them to your user only).

Boost:
- Download a binary release for your Visual Studio version.
- To help CMake find the boost install folder the BOOST_ROOT variable must be added to the system
  environment variables. This refers to the top level Boost folder (for instance 'C:\boost_1_74_0'),
  which contains both the 'boost' directory with the header files, as well as the folder with the
  Visual Studio binary libraries (like 'lib64-msvc-14.2').
- If you have multiple Visual Studio versions installed then all the corresponding binary library
  directories from the same Boost version should recide in the same BOOST_ROOT folder. CMake will
  pick the correct binaries.

Qt:
- Download a binary release for your Visual Studio version.
- To help CMake find the Qt install folder the QTDIR variable must be added to the system
  environment variables. This variable should point to the binary library directory, for instance
  'C:\Qt\5.15.2\msvc2019_64'.
- If you have more than one version of Visual Studio installed this variable may need to be changed
  accordingly if you switch to another version of Visual Studio. CMake must then be restarted and
  the cache deleted. Note that binary compatibility may deem this step unnecessary.
- You must also add the variable QT_QPA_PLATFORM_PLUGIN_PATH to the system environment
  variables. This variable refers to the platform plugins and is set to
  '${QTDIR}\plugins\platforms'. Starting from a clean build the build process must be run twice in
  order to create the necessary Qt files.

PugiXML & JsonCpp:
- Both these libraries must be built from source (using cmake and Visual Studio). Fetch the source
  files from:
  - PugiXML: pugixml.org
  - JsonCpp: github.com/open-source-parsers/jsoncpp
- Make sure that the cmake generator uses the correct version of Visual Studio and that the platform
  is set to x64.
- The include files and the built libraries may be set manually in CMake. A smoother approach is to
  adopt the convention that the include files are placed in the '~/Install/include/pugi' folder
  (replace with json for the json include files), while the library files are placed in the
  '~/Install/msvc2019_lib64/Release' folder (use Debug for the debug version of the libraries,
  change to msvc2015 for Visual Studio 2015).

OpenGL:
- If cmake does not find the gl.h and glu.h files they may be copied to the '~/Install/include/GL'
  folder. If you are using Visual Studio and selected the C++ workload option in the installer then
  the files should be located in a subfolder of "C:/Program Files (x86)/Windows Kits".

- For computers without working OpenGL drivers (typically the case for virtual machines) MESA may be
  used (software rendering). In the folder with the application there is a library named
  'opengl32sw.dll'. This library should be copied and renamed to 'opengl32.dll', which will then be
  used by the application.

FreeGLUT:
- Compilation of the sisl viewer requires freeglut. Compilation of the app is off by default.
- Freeglut may be downloaded and built using Visual Studio:
  https://github.com/FreeGLUTProject/freeglut
- The include and library files should be placed in locations in the same manner as for PugiXML &
  JsonCpp.

spdlog:
- Enabling logging requires spdlog. Off by default. When disabled all the log messages are written
  to cerr.
- spdlog may be downloaded and built using Visual Studio:
  https://github.com/gabime/spdlog
- The include and library files should be placed in locations in the same manner as for PugiXML &
  JsonCpp.

CMake:
- In order to run the testst you should add $CMAKE_DIR/bin to the PATH, allowing ctest.exe to be
  found.
- On Windows 10 the HOME variable is not set. This is needed by the cmake setup. Add HOME to the
  user environment variables, pointing to the home directory (typically 'C:\Users\<username>').
- For 64 bit applications using Visual Studio 2015 you should make sure to choose x64 when
  generating the solution using cmake-gui (default is x86).
- Optionally you may run cmake from the command line, in this example using Visual Studio 2019 on
  an Intel/AMD 64-bit system:
  $ mkdir build_msvc2019
  $ cd build_msvc2019
  $ cmake ../ -G "Visual Studio 16 2019" -A x64

Build the project in Release mode from the build folder (replace with 'Debug' for building in debug
mode):
$ cmake --build . --config Release --parallel

Install using gsudo/sudo (or run in a shell with administrator privileges):
$ gsudo cmake --install .

Building the gotools Visual Studio solution:
- Open the gotools Visual Studio solution file that was generated by cmake. Choose either Release or
  Debug, build the solution by pressing 'F7'.

Running the tests from a shell (like Git Bash):
- Run the tests in default (release) mode:
  $ ctest
- Run the tests in parallel:
  $ ctest -j ${NUMBER_OF_PROCESSORS}
- Run the tests in debug mode:
  $ ctest -C debug
- Run only the acceptance tests (use unit or integration for the other test types, using a unique
  substring like 'cep' will also work):
  $ ctest -L acceptance


MacOS
*********

Although we do not provide official support for MacOS, GoTools should nonetheless compile without
issues. It has been tested on MacBook Pro (M1 Max with ARM64) running MacOS Monterey 12.0.1, using
the CLion IDE (version 2021.2.3). It should compile using other IDEs (like XCode) without any
issues.

Install command line build tools:
$ xcode-select --install

We recommend using Homebrew to install the dependencies:
https://brew.sh

All dependencies may then be installed from the command line:

$ brew install pugixml
$ brew install boost
$ brew install qt5
$ brew install jsoncpp

The following environment variables should be set (for instance in your .bashrc file if you are
using bash):
- QTDIR should be set to the base qt folder containing the bin and lib dirs, typically
  /opt/homebrew/opt/qt5/.
- BOOST_ROOT should be set to the directory containing the boost include and lib directories,
  typically /opt/homebrew/opt/boost/.

OpenMP is not natively supported by Apple clang (version 15.0.0). It may however be enabled by
installing the LLVM OpenMP library:
$ brew install libomp

Set the following environment variables (add to .bashrc if you are using bash):
export CC=/usr/bin/clang
export CXX=/usr/bin/clang++
export CPPFLAGS="$CPPFLAGS -Xpreprocessor -fopenmp"
export CFLAGS="$CFLAGS -I/opt/homebrew/opt/libomp/include"
export CXXFLAGS="$CXXFLAGS -I/opt/homebrew/opt/libomp/include"
export LDFLAGS="$LDFLAGS -Wl,-rpath,/opt/homebrew/opt/libomp/lib -L/opt/homebrew/opt/libomp/lib -lomp"

Logging and shared builds are not supported on MacOS.

Command line steps for configuring, building and installing:
$ mkdir build_release
$ cd build_release
$ cmake ../ -G Ninja
$ cmake --build .
$ sudo cmake --install .