search

jal347 / cse100pa4

0 stars 0 forks source link

readme

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 important commands in 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

meson build
ninja -C build test

More information on meson and ninja 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

meson build
ninja -C build test

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

Getting Started with the Devcontainer

Building (Compiling And Running Executables)

Testing

There are 2 ways of running the unit tests (files with test_ prefix in test folder):

Both of these commands have their own special use cases:

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

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:

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 meson.build file. As you can see below, for test_BST.cpp we have to first define an executable, and then define a test that runs this executable.

test_bst_exe = executable('test_BST.cpp.executable', 
    sources: ['test_BST.cpp'], 
    dependencies : [bst, gtest_dep, util])
test('my BST test', test_bst_exe)

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: ninja -C build cov The coverage report should appear under build/meson-logs/coveragereport. 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: ninja -C build clang-format

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 3 static analyzers:

Dynamic Analysis

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

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: Debug

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 meson build and ninja -C build. ⚠️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.

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