# 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](https://visualstudiomagazine.com/articles/2023/08/30/vs-for-mac-retirement.aspx)
\*\* On Linux the support of Code - OSS and VSCodium isn't guaranteed
## Cloning the Template Project
Open your terminal and enter the following commands:
```shell
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 <your@email.com> # 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](#Visual-Studio)
* [CLion](#CLion)
* [VSCode](#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](#Editing-CMakeListstxt)
## 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](https://www.jetbrains.com/community/education/#students)
### 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](#Editing-CMakeListstxt)
## VSCode
Install a C/C++ compiler and CMake on your respective systems
Install the following extensions
* [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
* [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-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](https://hackmd.io/@OOP2023f/H1hB55R0n).
> Don't use the [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) 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 <kbd>Shift</kbd> + <kbd>F5</kbd> 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-CMakeListstxt)
## 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`.
```diff
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)
:::danger
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:
```bash
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`
Sign in with Wallet
Connect another wallet