Recent versions of REALbasic contain a new “Version Control Project” format. This saves the project as a whole bunch of text files. With these files, you can use a version control system such as Subversion (SVN) to manage changes in your REALbasic project. This article shows you how to set up Subversion on Mac OS X, create a repository for your project, and check in changes made within REALbasic.
This article assumes that you want to work with a local, file-based Subversion repository. I haven’t yet experimented with multi-user check in / out using Subversion and REALbasic, but the same principles below should work for multiple users.
Subversion Repository
Start by downloading Martin Ott’s Subversion installer for Mac OS X. For the purposes of this article I’m using Martin’s Subversion 1.4.3 package. (Many thanks to Martin for making such an easy installer available for Subversion.)
Once the package has downloaded, it should run automatically and present you with the Subversion installer. Click continue a few times, agree to the license, and select your system disk to install the Subversion software. Click continue, then Install, enter your admin password, and Subversion will be installed. Close the installer – this bit is done!
Next, download SvnX, an open-source Subversion GUI. (I’ve used version 0.9.9 when writing this article.) Copy SvnX from the disk image to your Applications folder. Launch SvnX. In SvnX’s preferences, make sure that your “Path to svn binaries folder” is set to be “/usr/local/bin”.
Project Setup and Creating Repository
For this walkthrough, we’ll create a new blank desktop application in REALbasic, and save it as a test project called “MyProject” (more on this later).
First, we need to create a Subversion repository. Note that this isn’t the place where you will work on your code. The “repository” is actually the database where Subversion stores all of the information about your code changes.
Create a folder called “MyProject” at the root of your system hard disk, and create a subfolder in “MyProject” called “svn”. “svn” will be used as the home for our new repository. (These names aren’t important – you can store the repository and the project anywhere you like with any folder names.) We’ll call our new Subversion repository “myproject”.
To create the new repository, open Terminal (/Applications/Utilities/Terminal.app), and type:
svnadmin create /Volumes/YourSystemDiskName/MyProject/svn/myproject
My system hard disk is called “Gorilla”, so for me, the command is:
svnadmin create /Volumes/Gorilla/MyProject/svn/myproject
All being well, this will have created your new Subversion repository in the “svn” folder.
Next up, you need to import a “revision 1″ set of files. This will be your starting point for your Subversion-managed REALbasic project. To set this up, create a new folder via the Finder, alongside “svn”, to hold the files for this initial import. Call it “svn_initial_import”. (The name isn’t important – it’s just what I chose to use.)
The new folder will be at this location:
/Volumes/YourSystemDiskName/MyProject/svn_initial_import/
Real Basic
Open REALbasic 2007r1. REALbasic will create a new blank desktop application by default. We’ll use this as our test project. Save the blank desktop application project in the “svn_initial_import” folder, using the “Version Control Project” format. Call the project “myproject.rbvcp” (this is the filename with “hide extension” turned off).
Your “svn_initial_import” folder should now contain the following files:
App.rbbas
MenuBar1.rbmnu
myproject.rbvcp
untitled.rbres
Window1.rbfrm
There’s a small problem here. That “untitled.rbres” file should actually be called “myproject.rbres”. Due to a bug in REALbasic 2007r1, it has been written with the wrong name. To fix this, in your REALbasic project, double-click on Window1 to open it in the editor. Then save the project (apple-s). Opening Window1 in the editor counts as a “change”, so when you save, the rbres file is created with the correct name – “myproject.rbres”. Delete untitled.rbres from the “svn_initial_import” folder, as it is not needed. Finally, close your project in REALbasic.
Your “svn_initial_import” folder will now contain the following files:
App.rbbas
MenuBar1.rbmnu
myproject.rbvcp
myproject.rbres
Window1.rbfrm
There’s a second bug in REALbasic 2007r1, whereby the MenuBar1.rbmnu file is modified the first time you re-open the project and save it. This results in MenuBar1.rbmnu getting modified unnecessarily, which we don’t want to happen once it’s been checked into Subversion. So, to work around this bug, we’ll trigger this before we do our first import.
To do this, navigate to “svn_initial_import” in the Finder, and look for the myproject.rbvcp file. This is the REALbasic project file for your project. Double-click the file, and it should open in REALbasic 2007r1. Save the project via Apple-S (even though nothing has really changed), and close the project. This will update MenuBar1.rbmnu, and avoids the bug causing any problems once we’ve checked in.
We can now perform our first import. To import these files as “revision 1″ of your project, type the following (using your own system disk name) into the Terminal:
svn import -m "Initial import" /Volumes/YourSystemDiskName/MyProject/svn_initial_import/ file:///Volumes/YourSystemDiskName/MyProject/svn/myproject/
The “-m” option adds a comment for this initial import. Subversion will import the contents of “svn_initial_import” folder into the “myproject” repository. The “file://” scheme indicates that you’re working on a local repository on your machine.
Subversion will print out a whole bunch of “Adding” lines to the Terminal, one for each text file in the “Version Control Project” format. You now have revision 1 of your project in Subversion! You can delete the “svn_initial_import” folder.
We can now do away with the Terminal, and start to use SvnX to manage the project and repository. Open SvnX, and from the Window menu, open the “Repositories” window. Click on the “plus” icon to tell SvnX about your new repository. Enter an appropriate name (“My Project Repository”), and the path to the repository (“file:///Volumes/YourSystemDiskName/MyProject/svn/myproject/”). You don’t need to add a username or password, as we haven’t set one on the repository. Double-click on the newly-added repository in the top half of the Repositories window, and the repository should open up in its own window.
The top half of this new window will show a list of revisions, with just “Rev # 1″ listed for now. The date of your “rev 1″ checkin, together with your username as “Author”, and “Initial import” as “Log message”, should all be displayed. The bottom half of this window will show a hierarchical list of the files and folders in the project.
Check out
The next task is to check out a copy of the project. With Subversion, you check out a copy of the entire repository into a “sandbox” directory. You then work on this copy of the repository (in REALbasic), and check any modified files (for windows, classes, modules etc.) back in to Subversion once you are done. You can keep using the same working copy for all of your future changes.
To create a new working copy, first create a folder on disk. Create a folder at:
/Volumes/YourSystemDiskName/MyProject/svn_code/
(Again, this can go anywhere, with any name).
Return to your “My Project Repository” window in SvnX, and click on the “svn checkout” green arrow icon in the toolbar. Navigate to your working copy folder (“svn_code”), and select “open”. This will check out a copy of the entire repository to your working copy folder (you can have a look at it in the Finder and see all of the files in there).
Open the “Working Copies” window from the “Window” menu in SvnX. SvnX will have created a new working copy called “My Project”. (SvnX’s choice of name is just a coincidence – it calls all new working copies “My Project” by default). We’ll come back to this working copy in SvnX in a minute.
Navigate to your working copy folder (“svn_copy”) in the Finder, and look for the .rbvcp file. This is the REALbasic project file for your project. Double-click the file, and it should open in REALbasic 2007r1.
To check Subversion is working, let’s make a small change to the project and check it back in to the repository. In REALbasic, add a new module to the project (leave it named as Module1), and save the project in REALbasic.
Switch back to SvnX, and open your working copy by double-clicking on it in the “Working Copies” window. The following two files are listed in the project window:
myproject.rbvcp
Module1.rbbas
(This is SvnX’s “smart mode” view of your project, showing all files which have changed or are new / missing.)
myproject.rbvcp is coloured black, with an “M” in the first column, indicating that it has been modified. myproject.rbvcp is modified every time you add / remove an object to / from the project, which is why it appears in the list following the addition of Module1.
Module1.rbbas (the text file for the new module we just added) is coloured blue, with a “?” in the first column. This indicates that it is new, and that it will need adding to the repository.
To add this new file, select it and click on the “Add” button. You will be asked if you are sure you want to Add items. Say “Yes”. Module1.rbbas will turn black, and now has an “A” in the left-hand column. It hasn’t yet been added to the repository, however – we do that as a commit action.
Select both files, and click on the “commit” button on the right-hand side of the window. You’ll be prompted for a “commit” comment, to describe what changes you have made. (All changes in Subversion need a comment – this is a Good Thing). Add a comment such as “Addition of a new Module, Module1, for testing SVN”, and click “Commit”. The two files will disappear from the Smart Mode view of your working copy, as they have now been committed to the repository.
If you switch to your “My Project Repository” window in SvnX, and click the “refresh” button (a small grey circle with an arrow
curved inside it, top right of the window), then a new “rev # 2″ will appear above rev 1. Click the radio button for rev 2, and you will see the hierarchical view of files at the bottom of the window change to include Module1.rbbas. You have now checked in your second revision!
If you delete an item from your REALbasic project, note that the corresponding file is NOT deleted from your working copy. The “myproject.rbvcp” file will be updated, to no longer include the item in the project, but the item’s file will still exist.
For example: open myproject.rbvcp in REALbasic, delete Module1, and save the project. If you now refresh your working copy view in SvnX, myproject.rbvcp will be listed as modified (and will need checking in), but Module1.rbbas is not listed as deleted. The file for Module1 can still be found in your working copy directory.
If you wish, you can manually delete the files for the removed project items, and check in these deletions to Subversion. (You can always retrieve the files from an earlier revision if you need them again in the future.) In this example, delete the Module1.rbbas file from the “svn_code” folder via the Finder, and refresh your working copy view in SvnX. Module1.rbbas will be listed in red, with an “!” in the left-hand column. Select Module1.rbbas, and click on the “Remove” button on the right-hand side of the window. You will be asked if you want to remove the selected items. Say “Yes”. Module1.rbbas will be listed with a “D” in the first column (although it is not yet deleted from the repository). Select both myproject.rbvcp and Module1.rbbas, and click the “commit” button. Add a comment such as “Deleted Module1 as it is no longer needed”. Your repository will now have a new revision, with the Module1.rbbas file removed.
For a useful reference to Subversion, check out Version Control with Subversion, a free online copy of the O’Reilly book of the same name.
Update: If you’re using REALbasic 2007r4 or later, be sure to check out Charles Yeomans’ useful tip on hiding .rbuistate files from Subversion.