Environment Setup

How to Use this Guide

This guide aims to be a detailed yet simple to follow all-in-one solution for both new and experienced students. As a result, there are lots of screenshots and technical details that you can safely ignore if you don't understand the meaning of it.

You shouldn't blindly copy and paste commands into your terminal, please read this guide carefully before making any changes.

This guide assumes you have read and setup How to Use Git. Proceed if you have already setup GitLab and SSH.

Officially Supported Platforms and Editors

	Windows	macOS	Linux
Visual Studio	v	?*	x
CLion	v	v	v
VSCode	v	v	v**

* Microsoft Kills Visual Studio for Mac
** On Linux the support of Code - OSS and VSCodium isn't guaranteed

Cloning the Template Project

Open your terminal and enter the following commands:

git clone git@140.124.181.133:OOP2023f/template.git OOP2023F
cd OOP2023F
git config user.name <your-name>         # This step is optional
git config user.email <[e-mail]>   # This step is optional
git remote set-url origin <your-gitlab-hw-repo.git>
git push

Some editors also provide a way to do this graphically.

Simplified project layout for reference

.
├── src
│   └── traversal.cpp
├── include
│   └── traversal.hpp
├── test
│   ├── ut_sanity_check.cpp
│   └── ut_traversal.cpp
├── CMakeLists.txt
└── files.cmake

Next, keep following along with the IDE or editor of your choice.

• Visual Studio
• CLion
• VSCode

Visual Studio

The compiler and CMake comes with Visual Studio, so no additional setup is needed.

Visual Studio 2022 or higher is recommended

Compiling & Executing Program

First, click "Continue without code".

On the top left, go to "File -> Open -> CMake…" and navigate to where CMakeLists.txt is located. Make sure to open the CMakeLists.txt file and not the containing folder.

You will be greeted will the following screen:

To run the project, click on the drop-down in the upper center and choose "ut_all.exe" then click on the start button.

The test results will be shown in a separate console pop-up.

To see how to edit files, see here

CLion

The compiler and CMake comes with CLion, so no additional setup is needed.

This is a paid software, but students are eligible for a free license with a school email as long as the student status holds
See more on JetBrains webpage

Compiling & Executing Program

First, "Open".

Navigate to your project location and open it.

The CLion default settings are pretty good so click "OK" to continue.

You will be greeted will the following screen:

To run the project click the "Start" button in the top right. Make sure you have selected the "ut_all" target so every test will be run.

CLion automatically detects and integrates with googletest. The test results will be shown below.

You can click on the "Show Passed" check icon to view all tests including successful ones.

To see how to edit files, see here

VSCode

Install a C/C++ compiler and CMake on your respective systems

Install the following extensions

• CMake Tools
• clangd

Using VSCode w/ Windows is generally not recommended since clangd requires an installation of Visual Studio. If you still want to setup an environment manually, you can install Visual Studio and reference this guide.

Don't use the C/C++ extension by Microsoft as it has worse intellisense and poor integration with other tools listed

Compiling & Executing Program

Opening the folder will trigger CMake Tools to configure the project. Make sure to open the folder containing CMakeLists.txt(i.e. the OOP2023F folder). Some environments will break if this project is not opened at the top level.

When first opening the project, the extension will ask you to select a compiler to use, this can be GCC/MinGW, Clang/LLVM, or MSVC/Visual Studio. Select the one you want to use and the extension will handle the rest of the setup.

If the window somehow doesn't show up you can manually click the "No Kit Selected"(or "No active kit" for some reason) button below

Clicking the "Start" icon in the bottom center, or simply pressing Shift + F5 will build, run the program and show the results in the terminal.

Running the program will show the test results in the terminal.

If you want to see organized test results, click the triangular flask icon on the left bar. Click "Refresh" and "Run Tests" will list all test results found by CMake and googletest

When setting up the project for the first time, it will take awhile depending on your network speed because it will download googletest source files. Later builds won't take as long.

To see how to edit files, see here

Editing CMakeLists.txt

The project folders are categorized into three parts: src, include, and test. After adding a new file, open files.cmake under the root directory. Append your file relative to its parent folder in its respective category. For example, files.cmake should look like the following after adding two files include/Entity.hpp and src/Entity.cpp.

set(SRC_FILES
    ...
+   Entity.cpp
)

set(INCLUDE_FILES
    ...
+   Entity.hpp
)

set(TEST_FILES
    ...
)

Adding incorrect paths would cause CMake configuration to fail so make sure to double-check your filenames and paths.

Setting cmake.automaticReconfigure to true in VSCode settings will make the extension to automatically reload CMake every time CMakeLists.txt or *.cmake files on save.

Terminal or Automated Scripts (Unofficial Support)

Following or completing this section is NOT REQUIRED for this course, proceed at your own risk if you meet any of the following conditions:

1. You aren't familiar with the terminal
2. You haven't heard of or used the tools mentioned below
3. You don't understand what you are reading
4. You are on Windows (sorry, not sorry)
5. You don't want to waste your time

If you encounter issues following this section, feel free to ask questions during TA hours however your problems isn't guaranteed to be fixed.

Install a C/C++ compiler and CMake on your respective systems and cd to the project root directory

Run the following command:

CC=<YOUR_C_COMPILER> CXX=<YOUR_C++_COMPILER> cmake -B <BUILD_DIR>
cmake --build <BUILD_DIR>

Unit Test

cd <BUILD_DIR>
ctest

Memory Leak Check (Linux only with valgrind installed)

cd <BUILD_DIR>
ctest -T memcheck

valgrind is only compatible with Linux and BSD systems

Coverage Test

./scripts/coverage.sh

open ./<BUILD_DIR>/ut_all_coverage/index.html with your preferred browser

gcovr is a Python script so a Python installation is required.
If you are using GCC, make sure gcov is in $PATH.
If you are using Clang, install LLVM and make sure llvm-cov is in $PATH.
The --coverage compile flag doesn't work on MSVC.

Additional Tips & Tricks

For other editors with LSP support(e.g. Neovim) to work with this project, clangd is required

During setup use ... cmake -B <BUILD_DIR> ... -DCMAKE_COMPILE_COMMANDS=ON