gem5 has been designed with a Linux environment in mind. We test regularly on Ubuntu 18.04, Ubuntu 20.04, Ubuntu 22.04 to ensure gem5 functions well in these environments. Though any Linux based OS should function if the correct dependencies are installed. We ensure that gem5 is compilable with both gcc and clang (see Dependencies below for compiler version information).
Mac OS should work when compiling using the clang compiler, with all other dependencies installed. However, at present, we do not officially test our builds on Mac OS. We therefore cannot guarantee the same stability for those wishing to compile and run gem5 in Mac OS as we can in Linux-based systems. In later versions of gem5, we hope to more effectively support Mac OS through improved testing.
As of gem5 21.0, we support building and running gem5 with Python 3.6+ only.. gem5 20.0 was our last version of gem5 to provide support for Python 2.
If running gem5 in a suitable OS/environment is not possible, we have provided pre-prepared Docker images which may be used to compile and run gem5. Please see our Docker section below for more information on this.
If compiling gem5 on Ubuntu 22.04, or related Linux distributions, you may install all these dependencies using APT:
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
If compiling gem5 on Ubuntu 20.04, or related Linux distributions, you may install all these dependencies using APT:
sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \ libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \ python3-dev python-is-python3 libboost-all-dev pkg-config
If compiling gem5 on Ubuntu 18.04, or related Linux distributions, you may install all these dependencies using APT:
sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \ libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \ python3-dev python libboost-all-dev pkg-config
For users struggling to setup an environment to build and run gem5, we provide the following Docker Images:
Ubuntu 22.04 with all optional dependencies: gcr.io/gem5-test/ubuntu-22.04_all-dependencies:v22-1 (source Dockerfile).
Ubuntu 22.04 with minimum dependencies: gcr.io/gem5-test/ubuntu-22.04_min-dependencies:v22-1 (source Dockerfile).
Ubuntu 20.04 with all optional dependencies: gcr.io/gem5-test/ubuntu-20.04_all-dependencies:v22-1 (source Dockerfile).
Ubuntu 18.04 with all optional dependencies: gcr.io/gem5-test/ubuntu-18.04_all-dependencies:v22-1 (source Dockerfile).
To obtain a docker image:
docker pull <image>
E.g., for Ubuntu 20.04 with all optional dependencies:
docker pull gcr.io/gem5-test/ubuntu-20.04_all-dependencies:v22-1
Then, to work within this environment, we suggest using the following:
docker run -u $UID:$GID --volume <gem5 directory>:/gem5 --rm -it <image>
Where <gem5 directory>
is the full path of the gem5 in your file system, and <image>
is the image pulled (e.g., gcr.io/gem5-test/ubuntu-22.04_all-dependencies:v22-1
).
From this environment, you will be able to build and run gem5 from the /gem5
directory.
git clone https://github.com/gem5/gem5
gem5‘s build system is based on SCons, an open source build system implemented in Python. You can find more information about scons at http://www.scons.org. The main scons file is called SConstruct and is found in the root of the source tree. Additional scons files are named SConscript and are found throughout the tree, usually near the files they’re associated with.
Within the root of the gem5 directory, gem5 can be built with SCons using:
scons build/{ISA}/gem5.{variant} -j {cpus}
where {ISA}
is the target (guest) Instruction Set Architecture, and {variant}
specifies the compilation settings. For most intents and purposes opt
is a good target for compilation. The -j
flag is optional and allows for parallelization of compilation with {cpus}
specifying the number of threads. A single-threaded compilation from scratch can take up to 2 hours on some systems. We therefore strongly advise allocating more threads if possible.
The valid ISAs are:
The valid build variants are:
These versions are summarized in the following table.
Build variant | Optimizations | Run time debugging support |
---|---|---|
debug | X | |
opt | X | X |
fast | X |
For example, to build gem5 on 4 threads with opt
and targeting x86:
scons build/X86/gem5.opt -j 4
In addition, users may make use of the “gprof” and “pperf” build options to enable profiling:
--gprof
flag. E.g., scons build/ARM/gem5.debug --gprof
.--pprof
flag. E.g., scons build/X86/gem5.debug --pprof
.Once compiled, gem5 can then be run using:
./build/{ISA}/gem5.{variant} [gem5 options] {simulation script} [script options]
Running with the --help
flag will display all the available options:
Usage ===== gem5.opt [gem5 options] script.py [script options] gem5 is copyrighted software; use the --copyright option for details. Options ======= --version show program's version number and exit --help, -h show this help message and exit --build-info, -B Show build information --copyright, -C Show full copyright information --readme, -R Show the readme --outdir=DIR, -d DIR Set the output directory to DIR [Default: m5out] --redirect-stdout, -r Redirect stdout (& stderr, without -e) to file --redirect-stderr, -e Redirect stderr to file --stdout-file=FILE Filename for -r redirection [Default: simout] --stderr-file=FILE Filename for -e redirection [Default: simerr] --listener-mode={on,off,auto} Port (e.g., gdb) listener mode (auto: Enable if running interactively) [Default: auto] --listener-loopback-only Port listeners will only accept connections over the loopback device --interactive, -i Invoke the interactive interpreter after running the script --pdb Invoke the python debugger before running the script --path=PATH[:PATH], -p PATH[:PATH] Prepend PATH to the system path when invoking the script --quiet, -q Reduce verbosity --verbose, -v Increase verbosity Statistics Options ------------------ --stats-file=FILE Sets the output file for statistics [Default: stats.txt] --stats-help Display documentation for available stat visitors Configuration Options --------------------- --dump-config=FILE Dump configuration output file [Default: config.ini] --json-config=FILE Create JSON output of the configuration [Default: config.json] --dot-config=FILE Create DOT & pdf outputs of the configuration [Default: config.dot] --dot-dvfs-config=FILE Create DOT & pdf outputs of the DVFS configuration [Default: none] Debugging Options ----------------- --debug-break=TICK[,TICK] Create breakpoint(s) at TICK(s) (kills process if no debugger attached) --debug-help Print help on debug flags --debug-flags=FLAG[,FLAG] Sets the flags for debug output (-FLAG disables a flag) --debug-start=TICK Start debug output at TICK --debug-end=TICK End debug output at TICK --debug-file=FILE Sets the output file for debug [Default: cout] --debug-ignore=EXPR Ignore EXPR sim objects --remote-gdb-port=REMOTE_GDB_PORT Remote gdb base port (set to 0 to disable listening) Help Options ------------ --list-sim-objects List all built-in SimObjects, their params and default values
The EXTRAS scons variable can be used to build additional directories of source files into gem5 by setting it to a colon delimited list of paths to these additional directories. EXTRAS is a handy way to build on top of the gem5 code base without mixing your new source with the upstream source. You can then manage your new body of code however you need to independently from the main code base.