:authors: Jason Power -------------- Building gem5 -------------- Requirements for gem5 ~~~~~~~~~~~~~~~~~~~~~ See `gem5 requirements`_ for more details. .. _gem5 requirements: http://gem5.org/Compiling_M5#Required_Software 1. hg (Mercurial_): The gem5 project uses Mercurial_ for version control. Mercurial_ is a distributed version control system (like git). It uses simple commands that should be familiar to svn users as well. More information about Mercurial_ can be found by following the link. Mercurial should be installed by default on most platforms. However, to install Mercurial in Ubuntu use .. code-block:: sh sudo apt-get install mercurial 2. gcc 4.6+ You may need to use environment variables to point to a non-default version of gcc. For CSL machines, you can add the following to your `.bashrc.local`, assuming you're using bash as your shell. .. code-block: sh export PATH=/s/gcc-4.7.3/bin:$PATH export LD_LIBRARY_PATH=/s/gcc-4.7.3/lib64:$LD_LIBRARY_PATH On Ubuntu, you can install a development environment with .. code-block:: sh sudo apt-get install build-essential 3. SCons_ 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 .. code-block:: sh sudo apt-get install scons 4. Python 2.5+ gem5 relies on the Python development libraries. On CSL machines, you may experience errors with the default Python version (2.5). To use version 2.7 you can add the following to your `.bashrc.local`: .. code-block:: sh export PATH=/s/python-2.7.3/bin:$PATH export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/s/python-2.7.3/lib export LIBRARY_PATH=/s/python-2.7.3/lib:$LIBRARY_PATH To install these on Ubuntu use .. code-block:: sh sudo apt-get install python-dev 5. SWIG_ 2.0.4+ SWIG_ is a set of scripts and libraries that wraps `C++` objects and exports them to scripting languages, like Python. gem5 uses SWIG to export `C++` SimObjects to the Python configuration files. To install SWIG on Ubuntu use .. code-block:: sh sudo apt-get install swig You may have to install SWIG manually. In that case, you can download the source from http://www.swig.org/download.html. Version 2.0.4 is known to work with gem5. Then, unpack, build, and install: .. code-block:: sh tar -xvzf swig-2.0.4.tar.gz ./configure --prefix= make && make install .. _Mercurial: http://mercurial.selenic.com/ .. _SCons: http://www.scons.org/ .. _SWIG: http://www.swig.org/ Getting the code ~~~~~~~~~~~~~~~~ Change directories to where you want to download the gem5 source. Then, to clone the repository, use the ``hg clone`` command. .. code block:: sh hg clone http://repo.gem5.org/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 :ref:`ruby`, 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. .. code block:: sh scons CPU_MODELS="AtomicSimpleCPU,MinorCPU,O3CPU,TimingSimpleCPU" build/X86/gem5.opt -j9 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: :: scons: Reading SConscript files ... Mercurial libraries cannot be found, ignoring style hook. If you are a gem5 developer, please fix this and run the style hook. It is important. Checking for leading underscore in global variables...(cached) no Checking for C header file Python.h... (cached) yes Checking for C library pthread... (cached) yes Checking for C library dl... (cached) yes Checking for C library util... (cached) yes Checking for C library m... (cached) yes Checking for C library python2.7... (cached) yes Checking for accept(0,0,0) in C++ library None... (cached) yes Checking for zlibVersion() in C++ library z... (cached) yes Checking for GOOGLE_PROTOBUF_VERIFY_VERSION in C++ library protobuf... (cached) yes Checking for clock_nanosleep(0,0,NULL,NULL) in C library None... (cached) no Checking for clock_nanosleep(0,0,NULL,NULL) in C library rt... (cached) yes Checking for timer_create(CLOCK_MONOTONIC, NULL, NULL) in C library None... (cached) yes Checking for C library tcmalloc... (cached) yes Checking for C header file fenv.h... (cached) yes Checking for C header file linux/kvm.h... (cached) yes Checking size of struct kvm_xsave ... (cached) yes Checking for member exclude_host in struct perf_event_attr...(cached) yes Building in /afs/cs.wisc.edu/p/multifacet/users/powerjg/gem5-tutorial/gem5/build/X86_MESI_Two_Level Variables file /afs/cs.wisc.edu/p/multifacet/users/powerjg/gem5-tutorial/gem5/build/variables/X86_MESI_Two_Level not found, using defaults in /afs/cs.wisc.edu/p/multifacet/users/powerjg/gem5-tutorial/gem5/build_opts/X86_MESI_Two_Level scons: done reading SConscript files. scons: Building targets ... [ISA DESC] X86_MESI_Two_Level/arch/x86/isa/main.isa -> generated/inc.d [NEW DEPS] X86_MESI_Two_Level/arch/x86/generated/inc.d -> x86-mesi-two-level-deps [ENVIRONS] x86-mesi-two-level-deps -> x86-mesi-two-level-environs [ CXX] X86_MESI_Two_Level/sim/main.cc -> .o .... .... .... [ SHCXX] drampower/src/MemoryPowerModel.cc -> .os [ SHCXX] drampower/src/MemorySpecification.cc -> .os [ SHCXX] drampower/src/Parameter.cc -> .os [ SHCXX] drampower/src/Parametrisable.cc -> .os [ SHCXX] drampower/src/libdrampower/LibDRAMPower.cc -> .os [ AR] -> drampower/libdrampower.a [ RANLIB] -> drampower/libdrampower.a [ CXX] X86_MESI_Two_Level/base/date.cc -> .o [ LINK] -> X86_MESI_Two_Level/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 ~~~~~~~~~~~~~~