Assignment 0. Devops

1 Fork our repo, and clone it and all the libraries
2 Build the libraries and the demo app
3 Send us a screenshot

See the schedule for due date info.

This assignment is just about building the C++ development environment you’ll use in the coming assignments to build your ray tracing and rasterization pipelines. For this class we are providing a collection of libraries; some are standard external libraries, some are built just for this course to make the specific goals of the assignments easier to achieve with less code.

The external libraries include:

Embree, Intel’s collection of high performance ray tracing kernels. It provides a quite simple interface that makes it easy to get started, and also provides the parallel and streaming kernels needed to get to higher performance.
Assimp (stands for “asset importer”), a popular open-source library for reading scenes. It supports lots of scene formats and puts the mesh and hierarchy data into a simple lowest-common-denominator structure that it’s easy to read it from.
Nanogui, a minimal user interface framework on top of OpenGL. It provides cross-platform UI with no need for any help from the native window system.
STB, a header-only library providing very simple versions of common graphics needs such as image i/o.
cpplocate, to simplify finding our assets.
GLM, a vector math library that uses conventions identical to GLSL.

The libraries we are providing for this course include:

GLWrap, which provides some simple wrappers around OpenGL objects to support writing OpenGL code in a reasonable C++ style.
RTUtil, which provides a number of functions for input parsing, geometric computations, reflectance models, and random sampling, as well as ImgGUI, a simple app built on GLWrap and Nanogui that provides the ability to display an image in a window.

The goal for this first week is to get your development environment set up and the libraries all compiled. To get set up follow the steps below, ending with a handin. Please don’t hesitate to reach out for help; C++ development is tricky and if you don’t have much experience it’s likely you will run into one problem or another.

1 Fork our repo, and clone it and all the libraries

First go to our repository at https://github.coecis.cornell.edu/cs5625/Starter22 and make a fork using the GitHub web UI. Your fork should be a private repository. This will let you easily pull updates related to bug fixes and later assignments from our repository into yours. Then clone your repository with:

git clone --recursive https://github.coecis.cornell.edu/<path to your repo>.git

(where you fill in the actual URL for your repository). This gets you the contents of our repository and also the git submodules that bring in the various libraries we depend on. If you forget --recursive (I always do), it’s OK; you can always get the submodules into the right state by running:

git submodule update --init --recursive

Once the submodules are there, you will see lots of files under ext/.

There is one library that’s tricky to build from source, Intel’s TBB (used by Embree), so you’ll want to install it separately (see platform-specific hints below). The Embree API documentation and this guide have more details about TBB.

The starter code is set up to use the CMake build system, which you can install with its own installer or as suggested below.

1.1 Hints for MacOS users

On the Mac the easiest way to get the tools you need is from one of the open-source package managers:

For Homebrew, install cmake and tbb.
For MacPorts, install cmake and onetbb.

Make sure you’re installing the version of TBB appropriate for your system’s architecture – for example, if you are on an M1 Mac do not install the x86 version of TBB. This will happen if you’re running Homebrew through Rosetta.

By default CMake may try to build for an old OS version that is not supported by the libraries, so we recommend setting a particular minimum version using -DCMAKE_OSX_DEPLOYMENT_TARGET=12.0 (substitute the version of your OS if it is older than 12.0).

If your Mac has an Apple CPU (M1, etc.) you will need to mention this to CMake by giving it the option -DCMAKE_OSX_ARCHITECTURES=arm64 (on an Intel mac just omit this entirely).

So where we write just cmake .. below, you will write something like

cmake -DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=12.0 ..

You can use Xcode (Apple’s native IDE) instead of Make if you prefer, by asking CMake to generate Xcode project files using the option -G Xcode.

1.2 Hints for Windows users

You can install CMake with its installer. CMake can work with the Unix make utility or with Visual Studio. Most students who use Windows choose Visual Studio.

To use Visual Studio, ask CMake to generate Visual Studio project files using the option -G "Visual Studio 17 2022" (substitute your version if needed; cmake -G by itself provides a list of available generators).

If you want to go the Make route, you can install Make from here, and then will need to set up the PATH variable for it.

To install TBB on Windows there is an installer or you can download it from here. You may find that you also need to set the TBB_ROOT environment variable to the location of your download if you use the second method.

1.3 Hints for Linux users

On Linux, you’re going to need your distribution’s core development packages (i.e., build-essential on Ubuntu and base-devel on Arch) which you can install using your system’s package manager.

You will also need the TBB development libraries – libbtbb-dev on Ubuntu or tbb on Arch. If you get a warning about using an outdated version of TBB, that is okay to ignore.

Additionally, you might need packages required for developing an application that creates windows. This will be xorg-dev on Ubuntu. For other distros, you can see the GLFW info page about which packages might be required, though their absence is typically pretty easy to diagnose.

2 Build the libraries and the demo app

To build the demo app, follow this sequence, starting from the root directory of your working copy of our repository:

mkdir build  # With CMake you always want to build in a separate directory.
cd build
cmake ..     # This tells CMake to look for its configuration in the parent directory.
make -j 5    # CMake just sets up files for Make; this asks Make to actually build the software.

This will take a few minutes. The -j <n> option tells Make how many parallel tasks to run; conventional wisdom says that for the fast builds you should make this the number of CPU cores on your system + 1. Once you’ve compiled once and are just compiling code changes as you develop, you might want to omit this option to build with 1 thread, so that the make output is more sequential and thus more legible.

At the end, if all goes well, you will have an executable called Demo in the build directory. Run it:

./Demo

and you should get a colorful window.

If you have problems at this phase they are likely related to compiler setup, development environment, or other things, and you will want to reach out for some help!

3 Send us a screenshot

Finally, take a screen shot of the demo app and hand it in on CMS. The point value of this week’s assignment is very small; the goal is to get you set up while there is still time to get help with build environment issues.