Difference between revisions of "Build System"
(Created page with "==Build System== M5's build system is based on Scons, an open source build system implemented in python. You can find more information about scons at www.scons.org. The main sco…") |
(→Command line options) |
||
| Line 38: | Line 38: | ||
|- | |- | ||
| --no-color || Turn off colorized output | | --no-color || Turn off colorized output | ||
| + | |- | ||
| + | | --default || Override which build_opts file to use for defaults | ||
| + | |- | ||
| + | | --ignore-style || Disable style checking hooks | ||
| + | |- | ||
| + | | --update-ref || Update test reference outputs | ||
| + | |- | ||
| + | | --verbose || Print full tool command lines | ||
|} | |} | ||
Revision as of 13:47, 10 March 2011
Contents
Build System
M5's build system is based on Scons, an open source build system implemented in python. You can find more information about scons at www.scons.org. The main scons file is called SConstruct and is found in the root of the source tree. additional scons files are called SConscript and are found throughout the tree, usually near the files they're associated with.
Build targets
In M5, scons build targets are of the form <build dir>/<configuration>/<target>. The <build dir> part of the target is a directory path that ends in "build". Typically this is simply "build" by itself, but you can specify a directory called "build" located somewhere else instead. The <configuration> part selects a set of preset build configuration variables values which correspond to common . The possible options are the file names in the build_opts directory, and are discussed more below. The build targets can be regression tests which are explained in more detail below, or they can be different versions of the M5 binary. The name of the binary is "m5" with an extension that specifies what version to build. Currently supported versions are m5.debug, m5.opt, m5.fast, and m5.prof.
m5.debug has optimizations turned off. This ensures that variables won't be optimized out, functions won't be unexpectedly inlined, and control flow will won't behave in surprising ways. That makes this version easier to work with in tools like gdb, but without optimizations this version is significantly slower than the others. You should choose it when using tools like gdb and valgrind and don't want any details obscured, but other wise more optimized versions are recommended.
m5.opt has optimizations turned on and debugging functionality like asserts and DPRINTFs left in. This gives a good balance between the speed of the simulation and insight into what's happening in case something goes wrong. This version is best in most circumstances.
m5.fast has optimizations turned on and debugging functionality compiled out. This pulls out all the stops performance wise, but does so at the expense of run time error checking and the ability to turn on debug output. This version is recommended if you're very confident everything is working correctly and want to get peak performance from the simulator.
m5.prof is similar to m5.fast but also includes instrumentation that allows it to be used with the gprof profiling tool. This version is not needed very often, but can be used to identify the areas of M5 that should be focused on to improve performance.
These versions are summarized in the following table.
| Binary name | Optimizations | Run time debugging support | Profiling support |
|---|---|---|---|
| m5.debug | X | ||
| m5.opt | X | X | |
| m5.fast | X | ||
| m5.prof | X | X |
Command line options
Scons will recognize the following command line options specific to M5.
| Option | Effect |
|---|---|
| --color | Turn on colorized output |
| --no-color | Turn off colorized output |
| --default | Override which build_opts file to use for defaults |
| --ignore-style | Disable style checking hooks |
| --update-ref | Update test reference outputs |
| --verbose | Print full tool command lines |
Environment variables
The following environment variables are imported from the host environment for use in scons:
| Variable | Use |
|---|---|
| AS | Assembler command |
| AR | Archive tool command |
| CC | C compiler command |
| CXX | C++ compiler command |
| HOME | User's home directory |
| LD_LIBRARY_PATH | Path to search for library files |
| PATH | Path to search for programs |
| PYTHONPATH | Path to search for python files |
| RANLIB | Ranlib command |
| M5_CONFIG | Where to look for the special ".m5" directory |
| M5_DEFAULT_BINARY | The default build target which overrides the default default build/ALPHA_SE/m5.debug |
Configuration variables
These configuration variables are used to control the way M5 is built. Some are global, affecting all configurations built in the same build directory. Some are sticky, which means they retain their value once set. The available options are summarized in the following tables.
Global sticky
| Variable | Description | Default |
|---|---|---|
| CC | C Compiler | CC environment variable or value determined by scons |
| CXX | C++ Compiler | CXX environment variable or value determined by scons |
| BATCH | Use batch pool for build and tests | False |
| BATCH_CMD | Batch pool submission command | qdo |
| M5_BUILD_CACHE | Cache built objects in this directory | False |
| EXTRAS | Add extra directories to the compilation |
Global non-sticky
| Variable | Description | Default |
|---|---|---|
| VERBOSE | Print full tool command lines | False |
| update_ref | Update test reference outputs | False |
Non-global sticky
| Variable | Description | Default | Exported as config/*.hh |
|---|---|---|---|
| TARGET_ISA | Target ISA | alpha | X |
| FULL_SYSTEM | Full-system support | False | X |
| CPU_MODELS | CPU Models | AtomicSimpleCPU,InOrderCPU,O3CPU,TimingSimpleCPU | |
| NO_FAST_ALLOC | Disable fast object allocator | False | X |
| FAST_ALLOC_DEBUG | Enable fast object allocator debugging | False | X |
| FAST_ALLOC_STATS | Enable fast object allocator statistics | False | X |
| EFENCE | Link with Electric Fence malloc debugger | False | |
| SS_COMPATIBLE_FP | Make floating-point results compatible with SimpleScalar | False | X |
| USE_SSE2 | Compile for SSE2 (-msse2) to get IEEE FP on x86 hosts | False | |
| USE_MYSQL | Use MySQL for stats output | whether mysql_config was found | X |
| USE_POSIX_CLOCK | Use POSIX Clocks | whether posix clocks are available on this host | X |
| USE_FENV | Use <fenv.h> IEEE mode control | whether fenv.h was found on this host | X |
| USE_CHECKER | Use checker for detailed CPU models | False | X |
| CP_ANNOTATE | Enable critical path annotation capability | False | X |
| RUBY | Build with Ruby | False | |
| PROTOCOL | Coherence protocol for Ruby | MI_example | X |
| NO_HTML | Do not create HTML files | False | |
| NO_VECTOR_BOUNDS_CHECKS | Don't do bounds checks | True | X |
| GEMS_ROOT | Add debugging stuff to Ruby | the directory where GEMS is stored, currently src/mem | X |
Setting configuration variable values
The first way you set configuration variable values is through the configuration name you choose as part of the build target. This file is loaded from build_opts and contains preset values for some of these variables which configures the build as the file name suggests. For instance, using the SPARC_FS configuration will turn on full system mode with the FULL_SYSTEM variable and set the TARGET_ISA to sparc.
It is important to note that the values in the file corresponding to the configuration you picked are -default- values and are only used if no directory already exists with its own values already in place. Those files are for defining reasonable starting points to configure M5 to behave the way you want it to, and are not intended to actively configure a particular build.
If you want to change a value after your build and configuration directory is already created, or if you want to override a value as it's created, you can specify the new values on the command line. The syntax is similar to setting environment variables at a shell prompt, but these go after the scons command. For example, to turn on RUBY support for an existing ALPHA_FS build, you could use the following command.
scons RUBY=True build/ALPHA_FS/m5.opt
It's often a good idea to add --help to the scons command line which will print out all of the configuration variables and what their values are. This way you can make sure everything is set up like you want, and that you don't have any typos in any variable names. If everything is as you expect, you can remove --help to actually start the build.
