JavaNLP Quick Guide to Source Code Management

Here at the JavaNLP mines we use Subversion to manage our source code. If you're not familiar with source control schemes, please first read the entire Subversion book. If you're coming from a CVS background, you'll find the transition an easy one, but you may wish to read the Subversion for CVS users appendix.

Setup

Note that these steps are necessary even if you check out from a remote machine! (Subversion "svn+ssh" mode will log in as you and run SVN binaries, so the paths must be correct.) If you see the message svnserve: Command not found., this is what you forgot to do!

On any NLP machine, add the following to your .cshrc file:

  source /u/nlp/bin/setup.csh

Users enlightened enough to use bash should instead add the following to your .bashrc file:

  source /u/nlp/bin/setup.bash

It's also a good idea to add the following to your .bash_profile file:

  source ~/.bashrc

If you're going to be checking things out on an NLP machine, run source filename (where filename is the file you just edited) to push those changes to your current environment (you only need to do this once; the file you just edited is loaded each time you log in or open a new terminal).

File protections

The SVN repository has to remain all nlp group read/write. If you added the "source" line described above to your .cshrc or .bashrc or whatever, you're all set. But in any case, the following command must be run in your environment at login lest you break the repository:

umask 002

Otherwise files and directories will not be created so they are group writeable, and the repository will stop working for everyone else! For more on the issues here, see Chapter 6 of the SVN Book. If you mess this up, you need to go to /u/nlp/svnroot and fix protections or group ownership manually (with chmod and/or chgrp).

Initial checkout

NLP machines / machines with access to /u/nlp/

To check out the JavaNLP repository, move to a comfortable directory, and run:

svn co file:///u/nlp/svnroot/trunk/javanlp

Now watch, slack-jawed in amazement, as the files roll by, much like the days of our precious mortality, zooming by all too fast until, before you know it, they're gone and what do you have to show for yourself but some publications in an obscure journal and an office full of travel mugs. Congratulations! You've checked out all of JavaNLP.

Non-NLP machines / machines without access to /u/nlp/

In addition to setting up your paths on the NLP machines as described above, you will need svn binaries installed locally.

Then, all you need to do is run this:

svn co svn+ssh://username@jacob.stanford.edu/u/nlp/svnroot/trunk/javanlp

It may ask you for a password, because it is logging in remotely as you. See the working with multiple machines guide for instructions on how to avoid typing your password for every svn command.

Eclipse

See here.

IntelliJ

See here.

Windows machines

Unless you're crazy, just use Eclipse (above) or IntelliJ (also, above).

Mac OS X machines

Either use Eclipse, IntelliJ, or use svn from the command line.

If you're using Mac OS X 10.5 (Leopard), svn (1.4.4) just comes with it in /usr/bin
Otherwise, you can get Mac OS X binaries here. It's probably easiest to use the CollabNet ones (unless you're already into Fink or MacPorts).
Follow the non-NLP machines information above

Repository Setup

For basic use, you only need to know the basic layout. So, here's the layout of the trunk:

javanlp/
- bin/
  Holds several useful scripts
- javadoc/
  Self explanatory
- projects/
  - core/
    Currently pretty much anything that isn't RTE or MT specific
  - mt/
    Anything specific to Machine Translation
  - pubcrawl/
    Basically defunct project
  - rte/
    Anything specific to Robust Textual Entailment
- build.xml
  ant build script for everything

The projects/ subdirectory consists of several separate subprojects. With the exception of referencing core/, none of these projects should reference each other. In particular, this means that core/ should have no dependencies on other projects! Projects are laid out in a relatively consistent way:

lib/
Holds jars for this project. Feel free to add reasonably licensed libs that don't duplicate functionality we alredy have (in lib/ or in our own code). If you add a library here, also add its source in libsrc/.
libsrc/
Holds source code for libraries, normally compressed in a zip/jar file.
src/
All the non-test source code for this project goes here.
test/
All test code goes here. We use jUnit. Unit tests go in the src/ directory inside here.
build.xml
ant build script for everything

Using Subversion quick-start

See A Guided Tour of SVN for a complete guide to all the interesting things you can do with your local copy. The very basic commands you need to know about are these:

svn status: Shows which files you've modified. Add a -u at the end to contact the server and also show which files need to be updated. CVS users, this is equivalent to cvs -n update.
svn update: Merges all changes that other people have committed to the repository into your local copy. See the chapter on conflict resolution. (CVS users, conflict resolution is a little different (mainly in that you must run svn resolved after resolution) so I highly recommend reading that chapter for you too.)
svn commit: Commits your changes to the repository. Subsequent updates by others will cause them to receive those changes. See the New Member's Guide for all the rules you must follow before committing code lest you be subject to yellage.
svn diff: Shows the changes you've made. Use svn revert to discard them (irrevokably!).
svn blame: Shows who's responsible for each bug.
svn add: Marks a file to be added to the repository at the next commit.
svn mv,rm,cp: Moves, re-moves, and copies files under svn control. svn revert will undo it. History is preserved and the diffs are done intelligently, so e.g. copying a huge directory increases the respository size by only a small constant amount.

CVS

Here's the old CVS guide, only relevant to a couple of non-JavaNLP projects still in CVS.