MacOS Setup

System setup

These steps need to be done only once on a given computer.

You system will need the following elements:

- A C++ compiler (clang), and compilation tools including pkg-config
- CMake

You may also want to install Visual Studio Code to edit your code if you haven't it yet.

Check that g++/clang++ is installed in typing in command line

g++ -v

And follow the installation instruction if the OS proposes to install it. (You may have to install XCode if you get an error mentioning it.)

For the other dependencies (cmake, GLFW library), the easiest way is to use a package manager such as HomeBrew.

To install Homebrew, follow the instructions of the website, and then check with brew -v.

Once Homebrew is installed, the dependencies can be installed using these instructions

# CMake tool to compile
brew install cmake

# Install pkg-config - tool helping to find library for compilation
brew install pkg-config

# Install ninja - a compilation chain tool
brew install ninja

# Install glfw - the window handler used as external library
brew install glfw

Once GLFW is install, you may have to explicitly add its path with the following two lines to be added in the file .zshrc in your home directory

export CPATH=/opt/homebrew/include
export LIBRARY_PATH=/opt/homebrew/lib

First compilation

The following instructions need to be done in full once per projet, or/and when a given project is moved from one machine to another.

Open a command line in the "root" directory corresponding to a scene.

For instance cgp/examples/example_compilation/

The "root" directory of a scene always contain a premade Makefile and a CMakeLists.txt. You can compile and execute the project using either of them on command line.

Method 1: If you use the provided Makefile

make
#  You can also type make -j for faster compilation in parallel 
#  or make -jN, where N is the fixed number of threads

./example_compilation
# Adapt the executable name to your scene

Note:

- If this method works, it is the simplest one on command line.
- Make is a standard Unix command allowing to automatize some calls efficiently. The Makefile is the file that parameterizes which operations should be done when calling the command "make". In our case, it calls the C++ compiler (g++) on all the sources files.

Method 2: If you use the CMakeLists.txt

# Create a separated directory (avoids "polluting" the root directory)
mkdir build

# Go to the build/ directory
cd build

# Run CMake
cmake ..
# A file Makefile should be generated

# Compile
make
# Make sure the compilation succeed, an executable should be created (ex. example_compilation)
#  You can also type make -j$(nproc) for faster compilation in parallel
#  Or make -j 4 (replace 4 with any number of threads you want)

# Run the executable (adapt the name to your current scene)
./example_compilation

Rem.

- This method requires more steps than using the provided Makefile, but may work on more systems.
- CMake is a high level tool to handle compilation processes for possibly large project. CMake does not compile itself the code, but generate intermediate files such as Makefile on Unix, or Visual Studio projects on Windows. CMake can also be used by IDE to load projects.
- The execution of CMake is parameterized by the file CMakeLists.txt.

Mac Security

In some cases, Mac OS may block the run of the executable saying that "libglfw.3.dylib cannot be opened because the developer cannot be verified".

One way to bypass this issue is to open this file with your file explorer

- Open finder to the path of the file (cgp/library/third_party/precompiled/glfw/macos/lib/)
- Try to open it using CTRL+Click
- Select Open
- Once the file is accepted by the OS, try again to execute the code.

Another way is to tune the "Security & Privacy" options of your OS.

Explanation:

- libglfw.3.dylib is the dynamic library associated to GLFW (the window manager).
- The file is packed with the library so that you don't have to install glfw externally.
- Mac tries to block apps and library that do not come from an officially supported distributor.

Re-compiling after code modification

When the C++ code is modified, a new executable must be compiled again. This compilation simply consists in calling make again (or make -j[N]).

make   # recompile only what is necessary
./example_compilation  # run the new executable

Notes:

- To clear the temporary files generated during the compilation you can type make clean.
- When calling several times "make" on the same project, only the files that need to be recompiled (the one that have been modified) are processed. This allows to save time compare to a complete compilation of all the source files.
- When using CMake, the build/ directory contains only temporary files. This directory can be removed safely and re-generated on demand. This build/ directory is dependant of the machine, and should not be uploaded on a shared repository using git for instance.

IDE for code edition

Beyond the simple compilation and execution of the project, you are highly encouraged to use a complete IDE (Integrated Development Environment) to edit C++ code. Compared to a simple text editor, an IDE will help you to use efficiently a library (such as CGP) in providing auto-completion (for functions/class names, arguments, etc) to naviguate quickly through the files, as well as proposing debug tools.

You may use VS Code with C++ plugins. Make sure to load a project in opening a folder ("File" \(\rightarrow\) "Open Folder) the root directory, and not simply opening a single file. VS Code is a versatile tool usefull for multiple language, but may require some setup to recognize C++ project.

Another good IDE for C++ is QtCreator. QtCreator has the advantage to be able to be specialized for C++ and doesn't require any tuning or plugins to work.
QtCreator can be installed using brew with these instructions

brew cask install qt-creator

Follow these instructions to use QtCreator.