5 May 2014 by Remco Bouckaert

There are two ways to put everything you need for a BEAST package into a zip file so that it can be used by the package manager:

• If you like ant, the easieast way is re-using a build.xml file
• Otherwise, you can zip up a package by hand

The first way has the disadvantage you might not quite understand everything that goes on. So, to my surprise, many people opt for the second way — hence the explanation below to tell everything you need to know to make it work

Using ant

Assumptions for this way to work:

• You have you project organised such that the BEAST2 source code is in the beast2 directory and your package source code is in beast2/../mypackage, that is mypackage is a sibling directory of beast2.
• The source code is inside the mypackage/src directory and you use the beast package for classes you want to distribute.

1. Copy a build.xml and version.xml file from an existing project into the directory of your package directory. I’ll assume these get copied from the build.xml file from the RBS package, but you can use XML files from other projects as well.
2. Search/replace every occurrance of RBS with the name of your package in build.xml
3. You may want to change files that are copied. Go to the “addon” target in the build.xml file (where it says <target name="addon") where you see a few &ltcopy> elements. You may need to delete some entries if you do not have any BEAUti templates, or rename them.
4. Do the same with version.xml
5. run ant addon from the command line inside the mypackage directory.

The screen output — a fragment shown below — will show where the zip file containing the package will be created, in this case /Users/remcobouckaert/workspace/mypackage/build/dist/MyPackage.addon.v1.0.0.zip:

...

addon:
   [delete] Deleting directory /Users/remcobouckaert/workspace/mypackage/release/add-on
    [mkdir] Created dir: /Users/remcobouckaert/workspace/mypackage/release/add-on
    [mkdir] Created dir: /Users/remcobouckaert/workspace/mypackage/release/add-on/lib
    [mkdir] Created dir: /Users/remcobouckaert/workspace/mypackage/release/add-on/examples
    [mkdir] Created dir: /Users/remcobouckaert/workspace/mypackage/release/add-on/templates
     [copy] Copying 1 file to /Users/remcobouckaert/workspace/mypackage/release/add-on
     [copy] Copying 47 files to /Users/remcobouckaert/workspace/mypackage/release/add-on/examples
     [copy] Copying 1 file to /Users/remcobouckaert/workspace/mypackage/release/add-on/lib
     [copy] Copying 1 file to /Users/remcobouckaert/workspace/mypackage/release/add-on
     [copy] Copying 2 files to /Users/remcobouckaert/workspace/mypackage/release/add-on/templates
      [jar] Building jar: /Users/remcobouckaert/workspace/mypackage/build/dist/MyPackage.addon.v1.0.0.zip
     [echo] Add-on version v1.0.0 release is finished.

BUILD SUCCESSFUL
Total time: 9 seconds

Roll your own

You might want to read the relevant chapter in the BEAST book to start with.

BEAST looks for jar files inside the package directory where each package has its own subdirectory. It only picks up jar files if they are in the lib directory. Likewise, BEAUti templates are only picked up from XML files in the templates directory.

By convention, the following directory structure with some of the files are expected:

   META-INF/
   META-INF/MANIFEST.MF
   examples/                 // example XML or JSON files
   examples/myExample.xml
   doc/                      // user documentation
   doc/mypackage.pdf
   lib/                      // jar files with executable code and dependent libraries
   lib/mypacakge.addon.jar
   templates/                // BEAUti template files
   templates/MyTemplate.xml
   MyPackage.src.jar         // zipped up source files
   version.xml               // version and dependency information

The version.xml file tells the version of the package and which other packages — and their versions — this package relies on.

So, you should create the above files, in a structure similar to the above and zip them up. Note that you want to compile the java classes to be 1.6 compatible if you only use 1.6 code. Also, make sure that the jar with binary classes is in the lib directory (not mypackage/lib or addon/lib). Finally, any BEAUti templates should go in the templates directory.

You might want to name your zip file something along the lines of mypackage.addon.v1.0.0.zip to keep track of version numbers and indicating the purpose of the file.

Trouble shooting

The ant file fails: typically, ant produces sensible error messages, so read these! Typos, missing files, misnamed directories are not uncommon.

BEAST does not load the jar file: perhaps it is in the wrong location. BEAST expects mypackage.jar to be in the location $BEAST/2.1/MyPackage/lib/mypacakage.jar where $BEAST is the package directory for your OS, 2.1 is the version number (major=2, minor=1, patchnr=any) of BEAST. If you happen to zip all files in the addon directory, your jar file may end p in $BEAST/2.1/MyPackage/addon/lib/mypacakage.jar where it is ignored.

BEAST says wrong version nr: the jar file is compiled against a java version newer than 1.6. Many users are still using Java 6, so we try to keep the code Java 1.6 compatible for now. To fix this, ensure the jar file is 1.6 compatible.

BEAUti template does not load: perhaps it is not in the correct location. BEAUti tries to load templates of packages by loading any XML file from the directory $BEAST/2.1/MyPackage/templates/. If your template is in another location, it will be ignored.

Installing the package

Some options:

• let me know the url where the zip file is available on web and I wil add it to the list of packages that BEAUti uses to manage packages. This way, everyone that install BEAST/BEAUti has access to the package immediately.
• ask users to unzip your zip file in the BEAST pacakge directory, which can be a bit awkward.
• maintain your own package XML file (similar to the one here, and tell users the url of the package XML file. In the package manager in BEAUti, you can add this url using the Manage package locations button.