_pages/documentation/learning_gem5/part1/part1_1_building.md

---
layout: documentation
title: Building gem5
doc: Learning gem5
parent: part1
permalink: /documentation/learning_gem5/part1/building/
author: Jason Lowe-Power
---

Building gem5
=============

This chapter covers the details of how to set up a gem5 developmment
environment and build gem5.

Requirements for gem5
---------------------

See [gem5 requirements](http://www.gem5.org/documentation/general_docs/building#dependencies) for more details.

On Ubuntu, you can install all of the required dependencies with the
following command. The requirements are detailed below.

```
sudo apt install build-essential git m4 scons zlib1g zlib1g-dev libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev python-dev python
```

1.  git ([Git](https://git-scm.com/)):
    :   The gem5 project uses [Git](https://git-scm.com/) for version
        control. [Git](https://git-scm.com/) is a distributed version
        control system. More information about
        [Git](https://git-scm.com/) can be found by following the link.
        Git should be installed by default on most platforms. However,
        to install Git in Ubuntu use

        ```
        sudo apt install git
        ```

2.  gcc 7+
    :   You may need to use environment variables to point to a
        non-default version of gcc.

        On Ubuntu, you can install a development environment with

        ```
        sudo apt install build-essential
        ```

       **We support GCC Versions >=7, up to GCC 11**

3.  [SCons 3.0+](http://www.scons.org/)
    :   gem5 uses SCons as its build environment. SCons is like make on
        steroids and uses Python scripts for all aspects of the build
        process. This allows for a very flexible (if slow) build system.

        To get SCons on Ubuntu use

        ```
        sudo apt install scons
        ```

4.  Python 3.6+
    :   gem5 relies on the Python development libraries. To install
        these on Ubuntu use

        ```
        sudo apt install python3-dev
        ```

5.  [protobuf](https://developers.google.com/protocol-buffers/) 2.1+ (**Optional**)
    :   "Protocol buffers are a language-neutral, platform-neutral
        extensible mechanism for serializing structured data." In gem5,
        the [protobuf](https://developers.google.com/protocol-buffers/)
        library is used for trace generation and playback.
        [protobuf](https://developers.google.com/protocol-buffers/) is
        not a required package, unless you plan on using it for trace
        generation and playback.

        ```
        sudo apt install libprotobuf-dev protobuf-compiler libgoogle-perftools-dev
        ```

6. [Boost](https://www.boost.org/) (**Optional**)
    :   The Boost library is a set of general purpose C++ libraries. It is a
        necessary dependency if you wish to use the SystemC implementation.
        ```
        sudo apt install libboost-all-dev
        ```

Getting the code
----------------

Change directories to where you want to download the gem5 source. Then,
to clone the repository, use the `git clone` command.

```
git clone https://gem5.googlesource.com/public/gem5
```

You can now change directories to `gem5` which contains all of the gem5
code.

Your first gem5 build
---------------------

Let's start by building a basic x86 system. Currently, you must compile
gem5 separately for every ISA that you want to simulate. Additionally,
if using ruby-intro-chapter, you have to have separate compilations for
every cache coherence protocol.

To build gem5, we will use SCons. SCons uses the SConstruct file
(`gem5/SConstruct`) to set up a number of variables and then uses the
SConscript file in every subdirectory to find and compile all of the
gem5 source.

SCons automatically creates a `gem5/build` directory when first
executed. In this directory you'll find the files generated by SCons,
the compiler, etc. There will be a separate directory for each set of
options (ISA and cache coherence protocol) that you use to compile gem5.

There are a number of default compilations options in the `build_opts`
directory. These files specify the parameters passed to SCons when
initially building gem5. We'll use the X86 defaults and specify that we
want to compile all of the CPU models. You can look at the file
`build_opts/X86` to see the default values for the SCons options. You
can also specify these options on the command line to override any
default.

```
python3 `which scons` build/X86/gem5.opt -j9
```

> **gem5 binary types**
>
> The SCons scripts in gem5 currently have 5 different binaries you can
> build for gem5: debug, opt, and fast. These names are
> mostly self-explanatory, but detailed below.
>
> debug
> :   Built with no optimizations and debug symbols. This binary is
>     useful when using a debugger to debug if the variables you need to
>     view are optimized out in the opt version of gem5. Running with
>     debug is slow compared to the other binaries.
>
> opt
> :   This binary is build with most optimizations on (e.g., -O3), but
>     with debug symbols included. This binary is much faster than
>     debug, but still contains enough debug information to be able to
>     debug most problems.
>
> fast
> :   Built with all optimizations on (including link-time optimizations
>     on supported platforms) and with no debug symbols. Additionally,
>     any asserts are removed, but panics and fatals are still included.
>     fast is the highest performing binary, and is much smaller than
>     opt. However, fast is only appropriate when you feel that it is
>     unlikely your code has major bugs.
>
The main argument passed to SCons is what you want to build,
`build/X86/gem5.opt`. In this case, we are building gem5.opt (an
optimized binary with debug symbols). We want to build gem5 in the
directory build/X86. Since this directory currently doesn't exist, SCons
will look in `build_opts` to find the default parameters for X86. (Note:
I'm using -j9 here to execute the build on 9 of my 8 cores on my
machine. You should choose an appropriate number for your machine,
usually cores+1.)

The output should look something like below:

    Checking for C header file Python.h... yes
    Checking for C library pthread... yes
    Checking for C library dl... yes
    Checking for C library util... yes
    Checking for C library m... yes
    Checking for C library python2.7... yes
    Checking for accept(0,0,0) in C++ library None... yes
    Checking for zlibVersion() in C++ library z... yes
    Checking for GOOGLE_PROTOBUF_VERIFY_VERSION in C++ library protobuf... yes
    Checking for clock_nanosleep(0,0,NULL,NULL) in C library None... yes
    Checking for timer_create(CLOCK_MONOTONIC, NULL, NULL) in C library None... no
    Checking for timer_create(CLOCK_MONOTONIC, NULL, NULL) in C library rt... yes
    Checking for C library tcmalloc... yes
    Checking for backtrace_symbols_fd((void*)0, 0, 0) in C library None... yes
    Checking for C header file fenv.h... yes
    Checking for C header file linux/kvm.h... yes
    Checking size of struct kvm_xsave ... yes
    Checking for member exclude_host in struct perf_event_attr...yes
    Building in /local.chinook/gem5/gem5-tutorial/gem5/build/X86
    Variables file /local.chinook/gem5/gem5-tutorial/gem5/build/variables/X86 not found,
      using defaults in /local.chinook/gem5/gem5-tutorial/gem5/build_opts/X86
    scons: done reading SConscript files.
    scons: Building targets ...
     [ISA DESC] X86/arch/x86/isa/main.isa -> generated/inc.d
     [NEW DEPS] X86/arch/x86/generated/inc.d -> x86-deps
     [ENVIRONS] x86-deps -> x86-environs
     [     CXX] X86/sim/main.cc -> .o
     ....
     .... <lots of output>
     ....
     [   SHCXX] nomali/lib/mali_midgard.cc -> .os
     [   SHCXX] nomali/lib/mali_t6xx.cc -> .os
     [   SHCXX] nomali/lib/mali_t7xx.cc -> .os
     [      AR]  -> drampower/libdrampower.a
     [   SHCXX] nomali/lib/addrspace.cc -> .os
     [   SHCXX] nomali/lib/mmu.cc -> .os
     [  RANLIB]  -> drampower/libdrampower.a
     [   SHCXX] nomali/lib/nomali_api.cc -> .os
     [      AR]  -> nomali/libnomali.a
     [  RANLIB]  -> nomali/libnomali.a
     [     CXX] X86/base/date.cc -> .o
     [    LINK]  -> X86/gem5.opt
    scons: done building targets.

When compilation is finished you should have a working gem5 executable
at `build/X86/gem5.opt`. The compilation can take a very long time,
often 15 minutes or more, especially if you are compiling on a remote
file system like AFS or NFS.

Common errors
-------------

### Wrong gcc version

    Error: gcc version 5 or newer required.
           Installed version: 4.4.7

Update your environment variables to point to the right gcc version, or
install a more up to date version of gcc. See
building-requirements-section.

### Python in a non-default location

If you use a non-default version of Python, (e.g., version 3.6 when 2.5
is your default), there may be problems when using SCons to build gem5.
RHEL6 version of SCons uses a hardcoded location for Python, which
causes the issue. gem5 often builds successfully in this case, but may
not be able to run. Below is one possible error you may see when you run
gem5.

    Traceback (most recent call last):
      File "........../gem5-stable/src/python/importer.py", line 93, in <module>
        sys.meta_path.append(importer)
    TypeError: 'dict' object is not callable

To fix this, you can force SCons to use your environment's Python
version by running `` python3 `which scons` build/X86/gem5.opt `` instead
of `scons build/X86/gem5.opt`.

### M4 macro processor not installed

If the M4 macro processor isn't installed you'll see an error similar to
this:

    ...
    Checking for member exclude_host in struct perf_event_attr...yes
    Error: Can't find version of M4 macro processor.  Please install M4 and try again.

Just installing the M4 macro package may not solve this issue. You may
nee to also install all of the `autoconf` tools. On Ubuntu, you can use
the following command.

```
sudo apt-get install automake
```

### Protobuf 3.12.3 problem

Compiling gem5 using protobuf might result in the following error,

```
In file included from build/X86/cpu/trace/trace_cpu.hh:53,
                 from build/X86/cpu/trace/trace_cpu.cc:38:
build/X86/proto/inst_dep_record.pb.h:49:51: error: 'AuxiliaryParseTableField' in namespace 'google::protobuf::internal' does not name a type; did you mean 'AuxillaryParseTableField'?
   49 |   static const ::PROTOBUF_NAMESPACE_ID::internal::AuxiliaryParseTableField aux[]
```

The root cause of the problem is discussed here: [https://gem5.atlassian.net/browse/GEM5-1032].

To resolve this problem, you may need to update the version of ProtocolBuffer,
```
sudo apt update
sudo apt install libprotobuf-dev protobuf-compiler libgoogle-perftools-dev
```

After that, you may need to clean the gem5 build folder **before** recompiling gem5,
```
python3 `which scons` --clean --no-cache        # cleaning the build folder
python3 `which scons` build/X86/gem5.opt -j 9   # re-compiling gem5
```

If the problem persists, you may need to completely remove the gem5 build folder **before** compiling gem5 again,
```
rm -rf build/                                   # completely removing the gem5 build folder
python3 `which scons` build/X86/gem5.opt -j 9   # re-compiling gem5
```