Installation

1.  Java version

Oracle JDK version 7 (1.7) or later must be installed on all platforms for Camino to compile and run. To test this, run

javac -version
java -version

Oracle refers to Java version 1.7 in the code but Java 7 in the documentation, so if you have Java 7 you will see reference to 1.7.X when you run the above commands.

If you have java but not javac, you have the Java Runtime Environment (JRE) - download the Java Development Kit (JDK) so that you can install Camino.

2.  Setting the maximum memory allocation

It's may be necessary to increase the amount of RAM Camino can use from the default 1000 Mb. To do this, set the environment variable CAMINO_HEAP_SIZE to the number of megabytes of RAM you want to allow Camino to allocate, which must be less than your available physical RAM (a bit less than the total because some RAM is used by the system). For example, if you have 2Gb of RAM, you should safely be able to set CAMINO_HEAP_SIZE to 1800 or so.

The exact procedure will depend upon your shell. Type

echo $SHELL

to tell what you have. If it's sh / bash, then type

export CAMINO_HEAP_SIZE=1800

If your shell is csh / tcsh, then type

setenv CAMINO_HEAP_SIZE 1800

You can set these values in your configuration files so that they remain in effect - see below for examples of how to do this.

3.  Installing on Linux/Unix

System requirements
In order to run Camino you will need:

  • A bash-like shell environment
  • The GNU make command.
  • The man command.

Step 1: Installing Java and Setup
Many Linux distributions have a package management system that will do the installation for you without going to the Sun site. However, these may require system administrator privileges. After installation, you may need to add Java to your PATH, so that you can call javac and java. The method for doing this is slightly different for different shells.

If your shell is bash, open the file $HOME/.bashrc in a text editor and add

export PATH=/path/to/java/bin:$PATH

where /path/to/java/bin is the directory containing javac, java and the other JDK commands. If your shell is csh/tcsh, edit $HOME/.cshrc or $HOME/.tshrc and add

setenv PATH /path/to/java/bin:$PATH

Step 2: Install and compile Camino
You may obtain the source code by downloading an archive from the site or by checking out the code via Git. Please see the Camino Sourceforge page for details of the code repository. If you have a downloaded archive, the file name will contain the exact version that you downloaded, for example camino-code-17f6c97f81335072e2d59b.zip. The string at the end is a hash that uniquely identifies the exact snapshot of the code - if you ever need support, this will let us know what version you have. Unpack the code:

unzip camino-code-17f6c97f81335072e2d59b.zip

You probably also want to move it to a more generic path:

mv camino-code-17f6c97f81335072e2d59b camino

To compile the toolkit, type

cd camino
make

after this is completed, Camino is ready to use.

Step 3: Add Camino binaries and man pages to the path
Bash users should add

export MANPATH=/home/user/camino/man:$MANPATH
export PATH=/home/user/camino/bin:$PATH

to the end of the $HOME/.bashrc file. For csh/tcsh shells, edit $HOME/.cshrc or $HOME/.tshrc and add

setenv PATH /home/user/camino/bin:$PATH
setenv MANPATH /home/user/camino/bin:$PATH

The above examples assume Camino is installed in /home/user/camino, you should substitute the directory where Camino is installed.

4.  Installing on Mac OS X

System requirements
In order to run Camino you will need:

  • Mac OS X version recent enough to support the Javsa requirements, currently 10.7.3 (Lion) or later

The installation procedure is the same on Mac OS X as for Linux, except for the Java installation. We recommend that you install XCode, then follow the instructions for Linux/Unix from Step 2 onwards.

Step 1: Install XCode
Installing Xcode will give you several useful tools including Java, Git, Make and X11. If you have an OS X disk you can install XCode from there, otherwise get it from Apple.

Other handy Unix packages for the Mac can be obtained using HomeBrew.

5.  Installing on Windows

System requirements
In order to run Camino you will need:

  • Windows XP or Vista.
  • Cygwin.

Step 1: Installing Java and Setup
* Download and install the Java Development Kit (JDK) from Sun.

  • Once you have installed the JDK, add Java to your Windows path.
For Windows XP, this is accomplished as follows:
1) From the desktop, click the Start Button, right-click on "My Computer" and click on "Properties".
2) In the "System Properties" window that appears, select the "Advanced" tab.
3) Click the "Environment variables" button.
4) Highlight the "Path" variable in "System Variables" and click the "edit" button.
5) If the path to your Java SDK is not in the list, add the full path to the end of the list, using a semi-colon to separate it from the previous entry. Typically, the path will be similar to C:\Program Files\Java\jdk1.7.0_05\bin
For Windows Vista:
1) Click the Start Button, right-click on "Computer" and click on "Properties".
2) In the "System Properties" window that appears, click "Advanced system settings" on the left hand side.
3) Click the "Environment variables" button.
4) Highlight the "Path" variable in "System Variables" and click the "edit" button.
5) If the path to your Java SDK is not in the list, add the full path to the end of the list, using a semi-colon to separate it from the previous entry. Typically, the path will be similar to C:\Program Files\Java\jdk1.7.0_05\bin
  • To check that the necessary Java tools are correctly installed, run from a command prompt the following commands:
    javac -version
    java -version

Step 2: Installing Cygwin and Setup
Although the individual components of Camino will run from a command line under Windows, in order to get the most out of Camino it is necessary to have a Unix-like shell environment that allows data pipes and redirection. Without these facilities, it is extremely difficult to use Camino in the way it was designed.

Fortunately, it is easy to install Camino under windows with Cygwin. This section explains the procedure step-by-step.

  • Download the Cygwin installer from the Cygwin website and run the installer.
  • During installation you will be asked which packages you would like to install with Cygwin. By default, the installer may not install some of the packages Camino requires. You will need the following packages to run Camino:
    • make (in Devel) -- to build the toolkit
    • man (in System) -- to read the manual pages provided
  • Once installed, run Cygwin for the first time; in the directory C:\cygwin it will create a directory called home. Inside this directory will be a sub-directory with the name of the current user (e.g. C:\cygwin\home\yourname). You may encounter problems later on if there are spaces in the directory names. If your Windows user name has a space in it (e.g. C:\cygwin\home\Tobias Funke), we would recommend creating another sub-directory in home without spaces (e.g. C:\cygwin\home\TobiasFunke).

Step 3: Installing and Compiling Camino
You may obtain the source code by downloading an archive from the site or by checking out the code via Git. Please see the Camino Sourceforge page for details of the code repository. If you have a downloaded archive, the file name will contain the exact version that you downloaded, eg camino_v2_325.tar.bz2. Unpack the code with the commands:

bunzip2 camino_v2_325.tar.bz2
tar xvf camino_v2_325.tar

replacing the version numbering with whichever version you have. The version information is stored in camino/version_info.txt - please include this information if you contact us for help.

To compile the toolkit, type

cd camino
make

add the camino bin directory to your path (see unix installation for more details)

export PATH=$CAMINO/bin:$PATH

where $CAMINO is the path to your camino directory.

After this is completed, Camino is ready to use.

Many thanks to Jonathan Ashmore for his helpful comments in creating this guide.