Disclaimer don't get the wrong idea about what you've found here

What appears below are my personal notes I wish were part of my long-term memory but don't always seem to fit. I strive for accuracy and clarity and appreciate feedback. If applying any of this information anywhere, confirm for youself the correctness of your work as what you see below might very well be, albeit unintentionally, incorrect or misleading. These notes are here as an easy reference for myself.

Information worthy of a more formal presentation will appear elsewhere than this "Scratch" area. - ksb

KSB's BFD/Ant Cheat Sheet

Table of Contents


Administrative Making sure bfd is properly installed

If the symlink to bfd is not in /usr/local/bin, then bfd probably needs to be installed. bfd is installed and updated using rsync. glacier is where this will be described but it will look something like this (done as root):

# cd /usr/local/icecube/tools
# wget http://glacier.lbl.gov/rsync.daq.Linux-i386
# rsync --delete -vrlpt -e ssh --include-from=rsync.daq.Linux-i386 $USER@glacier.lbl.gov:/home/icecube/tools/ /usr/local/icecube/tools

or this

# cd /usr/local/icecube/tools
# rsync --delete -vrlpt rsync://glacier.lbl.gov/DAQ.Prod.Linux-i386/

BFD uses cvs, so $CVSROOT, etc. will need to set up for bfd to work.

Workspace Managing your bfd workspace

Use init to initialize a new BFD Workspace you'll need to know the location of the icecube tools (probably /usr/local/icecube/tools)

$ bfd init /usr/local/icecube/tools

This produces lots of output listing what is being installed.

Source the setup.sh (or .csh) file to setup your environment.

$ source setup.sh

This will need to be done with each new shell as it sets up your environment for ant, etc.

Use dispose to remove projects from your workspace, or the entire workspace itself:

$ bfd dispose wallace  # dispose of the wallace project
$ bfd dispose          # dispose of the entire workspace

To build all projects in a workspace:

$ ant lib.all     # Run the 'ant lib' target in each project (in a dependancy-aware order)
$ ant clean.all   # Run the 'ant clean' target in each project

The dependancies of a project are in it's project.xml file.

To build projects from the top of the workspace:

$ ant -DPROJECT=wallace lib              # Run the 'ant lib' target for wallace project
$ ant -DPROJECT=wallace defaultProject   # Makes wallace the default for ant commands in this dir
$ ant clean                              # This is now runs the clean target for wallace

Ant is used to create a new project (this is not the same as checking out an existing project):

$ mkdir wallace     # This dir needs to exist before the next command is run
$ ant -DPACKAGE=foo.bar.bat -DPROJECT=wallace createProject    # Create a new project wallace in a foo.bar.bat package

This creates a number of files and dirs under the wallace dir, many of which will need to be modified. This also sets the default package for the project to be foo.bar.bat.

Ant can also be used to create new classes, interfaces and packages:

$ cd wallace     # Or you'll need to specify -DPROJECT=wallace in the following commands
$ ant -DCLASS=Counter createInterface    # Use -DPACKAGE=some.other.package to use a different
$ ant -DCLASS=CounterImpl createClass    #   package than the default foo.bar.bat
$ ant -DPACKAGE=brand.new.package createPackage    # Creates a new package in wallace

The createPackage also sets the new package as the default for project.

To add files into bfd, use either the add or uadd bfd commands:

$ bfd uadd wallace     # Add all 'unknown' files in the wallace project
$ ant add newfile      # Add newfile into the current project.

The uadd command works recursively so you will be prompted for each dir of new files.

Projects Working with projects

Checkout a project:

$ bfd co [-a $CVSROOT] [-r tag] wallace

Using the optional CVSROOT or tag. If you don't specify a tag you get the HEAD (or most recently archived version) of the project.

Non-custom tags have the following form: VJJ-NN-BB. Where:

JJMajor version number
NNMinor version number
BBBugfix version number

For example:

$ bfd co -r V01-04-12 wallace

Checks out version 1.4.12 of wallace.

To build a project, cd into it and run one of the following ant targets:

$ cd project
$ ant lib           # builds jar file into ../lib
$ ant test          # runs unit tests
$ ant report        # (default target) generates unit test report in <workspace>/docs/junit/index.html
$ ant -projecthelp  # list the ant targets

Use archive commit your changes into the source code repository:

$ bfd ar [-m "Meaningfull descirption of changes made"] wallace  # archive your changes to the HEAD of the wallace project

The -m flag is optional. If missing, your $EDITOR will be used to compose the commit log.

Use the head command to remove a project from being stuck to a tag to being ready for archiving to the HEAD:

$ bfd head wallace  # Unstick wallace from any tags

This doesn't do an update so you might have to do that (is there a bfd command for that?) before you can archive any changes. If, for example, someone has archived changes to the same file but hasn't delivered it to a new tag.

Use deliver to tag the project's current state as having reached a new milestone:

$ bfd deliver [-j|-n|-b]|-t tag wallace   # deliver (tag) wallace to a new release state

Where -j, -n, & -b increment the Major, Minor & Bugfix part of the tag respectively. The -t tag is for creating a custom tag. Thus only one of these flags can be used.

MetaProjects Working with sets of projects

A metaproject is a project which contains a set of other projects. A tag on a metaproject identifies each contained project at a specific tag.

Checking out a Metaproject is identical to checking out a simple project:

$ bfd co [-r tag] WALLACE  # Checkout WALLACE meta-project

This will checkout all of the projects in the WALLACE meta-project into the current dir. The WALLACE dir (named after the metaproject), has metaproject specific files, not the subprojects. If you don't specify a tag you get the HEAD of each project. Meta-project names are all uppercase by convention.

Given that checking out a metaproject doesn't nest the projects into the metaproject dir, you might prefer to use the produce command below. Personally, I'd like to see an option that allow a checkout of a metaproject into a single dir.

The produce command creates a whole new BFD workspace where it checks-out, builds and runs tests for the metaproject.

$ bfd produce -r V01-00-01 -l WALLACE.V01-00-01 WALLACE /usr/local/icecube/tools  # Checkout and build the WALLACE metaproject in a new LOCAL-WALLACE.V01-00-01 workspace dir

The -r tag arg is the same as for checkout wrt metaprojects, the -l identifies a subdir in which the new BFD workspace where all this work will be done and the /usr/local/icecube/tools identifies the location of the bfd tools location - the arg when it does the bfd init to build the new workspace. This can be picked up if $TOOLS is set to this location.

(Seems to me that all of these args (except the metaproject) should be optional. A missing -r means to pull from the HEAD for each project and a missing -l means to do the building work in each project dir. The requirement of the TOOLS dir is a known bug.)

Keith S. Beattie is responsible for this document, located at http://dst.lbl.gov/~ksb/Scratch/bfd_cheatsheet.html, which is subject to LBNL's Privacy & Security Notice, Copyright Status and Disclaimers.

Last Modified: Monday, 25-Feb-2013 16:57:57 PST