|
|
|
|
|
|
|
|
|
|
Repository Information |
|
|
|
|
|
|
Server: repository.eecs.berkeley.edu
SVN Repository Location: /public
Login Method: SSH with public keys(See the section on accounts below...)
URL: svn+ssh://repositorypub@repository.eecs.berkeley.edu/public/
Web Access: Open System Repository
Do not attempt to check out the entire repository, it is over 4GB at the current time, and only growing. See below for documentation about how to find what you need.
Note that there is also a private repository, which contains sensitive information.
|
|
|
|
|
|
|
|
|
Access |
|
|
|
|
|
|
There are two ways to access the repository. Public access is available through the Open System Repository.
Most code is published this way and licensed under the BSD license. The repository website will show an older version (6 months old) of the repository contents. To see the
current contents, you will need SSH access. SSH access will be granted only to researchers and industrial partners affiliated with
RAMP, BWRC, GSRC,
BEE2, BEE3, ParLab and related projects.
Access to the Subversion Repository is controlled by SSH public keys. To gain access you will need to
send an SSH public key, along with the following information to repository-admin <at> lists.berkeley.edu (plain text e-mail preferred).
- Full Name (Last name, first name):
- Affiliation(University or Company):
- Preferred Email Address:
- Personal Website:
- Requested Username:
- Requested Projects Access: See the repository layout at the bottom of this page for a list of projects in the repository.
- Project Name:
- Project Website:
- Grad Student Supervisor (Undergrads only. Last name, first name):
- Grad Student E-mail:
- Professor (Grad students & undergrads. Last name, first name):
- Professor E-mail:
- Please attach your SSH public key. See below for instructions on generating one, or you may use one you already have.
- Please list the repository etiquette rules, shown in bold below, as a sign that you have at least glanced over this page.
Once we have this information you will receive access within one business of our confirming your
information. In particular, access for people not associated with the RAMP project will likely be delayed.
Anyone with access to the repository must be on the mailing list for special announcements. This is
not optional, but it is a low traffic list. Changes to the information on this page will be announced
on that list.
Finally, there are some files which must be heavily restricted for NDA, licensing or security reasons.
It is highly unlikely that anyone needs access to these, but inquires should go to repository-admin <at> lists.berkeley.edu.
|
|
|
|
|
|
|
|
|
SSH Public Keys |
|
|
|
|
|
|
This section includes instructions for creating and using SSH public keys. Please let us know if you find
errors or missing information. There are a number of SSH key tutorials online. The author found
HOWTO: set up ssh keys particularly helpful.
-
Generating an SSH key pair
- Find a machine with command line SSH (OpenSSH) installed. Linux, UNIX and Cygwin machines should all fit the bill.
- If you need to convert an existing key, see below.
-
Create your key pair: ssh-keygen -t dsa [-f keyfile]. This command will generate keyfile
and keyfile.pub. The default for keyfile is ~/.ssh/id_dsa, which is
perfectly acceptable if you don't already have a key pair.
-
When prompted for a password, give one. Do not create a password-less key pair unless you know what you're doing, and if
you're reading these instructions you probably don't yet.
-
keyfile is your SSH private key. Save it for use on the machine from which you want to log in.
-
keyfile.pub is your SSH public key. Save a copy for yourself, and send a copy to repository-admin <at> lists.berkeley.edu.
- You may wish to run chmod 600 keyfile keyfile.pub to ensure that other users cannot access your keys. Remember that
allowing another user to access your public key is not a problem, but your private key should be just that: private.
-
Converting SSH Keys
- These instructions are courtesy of //burnz.blog
- Find a machine with command line SSH (OpenSSH) installed. Linux, UNIX and Cygwin machines should all fit the bill.
-
Convert OpenSSH to SSH2: ssh-keygen -e -f [openssh-keyfile.pub] > ssh2-keyfile.pub. This command will
generate ssh2-keyfile.pub.
-
Convert SSH2 to OpenSSH: ssh-keygen -i -f [ssh2-keyfile.pub] > openssh-keyfile.pub. This command will
generate openssh-keyfile.pub.
- An SSH2 key can be easily identified as if starts with the line -- BEGIN SSH2 PUBLIC KEY --.
- An OpenSSH key by contrast starts with either ssh-dsa or ssh-rsa, with the DSA keys being regarded as more secure.
-
Using & Testing Your Key
- If you wish to test your key pair, or use it for purposes other than the RAMP SVN Repository, these steps are for you.
-
You will need two machines, lets call them A and B. These instructions assume you are running
on A and wish to SSH in to B.
- Copy your keyfile.pub to system B: scp keyfile.pub username@B:~/keyfile.pub
-
Concatenate your key to your authorized_keys file which lists those keys which are allowed to login through
that account: ssh username@B "cat ~/keyfile.pub >> ~/.ssh/authorized_keys". Note that the password you enter
should be the one for the login (username) not the one for your key yet.
Dissecting this command, it is logging you in to B from A and concatenating your public key to
the end of the ~/.ssh/authorized_keys file, which SSH reads when you try to log in.
-
Test your login: ssh [-i keyfile] username@B. Assuming that your keyfile was the default, you may omit the
-i option. When you are prompted for a password, use the password from your key. If the login succeeds you are in business.
- Feel free to delete keyfile.pub on B: ssh [-i keyfile] username@B "rm keyfile.pub"
-
Testing Your Repository Access
- Generate an SSH key (see above) and request repository access (see above).
-
This example will show how to use your public key with command line subversion. For other
clients (SmartSVN), please see their help files.
-
Attempt to just log in: ssh -i keyfile repositorypub@repository.eecs.berkeley.edu. This should print something like
( success ( 1 2 ( ANONYMOUS EXTERNAL ) ( edit-pipeline svndiff1 absent-entries ) ) ) and you will need to press
Control-C to exit. If this succeedes, you have access to the repository.
-
Check out the repository test directory (works on Linux, UNIX and cygwin):
ssh-agent sh -c "ssh-add keyfile && svn co
'svn+ssh://repositorypub@repository
/public/GettingStarted/trunk/'
'GettingStarted'".
You may need to use repository.eecs.berkeley.edu as the hostname, if you are not on the Berkeley network. Make sure there is no space in
the middle of your URL (between repository and /public).
This command will load ssh-agent, create a sh subshell, and then load your SSH key into the agent, and run
svn to check out a test directory. The convoluted form of this command is necessary (on some machines) to ensure that
the copy of ssh which svn runs has access to your SSH key.
|
|
|
|
|
|
|
|
|
How to Use Subversion (SVN)
|
|
|
|
|
|
|
The primary and best source of help for subversion usage is the subversion book,
though first time users may wish to instead start with Basic Usage.
Google will also return numerous useful pages including
a brief list of commands.
The main subversion project website will allow you to download the
standard client command line tools.
Many of the people on the RAMP project use the SmartSVN client, which is
platform agnostic (Java based) and provides an easy-to-use GUI.
We hope to be adding some more detailed tutorials soon, please let us know if there's anything in particular that isn't clear to you
so that we can document it.
|
|
|
|
|
|
|
|
|
Repository Etiquette |
|
|
|
|
|
|
Make use of the repository!
- The first rule of the repository: commit everything not automatically generated.
-
The second rule of the repository: commit everything not automatically generated. This means that all source code, documentation,
web page, papers and even installers and the documentation you are relying on are fair game. However, you should avoid comitting
the PDF of a paper written in Tex, a Java
.class file for which you have the .java file, or the non-code
files from a ModelSim or Xilinx ISE project.
- Learn it, live it, love it: if it's not in the repository, it doesn't exist!
- E-mail repository-admin <at> lists.berkeley.edu if you have trouble rather than avoiding using the repository. We're nice people
- If you're worried about someone seeing what you think isn't your best work, consider using your
/trunk/Private/username directory.
-
If you've got a class project related to RAMP, we're happy to give you space in
/trunk/Shared with proper access control so that other current
students in the class can't see your work, but we can move it to a more prominent location when it turns out to be useful.
Use good commit messages.
Commit messages are how other people know what you're up to. Make it easy for them.
- Bad Examples:
- "Initial Import"
- "Changed some stuff"
- "Fixed"
- Good Examples:
- "BEEKeeper - Initial Import"
- "RDLC1 & 2 - Updated copyright dates to include 2008"
- "RAMP Website - Posted RAMP Blue v4.0 photos"
- Awesome Example (1 message!):
BSD License Correction - Switch to 2 clause
Below is a list of regular expressions used to accomplish this
Regex1 Search
Regex1 Replacement
Regex2 Search
Regex2 Replacement
-
Notice that the "awesome example" is an 8 line commit message which includes not just an explanation of the changes,
but the regular expressions used to make them happen! So then when some poor student has to figure out how someone changed
200 files in one commit it is real clear.
Use svn:externals rather than duplicating things!
Of course it's better to just reference the relevant code or document, e.g. in a makefile, but for those rare occasions where
the thing you're interested in is somewhere completely different in the repository (or in another repository altogether) use
svn:externals so that the person who comes after you can find all the relevant files.
Basically you set a "property" (something SVN supports) on a directory which means "when you check out this directory, go check out this other crap and put it at the given path".
The SVN Book explains externals in great detail.
If you're using SmartSVN, just right click on the directory, go to "external" and you'll get a helpful little dialog box. Watch
out for spaces in path names (if it's in the local path it will cause trouble, if it's in the URL, change it to %20 to avoid trouble).
Use svn copy and svn move!
These commands will allow SVN to track the fact that you moved or copied a file, instead of thinking you just created a
new file. Feel free to also use a client like SmartSVN, which will try to help you out when you forget this, but guessing
(and asking you) if files were copied.
|
|
|
|
|
|
|
|
|
Directory Structure |
|
|
|
|
|
|
It is highly recommended that you do not check out the entire repository, as it is over 10GB for a single working copy.
Instead, find the directories you need and check them out one by one.
Each user and project in the repository has it's own source control tree include the standard SVN layout (branches, tags and trunk)
according to the Recommended Repository Layout
and Branching and Merging, thereby allowing individual projects to
have separate branches and tags, and simply access control.
-
/GettingStarted/trunk/:
Contains a readme file for those people testing their SVN access, as well as some notes about undergrad RAMP project ideas
and how to get access to BWRC where RAMP research at U.C. Berkeley is centered.
Should be readable to everyone and writeable to no one.
-
/Private/username/trunk/:
Each user will have read and write access to their own source control tree under /Private. No other users
(aside from repository admin and backup users) will have any access to this tree.
If you have code or documentation
which is related to RAMP, BEE2 or another hosted project, the best option is to put it within the /Project
directory, but if this makes you nervous, your private directory is a better choice than
not putting it in SVN at all. Not only does this mean we have a vague record, should your computer die tomorrow, but once you
are ready to make it available to others, we can simply use SVN to copy it to the correct location, and all the history can
be effortlessly preserved.
One possible trick for those interested in avoiding a complete working copy checkout: use svn:external
properties on your private directory to mount the various projects, papers and other useful directories which you
actually need. Remember, an external doesn't have to come from a different repository!
-
/Projects/:
Contains one source control tree per project, please be careful to create only one tree per major project.
-
AppServer/trunk/:
Contains the application server, a program designed to launch an application on a computer architecture
simulator and provide runtime support.
-
BDB/trunk/:
A debugging project by Kevin Camera.
-
/Projects/BEE/trunk/:
-
2:
Contains the new BEE2 repository. This include several example applications, hardware cores as well as
pristine linux (software/linuxppc-2.4) and BORPH (software/borph) for the control FPGA, and of course the PCBs.
This directory is over 1GB!
-
3:
Contains the BEE3 repository. This includes both hardware cores and software. It also includes the
externals/BEE3 directory which contains all the documentation received from BEEcube, Chen Chang
and Microsoft about the BEE3, including the main UCF file.
-
BEEKeeper:
Contains the source code (hardware and software) for the BeeKeeper, a JTAG over Ethernet board meant to help
in the programming and debugging of large multi-BEE systems.
-
IBOB:
Contains the PCBs for the IBOB, ADC, DAC and various other BEE2 aadd-on boards.
-
Website:
Contains the BEE2 and
BEE websites in source form.
-
BORPH/trunk/:
The BORPH FPGA operating system by Hayden So.
-
borph:
The BORPH source code, including the "patches" needed to modify the linux kernel.
-
BEE2:
Contains externals for pristine BEE2 linux (linuxppc-2.4) and the complete BORPH linux
kernel (borph) which is created by patching the linuxppc-2.4 kernel.
-
Classes/trunk/:
Course material and code for EECS150 and
CS194-6 Fall2008 at U.C. Berkeley.
There is also some common course development materials related to these, and a few other classes.
Other course material should be added over time.
-
Externals/trunk/:
Collected code and documentation from external projects. For example if two projects in this repository both
need the same library, it belongs here. For more information about the layout of this project, please see the
GateLib documentation.
-
GateLib/trunk/ & GateLib/branches/dev/:
A standard Gateware, Firmware and Tools library, used by EECS150,
RAMP and a number of other projects at U.C. Berkeley.
Contains the I/O library and FPGA_TOP files library for the CaLinx
boards, along with a number of the Digilent FPGA boards. Most
importantly GateLib contains standard Verilog modules which should be widely used. GateLib also contains
the XTools (ANTEDA, ANTTools, SVNTools, PubTools) and XLink (UART, VPI, Ethernet) suites. Write
access to the dev branch is relatively freely given, and fixes and suggestions are highly encouraged.
Over time stable cores are published to trunk for wider circulation.
-
HomeGateway/trunk/:
Source code and papers from the Protean Living project,
formerly called "Home Gateway."
-
IIAB/trunk/:
Code from the Internet-in-a-Box project, including a SPARC processor implementation, an FPU and
a network emulator.
-
Misc/trunk/ & Misc/branches/dev:
Contains a number of miscellaneous projects, mostly those which are not directly related to research,
or which are not yet integrated in to a larger project. Development happens in the dev branch, and
code is occasionally "released" to the trunk. Many sub-projects start here until they are ready for
wider use. Some projects such as XTools (Including ANTEDA, BibTools, Publications Common, etc.) and
XLink (Including JavaVPI) have already graduate from this project to a more permanent home in GateLib.
-
RAMP/trunk/:
The code and papers for the RAMP Project.
-
Climate:
Contains the source code for the Climate machine. Note that there are externals in this directory which
reference the private repository, and which reference other parts of the repository. In particular this
project uses Tensilica processors, which are covered by various
contracts and thus private, as well as GateLib.
-
Cluster:
Contains code and notes for the BEE3, Website and VM cluster being assembled at UC Berkeley.
-
Gold:
Contains the source code for RAMP Gold. Note that there are externals in this directory which
reference the private repository.
-
Publications:
All the publications, papers, degrees, presentations and documents associated with the RAMP project.
-
Events:
One directory per event with the RAMP related posters, presentations, notes and such from that event. Please
create subdirectories as appropriate if there are multiple posters or presentations per event.
Please use SVN tags to tag the version of any talks which are given on various days, at various events. Directories
should contain all of the source files for the any presentation or poster be it a single powerpoint deck, or
a myriad of included images.
-
Memos:
Contains incomplete publications, working notes (in the Notes directory) and general documentation
detritus. Highly useful, particularly to those new to the project.
-
Papers:
One directory per paper, named with the paper title. Please make sure to include all source files (illustrations)
as well as the text of the paper. Be sure not to include auxiliary files or e.g. the output of latex (not even
a PS or PDF since they can be easily generated). This directory should include technical reports, publications
and even dissertations.
-
RDLC:
Contains the source code for RDLC1 and RDLC2. This includes the complete code history for both versions.
-
White:
Contains some example Bluespec source code from the RAMP white project.
-
Website:
Contains the RAMP website in source form.
-
Repository/trunk/:
Support code, scripts and the Repository website in source form.
-
/Shared/special/trunk/:
Though this is primarily a research repository, many students will check class projects, particular those related to
their research in to their /Private/username/trunk/ directory. This directory is similarly intended for
not-yet ready to be widely seen code, for example class projects or other such loosely related work, which should be
shared rather than private.
Course project directories should be of the form: Class - usernamess or Class - teamname
or even Class SemesterYear, which might contain all the course projects for that semester.
These directories will only be readable to the people in the relevant group, to handle the situation where multiple students
are in the same class but are not working together.
|
|
|
|
|
|
|
|
|
|
|
