Hacking J-Bird (Version 0.5.2): Compile J-Bird for Yourself

NOTICES TO PEOPLE WHO COMPILE AND RUN J-BIRD FOR THEMSELVES IN THE SOURCE CODE DIRECTORY (i.e., people who do not use the installer)

- On 10 June 2006 commits were made to cvs that require some work on your part if you upgrade your code and if you have not upgraded since 10 June 2006. (J-Bird 0.5.0 was released in February, 2006, and J-Bird 0.5.1 was released well after 10 June 2006.)

ant allclasses
ant run-separate
ant run-launch

Note that run-separate needs to be run only once ever. The ant target run-launch is new. Depending on the state of the application, it runs the database builder, repairs the database, or launches J-Bird itself.

- A NEW VERSION OF MCKOI DATABASE WAS COMMITTED TO CVS ON 16 OCTOBER, 2004. THE VERSION IS MCKOIDB-1.0.3. IF YOU HAVE BEEN RUNNING A VERSION OF J-BIRD FROM CVS BEFORE 16 OCTOBER 2004 OR FROM DOWNLOADED SOURCECODE VERSION 0.4.0 OR EARLIER AND IF YOU ARE UPDATING THE SOURCE CODE AND RECOMPILING, FILES IN EXISTING J-BIRD DATABASES MUST BE REFORMATTED BEFORE YOU CAN RUN A NEWLY COMPILED VERSION OF J-BIRD. ALSO, THE J-BIRD DATABASE SCHEMA WAS MODIFIED AT THE SAME TIME, AND IT, TOO, MUST BE UPDATED BEFORE YOU RUN J-BIRD. IF YOU COMPILE AND RUN J-BIRD FOR YOURSELF YOU MUST REFORMAT FOR YOURSELF. TO DO SO RUN,

ant allclasses
ant update-mckoidb-format
ant update-jbird-schema

END OF NOTICES

Overview

If you compile J-Bird for yourself, you have two choices: compile and install J-Bird from the source code or unpack the source code and compile and run J-Bird from within the source code directories. If you simply want to use J-Bird, the first choice is best. If you are interested in modifying the source code, it is best to compile and run J-Bird from within the source code tree before actually installing it. (Prior to J-Bird version 0.5.2, the only possibility was to compile and run from within the source tree.)

Separate datasets are created and used by an installed copy of J-Bird and a copy that is run from within the source tree. Installed copies of J-Bird store data in the same locations as copies that are installed using the install packages that are distributed on sourceforge. Copies running in the source tree access data that are stored in a subdirectory of the basal source directory.

Prerequisites

To compile J-Bird, you'll need a Java development kit (usually called a jdk) rather than just a run-time environment (usually called a JRE). You'll need a development kit with version greater than or equal to 1.4, but you will be best off with the newest version. If you do have a run-time environment, you won't need it once you've installed a jdk. Development kits are available at http://java.sun.com/.

You also need Apache Ant version 1.6.2 or better, including the optional ant tasks. You can find ant at http://ant.apache.org/.

Unset your CLASSPATH variable before using ant to compile or install J-Bird. If you do not do so, some classes may not be compiled, and J-Bird will throw missing class exceptions.

Compile and install

To compile and install J-Bird change into the basal directory of the source tree. It should be named jbird or jbird-0.5.2. You will run all commands from this directory.

You can control where J-Bird is installed. To see the default destination on your computer, run the command

	ant show-install-dir

. If you satisfied with the result you can install J-Bird by running the command

	ant install

. To install in an alternate location, set the ant property "install.dir" to the directory in which J-Bird will be installed. For example, suppose that yours is a Windows computer and you would like to install in your home directory"C:\Documents and Settings\MyIDhere", where MyIDhere is replaced with your ID. The commands to run would be

	ant -Dinstall.dir="C:\Documents and Settings\MyIDhere" show-install-dir

to test whether you've correctly specified the property and

	ant -Dinstall.dir="C:\Documents and Settings\MyIDhere" install

to install J-Bird. In this example, the J-Bird directory J-Bird is be "C:\Documents and Settings\MyIDhere\J-Bird".

On Mac OS X, J-Bird is installed as an application bundle, and you can launch it by double clicking on it, just like any other application. On Windows shortcuts are created on the desktop and in the start-programs menu. On Unix/Linux, the script for launching J-Bird is in the J-Bird directory, and it is named J-Bird.sh.

Windows users can control whether shortcuts are installed for all users or for just the user that installs the software by setting the ant property shortcuts.win to either "common" or "personal". By default, shortcuts are installed for all users. For example, the command to install J-Bird in MyIDhere's home directory and to install shortcut for only MyIDhere is

	ant -Dshortcuts.win=personal -Dinstall.dir="C:\Documents and Settings\MyIDhere" install

Compile and run without installing

J-Bird can be compiled by changing into the jbird source directory, and running ant with the command

		ant allclasses
	

After compiling J-Bird (and downloading a master species list - see the section of the users guide for details on master species lists uguide.html#requirements), you can run J-Bird and build your database. Use the command

		ant run-launch