|
|
| (26 intermediate revisions by 8 users not shown) |
| Line 1: |
Line 1: |
| − | The M5 Repository uses the [http://selenic.com/mercurial Mercurial] (a.k.a hg) revision control system. The M5 repository is located at http://repo.m5sim.org. The repository website provides web access to history and changesets. See below about how to create your own copy of the repository on your local machine. | + | The gem5 repository is accessible at https://gem5.googlesource.com |
| | | | |
| − | There are two repositories that hold the M5 source code. Normally m5-stable will be automatically updated on a weekly basis from m5-dev. Generally we recommend that you use m5-stable.
| + | Clone it with: |
| − | * [http://repo.m5sim.org/m5-stable m5-stable] --- The last version of the repository that passed a full set of regression tests
| |
| − | * [http://repo.m5sim.org/m5 m5] --- The latest version of the repository, the code should all pass regression tests, however it has not been verified
| |
| | | | |
| | + | git clone https://gem5.googlesource.com/public/gem5 |
| | | | |
| − | ===What is it?===
| + | There is also an official read-only GitHub mirror at: https://github.com/gem5/gem5 |
| − | [http://www.selenic.com/mercurial Mercurial] (hg) is a distributed version control system. Every copy of a mercurial repository is complete---there is no one central copy of the repository---and any operation on it (committing changes, etc) without communicating with another repository. In brief it allows you to create a copy of the m5sim.org repository that is fully functional. Instead of having to manually diff/patch your changes when a new version is released simply executing a command will "pull" all changes in the m5sim.org repository into your local repository launching a merge tool whenever necessary. Additionally, sending patches to us for inclusion in the m5sim.org repository is a single command.
| |
| − |
| |
| | | | |
| − | ===Where can I get more information about it?===
| + | The main method for contributing code to gem5 is via our Gerrit code review website: https://gem5-review.googlesource.com |
| − | The main Mercurial website is [http://www.selenic.com/mercurial/ here]. Other good sources of information about Mercurial is the [http://hgbook.red-bean.com/ hg book] and the [http://www.ivy.fr/mercurial/ref/v1.0 HG Cheat Sheets]. We promise that it is worth taking 30 minutes to read some of the documentation to get you started. You may even decide that you really like hg and want to use it in your own projects. We do! | |
| | | | |
| − | ===How do I use it===
| + | The CONTRIBUTING file https://gem5.googlesource.com/public/gem5/+/master/CONTRIBUTING.md documents on how to contribute to gem5. |
| − | The first thing you need to do is install hg (from either package for your OS/distribution or from source). Debian and Ubuntu have packages named mercurial that you can install, MacPorts also has a package. The next thing you should do is setup a <code>.hgrc</code>. An example <code>.hgrc</code> is provided below. It enables various extensions that come with Mercurial and allows you to mail patches to the M5 mailing list if you so choose. | |
| | | | |
| − | [ui]
| + | The MAINTAINERS file https://gem5.googlesource.com/public/gem5/+/master/MAINTAINERS explains who are the subsystem maintainers. You may add them to reviews that touch a given subsystem. |
| − | # Set the username you will commit code with
| |
| − | username=Your Name <your@email.address>
| |
| − | ssh = ssh -C
| |
| − |
| |
| − | # Always use git diffs since they contain permission changes and rename info
| |
| − | [defaults]
| |
| − | qrefresh = --git
| |
| − | email = --git
| |
| − | diff = --git
| |
| − |
| |
| − | [extensions]
| |
| − | # These are various extensions we find useful
| |
| − |
| |
| − | # Mercurial Queues -- allows managing of changes as a series of patches
| |
| − | hgext.mq =
| |
| − |
| |
| − | # PatchBomb -- send a series of changesets as e-mailed patches
| |
| − | hgext.patchbomb =
| |
| − |
| |
| − | # External Diff tool (e.g. kdiff3, meld, vimdiff, etc)
| |
| − | hgext.extdiff =
| |
| − |
| |
| − | # Fetch allows for a pull/update operation to be done with one command and automatically commits a merge changeset
| |
| − | hgext.fetch =
| |
| − |
| |
| − | # Path to the style file for the M5 repository
| |
| − | # This file enforces our coding style requirements
| |
| − | style = /path/to/your/m5/util/style.py
| |
| − |
| |
| − | [email]
| |
| − | method = smtp
| |
| − | from = Your Name <your@email.address>
| |
| − |
| |
| − | [smtp]
| |
| − | host = your.smtp.server.here
| |
| | | | |
| − | ===Basic Commands===
| + | More general Git and Gerrit information: |
| − | Here are some basic commands for Mercurial, however this is not exhaustive and you should read the Mercurial documentation.
| |
| | | | |
| − | Cloning creates a complete and fully functional copy of a repository. To get started you should execute:<code> hg clone http://repo.m5sim.org/m5-stable</code>
| + | * https://git-scm.com/book |
| − | | + | * https://gerrit-review.googlesource.com/Documentation/index.html |
| − | Pull is used to update your repository with the latest changes on m5sim.org:<code> hg pull</code> If Mercurial downloaded any changes you'll need to update your repository with: <code>hg update</code> If you have any conflicting changes in your local repository you'll be prompted to merge them at this time. The fetch extension combines these two steps into one command as follows and we recommend you use it:<code> hg fetch</code>
| |
| − | | |
| − | You can see what files have been modified in your repository by executing: <code>hg status</code> and you can see a diff of the modified files by executing:<code>hg diff</code>.
| |
| − | | |
| − | | |
| − | | |
| − | ===Making Your Own Changes===
| |
| − | We highly recommend that you use Mercurial Queues(MQ) to make any changes to M5 that you personally need. There is a chapter on using MQ in the [http://hgbook.red-bean.com/hgbookch12.html HG-Book] you should take the time to read the chapter in the book, it will make your life much easier.
| |
| − | | |
| − | The basic idea of MQ is 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.
| |
| − | | |
| − | ===E-mailing Patches===
| |
| − | The [http://www.selenic.com/mercurial/wiki/index.cgi/PatchbombExtension patchbomb] extension is a great way to share patches with other users. It adds the <tt>hg email</tt> command which allows you to send a set of changesets (or mq patches) to the m5 developer's mailing list!
| |
| − | | |
| − | | |
| − | To e-mail us patches you'll need to add the following to <code>m5/.hg/hgrc</code> (or create it if it doesn't exist).
| |
| − | [email]
| |
| − | to = m5-dev@m5sim.org
| |
| − | Then to e-mail a particular changeset simply execute: <code>hg email [REV]</code>
| |
| − | | |
| − | __NOTOC__
| |
