Code Correctness

Setup

If you haven’t already, please do the Setup for the course. Otherwise, just register for the project using the registration tool and clone the repository as explained in the setup instructions. Please use the SSH link found on the registration page and in the email sent to you. It should look something like git@gitlab.caltech.edu:cs18-26sp/project01-blank.git.

Goals and Deliverables

In this project, you’ll begin writing the codebase that you’ll be working with over the next several weeks; it is very likely that you will still be using some of this code in week 10 of the term.

• This week, you will build structures that represent vectors, bodies (shapes with velocity, color, etc.), and scenes (collections of bodies).
• The main data structure we will use is an ArrayList which will be a list_t in C. We have provided you with the interface that documents how you can use lists along with its binary file. Thus, you will not have to implement the internals of the list.

vector_t

In vector.h, we’ve provided function prototypes which you should implement in vector.c. See the provided documentation in vector.h for what the functionality should be. Your vector.c file should (1) include the vector.h header and (2) define the functions specified in vector.h. You’ll be writing an extensive set of functions that act directly on vector_ts that are not pointers. Your vector_t will eventually represent position, velocity, acceleration, and other vector quantities in your physics engine.

list_t

You will not have to implement list_t, but we’ll point out a few things here that should make it easier to interact with them.

• Notice that the elements of list_t are pointers (void *), not values!
• list_init contains a free_func_t parameter. The free_func_t type is defined at the top of list.h. Essentially, it’s defining the free_func_t type as any function that returns void and takes in a void * (generic pointer).
• You can’t see the implementation of list_free, but suppose we didn’t take in a free_func_t parameter. Then a reasonable (and probably the only valid) implementation of list_free is to free() every element that it contains, and then to free the list_t itself. However, what if the objects inside the list_t allocate memory for their fields? In the case for an object like body_t, free() would only free the space allocated for the body_t struct, but not any of the fields that might be allocated in body_init(), leading to memory leaks. Thus, we pass in a free_func_t so that the list_t knows which function to run on each element when list_free is called. In the case of managing multiple bodies, for example, we would initialize a list_t of bodies with list_init(capacity, body_free).
• Importantly, list_t takes ownership of its elements depending on if freer is NULL or not. If freer is NULL, then the list_t doesn’t free its elements whatsoever when list_free is called. This might not be relevant to this project, but it will be if you ever want to keep ownership of an item while adding it to a list_t.

body_t

body_t will be our primary structure to represent objects in our demos and games. For now, they’ll have a color, shape, rotation, velocity, position, and mass. The mass won’t be used in your demos this week, but they will be used once we implement forces and impulses in the next few weeks.

The shape of the body_t can be represented as a fixed-size list_t of vector_t’s. We will take the convention that a body’s vertices are stored in a counter-clockwise order. Like you did with vector_t, look at the provided documentation in body.h and implement body_t.

scene_t

We’ll also implement a new scene_t abstraction to represent a collection of bodies. While its functionality seems pretty basic for now, it will be much more helpful in later weeks and prove to be much easier to manage than a list_t of bodies.

Running and Testing your Code: make and the Makefile

All the projects in our class will have the following directory structure:

• include: header files go here
• library: source files for your libraries (e.g., list, body, etc.)
• demo: source files for the demos go here
• game: source files for the game go here
• tests: test source files go here
• out: built object files will be generated here
• ref: reference object files for the demo and game are provided here
• bin: built binaries will be generated here

We have provided you with a Makefile which is set up to build the project. It allows you to run the following commands:

• make demo: compile the demo and runs the web server
• make game: compile the game and runs the web server
• make test: compile all libraries and tests and run all the tests
• make NO_ASAN=true demo compiles the demo without asan - this is recommended if the demo lags.
• make server: Run the web server with the current binaries
• make clean: remove all generated binaries

To run all the tests, all you need to type is make test. To run compile and run an individual test suite, run the following commands (replacing vector with the test suite you want to run):

make bin/test_suite_vector
./bin/test_suite_vector