Difference between revisions of "Adding Functionality"

From gem5
Jump to: navigation, search
(New page: This page describes the methods available to extend M5 while preserving the ability to update to new versions. If you intend to make any changes to M5 we '''strongly''' advise you to follo...)
 
(Clean out a bunch of redundant info)
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
This page describes the methods available to extend M5 while preserving the ability to update to new versions. If you intend to make any changes to M5 we '''strongly''' advise you to follow one of the following methods. It will save you a great deal of time in the future and allow you to take advantage of new M5 versions without the error prone process of manually diffing and patching versions.
+
If you find the need to modify or extend gem5, you may be tempted to just start editing files in your local gem5 repository.  While this approach will work initially, it will cause problems if/when you decide to update your copy of gem5 with changes that have been made since you originally cloned the repository.  It's very likely that you will want to update your code to get bug fixes and new features. Thus we '''strongly''' advise you to follow one of the following methods. It will save you a great deal of time in the future and allow you to take advantage of new gem5 versions without the error prone process of manually diffing and patching versions.
  
−
There are two recommend ways to add your own functionality to M5 and retain the ability to revision control your own code. The first suggested method relies on the queues feature of Mercurial (the revision control tool used for M5 development). The second relies on your own source control scheme (you could use mercurial or something else), and instead uses the [[Extras]] functionality in the build process to link extra objects into M5. In some situations a hybrid approach may be the best one, where the features you're attempting to evaluate are handled via the extras functionality, and minor changes to interfaces are done with Mercurial queues.
+
There are two recommend ways to add your own functionality to gem5 and retain the ability to revision control your own code: Mercurial Queues (MQ) and the EXTRAS feature of our build system.
  
 +
Mercurial Queues is the most powerful option, as it tracks changes you make to the existing gem5 code as well as files you may add to the source tree.  It's also the recommended path for developing changes that you contribute back to the public code base (see [[Submitting Contributions]]).  For more information, see [[Managing Local Changes with Mercurial Queues]].
  
−
1. The first method is using [http://hgbook.red-bean.com/hgbookch12.html Mercurial Queues](MQ).  MQ provides management commands inis to provide management commands to create and apply patches to an upstream source tree. When the underlying source tree is updated (see above), you can remove your patches, get the new changes and reapply your patches very quickly. The patches themselves can be an complete mercurial repository that is revision controlled. It's essential to read the above chapter in the Mercurial manual to understand this process, but briefly you would begin by creating a mercurial queues repository. You can then add patches to the mercurial queues repository and automatically update them based on the changes you've made. With this method it is good to segment changes into logical blocks rather than have one large patch for all your changes. When it comes time to update to a new version of M5 you remove all your patches from the repository, update to the latest version and add re-apply all of your patches. Normally this requires minimal effort. For example:
+
The [[Extras | EXTRAS]] option is more limited, in that it only allows you to compile additional files in to the gem5 code base, rather than changing or overriding existing files. However, the code compiled with EXTRAS is completely decoupled from the gem5 repository, and thus can be managed separately (e.g., in a different Mercurial repository, or using a completely different revision control system). EXTRAS can also be used to incorporate code that can't be distributed with gem5 due to licensing issues (e.g., the "encumbered" [[repository]]).  Often users end up using EXTRAS to incorporate new SimObject models while they concurrently manage a (ideally much smaller) set of changes using MQ.  See the [[Extras | EXTRAS]] page for more details.
−
<pre>
 
−
hg qinit -c
 
−
hg qnew my_new_feature.diff
 
−
  echo "// No so much a new feature as an additional line in the source tree" >> src/sim/main.cc
 
−
hg qrefresh # my_new_feature.diff now contains the the extra line in the source tree
 
  
−
# Remove the patch by executing
 
−
hg qpop
 
−
# Reapply the patch by executing
 
−
hg qpush
 
−
# Commit the changes to the path
 
−
hg qcommit
 
  
−
#To update to the latest version of M5
+
__NOTOC__
−
hg qpop -a
 
−
hg fetch
 
−
hg qpush -a
 
−
 
 
−
# Again PLEASE read the manual
 
−
</pre>
 
−
 
 
−
2. The other method relies on the extras functionality in the build process. You can create new models for M5 and place them in a directory of your choosing. If you would like to use mercurial to revision control this directory, you may, however you can control revisions in any manner. In the root of this directory you should have a SConscript that uses the <code> Source()</code> and <code>SimObject()</code> scons function that are used in the rest of M5. An example of how this works is provided in the encumbered directory.
 

Latest revision as of 00:43, 23 May 2015

If you find the need to modify or extend gem5, you may be tempted to just start editing files in your local gem5 repository. While this approach will work initially, it will cause problems if/when you decide to update your copy of gem5 with changes that have been made since you originally cloned the repository. It's very likely that you will want to update your code to get bug fixes and new features. Thus we strongly advise you to follow one of the following methods. It will save you a great deal of time in the future and allow you to take advantage of new gem5 versions without the error prone process of manually diffing and patching versions.

There are two recommend ways to add your own functionality to gem5 and retain the ability to revision control your own code: Mercurial Queues (MQ) and the EXTRAS feature of our build system.

Mercurial Queues is the most powerful option, as it tracks changes you make to the existing gem5 code as well as files you may add to the source tree. It's also the recommended path for developing changes that you contribute back to the public code base (see Submitting Contributions). For more information, see Managing Local Changes with Mercurial Queues.

The EXTRAS option is more limited, in that it only allows you to compile additional files in to the gem5 code base, rather than changing or overriding existing files. However, the code compiled with EXTRAS is completely decoupled from the gem5 repository, and thus can be managed separately (e.g., in a different Mercurial repository, or using a completely different revision control system). EXTRAS can also be used to incorporate code that can't be distributed with gem5 due to licensing issues (e.g., the "encumbered" repository). Often users end up using EXTRAS to incorporate new SimObject models while they concurrently manage a (ideally much smaller) set of changes using MQ. See the EXTRAS page for more details.


Retrieved from "http://repo.m5sim.org/wiki/index.php?title=Adding_Functionality&oldid=7848"