Difference between revisions of "Compiling M5"

From gem5
Jump to: navigation, search
(Required Software: mention python-dev package; reorganize a bit)
(Required Software: emphasize newness of SCons & SWIG versions)
Line 12: Line 12:
 
There a few utility scripts written in Perl, but Perl is not necessary to build or run the simulator.
 
There a few utility scripts written in Perl, but Perl is not necessary to build or run the simulator.
  
If you don't have administrator privileges on the machine you are trying to compile on, and the Python or SCons packages are missing or out-of-date, note the following:
+
Note that the required versions for both SCons and SWIG are fairly recent.  For example, they are newer than the packaged versions for the current Debian stable and Ubuntu 6.06 releases, so you may well need to install them from source (or go to Debian testing or unstable).  If you don't have administrator privileges on the machine you are trying to compile on, and the Python or SCons packages are missing or out-of-date, note the following:
 
*You can use a non-default installation of the Python interpreter by either (1) rearranging your PATH so that scons finds the non-default 'python' first or (2) explicitly invoking an alternative interpreter on the scons script, e.g., "/usr/local/bin/python2.4 `which scons` [args]".
 
*You can use a non-default installation of the Python interpreter by either (1) rearranging your PATH so that scons finds the non-default 'python' first or (2) explicitly invoking an alternative interpreter on the scons script, e.g., "/usr/local/bin/python2.4 `which scons` [args]".
 
*You can use the "scons-local" package to install scons in your m5 directory, or install SCons in your home directory using the '--prefix=' option.
 
*You can use the "scons-local" package to install scons in your m5 directory, or install SCons in your home directory using the '--prefix=' option.

Revision as of 15:22, 21 August 2006

M5 runs on Linux, Mac OS X, OpenBSD, and Microsoft Windows (under Cygwin), but should be easily portable to other Unix-like OSes. Cross-endian support has been mostly added, however this has not been extensively tested. All the syscall emulation (_SE) targets support running regardless of host/target endianess, however at present ALPHA_FS does not fully support big endian machines.


Required Software

To build M5, you will need the following software:

  • g++ version 3.4 or newer. Once upon a time, M5 built with g++ 2.95, but it probably doesn't anymore; < 3.4 seems to have some issues with templates.
  • Python, version 2.4 or newer. M5 links in the Python interpreter, so you need the Python header files and shared library (e.g., /usr/lib/libpython2.4.so) in addition to the interpreter executable. These may or may not be installed by default. For example, on Debian/Ubuntu, you need the "python-dev" package in addition to the "python" package.
  • SCons, version 0.96.91 or newer. SCons is a powerful replacement for make. See here to download SCons.
  • SWIG, version 1.3.28 or newer.

There a few utility scripts written in Perl, but Perl is not necessary to build or run the simulator.

Note that the required versions for both SCons and SWIG are fairly recent. For example, they are newer than the packaged versions for the current Debian stable and Ubuntu 6.06 releases, so you may well need to install them from source (or go to Debian testing or unstable). If you don't have administrator privileges on the machine you are trying to compile on, and the Python or SCons packages are missing or out-of-date, note the following:

  • You can use a non-default installation of the Python interpreter by either (1) rearranging your PATH so that scons finds the non-default 'python' first or (2) explicitly invoking an alternative interpreter on the scons script, e.g., "/usr/local/bin/python2.4 `which scons` [args]".
  • You can use the "scons-local" package to install scons in your m5 directory, or install SCons in your home directory using the '--prefix=' option.

Possible Targets

M5 can build many binaries each for a different guest architecture, simulation mode, and use. The currently available architectures are ALPHA, SPARC, and MIPS.

Each of these can built in two simulation modes:

  • FS - Full System mode. This mode simulates a complete system including a kernel, I/O devices, etc. This mode currently only works with the ALPHA architecture.
  • SE - Syscall Emulation mode. This mode simulates statically compiled binaries by functionally emulating any syscall they make.

For each possible architecture and mode, several different executables can be built:

  • m5.debug - A binary used for debugging without any optimizations. Since no optimizations are done this binary is compiled the fastest, however since no optimizations are done it executes very slowly. (-g3 -gdwarf-2 -O0).
  • m5.opt - A binary with debugging and optimization. This binary executes much faster than the debug binary and still provides all the debugging facility of the debug version. However when debugging source code it can be more difficult to use that the debug target. (-g -O3)
  • m5.prof - This binary is like the opt target, however it also includes profiling support suitable for use with gprof. (-O3 -g -pg).
  • m5.fast - This binary is the fastest binary and all debugging support is removed from the binary (including trace support). (-O3 -DNDEBUG)

Compiling

Starting in the root of the source tree, you can build M5 using a command of the form:

% scons build/<arch>_<mode>/m5.<binary>

where the items between <> are the architectures, modes and binaries listed above. For example:

% cd m5
% scons build/ALPHA_FS/m5.debug

scons: Reading SConscript files ...
Checking for C header file fenv.h... yes
Building in /tmp/m5/build/ALPHA_FS
Options file /tmp/m5/build/options/ALPHA_FS not found,
  using defaults in build_opts/ALPHA_FS
Compiling in ALPHA_FS with MySQL support.
scons: done reading SConscript files.
scons: Building targets ...
g++ -o build/ALPHA_FS/base/circlebuf.do -c -pipe -fno-strict-aliasing
    -Wall -Wno-sign-compare -Werror -Wundef -g3 -gdwarf-2 -O0
    -DTHE_ISA=ALPHA_ISA -DDEBUG -Iext/dnet -I/usr/include/python2.4
    -Ibuild/libelf/include -I/usr/include/mysql -Ibuild/ALPHA_FS
    build/ALPHA_FS/base/circlebuf.cc
...

If your output looked like the above, then congratulations, you've compiled M5! The final binary is located at the path you specified in the argument to scons, e.g., build/ALPHA_FS/m5.debug. For more build options and further details about the build system, see the SCons build system page.

Testing your build

Once you've compiled M5, you can verify that the build worked by running regression tests. Regression tests are also run via scons. The command to run all tests for a particular is constructed as follows:

% scons build/<target>/tests/<binary>

For example, to run the regression tests on ALPHA_FS/m5.opt, type:

% scons build/ALPHA_FS/tests/opt

The regression framework is integrated into the scons build process, so the command above will (re)build ALPHA_FS/m5.opt if necessary before running the tests. Also thanks to scons's dependence tracking, tests will be re-run only if the binary has been rebuilt since the last time the test was run. If the previous test run is still valid (as far as scons can tell), only a brief pass/fail message will be printed out based on the result of that previous test, rather than the full output and statistics diff that is printed when the test is actually executed.

Regression tests are further subdivided into three categories ("quick", "medium", and "long") based on runtime. You can run only the tests in a particular category by adding that category name to the target path, e.g.:

% scons build/ALPHA_FS/tests/opt/quick

(Note that currently the "medium" and "long" categories are empty; all of the tests are "quick".)

Specific tests can be run by appending the test name:

% scons build/ALPHA_FS/tests/opt/quick/10.linux-boot

For more details, see Regression tests.