% installation.tex
%
% The documentation in this file is part of Pyxplot
% <http://www.pyxplot.org.uk>
%
% Copyright (C) 2006-2012 Dominic Ford <coders@pyxplot.org.uk>
%               2008-2012 Ross Church
%
% $Id: installation.tex 1310 2012-09-19 12:53:28Z dcf21 $
%
% Pyxplot is free software; you can redistribute it and/or modify it under the
% terms of the GNU General Public License as published by the Free Software
% Foundation; either version 2 of the License, or (at your option) any later
% version.
%
% You should have received a copy of the GNU General Public License along with
% Pyxplot; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA  02110-1301, USA

% ----------------------------------------------------------------------------

% LaTeX source for the Pyxplot Users' Guide

\chapter{Installation}

\label{ch:installation}

In this chapter we describe how to install Pyxplot on a range of UNIX-like
operating systems.

Pyxplot works on most UNIX-like operating systems. We have tested it under
Linux, Solaris\index{Solaris} and MacOS\index{MacOS}, and believe that it
should work on other similar POSIX systems. We regret that it is not available
for Microsoft Windows, and have no plans for porting it at this time.

\section{Installation within Linux distributions}

By far the easiest way to install Pyxplot under Linux is to use your
distribution's package manager.  If you use a recent release of
Gentoo\index{Gentoo Linux}\index{installation!under Gentoo}\footnote{See
\url{http://gentoo-portage.com/sci-visualization/pyxplot}}, Ubuntu\index{Ubuntu
Linux}\index{installation!under Ubuntu}\footnote{See
\url{http://packages.ubuntu.com/pyxplot}} or Debian\footnote{See
\url{http://packages.debian.org/pyxplot}}, your package manager can install
Pyxplot and all its dependencies for you, though the packaged version may be
several months behind the latest release. Please note that this manual
describes Pyxplot~0.9.x, which is a very substantial upgrade to version~0.8.x.
To install the packaged version of Pyxplot under Debian or Ubuntu, simply type:

\begin{verbatim}
apt-get install pyxplot gv
\end{verbatim}

Users of other distributions, or who want a newer version of Pyxplot, should
use the {\tt .tar.gz} archives available from the Pyxplot website. The process
is described below.

\section{System requirements}

Pyxplot depends on the following software packages, which are not included in
the source tarball:\index{system requirements}

\vspace{0.5cm}
\begin{itemize}
\item fftw (version 2 or, preferably, 3+) \index{fftw}
\item gcc and make\index{gcc}\index{make}
\item Ghostscript \index{Ghostscript}
\item The Gnu Scientific Library (version 1.10+) \index{gsl}
\item ImageMagick \index{ImageMagick}
\item \latexdcf\ (version $2\epsilon$; a full installation is likely to be required in distributions which offer a choice) \index{latex}
\item libpng (version 1.2+) \index{libpng}
\item libxml2 (version 2.6+) \index{libxml}
\item zlib \index{zlib}
\end{itemize}
\vspace{0.5cm}

\noindent It is very strongly recommended that the following software packages
also be installed:

\vspace{0.5cm}
\begin{itemize}
\item cfitsio -- required for Pyxplot to be able to plot \datafile s in FITS format.
\item Ghostview \index{Ghostview} (or {\tt ggv}) -- required for Pyxplot to be able to display plots live on the screen; Pyxplot remains able to generate image files on disk without it. Alternatively, the \indcmdt{set viewer} within Pyxplot allows a different PostScript viewer to be used.
\item gunzip \index{gunzip} -- required for Pyxplot to be able to plot compressed \datafile s in {\tt .gz} format.
\item The Gnu Readline Library (version 5+) \index{readline} -- required for Pyxplot to be able to provide tab completion and command histories in Pyxplot's interactive command-line interface.
\item libkpathsea \index{libkpathsea} -- required to efficiently find the fonts used by \latexdcf.
\item wget \index{wget} -- required for Pyxplot to be able to plot \datafile s directly from the Internet.
\end{itemize}
\vspace{0.5cm}

\noindent In the case of the recommended packages, Pyxplot tests for the
availability of each when it is installed and issues a warning if any are not
found. Installation can proceed, but some of Pyxplot's features will be
disabled. If they are later added to the system, Pyxplot should be reinstalled
to take advantage of their presence.

\subsection{Dependencies in Debian and Ubuntu}

Debian and Ubuntu users can find the above software in the following
packages\footnote{The package names listed here are correct as of Debian
Squeeze and Ubuntu 12.04 (Precise). However, packages occasionally change name
between versions.}: \index{Debian Linux}\index{Ubuntu
Linux}\index{installation!under Debian}\index{installation!under Ubuntu}

\vspace{2mm}
\noindent {\tt fftw3-dev}, {\tt gcc}, {\tt ghostscript}, {\tt gv}, {\tt imagemagick}, {\tt libc6-dev},\newline
\noindent {\tt libcfitsio3-dev}, {\tt libgsl0-dev}, {\tt libkpathsea-dev}, {\tt libpng12-dev},\newline
\noindent {\tt libreadline-dev}, {\tt libxml2-dev}, {\tt make}, {\tt texlive-latex-extra},\newline
\noindent {\tt texlive-latex-recommended}, {\tt texlive-fonts-extra},\newline
\noindent {\tt texlive-fonts-recommended}, {\tt wget}, {\tt zlib1g-dev}.
\vspace{2mm}

\noindent These packages may be installed from a command prompt by typing, all on one line:

\begin{verbatim}
sudo apt-get install fftw3-dev gcc ghostscript gv imagemagick
       libc6-dev libcfitsio3-dev libgsl0-dev libkpathsea-dev
       libpng12-dev libreadline-dev libxml2-dev make
       texlive-latex-extra texlive-latex-recommended
       texlive-fonts-extra texlive-fonts-recommended wget
       zlib1g-dev
\end{verbatim}

\subsection{Dependencies in MacOS}

Users of MacOS~X can find the above software in the following MacPorts packages:
\index{MacOS X}\index{MacPorts}

\vspace{2mm}
\noindent {\tt cfitsio}, {\tt fftw-3}, {\tt ghostscript}, {\tt gsl-devel}, {\tt gv}, {\tt ImageMagick}, {\tt libpng},\newline
\noindent {\tt libxml2}, {\tt readline-5}, {\tt texlive}, {\tt wget}, {\tt zlib}.
\vspace{2mm}

It may then be necessary to run the command
\begin{verbatim}
export C_INCLUDE_PATH=/opt/local/include
\end{verbatim}
before running the {\tt configure} script below.

\section{Installation from source archive}
\index{installation}

First, download the required archive can be downloaded from the front page of
Pyxplot website -- \url{http://www.pyxplot.org.uk}. It is assumed that the
packages listed above have already been installed; if they are not, you will
need to either install them yourself, if you have superuser access to your
machine, or contact your system administrator.\index{installation!user-level}

\begin{itemize}
\item Unpack the distributed .tar.gz:

\begin{verbatim}
tar xvfz pyxplot_0.9.2.tar.gz
cd pyxplot-0.9.2
\end{verbatim}

\item Run the installation script:

\begin{verbatim}
./configure
make
\end{verbatim}

\item Finally, start Pyxplot:

\begin{verbatim}
./bin/pyxplot
\end{verbatim}

\end{itemize}

\subsection{System-wide installation}

Having completed the steps described above, Pyxplot may be installed
system-wide by a superuser with the following additional
step:\index{installation!system-wide}

\begin{verbatim}
sudo make install
\end{verbatim}

By default, the Pyxplot executable installs to {\tt /usr/local/bin/pyxplot}.
If desired, this installation path may be modified in the file {\tt
Makefile.skel}, by changing the variable {\tt USRDIR} in the first line to an
alternative desired installation location.

Pyxplot may now be started by any user of the system, simply by typing:

\begin{verbatim}
pyxplot
\end{verbatim}