SVN version control

Historical note: OpenCores changed the revision control system from CVS to SVN in March 2009. All projects were then transferred over to SVN (with all historical information included).

An introduction to SVN

Subversion (shorted SVN) [1] is a free source code manager and version control system intended to replace CVS (Code Versioning System). SVN is and has been extensively used to share cooperative work.

Getting started with Subversion

The easiest way to see the benefits of Subversion is to use it. Getting started might look intimidating at first, but with the use of a simple set of command line instructions – or with the help of graphical tools as tortoise or rabbitvcs - the learning process can be short-ciruited.

1. Installing a Subversion client To get started, you will need a subversion client, and the ability to create your first repository. The database which Subversion uses to store your files in the repository is Berkeley DB version 4[6].

   For Debian users, Subversion is included in unstable. For RedHat and Mandrake (and other RPM based distributions), there are RPMs, available off the project download page. For everyone else, you can build from sources. The latest release source tarballs are available on the Subversion site [7].

   To build from sources, look at section II of the install guide [8]. The basic procedure is the usual ./configure, make, make install.

   If you want to build from the latest sources, the requirements are a little more complicated - see the install guide for details.

2. Learn Subversion in 3 minutes Here's a short list of the most common subversion commands along with a description of what they do. A slightly more detailed list is available in the Subversion Quick Guide [11], and a comprehensive description of all commands available in Subversion is available in the Subversion book [3].

   Command	Description
   co/checkout	Check out a copy of the source code to a working copy
   ci/commit	Commit your local changes to the repository
   up/update	Update your working copy to reflect changes to the repository since your last update
   status	New in Subversion - summarise your local changes, without talking to the repository, or summarise resources that are out of date without updating
   add, remove/rm	Add or remove files to/from version control
   copy/cp, move/mv	New in Subversion - copy/move a file or directory to another file, keeping old version history
   merge	Equivalent to cvs update -j - merge changes from another location into the working copy
   switch	Change your working copy to use another branch
   diff	Get differences between your working copy and the last updated sources (new to Subversion), or the current repository
   log	Show log entries for resource
   propadd, proplist, propdel, propviewi	New in Subversion - manipulate metadata on a file. You can associate arbitrary data to any file or directory. A certain number of metadata keys have a special meaning (for example, svn:mime-type)

How to use Subversion with OpenCores

OpenCores changed the revision control system from CVS to SVN in March 2009. All projects were then transferred over to SVN (with all historical information included).

When creating a new project a subversion repository is automatically created with the trees tags, branches and trunk. Only maintainer(s) has the possibility to do commit

We will now try to explain how to use the subversion repository with a few examples of different use case below. For all examples we will use the Ethernet SMII IP core as an example. The name given to this repository is smii.

1. Get a tar file with the latest release

   This can be done from your web browser on the projects page. For each project there is a link to a tar file containing the latest revision of the content in trunk. Download the file, extract the files and you have a local copy.

   $ tar xvzf smii_latest.tar.gz

2. Check out a copy of the source code to a working copy

   $ svn co http://opencores.org/ocsvn/smii/smii/trunk

   You can optionally include username and password

   $ svn co --username user --password passwd http://opencores.org/ocsvn/smii/smii/trunk

   To include possible updates you do the following

   $ cd trunk
   $ svn update

3. Commit changes

   If you have changed local files and are a maintainer of the project you can commit your changes to the repositry To check for local changes

   $ svn status
   M Makefile

   The local file Makefile have been changed. To see changes use svn diff

   $ svn diff Makefile
   Index: Makefile
   ===================================================================
   --- Makefile (revision 3)
   +++ Makefile (working copy)
   @@ -19,6 +19,7 @@
   vppp --simple +define+SMII+8 tmp.v > smii_module_inst_8.v
   
   smii:
   - vppp --simple +define+ACTEL generic_buffers.v smii_sync.v smii_txrx.v | cat copyright.v - > smii.v
   + vppp --simple +define+ACTEL generic_buffers.v smii_sync.v smii_txrx.v | cat copyright.v - > smii_ACTEL.v
   + vppp --simple generic_buffers.v smii_sync.v smii_txrx.v | cat copyright.v - > smii.v
   
   all: comp1 comp2 comp3 comp4 comp8 smii

   The Makefile have a new line. The make script now generate a new file, smii_ACTEL.v. To place this new file under revision control:

   $ svn add smii_ACTEL.v
   A smii_ACTEL.v

   The file is now scheduled for revision, it will be included on next commit. After rebuilding the project with make all we can see current status

   $ svn status
   ? tmp.v
   M smii.v
   M Makefile
   A smii_ACTEL.v

   Two files modified and one file added. Note that the file tmp.v is not under revision control. We can now commit the changes to the repository.

   $ svn -m "added ACTEL version with BUFG" commit
   Sending verilog/Makefile
   Sending verilog/smii.v
   Adding verilog/smii_ACTEL.v
   Transmitting file data ...
   Committed revision 4.

4. Creating tags

   Tagging or releasing an IP core should be done either to reflect that the status of the project has reach a defined point or that we want to specify a certain state of the repository to be used in testing or actual products. Tagging makes it easy for the end user to use a defined version of the IP.

   In subversion tagging is done with svn copy to the tag tree. First we should create a new directory in the tag tree to reflect the tag to be made. Secondly you copy the source files from trunk to tag.

   In this example we want to make a prerelease to be used for testing of the IP

   $ svn mkdir -m "Prerelease to be used for testing" http://opencores.org/ocsvn/smii/smii/tags/P0
   Committed revision 5.
   
   $ svn copy -m "P0" http://opencores.org/ocsvn/smii/smii/rtl http://opencores.org/ocsvn/smii/smii/tags/P0
   Committed revision 6.

All of the above examples can be done from a GUI client. A GUI can make a lot of functions easier. This is especially true if in windows the Tortoise clinet is used. In Tortoise there is a repo-browser. When opened the user can do server side copy. This makes tagging and branching a lot easier.

Toward GIT

As for all technologies. version control systems evolve. In the recent years a prominent use of GIT proliferated in the whole software community. Sparked at first by the Linux kernel developers, it is quickly diffusing widely among digital design engineers developing gateware cores as well.

The OC-team is well aware of this important technology trend and it is considering which best approach could give contributors access to GIT version control without affecting performance, traceability and platform compatibility.

References

• Revised by Andrea Borga, 2017
• Material reworked to suit OpenCores use case, 2009
• First edition copyright David Neary, 2003