Version 0.0.1

View:

General Overview

Subversion (abbreviated svn), is a collection of programs which enable multuiple programmers to conveniently work on the same project. It makes aquiring the complete sources, checking changes in to the official version, summarizing changes, and version control easy and convenient.

Subversion uses a client-server model. A Subversion server has one or more respositories, which typically can be thought of as projects in Microsoft Visual C++ terminology, though this is not an exact analogy. The Subversion respository for each program is the master copy of that program. Individual programmers can retrieve as many copies of the respository as they like and work on them locally (in Subversion terminology, you check out the respository). Once a programmer has finished making his changes, he sends his copy to the subversion server to become the current version of the repository. This is called commiting the changes.

The Subversion server will handle:

SolarTech's cvs respositories are hosted on Hepaestus (network name: solartech.chrislansdown.com).

How Subversion is used

This is probably described most easily with an example, so let's assume a very simple Subversion setup. Let's say that we have two programmers, call them Nick and Chris, and one Subversion respository, for The Program™.

Suppose that there is a bug in The Program™, and Nick and Chris are working together to fix the bug. To make sure that they're working from the production code, they each check out a fresh copy of The Program™. Through testing and reading the code, they discover that they're facing not one but two related bugs. Nick fixes the first, more complicated bug and Chris fixes the easier, less complicated bug.

At the moment, neither Nick nor Chris has a copy of the source for The Program™ which can be built and shipped to customers. This is where Subversion saves the day. When Chris is finished with the fix for the smaller bug, he checks the fix into the Subversion respository. Chris is prompted for an explanation of the change that he made, and the master copy is updated with the changes.

When Nick is finished with the update for the larger bug, he checks in his copy. Since Nick and Chris changed different portions of the code, there are no problems with the check in and Nick is prompted for an explanation of his change. (If there were conflicts that Subversion could not automatically resolve, Nick would be prompted to resolve them manually.)

Now that the cvs repository has both bug fixes, Nick checks out a fresh copy of the Subversion repository, builds The Program™ from scratch, and ships the compiled version off to the delighted customers.

Getting Started

Subversion

If you have the pleasure of being on a Debian system, this is easy. Just apt-get install subversion subversion-tools. For those stuck on windows, read on.

You will need to download subversion. Version 1.1.4, which is the latest as of the writing of this document, is available here. To check for later versions, go to subversion.tigris.org.

Run the installer — the default options are fine, but you can customize the location etc. if you prefer. Subversion is a command line tool, so to use it you will need to launch a command shell. To do so, choose the Start menu, Run..., and enter the program "cmd". This will bring up a windows command shell.

Subversion

When you check out a repository, subversion will create a directory with the name of the repository you checked out. In most cases, this will be "trunk". Generally, you'll want to rename this to something more meaningful before working with your freshly checked out copy. You can work on a given checkout indefinitely — updating and committing in a never ending cycle of up-to-dateness, or you can discard it once it's served your purposes.

You can also have as many copies of the same repository checked out as you like, so if you want to experiment with changes or just make changes you're not interested in keeping (such as littering your program with printf() statements in order to do debugging), feel free.

(The following instructions are all to be entered in a command shell. Since most people who need to read this document are stuck on windows, the examples given are for a windows command shell. Of course everything is better on unix, but it will be assumed that the reader knows where he's keeping things and can change '\' to '/'.)

To go to a directory on your C drive, type:

cd "c:\Path\To\Directory with spaces in the name"

(If the directory that you want to go to does not have spaces in its name, you may omit the quotes.)

To check out a repository, cd to a directory where you wish to put your copy, then use the command:

svn checkout https://solartech.chrislansdown.com/category/progname/trunk

This will create a directory trunk. You can rename this to anything that you like (since all svn commands are run from within this directory, it doesn't matter what you call it — for simplicity, however, this document will just refer to the repository directory as trunk). You may now go into trunk and edit, build, etc. the program. When you wish to commit your changes to the Subversion repository run the following command from within the repository directory:

svn commit

If you know that someone else has committed a change that you want like in your local copy, or just because it's good programming practice to update before doing a commit, run the following command from within the repository directory:

svn update

If you wish to see what the changes you've made to your local repository are, run this command from within the repository directory:

svn diff

There are a few other tidbits about using Subversion which are good to know for practical use. Also, the above presumes that you're working with the trunk. If you want to work with a branch or merge instead, you'll subsitute branch/branchname or tag/tagname for trunk; this is covered in more detail later.

A few other tidbits about using Subversion

Adding and Removing Files

In order to facilitate files used locally for development but not meant to be included in a Subversion repository (for example, compiled object files, test data files, etc), Subversion must be explicitly told when a given file is to become part of a repository or to stop being part of it. The two relevant commands are add and remove (all of the following commands are done within the repository directory).

svn add filename
svn remove filename

Remember that nothing that you do takes effect in the repository until you commit it, i.e. when you're done adding or removing files, run the command:

svn commit

Please note that the above also holds true for directories, so if you want to add or remove a sub-directory to a repository, you do it in the same way:

svn add dirname
svn remove dirname

Branches and Tags

Branches and tags are both implemented in subversion by directory copying. For the time being, see the book.

Organization of the Repositories

The repositories on hephaestus are organized in a shallow heirarchy. The following is an explanation of the heirarchy of respositories on Hephaestus, with the bold entries being the name to use with svn commands:

messageboard/

This category is for all projects related to the Message Board

control_console_octagon
This repository holds the software which runs on the Octagon Systems based controller in the message boards.
control_center_2000
This repository holds the Control Center 2000 software for Windows2000 which is used to control message boards over modem, cell phone modem, wireless modem, direct serial connection, etc.
charge_controller
This respository holds the firmware for the charge controller.
arrowboard/

This category is for all of the software which runs on an arrowboard or is otherwise used to drive/use an arrowboard.

control_module
The arrowboard control module.
display_module/

This category is for all software which is run on, or used to test, a display module.

firmware_monochrome_6x9
The firmware which runs a classic 6x9 monochrome LED module.
pc_test_monochrome_6x9
The DOS bootable PC software which tests LED modules via a serial interface.