BONc INSTALLATION
The below is the INSTALLATION.txt for the latest release on BONc.
Copyright (c) 2007-2010, Fintan Fairmichael, University College Dublin
All rights reserved.
INSTALLATION INSTRUCTIONS
This INSTALLATION.txt explains how to install and use bonc.
Contents:
1. Debian based systems (including Ubuntu)
1.1 Installing on Debian
1.1.1 Dependencies
1.2 Updating on Debian
1.3 Running
2. Systems with the bash shell (Linux and Unix variants, OSX, Cygwin)
2.1 Dependencies
2.1.1 Cygwin (windows)
2.1.2 OSX
2.1.3 Debian
2.1.4 Other linux
2.2 Installing
2.2.1 With the update script
2.2.2 Without the update script
2.3 Updating
2.3.1 With the update script
2.3.2 Without the update script
2.4 Running
2.4.1 Setting JAVA_HOME and BON_HOME
3. Windows without Cygwin
4. Building from source
4.1 Requirements
4.2 Getting the source
4.3 Building
1. DEBIAN BASED SYSTEMS
=======================
The debian build depends on the Sun java version. You must have either
sun-java6-bin or sun-java5-bin installed.
1.1 Installing on Debian
------------------------
Add the following line to your sources.list (/etc/apt/sources.list):
sudo wget http://hunter.ucd.ie/bon/bonc.list -O /etc/apt/sources.list.d/bonc.list
Then:
sudo apt-get update
sudo apt-get install bonc
(or just use synaptic manager to update your sources and install bonc).
1.1.1 Dependencies
The following packages are required:
openjdk-6-jre, sun-java5-bin, or sun-java6-bin (for java)
graphicsmagick (for image manipulation)
rubber (for compiling latex output)
texlive-extra-utils (for pdfcrop, used on generated pdfs)
These dependencies should be automatically dealt with by the apt package
manager.
1.2 Updating on Debian
----------------------
Once you have added our repository to your sources.list, you should
automatically get prompted to install updates to bonc.
You can force your system to update its software cache by issuing the
following command:
sudo apt-get update
1.3 Running
-----------
The debian release creates a symlink from /usr/bin/bonc to a script that
sets the relevant environment variables and runs the main script. Thus, bonc
should automatically be on your path and work correctly.
2. SYSTEMS WITH BASH
====================
Bonc releases are available from http://kind.ucd.ie/products/opensource/BONc/releases/
2.1 Dependencies
----------------
For the most part a Java Runtime Environment (JRE) is only required. However,
to make use of the new documentation generation some additional third-party
tools are required.
2.1.1 Cygwin (windows)
Ensure the following packages are installed:
tetex-base
graphicsmagick
Additionally, the rubber tool must be downloaded manually and its installation
location added to the path (e.g. "export $PATH:/path/to/dir/containing/rubber")
You will find rubber here: http://www.pps.jussieu.fr/~beffara/soft/rubber/
2.1.2 OSX
The easiest way is to get mac ports. Then:
sudo port install graphicsmagick rubber texlive_base
2.1.3 Debian
sudo apt-get install openjdk-6-jre graphicsmagick rubber texlive-extra-utils
2.1.4 Other linux
You will need to install and ensure that graphicsmagick, pdfcrop, rubber and
a latex compiler are installed. Your package manager most likely has these
(although note that pdfcrop usually comes as part of tetex or texlive extras)
2.2 Installing
--------------
Firstly choose a location to install the software to.
NB. wget does not exist on OSX as standard (although it is available via
MacPorts and fink). If you don't have wget, you will have to use the
non-update script methods for installing and updating (2.1.2 and 2.2.2).
2.2.1 With the update script
From the commandline navigate to the desired directory and issue the
following commands:
wget http://kind.ucd.ie/products/opensource/BONc/releases/update
chmod a+x update
./update
Alternatively:
wget -qO - http://kind.ucd.ie/products/opensource/BONc/releases/update | bash
2.2.2 Without the update script
- Visit http://kind.ucd.ie/products/opensource/BONc/releases/
- Download a package of the latest version (e.g., bonc-XXX.tar.gz).
- Extract the files to the desired location (e.g. tar xzf bonc-XXX.tar.gz)
2.3 Updating
------------
2.3.1 With the update script
- From the commandline navigate to the location you previously installed to.
- Simply run the update script
./update
- The script will determine if there is a newer version and, if so, download
it and replace the existing version.
NB. You must be in the actual directory when executing the script
(i.e. ./update)
2.3.2 Without the update script
Simply follow the steps from 2.1.2 for downloading and extracting, ensuring
that when you extract it will overwrite the existing copy.
2.4 Running
-----------
When in the directory you have installed to you can invoke bonc by typing
./bonc
If you want to issue the command from any location, you have two choices:
1. Create a bash alias: add the line "alias bonc=/path/to/bonc/bonc" to
your .bashrc, .bash_aliases or similar. Note that this will use any
already set value of JAVA_HOME, or the version of java on the path if
JAVA_HOME is not set
2. Create a short script that sets BON_HOME, JAVA_HOME and then calls the
actual bonc script. An example of this script is included as
"my-bonc.example" in each release. You can then create a symlink from a
location on your path (e.g. /usr/bin or /usr/local/bin) to this script.
- Copy my-bonc.example:
cp my-bonc.example my-bonc
- Edit my-bonc and fill in the locations for BON_HOME and JAVA_HOME. See
2.3.1 below for information on how to set these.
- Create a symlink from a location in your path to this script:
sudo ln -s /usr/local/bin/bonc /path/to/bonc/my-bonc
If you do the above then bonc will be set up to run and unaffected by
updates of the software (since my-bonc will not be replaced during
updates)
3. Add the installation directory to your path. One way of doing this is to
add a line like the below to your .bash_profile file:
export PATH=$PATH:/path/to/install
2.4.1 Setting JAVA_HOME and BON_HOME
The tool requires two environment variables to be set: JAVA_HOME and BON_HOME.
BON_HOME can be automatically detected if you are running the script directly
(i.e. you are not using a symlink to the script).
If you do not set JAVA_HOME, and JAVA_HOME is not already set in your
environment then the version of java that is on your path will be attempted.
- BON_HOME must be set to be the location where the tool has been installed.
- JAVA_HOME must be the location of a Java Runtime Environment (JRE) version
1.5/5.0 or greater, such that the file $JAVA_HOME/bin/java is a valid
executable.
NB. The paths set should not include the trailing '/'
It is possible to edit and set these at the top of the bonc script, but these
settings are liable to be lost as the script will be replaced during
upgrades. To prevent this, you can set their value in your bash configuration
files (.bashrc, .bash_profile or similar), or using the my-bonc script as
described in option 2 above. Note that the syntax for setting an environment
variable in bash is "export VAR=value".
3. WINDOWS WITHOUT CYGWIN
=========================
Bonc releases are available from http://kind.ucd.ie/products/opensource/BONc/releases/
1. Download the zip of the latest build.
2. Unzip the package to a location of your choice.
3. Edit bonc.bat and set BON_HOME to be the location you extracted to.
4. Edit bonc.bat and set JAVA to be the java executable you wish to use.
Note that this can simply be "java" if you want to use the version of
Java that is already on your path. Otherwise enter the full path of the
java executable you wish to use.
5. Run bonc by executing bonc.bat
You can add bonc to your path by simply editing your path variable and adding
the path to where you extracted the downloaded build.
Note that the new documentation generation does not currently work on windows
without cygwin.
4. BUILDING FROM SOURCE
=======================
4.1 Requirements
----------------
- Building from source requires Java version 5 or later.
- Building uses Apache Ant (http://ant.apache.org/). It has been tested on
version 1.6.5 and 1.7.0, but may work on others.
4.2 Getting the source
----------------------
You can download the latest source from subversion:
svn co https://mobius.ucd.ie/repos/src/bon/bonc
4.3 Building
------------
Inside the directory where you downloaded the source, issuing the command:
ant compile
will compile the source (including generating the lexers/parsers through antlr)
To build a version that can be executed, issue the following command:
ant dist
This will create and place all the required files inside the dist/ subdirectory.
Executing the bonc script located in the dist/ directory will run the built
version.