%\VignetteIndexEntry{EBImage: installation HOWTO}
%\VignetteDepends{}
%\VignetteKeywords{installation}
%\VignettePackage{EBImage}

\documentclass[11pt]{article}
%% times,10pt,twocolumn
\usepackage{graphicx}
\usepackage{verbatim}
\topmargin -1.5cm        % read Lamport p.163
\oddsidemargin -0.04cm   % read Lamport p.163
\evensidemargin -0.04cm  % same as oddsidemargin but for left-hand pages
\textwidth 16.59cm
\textheight 21.94cm 

\usepackage{color}
\usepackage{hyperref}
\definecolor{darkblue}{rgb}{0.2,0.0,0.4}

\newcommand{\lib}[1]{{\mbox{\normalfont\textsf{#1}}}}
\newcommand{\file}[1]{{\mbox{\normalfont\textsf{'#1'}}}}
\newcommand{\R}{{\mbox{\normalfont\textsf{R}}}}
\newcommand{\EBImage}{{\mbox{\normalfont\textsf{EBImage}}}}
\newcommand{\Rfunction}[1]{{\mbox{\normalfont\texttt{#1}}}}
\newcommand{\Robject}[1]{{\mbox{\normalfont\texttt{#1}}}}
\newcommand{\Rpackage}[1]{{\mbox{\normalfont\textsf{#1}}}}
\newcommand{\Rclass}[1]{{\mbox{\normalfont\textit{#1}}}}
\newcommand{\code}[1]{{\mbox{\normalfont\texttt{#1}}}}

\newcommand{\email}[1]{\mbox{\href{mailto:#1}{\textcolor{darkblue}{\normalfont{#1}}}}}
\newcommand{\web}[2]{\mbox{\href{#2}{\textcolor{darkblue}{\normalfont{#1}}}}}

\usepackage{theorem}
\theoremstyle{break} \newtheorem{Ex}{Exercise}
\newenvironment{Sol}{\tiny}{}

%\usepackage[baseurl={http://www.ebi.ac.uk/~osklyar/EBImage/},pdftitle={EBImage - installation HOWTO},pdfauthor={Oleg Sklyar},pdfsubject={EBImage},pdfkeywords={installation},pagebackref,bookmarks,colorlinks,linkcolor=darkblue,citecolor=darkblue,pagecolor=darkblue,raiselinks,plainpages,pdftex]{hyperref}

\begin{document}

\begin{figure}
%\vspace*{.1in}
\begin{center}
\scalebox{0.2}{\includegraphics{logo.png}}
\end{center}
\end{figure}

\title{\Rpackage{EBImage} installation HOWTO}
\author{Oleg Sklyar\\
 \email{osklyar@ebi.ac.uk} }

\maketitle

The package was tested to work on Linux (32/64 bit), MacOS, Windows XP (32 bit) and Solaris (64 bit). It should be possible to install and run the package on other versions of UNIX-like and Windows systems in a similar manner. On Windows, all dependencies are required. On other systems, some dependencies are recommended (but not required) in order to enjoy the full functionality of the package. \lib{GTK+} support was not tested on MacOS, but there is no apparent reason for the package to fail to support it.

%--------------------------------------------------
\section{UNIX/Linux Installation}
%--------------------------------------------------

The installation should be performed from the source after the following dependencies are satisfied:

\begin{description}
    \item \lib{ImageMagick} version at least 6.2.0,
    \item \lib{GTK+} version at least 2.6 (recommended).
\end{description}

On most Linux distributions, these libraries are available as precompiled binaries in \lib{rpm} or \lib{deb} format. You will also need the corresponding header files\footnote{A library's header files are necessary to compile other programs, such as \lib{EBImage}, that use the library. The header files contain necessary information about the functionality of the library.}, these are in equinomous package with suffix \code{-dev} or \code{-devel}. The following instructions work for Ubuntu Linux, but other distributions have similar packages with slight naming differences.

For \lib{ImageMagick}, you will need to install  \code{libmagick9-dev} (including its dependencies) using \code{apt-get} or the Synaptic package manager. Alternatively, you can download the latest version of \lib{ImageMagick} from \url{http://www.imagemagick.org} and install it from source using 
\begin{verbatim}
./configure && make && make install
\end{verbatim}
This will also install the header files.

\Rpackage{EBImage} will function without \lib{GTK+}, but most of its GUI functionality (image chooser, interactive image display with zoom features etc) will be disabled. You will need \code{libgtk2.0-dev} with all the dependencies, which normally include \code{glib}, \code{pango-dev}, \code{libcairo-dev}, \code{atk-dev} and some others. Alternatively, all these packages can be installed from source available at \url{http://www.gtk.org} along with the corresponding installation instructions. When installing \lib{GTK+}, please ensure that you also install \code{pkg-config} as it is used to determine the location of \lib{GTK+} include files and its compile flags. Without this package, \lib{GTK+} will not be located on your system by the package installer. \code{pkg-config} is normally installed in UNIX/Linux systems running the \lib{GNOME} desktop manager, it is also likely in this case that you have necessary \lib{GTK+} development files because \lib{GNOME} is build upon \lib{GTK+}.

After the dependencies are installed, install the package with the standard \code{R CMD INSTALL} script.

%--------------------------------------------------
\section{MacOS Installation}
%--------------------------------------------------

Analogously to the UNIX/Linux installation, this should be performed from source using the same technique and dependencies. 

One can use the \lib{fink} project (\url{http://fink.sf.net}) to download and install dependencies, or install them from
source as in Linux. Both work fine. Sometimes, MacOS users get problems with a UNIX \code{libtool}, it is likely that a MacOS-specific \code{libtool} should be installed, which is named \code{glibtool}. It is also available from \lib{fink}. 

I have not yet checked if the \lib{GTK+}-enabled version works on MacOS, but since \code{gtk+2-dev} and \code{gtk+2-shlib} are available at \lib{fink}, it is worth trying. Please note that you will need \code{pkgconfig} (also available from \lib{fink}) in order for the installation script to find your \lib{GTK+} includes.

%--------------------------------------------------
\section{Windows 32bit Installation}
%--------------------------------------------------

The Windows binary package (extension \code{.zip}) contains a \lib{DLL} that was compiled on a 32 bit Windows XP machine. The source package (extension \code{.tar.gz}) is distributed with a \emph{precompiled} Windows \lib{DLL} included in \code{.\textbackslash inst\textbackslash winlibs\textbackslash}. This file is moved to the package's \code{.\textbackslash libs\textbackslash} during the Windows build process (\code{R CMD build --binary}) avoiding the compilation. If you do want to recompile the source package on Windows, please delete the \code{.\textbackslash inst\textbackslash winlibs\textbackslash} directory from the source tarball.

Whether you are installing a binary package or compiling it from source on Windows, you will need to have \emph{both} \lib{ImageMagick} and \lib{GTK+} installed and \emph{added} to your or system-wide \code{PATH} variable prior to the package installation.

If you plan to compile the package from source, first follow the \lib{R} instructions on compiling Windows packages and install all the necessary tools (Cygwin, MSYS, MinGW, MS Help Compiler etc). In the latter case it is recommended to install MinGW and MSYS into \code{c:\textbackslash mingw} as this path is hard coded into \code{.\textbackslash src\textbackslash Makevars.win} of the package. Otherwise you will need to edit this file. You do not need MinGW or MSYS if you install the binary package. For the binary package, just install the dependencies so that the library could function.

I have not checked if the package compiles on 64 bit Windows since I don't have such hardware. 

\subsection{Installing ImageMagick}

The Windows version of \lib{ImageMagick} is also available from \url{http://www.imagemagick.org}. Please ensure that you download a package named like \code{ImageMagick-6.x.x-x-Q16-windows-dll.exe}, where \code{x.x-x} stand for the minor version number. You need to pay attention that you download \code{*-windows-dll.exe} and not \code{*-static.exe} otherwise the shared libraries to use with the package will not be installed. You also should use the version with 16 bit \code{QUANTUM} depth (\code{*-Q16-*}) to ensure the best possible color range.

After starting the installation wizard, you can select the default settings and let the installer to register environmental variables for you. Ensure that the path to \lib{ImageMagick} was added to your \code{PATH} variable, e.g. that it contains somthing like \code{c:\textbackslash ImageMagick;}.

If you are planning to compile \Rpackage{EBImage} from source, select during the installation that you want development files to be installed as well of. In this case, it is strongly recommended to install \lib{ImageMagick} into a path that does not contain spaces. The recommended, and hard coded into \code{.\textbackslash src\textbackslash Makevars.win} is \code{c:\textbackslash ImageMagick}. If select another location, please be sure to update this file.

\subsection{Installing GTK+}

It is recommended to use the \lib{GladeWin32} project, \url{http://gladewin32.sf.net} for the source of \lib{GTK+} installer. The \url{www.gtk.org} site has its own installers, but the above one is an all-in-one installation which perfectly fits the needs of \Rpackage{EBImage}. Please download the latest available release of \emph{Gtk+/Win32 Development Environment} if you are planning to recompile the package from source, or \emph{Gtk+/Win32 
Runtime Environment} if you are just planning to use the binary. For the binary installation just run the installer and accept the default suggestions: the installer will register all environmental variables for you.

Please ensure now that the installer added the path to \lib{GTK+} \code{\textbackslash bin} directory \emph{before} the path to \code{c:\textbackslash Windows\textbackslash } and \code{c:\textbackslash Windows\textbackslash System32}. Otherwise, the package might find the wrong \code{xmlparser.dll} which is included in both, \lib{GTK+} and Windows itself (and is significantly outdated in Windows).

If you are planning to compile \Rpackage{EBImage} from source, install \lib{GTK+} into a path that does not contain spaces. It is strongly recommended to use the same directory where you installed MSYS and MinGW, namely \code{c:\textbackslash mingw}. This directory is hard coded into \code{.\textbackslash src\textbackslash Makevars.win} and you will need to modify this file if installing \lib{GTK+} elsewhere.

\subsection{Installing the package}

The binary package can be installed now using the R menu command to install a package from a local file.

To compile from source, ensure that \lib{R} is in your \code{PATH}, run \code{cmd} and switch to the directory with the package tarball. Now run \code{R CMD build --binary} to generate the binary. Then install it as above.

\end{document}