You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`meson build`| generate the `build` directory which holds all generated files such as executables |
4
+
|`rm -rf build && meson build`| remove and regenerate the `build` directory |
5
+
|`ninja -C build`| compile all executables (`-C build` tells ninja to first go into the build directory) <br> executables can be found under the `build` directory |
6
+
|`ninja -C build test`| compile all executables and run all your tests |
7
+
|`ninja -C build cov`| generate a code coverage report that can be found under `build/meson-logs/coveragereport`|
8
+
|`ninja -C build clang-format`| auto format your code |
9
+
|`ninja -C build cppcheck`| check your code for possible bugs |
10
+
|`ninja -C build clang-tidy`| check your code for possible bugs |
11
+
|`ninja -C build scan-build`| check your code for possible bugs |
12
+
|`meson test -C build --wrapper=valgrind`| analyze all tests for memory leaks |
13
+
|`valgrind build/test/bst/test_BST.cpp.executable`| analyze a single executable for memory leaks |
14
+
|`gdb build/test/bst/test_BST.cpp.executable`| debug a file |
Copy file name to clipboardexpand all lines: README.md
+108-19
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,68 @@
1
1
# C++ Project Template
2
2
This is a C++ project template using the meson build system.
3
+
There are two ways of testing out this project.
3
4
4
-
# Getting Started
5
-
- It is recommended to use a VSCode devcontainer, however if you want to work on the project without a devcontainer, you can find all the required dependencies in: `./devcontainer/Dockerfile` and manually install them on your machine
5
+
1. Use the ieng6 lab machines.
6
+
2. Use a devcontainer on your own computer.
7
+
8
+
ℹ️ You can find a cheatsheet of important commands in [COMMANDS_CHEATSHEET.md](COMMANDS_CHEATSHEET.md)
9
+
10
+
## Getting Started with ieng6
11
+
If you don’t want to setup a devcontainer on your machine, you have the option to remotely connect to the lab machines (a.k.a. ieng6) using ssh or physically work in the lab. No additional setup is necessary for you to do, as the lab computers are already equipped with all the tools that you need to work on your PA. The only major difference is, however, that you will not be able to use VSCode to write your code - you will have to use VIM (like you did in CSE 30) to write your code and use commands on the terminal to compile and run your program. Here’s a step by step guide for you to get started:
12
+
13
+
**1. Connect to ieng6** (skip this step if you are physically working on a lab machine)
14
+
If you’re on a Mac, you can open a terminal and use the command below and enter your password when prompted to connect to ieng6:
15
+
16
+
`ssh <your_cse_100_account>@ieng6.ucsd.edu`
17
+
18
+
For windows users, we encourage you to use the super convenient tool MobaXterm.
19
+
20
+
**2. Get the starter code**
21
+
This step is given to you on the write-up, but in summary, you have to clone the starter code repository by running the command below and enter your github username and password when prompted:
22
+
23
+
`git clone <the-url-provided-in-the-writeup>`
24
+
25
+
26
+
Everything from this point on is the same as what you would do if you were working in a devcontainer, but here’s a concise guide to compiling and running your code.
27
+
28
+
**3. Compiling your code**
29
+
Go into the root directory of your project:
30
+
31
+
`cd <sander, please put the name of the repo>`
32
+
33
+
To compile your code run
34
+
35
+
```
36
+
meson build
37
+
ninja -C build test
38
+
```
39
+
40
+
More information on meson and ninja is provided further below in this README.
41
+
42
+
**4. Running executables**
43
+
If you run ls now after compiling, you’d see there is a new directory called `build`. This directory contains the compiled binary executables that you can run. For example, to run main.cpp from the BST portion of the assignment, run the command below from the root folder of your project:
44
+
45
+
`./build/test/my-gtest/my-gtest.cpp.executable`
46
+
47
+
**5. Running unit tests**
48
+
To run your unit tests, in your project root directory, run
49
+
50
+
```
51
+
meson build
52
+
ninja -C build test
53
+
```
54
+
55
+
More information about testing is provided further below in this README.
56
+
57
+
58
+
## Getting Started with the Devcontainer
59
+
- ⚠️NOTE: Windows users, if you are running Windows Home edition, first read the note below the next item!
6
60
- Download and install Docker Desktop: https://www.docker.com/products/docker-desktop
7
61
- ⚠️NOTE: Docker Desktop for Windows requires the Hyper-V Windows feature which is not available on Home-edition. If you are running Windows Home-edition, install Docker Toolbox instead: https://docs.docker.com/toolbox/toolbox_install_windows/
8
62
- Make sure docker is running
9
63
- Download and install VSCode
64
+
- Open VSCode, click the "Extensions" icon on the left and install the "Remote Development" extension by Microsoft
65
+
![Remote Development Extension](images/install-remote-development-extension.png"Remote Development Extension")
10
66
- Open this project in VSCode
11
67
- There will be a popup asking if you want to open it in a devcontainer:
@@ -22,12 +78,14 @@ This is a C++ project template using the meson build system.
22
78
- ℹ️If you don't see a TERMINAL tab in the bottom panel of your screen, hit ``ctrl+` ``
23
79
- Cool, now you are fully set up to begin developing on the project!
24
80
25
-
# Building
81
+
# Building (Compiling And Running Executables)
82
+
- This project uses the `meson` build system along with `ninja`. In short, `meson` is comparable to `cmake`, it helps you configure your build. And `ninja` is comparable to `make`, which helps you actually build your binaries. `Ninja` uses the file called `compile_commands.json` in the build directory generated by `meson` to find out how to build your binaries. You can find more information on `meson` here: https://mesonbuild.com/
26
83
- To initialize the build setup using meson run: `meson build` in the terminal.
27
-
- A folder with the name "build" has now appeared in your project, but no binaries have been built yet
28
-
- To build the binaries run: `ninja -C build`
29
-
- Now you can run the main file: `./build/src/main.cpp.executable`
30
-
- Take a look at the `meson.build` files in the project root, src and test directories to understand how the build process works.
84
+
- A folder with the name "build" has now appeared in your project (but no executables have been built yet)
85
+
- To compile all the executables type: `ninja -C build` (`-C build` means we're first going into the `build` directory before running any of the ninja commands)
86
+
- To compile a single executable after build setup, type: `ninja -C build` followed by the path of the executable. For instance, to compile main in bst folder, type `ninja -C build test/my-gtest/my-gtest.cpp.executable`
87
+
- All the executables are under `./build/test/`. For instance, to run the main executable in bst folder, type: `./build/test/my-gtest/my-gtest.cpp.executable`
88
+
- (Take a look at the `meson.build` files in the project root, src and test directories to understand how the build process works.)
31
89
32
90
# Testing
33
91
There are 2 ways of running the tests:
@@ -45,24 +103,52 @@ Both of these commands have their own special use cases:
45
103
If you have already compiled the tests you can of course also run a specific test like so: `./build/test/math/math-test.cpp.executable`
46
104
47
105
## GoogleTest
48
-
The project includes the GoogleTest testing framework, look at `my-gtest` for an example.
49
-
GoogleTest documentation can be found here: https://github.com/google/googletest/blob/master/googletest/docs/primer.md
106
+
The GoogleTest framework allows you write atomic tests for your code without calling that test in a main or fitting it into your existing set of tests.
107
+
Look at `my-gtest` for an example.
108
+
109
+
To write a test, use the `TEST` macro:
110
+
```cpp
111
+
TEST(SuiteName, TestName) {
112
+
// Test code goes here
113
+
}
114
+
```
115
+
116
+
The GoogleTest framework uses assertions to determine whether a test has passed or failed. For instance, here are some of the assertions available:
117
+
118
+
- `ASSERT_EQ(val1, val2)` - Fails the test if the two values are not the same (note: this uses the `==` operator, so for pointers, it looks for pointer equality instead of equality between the two underlying objects).
119
+
- `ASSERT_NE(val1, val2)` - Fails the test if the two values are the same.
120
+
- `ASSERT_GT(val1, val2)` - Fails the test if `val1 <= val2`.
121
+
- `ASSERT_GE(val1, val2)` - Fails the test if `val1 < val2`
122
+
- `ASSERT_LT(val1, val2)` - Fails the test if `val1 >= val2`
123
+
- `ASSERT_LE(val1, val2)` - Fails the test if `val1 > val2`
124
+
125
+
You can learn more about writing tests from the [GoogleTest documentation](https://github.com/google/googletest/blob/master/googletest/docs/primer.md).
50
126
51
127
## Code Coverage
128
+
Calculating code coverage is a way of measuring the quality of your test suite.
129
+
A code coverage report shows the lines of code that were executed by your tests.
130
+
This will give you insight into the weaknesses in your test suite as you can easily see which lines of code are not yet tested.
131
+
52
132
You can generate a code coverage report of your tests by running:
53
133
`ninja -C build cov`
54
-
The coverage report should appear under `build/meson-logs`. You can open `index.html` in your browser for details.
134
+
The coverage report should appear under `build/meson-logs/coveragereport`. You can open `index.html` in your browser to see the full report.
55
135
56
-
# Code Quality
57
-
This project includes numerous tools that can help you make sure that the quality of the code is on par.
136
+
If you are ssh'd into ieng6, you will need to download the coverage report to your computer first before you can open it in a browser.
137
+
138
+
# Tools for Code Quality
139
+
This project includes numerous tools that can help you make sure that the quality of your code is on par.
58
140
59
141
## Auto Formatting
60
-
You may already have noticed that the code gets autoformatted when you save. This project is using `clang-format` to achieve that.
142
+
If you're working in a devcontainer, you may already have noticed that the code gets autoformatted when you save. This project is using `clang-format` to achieve that.
143
+
On ieng6, you'll have to run `clang-format` yourself.
144
+
61
145
To run `clang-format` on the entire project run:
62
146
`ninja -C build clang-format`
63
147
64
148
## Static Analysis
65
149
Static analysis tools parse your source code for possible causes of bugs and violations of code style rules.
150
+
They will notify you of suspicious looking code that may have a bug in it.
151
+
66
152
This project supports the following 3 static analyzers:
67
153
- `ninja -C build cppcheck`
68
154
- `ninja -C build clang-tidy`
@@ -74,8 +160,14 @@ Dynamic analysis tools do not parse the source code, but execute the compiled fi
74
160
- `valgrind build/src/main.cpp.executable`
75
161
76
162
# Debugging
77
-
The devcontainer comes with gdb installed and by default all source files are compiled with debugging support enabled.
78
-
To make life easier for you we've included 2 debugging tasks in the VSCode setup.
163
+
Both the devcontainer and ieng6 come with gdb installed and by default all source files are compiled with debugging support enabled.
164
+
165
+
You can run gdb like this: `gdb build/src/main.cpp.executable`
166
+
167
+
Try debugging main and then try debugging a test.
168
+
169
+
## Debugging in the devcontainer
170
+
In the devcontainer we've also included 2 debugging tasks in the VSCode setup.
79
171
Click the debug window icon on the left or use the short cut ctrl+shift+d (cmd+shift+d on mac).
80
172
You can see the following debug tasks:
81
173
@@ -84,10 +176,7 @@ You can run the debug task by clicking the green play icon.
84
176
85
177
Alternatively, you can press F5 to run the currently selected debug task.
86
178
179
+
⚠️NOTE: In case of an error when running a debug task the first thing to try is usually to delete your build dir and generate it again using `meson build` and `ninja -C build`.
87
180
⚠️NOTE: The "debug active file" task will not work if your active file does not have a meson configuration to be compiled to an executable. In case of an error look at the corresponding `build.meson` to make sure that the file you are trying to debug is being compiled into an executable.
88
181
89
182
You can create breakpoints by clicking left of the line numbers in VSCode.
90
-
91
-
Try debugging main and then try debugging a test.
92
-
93
-
You can also run gdb manually if you prefer that: `gdb build/src/main.cpp.executable`
0 commit comments