Difference between revisions of "Repository"

From gem5
Jump to: navigation, search
(E-mailing Patches)
(remove link to deprecated contributing page.)
 
(22 intermediate revisions by 8 users not shown)
Line 1: Line 1:
M5 uses the [http://selenic.com/mercurial Mercurial] (a.k.a. hg) revision control system.  The full M5 Mercurial repository is directly accessible at http://repo.m5sim.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 accessible at https://gem5.googlesource.com
  
We host two M5 source repositories:
+
Clone it with:
* [http://repo.m5sim.org/m5-stable m5-stable] --- The (relatively) stable repository.  The head of this repository is the latest version that has passed a full set of regression tests.  This is the recommended repository for most users.  This repository is updated automatically from the development repository when the full set of regressions runs and completes successfully.  Currently, the full regression suite is run weekly, so this repository will be updated roughly that often.
 
* [http://repo.m5sim.org/m5 m5] --- The development repository.  Code changes are always committed to this repository first.  This code should work, because developers are supposed to run a limited set of regression tests before committing to this repository.  However, this code has generally not been tested against the full regression suite, and developers occasionally mess up and commit things that don't work as well as they expected.
 
  
===What is it?===
+
  git clone https://gem5.googlesource.com/public/gem5
[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 m5sim.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 m5sim.org repository into your local repository launching a merge tool whenever necessary. Additionally, patches can be sent to us for inclusion in the m5sim.org repository with a single command.
 
 
 
===Where can I get more information about it?===
 
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?===
+
There is also an official read-only GitHub mirror at: https://github.com/gem5/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 main method for contributing code to gem5 is via our Gerrit code review website: https://gem5-review.googlesource.com
# 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===
+
The CONTRIBUTING file https://gem5.googlesource.com/public/gem5/+/master/CONTRIBUTING.md documents on how to contribute to gem5.  
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:
+
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.
hg clone http://repo.m5sim.org/m5-stable
 
  
Once you've got a clone of the repository, here are a few basic commands you can use:
+
More general Git and Gerrit information:
* <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, m5-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===
+
* https://git-scm.com/book
For guidance on how to effectively extend M5 within the Mercurial framework, see our section on [[Adding Functionality]].
+
* https://gerrit-review.googlesource.com/Documentation/index.html

Latest revision as of 10:13, 3 March 2018

The gem5 repository is accessible at https://gem5.googlesource.com

Clone it with:

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

There is also an official read-only GitHub mirror at: https://github.com/gem5/gem5

The main method for contributing code to gem5 is via our Gerrit code review website: https://gem5-review.googlesource.com

The CONTRIBUTING file https://gem5.googlesource.com/public/gem5/+/master/CONTRIBUTING.md documents on how to contribute to gem5.

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.

More general Git and Gerrit information: