OpenCores

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].

    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 to 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:

[1] Subversion home page http://subversion.tigris.org
[2] CVS home page http://www.cvshome.org/
[3] Subversion book http://svnbook.red-bean.com/book.html
[4] Subversion sources http://svn.collab.net/repos/svn/
[5] Inconveniences page http://subversion.tigris.org/inconveniences.html
[6] Berkeley DB home pagehttp://www.sleepycat.com/
[7] Subversion downloads http://subversion.tigris.org/servlets/ProjectDocumentList
[8] INSTALL http://svn.collab.net/repos/svn/trunk/INSTALL
[9] README http://svn.collab.net/repos/svn/trunk/README
[10] Apache2 home page http://httpd.apache.org/
[11] Neon home page http://www.webdav.org/neon/
[12] Quick Reference http://subversion.tigris.org/files/documents/15/177/foo.ps

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

© copyright 1999-2017 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.