Skip to main content

Installation

Course preparation video that goes over all of the information shown in this page.

Cloning the Course Repository​

The repository for all starter content for the course is hosted on github, but it contains a submodule as of 2024. The submodule is a reference to our current version of gem5, so please checkout only that version of gem5. The instructions for how to correctly clone the course materials is as follows:

  1. Clone using the command git clone https://github.com/cmput429/429-resources
    • The --recurse-submodules option allows git to clone gem5 from the gem5 repository as well, however this can take an absurd amount of time.
  2. cd into the 429-resources folder
  3. Run the command git submodule init
    • This will initialize the submodules as folders to fetch, you can learn more on the git website
  4. Run git submodule update to clone the submodules

Set up the Environment​

Once you have cloned the repo, you will notice a script setup.sh. Please run this script.

Setup Script Explanation

The setup script performs a number of actions, most notably:

  • Setting environment variables
  • Unpacking the .pkl files into .json files (in the local_resources directory)

Optionally, the setup script can also build gem5 using the default configuration.

Environment variables​

If you are worried about the environment variables, here are all of the settings that the script will change:

export GEM_PATH=\$C429_RESOURCES/gem5
export GEM_CONFIGS=\$C429_RESOURCES/gem5/configs
export GEM_TESTS=\$C429_RESOURCES/gem5/tests
export GEM5_CONFIG=\$C429_RESOURCES/local_resources/sources.json
export CC=gcc-11
export CXX=g++-11
alias gem5=\$GEM_PATH/build/RISCV/gem5.opt

Where we obtain $C429_RESOURCES by getting the directory from which this script was executed.

This consists of the variables to set the path of the gem5 build, as well as the path to the configuration file we will use to import the binaries you are required to run during this course. We also set the convenient alias so that you can run gem5 from anywhere.

PKL to JSON​

The .pkl files are in the local_resources folder, and you can read more about the pkl language on its documentation page. The goal is to provide gem5 with a list of workloads for you to use and pkl allows us to write json files without repeating all of the boilerplate. You can verify that the script is not doing anything malicious with the curl call on your own (we should probably check the hash of the binary, but I haven't implemented that yet).

Congrats, you did it, now move on to the installation of gem5 proper.

Building​

To install gem5, please consult the gem5 repository, which will have the most up-to-date information about the exact requirements. The information provided here is for your convenience.

  1. Clone the gem5 repository (if you cloned the 429-resources repository, you should already have done this)
  2. Switch to the gem5 directory
  3. (Only on personal machines) Install the prerequisites to gem5
    note

    These are already installed on lab machines.

    sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \
        libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \
        python3-dev libboost-all-dev pkg-config python3-tk
  4. checkout version 24 of gem5: git checkout v24.0.0.0
  5. execute nice -n 15 scons build/RISCV/gem5.opt -j$(nproc)
tip

If you want to get rid of the pre-commit message in gem5, then you can edit the $GEM_PATH/site_scons/site_tools/git.py file and make install_style_hooks return immediately:

$GEM_PATH/site_scons/site_tools/git.py
def install_style_hooks(env):
    return
info

The nice command ensures that your compilation process does not interrupt any other process for a GUI user. You can read more about this command using man nice, and if you have taken 379 the short summary is it decreases the scheduling priority of your process.

warning

gem5 is large (~1.3 GB), so if you have space concerns, you should clone and build the program in the /tmp directory on the lab machines. HOWEVER if you do this, you RISC (get it 😂) having gem5 deleted after you log out.

Note that building gem5 will take ~45 minutes and sometimes longer, so take a break, go outside, breathe some air, touch some grass.

For the Lazy Ones​

The whole installation process for all the course material can be accomplished using the below script:

#!/bin/bash

# Omit if on the lab machines, since prerequisites are already installed
sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \
    libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \
    python3-dev libboost-all-dev pkg-config python3-tk

# Clone the course repository
git clone https://github.com/cmput429/429-resources.git

# Get to the gem5 repository
pushd 429-resources
git submodule init
git submodule update

./setup.sh  # Run the setup script to unpack the .pkl files and set env vars

# Build gem5
popd
pushd gem5
git checkout v24.0.0.0
# if you want to get rid of the hooks:
# vim site_scons/site_tools/git.py
nice -n 15 scons build/RISCV/gem5.opt -j$(nproc)