Building the PIA Source Release Tar File

The build is done from your CVS working directory; however, the script does a clean checkout into a separate directory, $REL_DIR, which is set to $(HOME)/src_release by default. The actual release build is done in this directory, not your working directory.

Note that the build process is specific to the environment at Ricoh CRC; so far, that's where all releases are made. The gzipped tar file is generated directly in /pia1/pia/pia_srcversion.tgz and copied to the RiSource.org website. The release directory used to be copied over to /pia1/pia as src_releaseversion; this is no longer done by default. Since the PIA is now open source, binary releases are no longer made, either. Old src_release directories can just be deleted; .tgz files should be kept around for reference.

Preliminary Checking

Use the following command to ensure that references to your home directory have not snuck into the code; typically this happens when you save an AGENT.xml file for a new agent. (Note that the references to /home/steve in Doc/intro.html are OK -- they're in an example.) 

find . -type f \! -name \*class \! -name Root \! -name Repository -print0 |\
xargs -0 -e grep -n -e "$HOME"

Replace $HOME with /pia1 to catch additional references to CRC's local directory structure. References in the top-level Makefile and this note are OK because they involve the release process; a few other references occur in comments.

Of course, you should make sure that the PIA actually runs on your machine, and that the links (at least on the home page) are still good.

The Build Steps

Note that an abbreviated summary of the build process can be found in the top-level Makefile.
  1. Before doing the build, update these variables in PIA/Makefile: 
           RELEASE     = 2
       MAJOR       = 0
       MINOR       = 5
       SUFFIX      = a
  2. CVS commit Makefile
    The build does a clean checkout from the repository and will use the version of the Makefile that is checked out, not the version in your working directory.
  3. make prep-checkout
    This updates the pia version numer, removes the previous release directory, and tags the respository if CREATE_CVS_TAG has been set to 1. This is fairly expensive; if you are only changing the minor version number, consider doing make update-version instead.
  4. make rsync-cvs -- synchronize CVS repositories
    This uses rsync to synchronize the internal and external cvs respositories. You have to be running under ssh-agent for this to work. Otherwise, you'll have to do it manually so that ssh can prompt you for your passphrase: 
    cd /pia1/CvsRoot
rsync -e ssh -a --numeric-ids --delete -v PIA cvs.risource.org:/home/cvsroot/
    Don't be alarmed by the fact that this uploads everything -- the previous step (tagging) changes every file in the repository. Can't be helped.
  5. make src-release -- This does the rest of the build.
    The following table gives the make targets for the individual build steps in case you need to re-do or omit any of them. They all operate on the build directory, so you don't have to cd if you don't want to. The build no longer involves a make clean, so a minor release can be made without a complete rebuild. build_release does make doc, so it is strongly recommended that your machine have at least 128Mb of RAM.
    do_checkout check out the release from the public server.
    build_release Build the code and documentation
    tar_file Make a compressed tar file in /pia1/pia.
      Link the tar file to pia_src.tgz.

    make copy_src_dir is now optional; it copies the src_release directory to /pia1/pia. It uses up quite a lot of space, and can lead to directory trees that are hard to delete.

  6. Check for errors.
    The most common one is a javadoc failure; you can partially fix this with 
           cd ~/src_release/PIA/src/java
       make jdoc
    This doesn't build the indices, unfortunately.
  7. Update the www.RiSource.org website. This is best done via the ssh (secure shell) and scp (secure copy) commands.
This file contains some updates by <steve@rii.ricoh.com>.