\chapter[Installation Overview]{Installation Overview}
\label{chap:installation-overview}

As of release 0.9.6 of the polyxmass-bin package, no libpolyxmass
package is needed anymore.

The \pxm software suite is a multi-modular software framework. It is
made of a number of modular packages that depend on each other. The
installation of the \pxm software suite can be achieved with no pain
by following the instructions in this chapter. 


The dependencies between the modules of the \pxm software framework
are ``ordered'', which means that they require that the modules of the
framework be installed on the same system in an ordered manner.

Modules from the \pxm software suite might be modified independently,
which means that it is not required that they have the same package
version number. For example, a modification in the \filename{\pxmng}
program of the \pxm software suite might not necessarily involve
changes in the \filename{\pxmdatang} package ---that is also part of
the \pxm software suite. Thus, the \pxm program will have an
incremented version number, while the data package itself remains with
a constant version number. The dependencies are dealt with at install
time, so the best way to make a fresh install of the \pxm software
suite is to take all the most recent packages from \pxmurlbase. If
there are no errors (\textit{errare humanum est}) in the dependency
mechanics, all the packages should be installed easily.

Prior to analyzing the installation procedure as a whole, it is
necessary to describe the packaging systems that are available for the
user to install, manage and remove software packages from the system.

\noindent
\begin{center}
  \fbox{\parbox{0.9\textwidth}{Making packages for distributions comes
      at the price of big efforts from the packager. The program is
      always first distributed as a \fileformat{tar.gz} ``tarball''
      where all the sources required to compile the software are
      located. This ``tarball'' packaging is the most natural one for
      the developer, as it is very near to what she has used to
      develop the software. Packagers use these ``tarball'' packages
      to prepare binary packages so that non-geek users can easily
      install precompiled software onto their machine.  Preparing
      binary packages from source is a big work, and packagers do not
      always have the time required to do it in a short delay after
      new releases of the program. Please, be patient and wait for the
      packages to be prepared. If you find that the packages come too
      slowly after software release, learn how to package software and
      prepare the packages yourself.  I'll be happy to offer packages
      that you prepared on my server \pxmurlbase.}}
\end{center}

Delivering software to the users can be performed using a number of
file formats:

\begin{itemize}
\item Uncompiled source package file formats:
  \begin{itemize}
  \item \fileformat{tar.gz} files which need to be compiled using the
    \software{GNU make} program (these are the ``tarball'' archives
    mentioned earlier);
  \item \fileformat{dsc} plus \fileformat{tar.gz} files which need to
    be compiled into a binary installable package using the
    \DebianGNUL packaging system;
  \item \fileformat{src.rpm} files which need to be compiled into a
    binary installable package using the \software{rpm} tool;
  \end{itemize}
\item Binary ready-to-install package file formats:
  \begin{itemize}
  \item \fileformat{\_i386.deb} files that are dependent on the
    computing platform architecture (must be installed using the
    \software{apt-get} or the \software{dpkg} tools in the \DebianGNUL
    distribution);
  \item \fileformat{i386.rpm} files that are dependent on the
    computing platform architecture (must be installed using the
    \software{rpm} tool);
  \item \fileformat{\_all.deb} files that are non-dependent on the
    computing platform architecture (must be installed using the
    \software{apt-get} or the \software{dpkg} tools in the \DebianGNUL
    distribution);
  \item \fileformat{noarch.rpm} files that are non-dependent on the
    computing platform architecture (must be installed using the
    \software{rpm} tool).
  \end{itemize}
\end{itemize}


\renewcommand{\sectitle}{Installing From The \fileformat{tar.gz} Sources}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}


Installing a package from the source is as easy as issuing the
following commands in the correct order: \\

\begin{mynoindent}
  \prompt\ \command{cp} \filename{\pxmng-\pxmver.tar.gz}
  \filename{/tmp}
  \kbdEnterKey\ {\footnotesize copy the package file into a safe place}\\
  \prompt\ \command{cd} \filename{/tmp} \kbdEnterKey\ \\
  \prompt\ \command{tar} \option{xvzf}
  \filename{\pxmng-\pxmver.tar.gz} \kbdEnterKey\ {\footnotesize this
    unpacks the sources into a source
    tree in the \filename{\pxmng-\pxmver} directory} \\
  \prompt\ \command{cd} \filename{\pxmng-\pxmver} \kbdEnterKey \\
  \prompt\ \command{./configure} \option{---prefix=/usr}
  \option{---sysconfdir=/etc} \kbdEnterKey\ {\footnotesize these are
    the two conventional options used with the \command{./configure}
    command} \\
  \prompt\ \command{make} \kbdEnterKey\ {\footnotesize perform the
    actual compilation of the software} \\
  \prompt\ \command{su} \kbdEnterKey\ {\footnotesize become root if it
    is possible}\\
  \promptsu\ \command{make install} \kbdEnterKey\ {\footnotesize
    finally ask that the successfully compiled software be installed
    to the destination system directories, as required using the
    options to the \command{./configure} command}\\
\end{mynoindent}

As seen in the commands shown above, there are two options that the
user might try when running the \command{configure} script before
building the software:

\begin{itemize}
\item \option{---prefix=/usr}: this option governs the file-system
  tree where the software is to be installed. Binary packages always
  install new software in the file-system rooted at location
  \filename{/usr}. Source packages, like the ones being described
  right now, usually install software in the file-system rooted at
  location \filename{/usr/local}, as it is assumed that such software
  is only for use by the local machine, and does not enter in the
  composition of the default machine setup. It is possible to force
  source packages to install into the \filename{/usr} file-system tree
  by using the option \option{---prefix=/usr};
\item \option{---sysconfdir=/etc}: this options governs the
  installation of the most critical configuration files of the whole
  \pxm software suite. Binary packages set this option to
  \filename{/etc}, which means that all the critical configuration
  files are located in the \filename{/etc/polyxmass} directory. The
  default location for source packages, like the ones described here,
  is also \filename{/etc}.
\end{itemize}

\noindent The only reason why the user (who is installing software and
not merely using it) will want to use/modify the options above, is to
install software without having system administrator priviledges
(\textit{i.e.} without being root). In this case, it is
\emph{essential} that both options be passed identically to the
\command{configure} script of \emph{each package} of the \pxm software
suite. This is because each package of the suite is relying on the
knowledge that all the other packages have been installed in a
determinate file-system tree (\filename{/usr}, \filename{/tmp},
\filename{/opt} or \filename{/home/rusconi}, for example). This is
crucial, otherwise all the software suite's modules cannot speak one
to each other.

As one example, this is what I tried to make sure the software is
---in fact--- \textit{a priori} installation directory-agnostic:

\begin{itemize}
\item I installed the \pxmcommon package by issuing the following
  configuration/installation commands:
  \begin{itemize}
  \item \command{./configure} \option{---prefix=/tmp}
    \option{---sysconfdir=/tmp/etc};
  \item \command{make install} \medskip \\
    At this time the fundamental configuration/data files are located
    in a number of locations all rooted in \filename{/tmp}:
    \filename{/tmp/etc/polyxmass}, \filename{/tmp/share},
    \filename{/tmp/sbin}.
    \end{itemize}
  \item Next, I installed the other packages using always the same
    \command{./configure} \option{---prefix=/tmp}
    \option{---sysconfdir=/tmp/etc} command line.
\end{itemize}

When the operations above were performed successfully I could launch
the \command{\pxmng} program from \filename{/tmp/bin}. Since that
directory is not in the PATH, it is necessary to first change the
working directory to this directory, using \command{cd /tmp/bin}. Next
it is necessary to execute \command{\pxmng} by telling the shell that
the executable is to be found in the current working directory:
\command{./\pxmng}. The program should launch successfully.

\renewcommand{\sectitle}{Installing From The \software{deb} Binary Package}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}


\label{sect:inst-from-bin-deb} 

On the \DebianGNUL distribution, the packaging system makes the
installation of software incredibly easy. The \software{apt-get}
package manager is particularly clever in determining the dependencies
between packages in an inter-related array of two or more packages.
The \software{apt-get} package manager needs to connect to some place
over the network and download a file from that place (which is called
a software repository) that will tell what packages are available at
that specific place and how they inter-relate. Since the adoption of
\pxm as an official \DebianGNUL distribution package, installing the
software is a easy as issuing the following command lines as root:

\begin{mynoindent}
  \promptsu\ \command{apt-get} \option{update} \kbdEnterKey\\
  \promptsu\ \command{apt-get} \option{install} \filename{\pxmng}
  \kbdEnterKey\\
\end{mynoindent}

\noindent and something like the following will be output to your
terminal:

\begin{alltt}
Reading Package Lists... Done
Building Dependency Tree... Done
The following extra packages will be installed:
  polyxmass-bin polyxmass-bin-common polyxmass-common polyxmass-data
The following NEW packages will be installed:
  polyxmass-bin polyxmass-bin-common polyxmass-common polyxmass polyxmass-data
0 upgraded, 3 newly installed, 0 to remove and 9 not upgraded.
Need to get 5020kB of archives.
After unpacking 8577kB of additional disk space will be used.
Do you want to continue? [Y/n]
\end{alltt}

\noindent All this output to install one package? ---``What is it
going on?,'' you may ask. Well, that's the power of the system:
\software{apt-get} has detected that in order to install the \pxmng
package, it is necessary to first install packages onto which \pxmng
actually depends.  These packages are listed:

\begin{alltt}
  The following extra packages will be installed:
  polyxmass-bin polyxmass-bin-common polyxmass-common polyxmass-data
\end{alltt}

\noindent Which means that, in total, with the initially requested
package,

\begin{alltt}
The following NEW packages will be installed:
  polyxmass-bin polyxmass-bin-common polyxmass-common polyxmass-data polyxmass
0 upgraded, 5 newly installed, 0 to remove and 9 not upgraded.
\end{alltt}

\noindent If you accept to continue (key-in \kbdKey{Y} \kbdEnterKey),
this is what you get: all the packages get automatically downloaded,
installed and configured. That's the \DebianGNUL packaging system
magic: there is no higher standard for such package managing tasks
nowadays.

To see all the files that are provided by a given \DebianGNUL
package file, issue the following command:\\

\begin{mynoindent}
  \prompt\ \command{dpkg} \option{-c}
  \filename{\pxmng-bin\pxmver-1.i386.deb} \kbdEnterKey\\
\end{mynoindent}

The output of this command is a list of all the files ---along with
their destination directories--- that would be installed if the
package were installed as above.



\renewcommand{\sectitle}{Installing From The \software{rpm} Binary Package}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

\label{sect:inst-from-bin-rpm} 


Installing any \fileformat{rpm} package using the \software{rpm}
program\footnote{For an in-depth manual on the \software{rpm} packet
  manager, you might want to read \emph{Maximum RPM}, a book by Ed
  Bailey, available from \url{http://www.rpm.org}.} is as easy as
entering the following commands, as root:\\

\begin{mynoindent}
  \promptsu\ \command{rpm} \option{-ivh}
  \filename{\pxmcommonng-\pxmcommonver-1.i386.rpm} \kbdEnterKey\\
  \promptsu\ \emph{optionally} \command{rpm} \option{-ivh}
  \filename{\pxmdatang-\pxmdataver-1.i386.rpm}
  \kbdEnterKey\\
  \promptsu\ \command{rpm} \option{-ivh}
  \filename{\pxmbinng-\pxmver-1.i386.rpm} \kbdEnterKey\\
\end{mynoindent}

\noindent What these commands do is to read the contents in each of
the packages (these package files do contain a number of files packed
in them) and copy them to their destination directories.  The
\fileformat{rpm} file format lets the packager define where each of
the files contained in a package has to be installed. To see all the
files that are provided by a given \software{rpm}-based
package file, issue the following command:\\

\begin{mynoindent}
  \prompt\ \command{rpm} \option{-qpl}
  \filename{\pxmbinng-\pxmver-1.i386.rpm} \kbdEnterKey\\ 
\end{mynoindent}

The output of this command is a list of all the files ---along with
their destination directories--- that would be installed if the
package were installed as above.


\renewcommand{\sectitle}{Installation On A \OSname{Mac~OS~X} System With \software{Fink}}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

\label{sect:ins-macosx-fink}

The \OSname{Mac~OS-X} operating system can run \corpname{GNU} software
when the \software{Fink} porting system is installed (please, visit
\url{http://fink.sourceforge.net} for details on this project). The
notes below were kindly provided to me by D$\mathrm{^r}$ Mark Tracy.
If you find errors, they are mine, and I am the only one to be blamed
for badly transcribing these notes.

\bigskip\pxm was successfully installed on the Mac OS-X/Fink platform.
For example, version 0.8.6 of the modules of the \pxm software suite
could be installed using the info files maintained by D$\mathrm{^r}$
Mark Tracy.  These \software{Fink} \fileformat{info} files are scripts
much like the \software{rpm} \fileformat{spec} files. Using the
scripts, \software{Fink} will download the source tarballs, apply any
patches, install dependent packages, compile the code and install the
finished files.  The \software{Fink} packaging system relies on the
usual \fileformat{tar.gz} source files, which may be used without
modification.  However, the case may arise that the \OSname{Mac
  OS-X/Fink} platform requires that the package maintainer changes the
code of the source tree for one or more packages in the \pxm suite. In
this case, the patch files would be distributed along with the source
tarball files and the \fileformat{info} files.  The \fileformat{info}
script will automatically apply the patches, and complain should you
forget them.  Providing patch files for the software to build
correctly on any given platform is the task of the packager.  Once you
have downloaded all the required files (\fileformat{info},
\fileformat{patch}), the installation process is as easy as doing the
following: If you obtained the scripts from the \software{Fink}
server, \software{Fink} will automatically install them in the right
place and you skip the copying step. The \software{Fink} service tends
to lag behind the latest version due to their diligent review process.
If you obtained the scripts from \url{http://www.polyxmass.org}, you
need to copy them to the right place:  \\

\begin{mynoindent}
  \prompt\ \command{sudo cp *.info /sw/fink/10.3/local/main/finkinfo}\kbdEnterKey\ \\
  \prompt\ \command{sudo cp *.patch /sw/fink/10.3/local/main/finkinfo}\kbdEnterKey\ \\
\end{mynoindent}

Sudo will want your password.  Now comes the time to install the
packages by issuing the following commands:

\begin{mynoindent}
  \prompt\ \command{fink install polyxmass}\kbdEnterKey\ \\
  \prompt\ \command{fink install polyxmass-common}\kbdEnterKey\  (optional)\\
  \prompt\ \command{fink install polyxmass-doc}\kbdEnterKey\  (optional)\\
  \prompt\ \command{fink install polyxmass-examples}\kbdEnterKey\  (optional)\\
\end{mynoindent}

At the behest of the \software{Fink} team, the packages are named
somewhat differently under \software{Fink}. If the software packager
did everything right, \software{Fink} will calculate the dependencies,
and ask you if you want to install the dependent packages (say
yes).\footnote{If this is your first time installing, there will be a
  startling number of dependent files.}  \software{Fink} will begin
downloading the source tarballs.  Note that \pxm is dependent on
several libraries found in the unstable branch of the 10.3 package
tree, therefore \software{Fink} must be so configured (sorry, 10.2 is
no longer supported). When all is finished, open a new X-terminal
window to run the software (yes, it has to be new and it has to be X).


\renewcommand{\sectitle}{Summary}
\section*{\sectitle}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

\label{sect:ins-summary}



We have reviewed a number of ways the \pxm software suite might be
installed on a variety of platforms. The next chapters will deal with
each module separately. 

As a final reminder, before the user picks the best installation
method and does that installation, I would tell that the software
packages in the \pxm software suite should be installed in the
following order:

\begin{enumerate}
\item \filename{polyxmass-common}
\item \filename{polyxmass-bin-common} (or no such package, depending on
  the distribution)
\item \filename{polyxmass-bin} (or \filename{polyxmass}, depending on
  the distribution)
\item \emph{optionally} \filename{polyxmass-data}
\item \emph{optionally} \filename{polyxmass-doc}
\end{enumerate}

The following chapters will describe the software suite with all the
details that are required so that the user gets an intimate knowledge
of the way the whole integrated \pxm mass spectrometric software suite
works.


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "polyxmass"
%%% End: