Difference between revisions of "Extras"

From gem5
Jump to: navigation, search
(New page: The <code>EXTRAS</code> SCons option is a way to add functionality in M5 without adding your files to the M5 source tree. It's present to allow a user to compile in additional functionalit...)
 
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The <code>EXTRAS</code> SCons option is a way to add functionality in M5 without adding your files to the M5 source tree. It's present to allow a user to compile in additional functionality that isn't or can't be distributed with M5. This is useful for code that has an incompatible license, or code that is not suitable for inclusion in the M5 source tree at the present time.  
+
The <code>EXTRAS</code> SCons option is a way to add functionality in gem5 without adding your files to the gem5 source tree. Specifically, it allows you to identify one or more directories that will get compiled in with gem5 as if they appeared under the 'src' part of the gem5 tree, without requiring the code to be actually located under 'src'.  It's present to allow user to compile in additional functionality (typically additional SimObject classes) that isn't or can't be distributed with gem5. This is useful for maintaining local code that isn't suitable for incorporating into the gem5 source tree, or third-party code that can't be incorporated due to an incompatible license.  Because the EXTRAS location is completely independent of the gem5 repository, you can keep the code under a different revision control system as well.
  
The EXTRAS functionality is used to support EIO traces. The trace reader for EIO is licensed under the SimpleScalar license and the code to read these traces is not included in the M5 distribution.  
+
The main drawback of the EXTRAS feature is that, by itself, it only supports adding code to gem5, not modifying any of the base gem5 code. If you are changing the base gem5 code (instead of or in addition to adding code with EXTRAS), see [[Managing Local Changes with Mercurial Queues]].
  
The next examples show how to compile the EIO code, however if the extras path is modified any other suitable extra could be compiled in. To compile in code using EXTRAS simply execute the following
+
One use of the EXTRAS feature is to support EIO traces. The trace reader for EIO is licensed under the SimpleScalar license, and due to the incompatibility of that license with gem5's BSD license, the code to read these traces is not included in the gem5 distribution. Instead, the EIO code is distributed via a separate "encumbered" [[repository]].
scons EXTRAS=/path/to/m5_2.0_encumbered/eio build/ALPHA_SE/m5.opt
 
  
Inside the directory is a SConscript that SCons uses to compile the appropriate sources and add any SimObjects of iterest.
+
The following examples show how to compile the EIO code.  By adding to or modifying the extras path, any other suitable extra could be compiled in. To compile in code using EXTRAS simply execute the following
 +
scons EXTRAS=/path/to/encumbered build/ALPHA/gem5.opt
 +
 
 +
In the root of this directory you should have a SConscript that uses the <code>Source()</code> and <code>SimObject()</code> scons functions that are used in the rest of M5 to compile the appropriate sources and add any SimObjects of interest. If you want to add more than one directory, you can set EXTRAS to a colon-separated list of paths.
 +
 
 +
Note that EXTRAS is a "sticky" parameter, so after a value is provided to scons once, the value will be reused for future scons invocations targeting the same build directory (<code>build/ALPHA_SE</code> in this case) as long as it is not overridden.  Thus you only need to specify EXTRAS the first time you build a particular configuration or if you want to override a previously specified value.  For more information on sticky scons options, see the [[SCons build system]] page.
  
 
To run a regression with EXTRAS use a command line similar to the following:
 
To run a regression with EXTRAS use a command line similar to the following:
  ./util/regress --scons-opts="EXTRAS=/tmp/m5_2.0b4_encumbered -j2" quick
+
  ./util/regress --scons-opts="EXTRAS=/path/to/encumbered" -j 2 quick

Latest revision as of 20:27, 22 May 2015

The EXTRAS SCons option is a way to add functionality in gem5 without adding your files to the gem5 source tree. Specifically, it allows you to identify one or more directories that will get compiled in with gem5 as if they appeared under the 'src' part of the gem5 tree, without requiring the code to be actually located under 'src'. It's present to allow user to compile in additional functionality (typically additional SimObject classes) that isn't or can't be distributed with gem5. This is useful for maintaining local code that isn't suitable for incorporating into the gem5 source tree, or third-party code that can't be incorporated due to an incompatible license. Because the EXTRAS location is completely independent of the gem5 repository, you can keep the code under a different revision control system as well.

The main drawback of the EXTRAS feature is that, by itself, it only supports adding code to gem5, not modifying any of the base gem5 code. If you are changing the base gem5 code (instead of or in addition to adding code with EXTRAS), see Managing Local Changes with Mercurial Queues.

One use of the EXTRAS feature is to support EIO traces. The trace reader for EIO is licensed under the SimpleScalar license, and due to the incompatibility of that license with gem5's BSD license, the code to read these traces is not included in the gem5 distribution. Instead, the EIO code is distributed via a separate "encumbered" repository.

The following examples show how to compile the EIO code. By adding to or modifying the extras path, any other suitable extra could be compiled in. To compile in code using EXTRAS simply execute the following

scons EXTRAS=/path/to/encumbered build/ALPHA/gem5.opt

In the root of this directory you should have a SConscript that uses the Source() and SimObject() scons functions that are used in the rest of M5 to compile the appropriate sources and add any SimObjects of interest. If you want to add more than one directory, you can set EXTRAS to a colon-separated list of paths.

Note that EXTRAS is a "sticky" parameter, so after a value is provided to scons once, the value will be reused for future scons invocations targeting the same build directory (build/ALPHA_SE in this case) as long as it is not overridden. Thus you only need to specify EXTRAS the first time you build a particular configuration or if you want to override a previously specified value. For more information on sticky scons options, see the SCons build system page.

To run a regression with EXTRAS use a command line similar to the following:

./util/regress --scons-opts="EXTRAS=/path/to/encumbered" -j 2 quick