Using Subversion and Subclipse
in Windows and Linux Development in Eclipse

Russell Bateman
26 January 2010
last update:

Table of Contents

Introduction
Setting up Subclipse
Windows
Linux
Using Eclipse Team on projects
Set up a Dynamic Java Project
Set up a simple Java Project
Additional notes
Using Subversion outside of Eclipse
Icon decoration in Eclipse
Ignoring files for Subversion
What to add to Subversion
Synchronize with Repository
Subclipse and MyEclipse
Useful links

Introduction

This article explains how to set up and use Subversion on Windows and Linux, and set up and use Subclipse inside the Eclipse IDE to manage source code control.

If you're developing on Windows, you'll want to set up the TortoiseSVN software, a Windows client for Subversion access anthat works with the Windows File Explorer. You probably want to set up TortoiseSVN first before continuing. For that, please see Using TortoiseSVN and Subversion before coming back here.

On Linux, you should install (if you do not find already installed) an executable named svn and learn to use its command line, which is fairly simple for most operations, to handle Subversion operations on that platform.

Subclipse is a plug-in for Eclipse that executes Subversion commands from within Eclipse so that you do not need to go out to the filesystem. In my work, I find that I use both svn (or TortoiseSVN) and Subclipse to get my work done. Once my project is set up and I'm actively developing it in Eclipse, I don't use the more formal Subversion clients so much thereafter.

Setting up Subclipse...

To consume repository files through Eclipse (instead of going to Windows File Explorer), you must set up the Subclipse plug-in software. This tutorial was done on Eclipse Galileo, but I've also done it on Helios whence some of the Linux illustrations.

I've long worked on Linux using Eclipse Europa and Polarion Subversive (and not Subclipse) there. However, I have recently found that I can't seem to make Subversive work; it's too complicated. Subversive works fine although the Linux set-up is more work than the Windows.

Windows

  1. Pull down menu Help -> Install New Software...
    2.  
  2. Click on the Add... button. Name this site (non-crucial) "Subclipse" for example. Type in the URL. You can go to subclipse.tigris.org and see what the latest is. I used

    http://subclipse.tigris.org/update_1.6.x

    —the latest for Galileo as of this date of writing. Click OK.

    3.  
  3. In the principal content region of the Install dialog, there will be three projects. Select each one by checking their boxes. Then click Next.
    4.  
  4. Review and accept the licenses.
    5.  
  5. Click Finish.
    6.  
  6. The plug-ins will be installed. Then you must restart Eclipse.
    7.  
  7. To ascertain if the software installation was successful and is useful, right-click in the Eclipse Package Explorer on a package or file and choose Team. If there are options, then it probably works.

    Here, I've created a quick "Hello world" project whose sources I don't yet have in Subversion. The Team menu option is in place, but will not yet allow me to commit, update, etc.

    8.  
  8. See the Subclipse installation tutorial in the useful links below for this installation on Galileo and to walk a few steps further than I have here.

Linux

First, understand that if you experience troubles setting up Subclipse on Linux, you might need to spend some time at http://subclipse.tigris.org/wiki/JavaHL. I'm going to try to help you avoid that by what follows.

My success came on Ubuntu (Lucid) after trying trivially to set up Subclipse (just for Windows, which was very trivial), then trying Subversive (which I expected to work), then abandoning Subversive for a second try at Subclipse, which then succeeded. I have decided therefore that Subversive, which I once used on Linux years ago, no longer works and is no longer best practice for Eclipse development on Linux.

  1. You'll need to install the Subversion Java connector as noted in the article referenced above. 
    
# sudo apt-get install libsvn-java

    because that installs /usr/lib/jni and a JNI underneath that you need to solve the JavaHL issue. When you've finish, you should see something like: 

    
russ@russ-elite-book:~> ll /usr/lib/jni
total 244
lrwxrwxrwx 1 root root     23 2011-01-12 09:02 libsvnjavahl-1.so -> libsvnjavahl-1.so.0.0.0
lrwxrwxrwx 1 root root     23 2011-01-12 09:02 libsvnjavahl-1.so.0 -> libsvnjavahl-1.so.0.0.0
-rw-r--r-- 1 root root 249560 2010-07-08 09:53 libsvnjavahl-1.so.0.0.0
  2. Then add 
    
-Djava.library.path=/usr/lib/jni

    to eclipse.ini after the -vmargs line.

  3. Then, go to http://subclipse.tigris.org/, click on Download and Install, and look for the Eclipse update link, probably:

    http://subclipse.tigris.org/update_1.6.x

  4. In Eclipse, do Help -> Install New Software -> Add.
    5.  
  5. Call it "Subclipse" and add the update path (from the instruction above). Then install (glide through the Next buttons) and restart.

    6.  
  6. Go to Window -> Preferences -> Team -> SVN. If the library from the earlier step has not been added to eclipse.ini, then this step will initially yield an alert to the effect that the Subversion library doesn't exist. Thereafter, the alert will not appear, but SVN interface -> Client: will not show that JavaHL (JNI) is available.

    Once everything is copacetic, you should see (in Window -> Preferences):

    When you right-click on a project (under source control), you'll probably find that the Team menu item has only the items in the Windows illustration above (last step or two). You'll have to choose Share Project... before then seeing the usual, well populated Team menu.

That's all. See the wiki link at the top of these instructions if you can't sort it out. Read carefully. In particular, do Help -> About Eclipse -> Installation Details -> Configuration to see if the -Djava.library.path is set right. If not, it just ain't gonna work.

Using Eclipse Team menu on projects

In my experience, the best way to set up a new project in Eclipse that will be under source code control is at creation. However, my discussion here presupposes that your project exists already (and not that you're creating it from scratch).

This discussion holds completely for Eclipse work on Linux.

Set up a Dynamic Java Project

  1. In the Package Explorer view, right-click and choose New. If necessary (because it's not one of the "frequent" choices), choose Dynamic Web Project under Web.
    2.  
  2. Name the project.
    3.  
  3. Uncheck the box Use default, then click Browse.

    4.  
  4. Navigate to the top of the filesystem location of your project—already in Subversion. Click OK to establish this path as the directory for the project contents. This will a) operate solely on that path and b) not set up any filesystem structure in your Eclipse workspace for the project. The workspace will, nevertheless, contain information about the project (just no directories or files).
    5.  
  5. Fill out the remaining dialog items as you normally would as well as the information in the following dialogs. After you have done this, the project will be created, use the existing source code out of your repository and be ready for building.

Set up a simple Java Project

Creating a simple Java (not Dynamic Web) project happens similarly, but the dialog box is slightly different; otherwise, it works identically:

Additional notes

- You will find that you can update your copy of what's in the Subversion repository using TortoiseSVN or other Windows approaches (on Windows) or svn on Linux and Macintosh independently of Subclipse (i.e. not using Team -> Update from inside Eclipse). All you must do in Eclipse afterward is right-click on the project affected (by the independent filesystem operation) and choose Refresh.

- You will find Eclipse decoration of files and folders under repository control confusing. When you modify a file, its icon in Package Explorer will be decorated with a black box in the lower right-hand corner. However, other entities you have not (at least not intentionally) modified will begin to sport this decoration too. There are reasons for this, but some you must commit and others you must not if you are collaborating on source-code development with other team members. It's hard to explain this; experience will dictate which ones.

- There are often files in your Eclipse project that you do not want to come under Subversion control. To exclude these, right-click on one, choose Team, then Add to svn:ignore.

- What to add to your Subversion project? Add everything Eclipse creates in your Java Project except the bin subdirectory where generated class files are put. In the Dynamic Web Project, this subdirectory is named build, though you can change that name. You do not need to make these subdirectories for ignore in Subversion, you just don't mark them at all for anything. The files under these subdirectories are (re) generated each and every time you build.

- When collaborating in the team environment, there are two distinct processes including updating to new versions committed by teammates and committing new changes you've made. Obviously, these can conflict. You want to update before modifying and committing. Team -> Synchronize with Respository doesn't solve this, but it does provide a sophisiticated solution to seeing the state of your code respective to the repository. (It also borks any perspective you attempt it in—in my humble opinion.)

Subclipse and MyEclipse

Plug-in installation on MyEclipse works a little differently than described above. Instead of using Eclipse's Help -> Install New Software, you use Help -> MyEclipse Configuration Center and wait (a long time) for this feature to load and display.

Once you see that MyEclipse Configuration Center is us, click on the Software tab. You should see, in the left pane, software already in a list, one of which will almost surely be "Subclipse 1.6.x (w/related)".

Right-click on Subclipse and choose Add to Profile.... Just as illustrated above, you'll find you can select which components to include. In my case, I'm not interested in Mylyn and so I don't select it.

At this point, look at the right pane (My Software) and then to the bottom for an Apply button. Click that and, if all goes well, you'll soon have Subversion functionality.

I struggled to solve an error alert: 


Validating MyEclipse 8.6
Profile Contains Errors

Pulse has been unable to create a plan for MyEclipse 8.6. Please check the details below to diagnose the \
  issue. If problems persist, contact Pulse support via the forums at www.poweredbypulse.com.

Bad update sites
Missing requirement: MyEclipse 8.6 (Profile) 2.0.0.0000000003 \
  (com.poweredbypuse.profile-0-rb-578452-1292261416527 2.0.0.0000000003) \
  requires 'org.tigris.subversion.clientadapter.feature.feature.group 0.0.0' but it could not be found



This was solved by ensuring a connection with Pulse. The reason I didn't have
one is because MyEclipse does not make use of the Linux host-wide proxy
settings. You have to set up the proxy explicitly inside MyEclipse. To get to
this, I think I clicked around in the interface on places like the Sync
now button for About This Profile.





The other thing I did was to increase myeclipse.ini memory settings as
shown below in my -vmargs settings:





before:                              after:
-vmargs                              -vmargs
-Djava.library.path=/usr/lib/jni     -Djava.library.path=/usr/lib/jni
                                     -Xms256M
-Xmx512m                             -Xmx1024M
-XXLMaxPermSize=256m                 -XXLMaxPermSize=512M
-XX:ReservedCodeCacheSize=64m        -XX:ReservedCodeCacheSize=64m





I can't say that the -Djava.library.path setting was really necessary.
It is for Eclipse proper; MyEclipse didn't ask me to put it in, but it's not
complaining either and this library is needed.





After setting everything up in MyEclipse, do this for all projects imported out
of Subversion:




    

  1.  In the Project- Package Explorer, select all projects.

    2. 

       
    

  2.  Right-click and choose Team -> Share Project. 
    3. 

       
    

  3.  Click SVN. 
    4. 











There's an alert to the effect that you can't share all projects with each
other, but a list is provided that you can process one at a time by selecting,
then clicking Next or Finish. Each treated project then
disappears from the list which diminishes until you've done them all.














 Appendix: Some useful links