C++ Starter Project for CSE100.

This is a C++ starter project for CSE100. There are two ways of working on the PAs for this class:

1. Use the ieng6 lab machines.
2. Use a devcontainer on your own computer.

ℹ️ You can find a cheatsheet of CMake commands are listed in CMAKE_COMMANDS_CHEATSHEET.md

Getting Started with ieng6

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:

1. Connect to ieng6 (skip this step if you are physically working on a lab machine) 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:

ssh <your_cse_100_account>@ieng6.ucsd.edu

For windows users, we encourage you to use the super convenient tool MobaXterm.

2. Get the starter code 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:

git clone <the-url-provided-in-the-writeup>

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.

3. Compiling your code Go into the root directory of your project:

cd <name-of-the-project-directory>

To compile your code run

mkdir -p build && cd build && cmake ..
make

More information on CMake and Makefile is provided further below in this README.

4. Running executables 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:

./build/test/bst/main.cpp.executable data/actors.txt data/queryActors.txt

5. Running unit tests To run your unit tests, in your project root directory, run

mkdir -p build && cd build && cmake ..
make test 

More information about testing is provided further below in this README.

Getting Started with the Devcontainer

• ⚠️NOTE: Windows users, when installing Docker it may ask you if you want to configure it for running Windows containers or Linux containers. Choose Linux containers.
• ⚠️NOTE: Windows users, if you are running Windows Home edition, first read the note below the next item!
• Download and install Docker Desktop: https://www.docker.com/products/docker-desktop
  • ⚠️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/
• Make sure docker is running
• Download and install VSCode
• Open VSCode, click the "Extensions" icon on the left and install the "Remote Development" extension by Microsoft
• Open this project in VSCode
• There will be a popup asking if you want to open it in a devcontainer:
• Click "Reopen in Container"
• If you don't see the popup, you can also open the devcontainer with a command.
  • open the Command Palette in VSCode: ctrl+shift+p (cmd+shift+p on mac)
  • type "reopen" and hit enter
• The first time you are opening the devcontainer it will take a couple of minutes to install. But if you reopen it again at a later moment it should only take a matter of seconds.
• Once the devcontainer is up and running you'll see the files in your project reappear on the left
• Open bash in the VSCode Terminal tab:
  • ℹ️If you don't see a TERMINAL tab in the bottom panel of your screen, hit ctrl+`
  • ℹ️If you don't see a "Bash" option in the dropdown, click the plus icon to the right of the dropdown
• Cool, now you are fully set up to begin developing on the project!

Building (Compiling And Running Executables)

• This project uses the cmake build system along with make. In short, cmake is comparable to meson, it helps you configure your build. And make is comparable to ninja, which helps you actually build your binaries.
• To initialize the build setup using cmake run: mkdir -p build && cd build && cmake .. in the terminal.
• A folder with the name "build" has now appeared in your project and you should be in this folder right now (but no executables have been built yet)
• To compile all the executables type: make in build folder.
• To compile a single executable after build setup, type: make followed by the name of the executable. For instance, to compile main in bst folder, type make compress.cpp.executable in build folder.
• All the executables are under ./build/src/. All test executables are under ./build/test/. For instance, to run the main executable in bst folder, type: ./build/src/compress.cpp.executable in project root folder.
• (Take a look at the CMakeLists.txt files in the project root, src and test directories to understand how the build process works.)

Testing

The command to run the unit tests (files with test_ prefix in test folder):

• make test in build folder

Other than unit tests, there are also testing executables compiled using your code (like main.cpp.executable).

• Compiling a single testing executable
  • make test_HCTree.cpp.executable in build folder

If you have already compiled testing executable, you can run it like so: ./build/test/path/file-name.cpp.executable

GoogleTest

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. In this assignment, each file in src folder has a corrsponding test file in the test folder with prefix test_. To write a test, use the TEST macro:

TEST(SuiteName, TestName) {
    // Test code goes here
}

The GoogleTest framework uses assertions to determine whether a test has passed or failed. For instance, here are some of the assertions available:

• 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).
• ASSERT_NE(val1, val2) - Fails the test if the two values are the same.
• ASSERT_GT(val1, val2) - Fails the test if val1 <= val2.
• ASSERT_GE(val1, val2) - Fails the test if val1 < val2
• ASSERT_LT(val1, val2) - Fails the test if val1 >= val2
• ASSERT_LE(val1, val2) - Fails the test if val1 > val2

You can learn more about writing tests from the GoogleTest documentation.

Optional: If you want to add a new C++ file with tests, you will also have to update the corresponding CMakeLists.txt file. As you can see below, for test_HCTree.cpp we have to first define an executable, and then define a test that runs this executable.

add_executable (test_HCTree.cpp.executable test_HCTree.cpp)
target_link_libraries(test_HCTree.cpp.executable PRIVATE gtest_main huffman_encoder)
add_test(test_HCTree test_HCTree.cpp.executable)

Code Coverage

Calculating code coverage is a way of measuring the quality of your test suite. A code coverage report shows the lines of code that were executed by your tests. 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.

You can generate a code coverage report of your tests by running: make cov in build folder The coverage report should appear under build/code_coverage/report/. You can open index.html in your browser to see the full report.

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.

Tools for Code Quality

This project includes numerous tools that can help you make sure that the quality of your code is on par.

Auto Formatting

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. On ieng6, you'll have to run clang-format yourself.

To run clang-format on the entire project run: make format in build folder

Static Analysis

Static analysis tools parse your source code for possible causes of bugs and violations of code style rules. They will notify you of suspicious looking code that may have a bug in it.

This project supports the following 2 static analyzers:

• make cppcheck in build folder
• make scan-build in build folder

Dynamic Analysis

Dynamic analysis tools do not parse the source code, but execute the compiled files. This project supports Valgrind.

• valgrind build/test/bst/test_BST.cpp.executable

Debugging

Both the devcontainer and ieng6 come with gdb installed and by default all source files are compiled with debugging support enabled.

You can run gdb like this: gdb build/test/bst/test_BST.cpp.executable

Try debugging main and then try debugging a test.

Debugging in the devcontainer

In the devcontainer we've also included 2 debugging tasks in the VSCode setup. Click the debug window icon on the left or use the short cut ctrl+shift+d (cmd+shift+d on mac). You can see the following debug tasks:

You can run the debug task by clicking the green play icon.

Alternatively, you can press F5 to run the currently selected debug task.

⚠️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 mkdir -p build && cd build && cmake .. and make. ⚠️NOTE: The "debug active file" task will not work if your active file does not have a cmake configuration to be compiled to an executable. In case of an error look at the corresponding CMakeLists.txt to make sure that the file you are trying to debug is being compiled into an executable.

You can create breakpoints by clicking left of the line numbers in VSCode.