If you face any issues building the assignments, please feel free to ask for help on Piazza. If you still have problems with setups, please do not hesitate to come to office hours, project parties, or the end of lost sections for help! We will do our best to help get assignments up and running on your machine! :)

We highly recommend that you use a real IDE to code for assignments in this class, not a text editor such as Sublime Text or Visual Studio Code. Many assignments require very serious debugging. A real IDE will make debugging significantly easier for you than a text editor. We strongly encourage you to use:

In short, to build CS184 assignments, you need to perform the following steps:

  1. Download the assignments
  2. Set up code environment for your machine (needs to be done only once)
  3. Compile and run the assignments (needs to be done for each assignment)

For submitting your assignments, please visit this link.

0. Downloading Assignments

When an assignment is released, it will appear in your CS184 website profile, under Assignments. Once you accept the assignment through GitHub Classroom, a private repo will be generated for your assignment. You will need to clone and push to this repository that has your username in the repo name, and not the class skeleton.

$  git clone <YOUR_PRIVATE_REPO>

where<YOUR_PRIVATE_REPO> is the https link on the GitHub repository page. If you have not used git before, you may find this introduction helpful. Connecting to GitHub with SSH is also recommended to avoid typing your username and password everytime.

1. Setting Up C++ and Dependencies on Your Machine

Note: You need to perform these steps only once.

Platform: Windows, MacOS, Linux, Instructional Machines, and Others.

Windows

  1. Install Visual Studio 2019 or newer
    • Select "Desktop Development with C++" when installing Visual Studio
  2. Install Git for Windows
  3. Install Vcpkg
    • Open a PowerShell / CMD / Git Bash in the folder where you wish to install vcpkg, (e.g. C:/)
    • Vcpkg is a package management software that downloads and builds the required software dependencies
    • git clone https://github.com/microsoft/vcpkg
    • Go into the vcpkg folder
    • .\bootstrap-vcpkg.bat
    • After vcpkg is installed, install the dependency of this project
      • On 64-bit system (most systems today) .\vcpkg.exe install freetype:x64-windows
      • On 32-bit system (may not work well) .\vcpkg.exe install freetype

MacOS

  1. Open up your terminal and run xcode-select --install. Accept the XCode license if prompted. If in the later steps, you are unable to build, then try installing XCode through the Mac App Store.
  2. You should now be able to run g++ --version without any errors.
  3. We will be using CMake to build the assignments. If you don't have CMake on your Mac, you can easily install it by first installing HomeBrew (a third-party package manager for MacOS), and then running brew install cmake. Alternatively, you can download CMake directly from the CMake website.
  4. You will also need to install freetype libraries. A convenient way is by getting HomeBrew, and then running brew install freetype.

Common errors:

  • "CXX compiler identification is unknown": Try running sudo xcode-select --reset; sudo xcodebuild -license accept.

Linux (Ubuntu / Debian / apt)

Install the C++ build tools using the commands below. This assumes that you are on Ubuntu/Debian. Here is an explanation of each packaging necessary:

  • build-essential: A bundle that contains most packages needed for compiling C/C++ projects
  • cmake: The tool used to build assignments
  • xorg-dev: A bundle containing many dependencies related to X Window System
  • libfreetype6-dev: A dependency used by CS184 projects
  • mesa-common-dev libgl1-mesa-dev libglu1-mesa-dev: OpenGL development libraries
sudo apt update
sudo apt install build-essential cmake xorg-dev libfreetype6-dev
sudo apt install mesa-common-dev libgl1-mesa-dev libglu1-mesa-dev

Use the Instructional Machines (Soda 330 & Soda 349)

The EECS department provides instructional computers to students enrolled in a CS class. To get an account, create a WebAcct on the EECS instructional account webpage.

The easiest way to use the instructional machines is to make the trek to Soda and physically use the desktop computers in Soda 330 or Soda 349.

SSH Remote Access of Soda Machines

All these steps should run with no issues on the fourteen Soda 349 instructional machines. You can access these machines by ssh-ing in, e.g.

ssh cs184-???@s349-##.cs.berkeley.edu

where cs184-??? is your WebAcct name and s349-## is the ##-th computer in Soda 349. Unfortunately, OpenGL won't play nice with ssh, so in general, you will only be able to compile your code over ssh, not run it. However, for some projects, you can render the images and download them over scp or imgcat. Otherwise, you will have to physically travel to Soda 349 to verify that your code runs correctly.

We have also installed our dependencies on the hive (Soda 330) machines. You can also access these machines by ssh-ing:

ssh cs184-???@hive##.cs.berkeley.edu

As before, ## represents the ##-th computer in the lab (notice there is no dash). You can check the availability and usage of the hive machines using hivemind. These machines are also available in person, though be mindful of any labs or classes that may be using the lab.

If you develop on your personal computer and then would like to copy the code over to test it, you can use the scp command from the base project directory (on your own computer) as follows:

scp -r . cs184-???@s349-?.cs.berkeley.edu:~/destination_folder

After inputting your WebAcct password, all your files should be copied over as when using the normal cp command. Note that when you move code between computers, you will probably have to recompile, since the binaries are rarely cross-compatible.

If you modify code while working on the instructional machines, you can reverse the scp process to transfer the files back to your own computer by running this command from your personal computer.

scp -r cs184-???@s349-?.cs.berkeley.edu:~/hw1_folder ~/destination_folder

Setup on Other Operating Systems

Course staff will try our best in assisting you, but we can only confidently provide support on platforms listed here since there are too many platforms available to provide detailed instructions on all of them.

If you use a platform not listed here, you may have to use Google figure it out yourself. Try building the projects and installing whatever missing development libraries are needed. There are several main components you will need in order to build CS184 assignments:

  1. C++/G++ build toolchain
  2. CMake
  3. Xorg build headers
  4. Freetype development libraries

If all else fails, you can use the EECS instructional computers as those are known to work with CS184 projects.

2. Compiling and Running Assignments

Note: You will have to perform these steps at least once for each project.

Program: Visual Studio, XCode, CLion, and Command Line.

Visual Studio (Windows)

  1. Accept the assignment via your profile page in the course website
  2. Open Visual Studio, use "Clone or Check out Code"
    • Use the GitHub repository link
  3. After the project is opened and the files are listed, right click on CMakeLists.txt, and then click "CMake Settings for Assignment1"
    • On the left, press the add button and add a configuration with "x64-Release" (or "x86-Release" on a 32-bit machine). You will still be able to debug the project, but the optimizations of release code will be applied.
    • Then, find field "CMake toolchain file", enter [location of vcpkg]/scripts/buildsystems/vcpkg.cmake. (e.g. C:/vcpkg/scripts/buildsystems/vcpkg.cmake)
  4. "Build" -> "Build All"
    • Then, open the src folder and right click the main file for this project (e.g. drawrend.cpp for Project 1, and select "Set as Startup Item."
  5. Then you can run your project
  6. To set the arguments for running the project:
    1. Select draw.exe as the running target (The select box on the right side of the green "Run" button)
  7. Go to Menu -> Debug -> Debug and Launch Settings for draw
  8. After "name": "draw.exe", add a comma and a new line: "args": ["../../../svg/basic/"] (or any specific svg file of your choice)
  9. Your whole debug and launch config should look like this:
{
  "version": "0.2.1",
  "defaults": {},
  "configurations": [
    {
      "type": "default",
      "project": "CMakeLists.txt",
      "projectTarget": "draw.exe",
      "name": "draw.exe",
      "args": ["../../../svg/basic/"]
    }
  ]
}

XCode (MacOS)

Prof. Ren Ng made a helpful video tutorial on XCode similar to the instructions here. The video also contains additional details on how to debug using Xcode.

  1. Make sure that the latest Xcode.app is installed through the Mac app store
  2. Accept the assignment via your profile page in the course website
  3. Clone your assignment repository from GitHub (ssh is recommended)
  4. Open your Terminal and use cd to change directory into the project folder
  5. Create a folder called xcode, and CD into it: mkdir xcode; cd xcode
  6. Setup cmake for XCode (while inside the xcode folder): cmake -G Xcode ..
  7. Open Finder and navigate to the xcode folder
  8. Double-click on the <Project Name>.xcodeproj file to open the project in XCode (it has a blue icon with a pen and paintbrush)
  9. Build the project by clicking Project > Build on the top bar of your screen
  10. Click on ALL_BUILD, located near the top right of Xcode (see Ren's video for more details)
  11. Click Edit Scheme
  12. Select Run on the sidebar
  13. Select Info on the top bar of the Run page
  14. Set Executable to the executable (in the case of HW0, it is quad_test)
  15. Select Arguments (inside Edit Scheme > Run) to specify arguments (not necessary for HW0) (see Ren's video for help finding it)
  16. Select Options (inside Edit Scheme > Run) and specify the working directory to be the xcode folder.
  17. Press the play button to compile and launch the program

CLion (Windows / MacOS / Linux)

The advantage of using CLion over command line is the advanced debugging features.

Successfully building in CLion requires following a specific set of instructions. Please make sure to read these instructions especially carefully. If you are on Windows, you will still need to follow the setup instructions and install Visual Studio since C++ is bundled with Visual Studio.

  1. Accept the assignment via your profile page in the course website
  2. Clone your assignment repository from GitHub (ssh is recommended)
  3. Open CLion (available for free with a Jetbrains Student License)
  4. Be at the Welcome to CLion window. It is the window opened by default. To get here, close all CLion windows and reopen CLion.
  5. On the right side of the window, click Open
  6. Navigate to your project folder in the file explorer that just popped up
  7. Select CMakeLists.txt and press open (it only works if you select this special file)
  8. Click Open as Project
  9. Find the build project buttons and build
  10. To specify program arguments, find the run menu, and use Edit Configurations (not necessary for HW0, but important for later homeworks)
  11. Run the project either through the CLion GUI or through the command line (the binary will be inside the cmake-build-debug folder)

Command Line (MacOS / Linux)

  1. Accept the assignment via your profile page in the course website
  2. Clone your assignment repository from GitHub (ssh is recommended)
  3. Open your Terminal and use cd to change directory into the project folder
  4. Create a folder called build, and CD into it: mkdir build; cd build
  5. Setup cmake (while inside the build folder): cmake ..
  6. Build the project (while inside the build folder): make
  7. Run the project (while inside the build folder): ./quad_test (or whatever the binary name is)