JavaNLP Quick Guide Source Code Management

Here at the JavaNLP mines we use Subversion to manage our source code. If you're not familiar with the 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: setenv PATH "$PATH":/u/nlp/packages/subversion/bin. Users enlightened enough to use bash should add the following to your .bashrc file: export PATH=$PATH:/u/nlp/packages/subversion/bin.

If you're going to be checking things out on to an NLP machine, run source filename (where filename is the file you just edited) to push those changes to your current environment.

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 locally.

All you need to do is run this:

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

It may axe 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 OSX machines

Either use Eclipse, IntelliJ, or get subversion installed for command line use.

Install MacPorts from here.
Open up Terminal and run "sudo port install svn"
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)
src/
All the non-test source code for this project goes here.
test/
All test code goes here. We use jUnit
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.

File protections

The SVN repository has to remain all nlp group read/write. You should put in your .cshrc or .bashrc or whatever:

umask 002

as 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).