Setting Up the Development Environment

The following tutorial will help developers assisting with the Tranche Project develop a working understanding of the tools and workflow underlying the project's development. We will be using Subversion and NetBeans as an integral part of the development process.

This is not meant to be a general tutorial of the Subversion content managment system, nor the NetBeans IDE. There are a great deal of resouces that offer more in-depth coverage, including O'Reilly's Version Control with Subversion and the NetBeans Documentation page. We will focus on the concrete steps necessary for contributing to the Tranche Project.

Using Subversion and NetBeans

To begin, you will need to download and install Subversion and NetBeans. Both are open source and are very well documented.

Subversion is a content version control system that allows multiple users to safely edit and update code, as well as branch off stable versions. This safety is achieved by allowing users to check out code, edit the code, and then commit the code as long as the version is not out-of-date.

Subversion also provides a cheap copy, meaning that multiple versions can be stored based on their differences, as opposed to storing the entire files multiple times. As a result, Subversion saves storage space.

Because Subversion is a version control system, if (for any reason) a developer wants to roll back to a previous version, they can. This is particularly powerful if critical bugs are introduced in a newer version that require immediate reversal.

For more information, we recommend O'Reilly's Version Control with Subversion.

NetBeans is a Java IDE with excellent community support, a wealth of well-written documentation, and powerful plus intuitive modules. A great deal of functionality is built into NetBeans, including JUnit, which promotes positive software development practices with less time configuring and installing software.

There are also a great deal of add-on modules available in NetBeans. For user convenience, these modules can be added from within NetBeans, again saving the developer time from installation and seeking out modules from different sources.

For a growing list of resources, visit the NetBeans Documentation page.

Understanding this tutorial

This tutorial is broken up into two sections.

The first section offers a simple walkthrough of the process of obtaining, editting, and committing the code to the Tranche Subversion server.

  1. Checking out code from the Subersion repository
  2. Importing code into a new NetBeans project
  3. Debugging and revising in NetBeans
  4. Committing changes back to the Subversion repository

The second section is an introduction to using the Subversion module within NetBeans.

Special note pertaining to the commands: we will be demonstrating the usage of Subversion using Unix shell commands. However, you can download a GUI for your Subversion client, and you should have no problems following along, even from MS Windows. The Subversion project page recommends TortoiseSVN as an easy GUI alternative.

Also note that this tutorial will use svn when referring to the Subversion program.

Checking out and committing code

Checking out code from the Subversion repository

Assuming you have svn installed, you will want to verify that it is working and in your path:

% svn help

(Note that the modulus % represents the prompt, so you should type the command that follows in your shell.)

If everything worked, some basic usage information will be printed, followed by a list of commands. If you want more information about any particular command you can request information with svn help command. For example:

% svn help blame

If you did not get the output, you will have to determine the problem. If you received a message similar to command not found, you need to determine if the install was a success. If, for any reason, the executable is not in your path, you can always execute it by offering the full path:

% /path/to/svn help

This will get tedious fast, so you will probably want to add the parent directory to path. The method for doing this depends on your shell, so consult any system or internet references for more information.

The next step is to place the code in a convenient directory. You can choose where the code will reside — wherever you choose, change directory within the shell (cd /path/to/convenient/dir). Now, you can checkout the code using the following command:

% svn checkout svn://www.proteomecommons.org/svn/DFS

You will have a brief wait while your Subversion client retrieves the files.

At the end of the list of files, you will see a revision number. This may prove useful if you are unable to commit your changes due to outdated content. However, you don't need to remember this information, as you can always request it later:

% svn info

For a list of all versions:

% svn log

In the case of Tranche, the list will be long, so you can offer a limit on the number of versions to view. For example, to view the last 10:

% svn log --limit 10

Importing code into a new NetBeans project

Now that we have the code stored on our local file system, we will want to import the code into a new NetBeans project.

Assuming you are new to NetBeans, we will walk through the basics. To work with the Tranche logic and GUI, we will create two separate projects and link to the source code as well as the test code.

To begin, let's create a new project. In NetBeans 5.5, go to File > New Project..., and a dialog box should appear.

For both of our new projects, we will choose the category "General" and the project type "Java Project with Existing Sources", as is highlighted in the screen capture. When you have selected General > Java Project with Existing Sources, click Next >.

Our first project will be for the application logic code. You can select any project name, but this tutorial will use "Tranche", and you will follow the Tutorial more easily if you do the same. You can also select a directory of your choice. The project files (and there are quite a few) will go into this directory, so, to keep organized, you will want to place these in a new directory. By convention, using a directory with the same name as the project name is a Good Thing. In this case, the IDE created a new directory called Tranche in the directory of my choosing.

(Note: this does not need to be in the same directory as the source code. We will "link" the code, meaning you can store the project separately. I'm placing my project and source code in my temporary directory /Users/besmit/Tmp since I already have the projects created, but you will most likely want to store your projects and source code elsewhere.)

In general, you will probably want to store your code in a location that is accessible to you as a user. Here are my suggestions:

You may want to call this directory "ProteomeCommons.org" or something that will help you to uniquely identify the location of the code.

Notice that I unchecked "Set as Main Project" for this project. If you don't, the IDE will correct this when we add the GUI project. The main project will be the GUI, meaning we will execute the GUI from the NetBeans Run. Now click Next >.

The final step is to link the logic and test code. To do this, you will need to remember where you placed the code you checked out from Subversion. We will abstract and say that the root directory for your project is /DFS_ROOT. Using this as our convention, you will want to target the code as follows:

Note that my /DFS_ROOT is actually /Users/besmit/Tmp/pc.org. The screen capture shows the correct locations used for linking the first project.

You can now click Finish to create the first project. After the project is completed, you will see the project listed in the Projects pane. You can expand the view to get a list of source and test packages.

You can navigate through the packages and select classes, which you can then view and edit in the source code pane.

Now we want to repeat this process for our next project. This will give us the opportunity to consolidate our understanding of creating a project from existing source.

  1. Choose File > New Project... and highlight General and Java Project with Existing Sources. Click Next >
  2. Select a reasonable project name (this tutorial uses TrancheGUI) , and select the project location. For convention, you might select the same parent directory as our "Tranche" project. Keep "Set as Main Project" selected, and choose Next >
  3. We will now map the source and test directories:
    • The "Source Package Folders" is located at /DFS_ROOT/DFS/subprojects/GUI2/src
    • The "Source Package Folders" is located at /DFS_ROOT/DFS/subprojects/GUI2/test
    Now click Finish

We now have two projects. If you look at your two projects in the project pane, the GUI project should be bold – this means it is the main project, which will be executed whenever you choose to Run your code. If it is not bold, then Control-click (or right-click) on the GUI project and choose "Set Main Project".

Now let's try to build the project. Select Build > Build Main Project, and watch the output pane for the build message.

The project will not build, and the output pane will produce a gratuitous list of compilation errors concerning unknown packages. This is because we have not "linked" the application logic to the GUI. Let's resolve that now.

Expand the GUI project (in our case, TrancheGUI), control-click (or right-click) on Libraries, and select Add Project. A dialog box will appear, choose the directory for the Tranche project. Now click on Add Project JAR Files.

If you expand the Libraries view within the GUI project in the projects pane, you should now see a reference to the Tranche project.

Now try to build the main project again. The build will also fail, again citing unknown packages.

If you look in the source code directory (the code you checked out from Subversion), you will see a subdirectory called lib. This contains JARs with libraries used by the Tranche software.

To finish the process of preparing our projects, we will need to link the JARs in these directories to both projects. To do so, for both projects, expand their views in the project pane, control-click (or right-click) on Libraries, and select Add JAR/Folder....

We need to add all the JARs in the lib directory for both projects.

You will also need to add one more set of JARs under the Tranche GUI. To locate these last two JARs locate the subprojects folder, and then select the GUI2 folder, within the GUI2 folder is the lib folder where the last two JARs can be found.

After adding all of the libraries for both projects, you will want to verify that all the libaries are resolved for both projects. Expand the library views in the project pane for both projects. The Tranche should have all the JARs from the lib directory, and the TrancheGUI project should have all the JARs plus a reference to the Tranche project.

Now select Build > Clean and Build Main Project. After some time, you should see a success message. If you still have compilation errors citing unknown packages, make sure you included all the libraries listed above.

You are now ready to modify the code. It's worth mentioning that the build and clean build options in NetBeans actually uses Ant to maintain your compilation options. Ant is the Java build tool, similar to GNU make. NetBeans creates and maintains your Ant files for you, updating the options as you add and delete references.

Debugging and revision in NetBeans

At this point, since you have built the project, you can run it. Select Run > Run Main Project. You may be prompted to select the main class, which is org.tranche.gui.AdvancedGUI.

To debug the project, you may first want to select some break points in the code, which is as easy as clicking on the left margin of the source pane on the line at which you wish to break execution. You can also establish watches for variables.

Then select Run > Debug Main Project. You can add break points and new watches while debugging a process.

You can view a list of running processes in the Runtime (a tab near the Projects pane), expanding the Processes view. This offers a convenient way to terminate unwanted processes.

Under File, you will see Save and Save All. The former saves changes in the file you are currently editting, whereas the latter saves all open files.

Committing changes back to the Subversion repository

Once you are done, assuming your code in not out-of-date, you can commit your work back to the server:

% svn commit -m "A brief message about changes you made"

You may be prompted to supply your username and password again.

If the commit fails, you will have to resolve the issue with the other developers. If someone else checked out code and submitted the changes before you, the Subversion server will not accept your revisions due to the potential for semantic conflict (such as differences arising from a refactor). You can view the Subversion log to determine who submitted the code, and contact that individual to determine if any changes would make your code incompatible.

If your commit was a success, an email will go out to the Tranche Commit mail list.

This concludes the first part of our tutorial on using Subversion and NetBeans.

Using NetBean's Subversion module

NetBeans 6.0 is planned to include Subversion. However, as of NetBeans 5.5, you must install the module. However, NetBeans makes this trivial.

Select Tools > Module Manager. A dialog box will appear. Near the bottom, there is a button that says Update.... Click to open a new dialog box.

Chances are that you will leave the default locations alone, clicking on Next >. NetBeans will connect and display a list of modules. Find the Subversion module, Add it and select Update.

NetBeans will install the software for you. Once it is completed, you should see a new Subversion menu item. (You may need to restart NetBeans.)

You can explore the options available within the Subversion menu. You may notice the Checkout and Commit options we used earlier in this tutorial.

It is worth mentioning that you may receive an error when you attempt to checkout using the Subversion module, reporting that "NetBeans Subversion support requires Subversion executable!" Although you may have svn in your path, NetBeans may be running under a different user, meaning that it may not have the same path. (This is most likely the case if you are using Mac OS X.)

To resolve this issue, you could set the path that NetBean will use. However, because different operating systems offer different levels of root access, you may prefer to create a symbolic link. For example, say svn is located at /opt/local/bin/svn. We can add a symbolic link to /usr/bin, which is universally in any path. (This need not be the case, but would be a very rare exception.)

Verify the location, and use % ln -s /path/to/svn /path/to/new/link, e.g.,

% ln -s /opt/local/bin/svn /usr/bin/svn

If you are not privledged to write, which will most likely be the case:

% sudo ln -s /opt/local/bin/svn /usr/bin/svn

Now restart NetBeans, which should now have access to svn.

Conclusion and further topics

We have covered a lot of ground in little space. There is much more to cover with NetBeans, such as rollbacks and branching, and there are a great many more topics to explore within NetBeans, such as unit testing with JUnit and refactoring.

This tutorial has demonstrated the use of Subversion to checkout and commit changes to the Tranche Project code base, as well as viewing and editting the code within NetBeans. Both tools can be a great productivity tool, and as we saw with the NetBeans Subversion module, can even be integrated to simplify development.



Home   •   FAQ   •   Contact Us   •   Join email list   •   Collaborations   •   Credits