Difference between revisions of "Repository"

From gem5
Jump to: navigation, search
Line 1: Line 1:
gem5 uses the [http://selenic.com/mercurial Mercurial] (a.k.a. hg) revision control system.  The gem5 repositories are directly accessible at http://repo.gem5.org.  This website provides browser access to history and changesets and the ability to "clone" (create your own copy of) the repository on your local machine.
+
The gem5 repository is directly accessible at https://gem5.googlesource.com/.  This website provides browser access to history and changesets and the ability to "clone" (create your own copy of) the repository on your local machine. For more information on how to use git, please see https://git-scm.com/book.
  
We host several source repositories, including:
+
To clone the master gem5 repository:
* [http://repo.gem5.org/gem5 gem5] --- The development repository.  Code changes are always committed to this repository first.  This code should work, because developers are supposed to run all regression tests before committing to this repository.  However, there are cases where code has not been tested against the full regression suite, or differences in the test environment causes issues. In cases where tests are failing they are usually fixed in a matter of days.
+
> git clone https://gem5.googlesource.com/public/gem5
  
* [http://repo.gem5.org/encumbered encumbered] --- A repository for extensions to gem5 that are under a different, more restrictive license. Currently this only includes support for SimpleScalar's EIO trace format.
+
There are a few repositories other than the main gem5 development repository.
  
* [http://repo.gem5.org/linux-patches linux-patches] --– A repository for patches to the linux kernel that modify it so it can be simulated more efficiently. These patches are optional, but it's a good idea to use them if possible to cut down on simulation run time.
+
* public/m5threads: The code for a pthreads implementation that works with
 +
  gem5's syscall emulation mode.
  
Usually the development repository is better suited for those working on or requiring the latest gem5 features. If you intend to contribute your work (and we strongly encourage you to), then using the development repository is advised. If you like knowing gem5-stable has passed all of our regression tests, try that one. If whatever you try doesn't work for you, try the other one, as there may have been bugs fixed/introduced between stable and dev.  If neither works for you, go ahead and ask the mailing list.  Read [[Reporting Problems]] before sending your question to the mailing list.
+
The main method for contributing code to gem5 is via our code review website:
 
+
https://gem5-review.googlesource.com/. More information can be found
===What is Mercurial?===
+
from the following sources:
[http://www.selenic.com/mercurial Mercurial] (hg) is a distributed version control system. Every copy of a mercurial repository is complete and fully functional.  Any operation (examining history, committing changes, etc) can be done without communicating with a central repository.  (In fact, from mercurial's point of view, there is no central repository; the gem5.org repositories are "central" only by user convention.)  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 gem5.org repository into your local repository launching a merge tool whenever necessary. Additionally, patches can be sent to us for inclusion in the gem5.org repository with a single command.
+
  * http://gem5.org/Submitting_Contributions
 
+
* https://gerrit-review.googlesource.com/Documentation/index.html
===Where can I get more information about it?===
 
The main Mercurial website is [http://www.selenic.com/mercurial/ here].  Joel Spolsky wrote a nice [http://hginit.com tutorial] about mercurial.  The [http://hgbook.red-bean.com/ hg book] is also a good source of more in-depth information. 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 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>$HOME/.hgrc</code>. An example <code>.hgrc</code> is provided below. It enables various extensions that come with Mercurial.
 
 
 
[ui]
 
# 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 =
 
 
 
# 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 gem5 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===
 
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:
 
  hg clone http://repo.gem5.org/gem5-stable
 
 
 
Once you've got a clone of the repository, here are a few basic commands you can use:
 
* <code>hg status</code> shows what files have been modified in your repository
 
* <code>hg diff</code> shows a diff of the modified files
 
* <code>hg fetch</code> fetches any new updates from the repository you cloned (in this case, gem5-stable), and if necessary merges them with any changes you have made since the last update. Note that <code>fetch</code> is a convenient extension that combines several other primitive hg operations that you can also do separately: <code>hg pull</code>, <code>hg update</code>, and if needed <code>hg merge</code> and <code>hg commit</code>. See the mercurial documentation for more details.
 
 
 
===Making Your Own Changes===
 
For guidance on how to effectively extend gem5 within the Mercurial framework, see our section on [[Adding Functionality]].
 
__NOTOC__
 

Revision as of 09:21, 1 March 2017

The gem5 repository is directly accessible at https://gem5.googlesource.com/. This website provides browser access to history and changesets and the ability to "clone" (create your own copy of) the repository on your local machine. For more information on how to use git, please see https://git-scm.com/book.

To clone the master gem5 repository:

> git clone https://gem5.googlesource.com/public/gem5

There are a few repositories other than the main gem5 development repository.

* public/m5threads: The code for a pthreads implementation that works with
  gem5's syscall emulation mode.

The main method for contributing code to gem5 is via our code review website: https://gem5-review.googlesource.com/. More information can be found from the following sources:

* http://gem5.org/Submitting_Contributions
* https://gerrit-review.googlesource.com/Documentation/index.html