Setting up Subversion with Adobe Flash Builder 4 (Beta)

This tutorial will show you how to setup Subversion (SVN) with Flash Builder and how you use it. SVN is a great tool to backup your files, let others work on the same project and keep track of all versions of a file.

To read more about why you should use Subversion, read here. Note that this tutorial will only work with Flash Builder 4. For Flex 3, check out this tutorial. Screen captures in this tutorial are done on both OSX and Window, but Flash Builder is quite alike for both platforms so it should not matter.

Getting started

The classic versioning system CVS comes pre-installed in Flash Builder 4. To access Subversion code repositories requires installing a little extra software on your machine. What we want to install is Subclipse, a SVN plugin for Eclipse (and thus Flash Builder). On Windows, this is the only step required so skip ahead to the next heading (Installing Subclipse).

If you use OSX, it's a little more convoluted so the official Subclipse Wiki recommends that you download and install the OSX package that is provided on openCollabNet. The file contains a disk image and a package installer. Run the installer and follow the prompts.

Once installed, you will need to prepend /opt/subversion/bin to your PATH environment variable. This can be done a multitude of ways but an easy one is to add the following to the end of /etc/profile or ~/.profile:

export PATH=/opt/subversion/bin:$PATH

 If you have never edited the ".profile" file on your Mac, you can find a good tutorial here. When you have added the PATH variable, you're ready to continute this tutorial.

The openCollabNet installer

Installing Subclipse

Start by opening Help -> Software Updates -> Find and Install. This will open up a dialogue that will let you select to either update existing features or Search for new features to install. We are installing a new feature, so select this one.

Click through to the site selection dialogue. The Subclipse server is not in the default list, so we must add it manually. Click the "New Remote Site" button and set Name to "Subclipse".

Flash Builder 4 is based on Eclipse 3.4 and according to the standard Subclipse install procedure, the URL we shall use is "http://subclipse.tigris.org/update_1.6.x" (without the quotation marks). Enter the URL and press "OK". Make sure that only the server we just added is checked and click "Finish". Eclipse connects to the server and grabs the list of files available to us.

Make sure you only check off the required features, or you'll be asked to install a lot of other extensions as well.

Make sure that only "Subclipse Plugin" is checked and click "Next". Accept the terms, click "Next" and then "Finish" to install. This will start the download of the plugin. You'll need to verify the features installed and restart. That's it.

What you do next depend on what you want to use Subversion for. If you just want to connect to an existing SVN repository to download some code, skip ahead to the end of this tutorial. If you want to learn how to create your own repository and how to use SVN with it, keep reading.

Uploading your project

After the restart, you are ready to go! First you need to create a repository to stick your files in. You can do this using the tools provided by your SVN host or the command line if your server allows this.

For our purpose, we are using the free account at CVSDude (note: affiliate link). CVSDude offers a control panel that will let you add this easily.

Login to CVSDude and click the "Settings" link. From the right-hand menu select Settings -> Modules -> Add. Enter in your module name into the input box and click add new. We'll use "svntest" for this tutorial.

Back in Flash Builder 4, select Window -> Perspective -> Other..

Select "SVN Repository" from the list and click OK. Flash Builder will now switch to the new mode. To create a new project (a Repository), right click in the white space in the left panel called SVN Repositories and select"New" -> "Repository Location" from the popup menu.



Fill in the Repository path. If you signed up with CVSDude, they sent you an email with all the required details as part of the registration process. If you are connecting to a company server, ask the admin for the required details or if opted to set up your own server, you'll find the info you need on the web.

Next step is logging in.


You should consider saving the password or using a password agent such as PageAnt (Windows) or SSHKeychain (OSX) or you'll be asked this question a lot.

Switch back to the "Flash Development" perspective (in the upper right corner).
If you want to start with a new project, make one by selecting File -> New -> MXML Application (or any desired option in this menu).

Right click the project you want to add and select Team -> Share Project. (you may be asked to select between CVS and SVN, choose SVN.)

Next, select to use the repository location you just added.



Click next to proceed. You can think of the repository as just a folder on a server. You can add as many projects you want to a SVN repository, but may wish to plan how these files are organized since the initial commit will decide your future structure (The folder you commit initially will become your "root" folder). Keep this in mind when you create a proper repository. If you use CVSDude, you can easily delete repositories so lets forget about this for now and just continue.

Now select where to put the files. Specify a name or use the name of your project.



Click "Next". Type in a comment or leave the default comment. Click "Finish" to start ending the files to the repository. In the Commit dialogue that opens, you can select exactly what files to add or not. You'll want to add hidden files and folders (starting with a punctuation mark such as .flexProperties and .settings). These files are required by Flex Builder, so you should add them as well.


The Console panel will now fill with the commands sent to the server and the corresponding results. When using a good IDE such as Flex, you don't have to learn these commands or use the command line. All the required SVN commands can be initiated using the right click menu and wizards.

Working with SVN in Flex

We now have a working repository, so lets look closer at how to work with SVN in Flex 3. Start by creating a new ActionScript class in the "src" folder (File -> New -> ActionScript Class). Name the class "SomeClass". Did you notice that there is now a questionmark on the icon of the new file?

A star is also shown on the folder containing the file. This is how SVN tells you that the contents of a folder or file has changed. If you open a file, type a space and save it, SVN will mark it as changed. This makes it super easy to see any changes not sent to the SVN server.

Sending files to the server

Let's add the newly created file to SVN. Right click "SomeClass.as" an select Team -> Add to Version Control. Flex displays a dialogue that disappears as soon as the SVN server replies. The icon is now changed to a plus-sign to indicate that the file is added, but not yet COMMIT'ed (uploaded) to SVN. To do this, right click the file again and select Team -> Commit...



Type an appropriate message to describe the file and click "Finish" to send the file to the server. The star-icon is now replaced with a yellowish square showing us that all files have been sent to the server.

If there are files you want SVN to ignore, you specify this by clicking the file and selecting Team -> Add to svn:ignore. This will create a text file that simply contains names of files that should not be managed with SVN. You will have to commit the ignored files to the server as well for others to get this change as well.

To remove a file from CVS, just right click it, select "Delete" and then Commit the change (Team -> Commit). If you accidentally deleted a file, you can bring it back by selecting Team -> Switch to another Branch/Tag. Click the Revision radio button and press the Show Log button. Select the version you want to switch to and click OK. Your whole repository will now look like it did at that point in time. Copy the contents of the missing file and switch back to the latest version of the repository (this will be the same as HEAD unless you have been "branching"). Now you can add, paste and recommit the missing file.

Retrieving a former version of a file

One of the nice things about code versioning is that you can easily look through old versions of a file. Imagine that you solve a problem and later opt for a different solution. If you want to go back to the old solution, SVN will hold all your code and it's easy to switch back.

First we must ensure that we have a file that exists in several versions. For simplicity, we'll just change an existing file and commit it. Open "SomeClass.as" and add a comment in the class constructor. Commit this file (Team -> Commit). Now the file has two versions. Add more versions if you wish by changing the file and committing each version.

Now, let's have a look at the history of this file. Right click "SomeClass.as" and select Team -> Show History. A new panel will open and display the full history for this file.


(note: The default location is different from the image below. You can drag panels to where you like them by clicking and dragging the panel name.)

To see any of the versions, just double click it. To compare two files, select the two files from the list in the History panel and right-click to select "Compare". A new panel will display that easily let you see the differences.



Large files with many changes will show small rectangles in the margin along the scrollbar to show where the two files differ. This view is similar to the one you use merge files manually. Merging and branching is outside scope of this tutorial, but you can find more on this via Google.

To bring back a former version, right click the desired version in the History panel and select "Get content". Eclipse will then copy the contents of the old file into your existing file so that you can commit this as a new version. You never delete files from SVN. It's a complete record of how a project developed, who committed what and so on.

Don't forget to UPDATE!

The most common mistake when you start using SVN with other programmers is that you just start the day coding and then run into problems when you COMMIT the changes. While mostly cool, there are some things SVN does not like and the most important one of these is that you always work on a current version of a file. To prevent this:

Always start your day by right-clicking the project folder and select Team -> UPDATE

This will download any changed files. The more often there are changes to the repository, the more often you'll need to Update. Updating will not overwrite your changed files but it will alert you to possible conflicts.

If the server claims your file is out of date, compare it to what is in SVN using the History option above. That way you can see what is safe to copy into the updated file.

Importing an existing project

To finish off this tutorial, we need to show you how to connect to an existing project. This will allow you to get all the latest files in a project no matter where you are.

Imagine it's the christmas holidays and you left your computer at home intentionally. A client calls you up while you are at your parents. It's the "classic" crisis where the client insists that you HAVE TO fix a URL since they updated it without notifying you just before the holidays started. You could of cause ask the client to go somewhere unpleasant, but it's the season to be jolly and you know it's a quick fix if you only had the files...

• Borrow your dad's dated computer
• Download and install the trial version of Flex 3
• Import the project from SVN
• Make the change and commit
• Send the updated file to the customer

That's all. It's really that simple.

To do this, right click the white space in the Flex Navigator panel. Select Import and open "Other" to find "Checkout Projects from SVN".



Go through the steps as before by creating a new repository location. Select the folder to Checkout from the SVN server.



Click Finish to download the latest revision of each file and you are ready to serve your favorite customer.

That's where this tutorial ends. We've been through setup and the most common tasks like committing, comparing and replacing files. There are so many other things you can do with SVN, but that's beyond the scope of this tutorial.

 

About Jens C Brynildsen

Jens has been working with Flash since version 3 came out. Since then, he's been an active member of the Flash community. He's created more than a hundred Flash games (thus the name of his blog) but he also creates web/standalone applications, does workshops and other consulting. He loves playing with new technology and he is convinced that the moment you stop learning you die (creatively speaking). Jens is also the Editor of this website.

 

Comments

---

Submit a comment

Only registered members can comment. Click here to login or here to register