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 https://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 https://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: https://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 https://kind.ucd.ie/products/opensource/BONc/releases/update chmod a+x update ./update Alternatively: wget -qO - https://kind.ucd.ie/products/opensource/BONc/releases/update | bash 2.2.2 Without the update script - Visit https://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 https://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 (https://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.