gem5学习4——Build System

原文参见：gem5 Build System

gem5建立系统是基于SCons的，SCons是一个Python的系统建立开源应用。更多信息参见http://www.scons.org。SCons的主文件名为SConstruct，放在源代码根目录下。其他的SCons文件命名为SConscript，放在其它位置，通常与相关文件同目录。

建立目标

gem5中，使用SCons建立目标的格式为//。例如：

scons build/ARM/gem5.opt

是以build结尾的文件夹路径。通常是build，但也可以指定位于其它位置的名为build的文件夹。同一build目录下的所有目标由假定由同一主机平台编译，并且共享相同的全局变量设置。这些全局变量设置位于build/variables.global文件中。 

（例子中的ARM）选择一系列编译时的建立选项用以控制模拟器功能，例如ISA种类、CPU模式、Ruby一致性协议等。这些单独配置变量存在build/variables目录下不同的文件中。这个位置可用于彻底清除一次build下的所有配置文件（例如使用rm -rf）的同时保留变量设置。
第一次建立一个特定的配置时，通过在build_opts目录下寻找配置名，决定默认的单独配置变量设置。如果想要创建一个在上述目录下找不到的配置名，用--default 告诉SCons需要使用build_opts或build/variables下的哪个文件作为默认文件。

（例子中的gem5.opt）是要建立的gem5二进制类型，指定了要用到的编译器标志（compiler flags）集合。目前支持版本有：gem5.debug, gem5.opt, gem5.fast, gem5.prof, gem5.perf。

• gem5.debug 关闭了优化。保证变量不会被优化掉，功能不会被意料外的内联（inlined），以及控制流行为正常。该版本与gdb类的工具合作良好，然而关闭优化会造成该版本明显慢于其它版本。当使用gdb或valgrind等工具并且不希望任何细节被模糊掉时应该选择该版本，否则建议选择其它版本。
• gem5.opt 打开优化的同时保留了部分调试功能（例如，断言和DPRINTFs）。该版本良好地平衡了模拟速度与调试观察，是所有环境中最优的版本。
• gem5.fast 打开优化并关闭调试部分。最优的速度，代价是不能进行运行时错误检查与调试输出。如果确信所有功能可以正确运行并想要获得峰值性能，建议使用该版本。
• gem5.prof 类似于gem5.fast，但仍然保留了一些功能（instrumentation）可以用于gprof分析工具。该版本不常用，但可以用于找出gem5中应当被注意的部分以提升性能。
• gem5.perf 同gem5.prof，但是instrumentation使用google perftools，允许被google-pprof分析。该分析版本是gem5.prof的补充，可能可以在所有基于Linux的系统中替换gem5.prof。

下表总结以上版本：

Binary name	Optimizations	Run time debugging support	Profiling support
gem5.debug	No	Yes	No
gem5.opt	Yes	Yes	No
gem5.fast	Yes	No	No
gem5.prof	Yes	No	Yes
gem5.perf	Yes	No	Yes

命令行选项

gem5中SCons识别以下命令行选项：

Option	Effect
–colors	Turn on colorized output
–no-colors	Turn off colorized output
–default	Override which existing build configuration or 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

环境变量

以下环境变量由主机环境引入，用于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 at loading time
LIBRARY_PATH	Path to search for library files at linking time
PATH	Path to search for programs
PROTOC	protobuf compiler command
PYTHONPATH	Path to search for python files
RANLIB	Ranlib command
SWIG	swig 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/gem5.debug

配置变量

这些配置变量用于控制gem5的建立方式。有些是全局变量，影响build目录中的所有配置；有些只影响当前正在build的配置。不同于命令行选项，这些变量在SCons调用之间保留它们的值。

Global

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

Per Configuration

Variable	Description	Default	Exported as config/*.hh
CP_ANNOTATE	Enable critical path annotation capability	False	X
CPU_MODELS	CPU Models	AtomicSimpleCPU,InOrderCPU,O3CPU,TimingSimpleCPU
PROTOCOL	Coherence protocol for Ruby	MI_example	X
SS_COMPATIBLE_FP	Make floating-point results compatible with SimpleScalar	False	X
TARGET_ISA	Target ISA: ALPHA, ARM, MIPS, POWER, X86	alpha	X
USE_CHECKER	Use checker for detailed CPU models	False	X
USE_FENV	Use IEEE mode control	whether fenv.h was found on this host	X
USE_POSIX_CLOCK	Use POSIX Clocks	whether posix clocks are available on this host	X

设置配置变量的值

第一种方法是通过在建立目标时选择的配置名。从build_opts加载文件，其中包含部分预置值。

注意，文件中的值是默认值，只在没有指明变量值时使用。这些文件用于定义配置gem5的合理起始点，并非用于配置一个特定的build。

如果在建立后，配置文件夹已经被创建的情况下，想要改变变量的值；或者覆盖一个已被创建的值，可以在命令行指明新的值。语法类似于在shell提示符中设置环境变量的值，但是在scons命令后使用。例如，为已建立的ALPHA创建MESI_CMP_directory协议，可以使用如下命令：

scons PROTOCOL=MESI_CMP_directory build/ALPHA/gem5.opt

可以在scons命令行后添加–-help查看所有的配置变量以及其值。这种方法可以确保所有设置都是如你所想，并且所有的变量名都没有拼写错误。如果一切顺利，则可以移除-–help并开始build。

回归运行/测试

gem5的回归系统内置于SCons。这保证了gem5二进制文件在必要的时候可以自动重建，测试只在可能有不同结果时重新运行。

回归目标都在build目录下的tests中。测试输出文件路径确定了运行哪个测试以及如何运行。如下所示：

tests///////

可以省略路径，scons将自动build所有匹配指明的组件的可用测试。运行ALPHA配置下opt模式的所有快速测试，可以运行如下命令：

scons build/ALPHA/tests/opt/quick

回归框架集成在scons建立过程中，如果必要，在运行tests前上述命令将会(re)build ALPHA/gem5.opt。仅在test上一次被运行是rebuild前时，test会被重新运行。如果test的上一次运行仍然合法，基于上一次结果，只有一些简明的pass/fail信息会被输出，而不是完整的输出和统计数据。

回归测试基于运行时间被细分为quick和long两类。通过在目标路径上添加分类名可以运行特定类的test。例如：

scons build/ALPHA/tests/opt/long

附加test名可以运行特定测试：

scons build/ALPHA/tests/opt/quick/fs/10.linux-boot

更多信息见： Regression Tests 。

一些”quick”测试要求在没有附加设置的前提下运行。一些测试基于EIO支持，需要通过EXTRAS机制将encumbered库建立到gem5中。其它测试依赖系统文件，如在系统中特定位置的特定磁盘映像和内核。这些文件通常可用，不难找到。其它测试，通常基于SPEC benchmarks并且不属于”quick”类的，需要严格许可证的输入文件，我们无法发布。除非拥有许可证，否则这些测试无法被运行。

添加源文件和调试标记

通过在SConscript文件中将要添加的文件声明为python类的实例。编译系统基于使用的指定类知道如何处理这些文件。例如，将C++源文件foo.cc添加到系统中，可以在foo.cc同目录下的Sconscript中加入：

Source(‘foo.cc’)

编译系统自动查找并处理SConscript文件，可以在添加的文件附近创建一个文件或者拓展一个已经存在的文件。下表所示为源文件类型和功能。

Source file type	Description		Parameters
		Name	Description
PySource	Add a python source file to the named package	package	The name of the package
		source	The name of the python source file
SimObject	Add a SimObject python file as a python source object and add it to a list of sim object modules	source	The relative path to the python file defining the SimObject.
Source	Add a c/c++ source file to the build	source	Relative path to source file
		Werror	Whether to compile with -Werror. Defaults to True.
		swig	Whether to use flags suitable for a swig wrapper C++ file. Defaults to False.
		main	This file is part of main() for the gem5 binary. Defaults to False.
		skip_lib	Whether this file should be excluded from the library version of gem5. Defaults to False.
SwigSource	Add a swig file to the build	package	Package for the python version of the source.
		source	Relative path to the swig input file.
UnitTest	Add a unit test to the build	sources	A list or tuple of relative paths to the source files for the unit test.

定义调试/跟踪标记的机制类似，但不是指定文件。一个复合跟踪标记用于控制一组跟踪标记。

Trace flag type	Description		Parameters
		Name	Description
DebugFlag	Add an individual trace flag to the build.	name	The name of the new trace flag.
		desc	A description for this flag. This is optional but recommended.
CompoundFlag	Add a compound trace flag to the build.	name	The name of the new compound trace flag.
		flags	A list or tuple of the names of trace flags which this new compound trace flag will control.
		desc	A description for this flag. This is optional but recommended.

使用EXTRAS

EATRAS scons变量可用于将其他的源文件目录编译进gem5，用冒号将路径分开。EATRAS是一种在gem5代码基础上编译的便利方式，不会将新源码与上游源码混淆。可以独立管理自己的代码。