Packages (previously known as add-ons or plugins) can be installed through BEAUti or from the command line.

Desktop machines

The easiest way to Manage packages and install/un-install them is to start up BEAUti and select the menu File/Manage Packages. A window pops up where you can select the packages in the list to (un)install.

BEAST 2.1.2

In the example above, BDSKY, BEAST_CLASSIC, BEASTlabs, MODEL_SELECTION, RBS and SNAPP are installed, and the rest are not.

older versions of BEAST

In the example above, SNAPP and RB are installed, and the rest are not.

Installation directories

To see where packages are installed, click the button with question mark in the dialog’s right left corner. A new dialog is shown with the information where you can find packages. Different operating systems have different locations where the packages are installed. There is a local package directory and a system wide package directory. Packages installed through the packagemanager dialog in BEAUti are saved in the user’s local package directory. To install in the system wide directory, just move the directory with the package to the system wide package directory OR use the command line version (see below).

Mac:

Linux:

Server machines

For computers without GUI, like high performance clusters, packages can be managed through the command line. An application called ‘packagemanager’ is part of the Linux distribution of BEAST, and has the following options:

 Usage: packagemanager [-list] [-add <NAME>] [-del <NAME>] [-useAppDir] [-dir <DIR>] [-help] 
   -list List available packages
   -add Install the <NAME> package 
   -del Uninstall the <NAME> package 
   -useAppDir Use application (system wide) installation directory. Note this requires writing rights to the application directory. If not specified, the user's BEAST directory will be used.
   -dir Install/uninstall package in direcotry <DIR>. This overrides the useAppDir option
   -update Check for updates, and ask to install if available
   -updatenow Check for updates and install without asking
   -help Show help

 Examples:
 packagemanager -list
 packagemanager -add SNAPP
 packagemanager -useAppDir -add SNAPP
 packagemanager -del SNAPP

Alternatively the package manager can be launched as

   java -cp beast.jar beast.util.PackageManager

Installation on cluster

By default, packages will be installed in user's BEAST directories, but to make packages available to all users on a HPC cluster BEAST also picks up packages from a system directory (\Program Files\BEAST\2.6 on Windows, /Library/Application Support/BEAST/2.6 on OS X, and /usr/local/share/beast/ on Linux).

To install packages in such directory, use the `-useAppDir` option for the command line version of the package manager. Make sure you have write access rights to the system directory.

Customising installation directories

To install packages in custom directories using the packagemanager command line version, use the -dir option (see above), e.g.

packagemanager -dir /Users/me/my_package_dir -add bModelTest

to install the bModelTest package in directory /Users/me/my_package_dir. When starting BEAST, BEAUti etc, these programs need to be told about this custom directory. To do so, start them with java using the “beast.user.package.dir” directive. For example, like so:

java -Dbeast.user.package.dir=/Users/me/my_package_dir beast.app.beastapp.BeastLauncher beast.xml

It is probably be easiest to just edit the scripts in the directory where BEAST is installed (BEAST/bat for Windows, /Application/BEAST 2.6.6/bin on OS X, beast/bin on Linux), and add -Dbeast.user.package.dir=/Users/me/my_package_dir just after ever place where java is called (typically at the end of the script).

Similarly, there is the "beast.system.package.dir" variable to point to a system directory in a non-standard location. Packages need to be installed by hand in such custom system directory -- there is no packagemanager support to do so (unless the -Dbeast.system.package.dir directive is used when starting the packagemanager).

Install by hand

If for some reason you cannot install a package through BEAUti or the package manager, you can always install the package by hand. First, get the zip file you want to install. For example, to install the VSS package, download https://github.com/CompEvol/CBAN/releases/download/v2.1.2/VSS.addon.v1.0.0.zip. Then, create a VSS subdirectory

for Windows in Users\<YourName>\BEAST\2.X\VSS
for Mac in /Users/<YourName>\/Library/Application Support/BEAST/2.X/VSS
for Linux /home/<YourName>/.beast/2.X/VSS

Here <YourName> is the username you use, and in “2.X” the X refers to the major version of BEAST, so 2.X=2.1 for version 2.1.3.

Next, unzip the file VSS.addon.v1.0.0.zip inside the VSS directory

For BEAST v2.5.x and later, you need to reset the class path stored in the beauti.properties file. Easiest to do this is by starting BEAUti and click the menu File/Clear class path. Alternatively, delete the package.path entry from the beauti.properties file. The file is stored in the BEAST package directory (~/.beast/2.X/ for Linux, ~/Library/Application Support/BEAST/2.X/ on OS X, or c:\Users\yourname\BEAST\2.X\ on Windows).

Adding package repositories by hand

These entries are stored in beauti.properties file in the package directory has an entry for packages.url. Instead of managing these repositories through BEAUti, you can edit the file with a text editor. For example, if you set this entry to

packages.url=https\://raw.githubusercontent.com/CompEvol/CBAN/master/packages-extra.xml

(note the \ before :) the package manager will pick up packages from https://raw.githubusercontent.com/CompEvol/CBAN/master/packages-extra.xml.

Trouble shooting

To install packages you need internet access.

Some software prevents access to the internet by programs like BEAUti. In that case, either tell the software to grant access to BEAUti, or install packages by hand.

Releasing packages

When you develop your own package, to make it available for other users you need to create a zip file with source code, jar file, examples etc. in it. The easiest way to do this is to have an ant-script set up for this -- see for example the build.xml file for BEASTlabs on how to do this, and proceed as follows:

• Build the package using ant addon or just ant from the package directory.
• Test that the package works by installing it by hand.
• Upload the file yourpackage.addon.v1.2.3.zip to a place on the internet where it can be downloaded by the package manager. Note BEAST v2.6.3 and earlier cannot access the github release area -- this was the preferred way to make packages available, but due to a change in github this no longer works.

  A good place to store the package is as part of a github repository (like the packages repository).

• Make an entry in a package repository file. If your package is peer reviewed and published, and you want it to be available by default to all users, the best place to add it is in packages2.6.xml. If you do not have access already, just make a pull request with an updated package file.

  Note the comment at the start of the package file: NOTE: if you edit this file, DO NOT DELETE any entries. Older package versions will be available for running BEAST files so that analyses can be replicated with the package versions used in the original analysis.

  Make sure the package file parses! It is very easy to make a mistake (missing end tag, or typo in XML elements), so before committing any changes you can sanity check the file for instance by loading the XML in a browser. An even better test is to add the local file on your computer to your list of package repositories and start the package manager (or BEAUti). Note that local file URL should be of the form file:///tmp/packagefile.xml when the file packagefile.xml is in the /tmp/ folder on OS X or Linux and file:///c:/temp/pacakgefile.xml for the C-drive \temp\ directory on Windows.

  Alternatively, you can host your own package repository file, and add some instructions for users on how to add a package repository and install a file (see here for an example).

• Make sure the package turns up in the package manager and installs properly. Note that there may be a small delay due to the package repository file being cached.

Package directory structure

The directory structure of the package directory is of this form:

{package_directory}
	2.6/
		BEAST/
			lib/
			examples/
			templates/
			version.xml
			...
		BEASTLabs/
			lib/
			examples/
			templates/
			version.xml
			...
		bModelTest/	
			lib/
			examples/
			templates/
			version.xml
			...			

To install a specific version of a package, use the `-version` option to specify it for the command line version of the packagemanager. Alternatively, in the GUI version, uncheck the `Latest` checkbox in the bottom left corner of the package manager dialog. When clicking the `Install/Upgrade` button you will be asked to select a version from a drop down box. Specific versions will not be installed in the package directory as above, but in an `archive` directory, and the directory structure will look something like this:

{package_directory}
	2.6/
		BEASTLabs/
			lib/
			examples/
			templates/
			version.xml
			...
		archive/
			BEASTLabs/
				1.9.5
					lib/
					examples/
					templates/
					version.xml
					...
				1.9.6
					lib/
					examples/
					templates/
					version.xml
					...

The BEASTLabs version directly under the `2.6` directory will contain the latest version. Inside the archive directory version 1.9.5 and 1.9.6 of the package are installed. When running BEAST only one of these package will be loaded, and the other versions of the same package will be ignored.