\chapter[\mXp\ Installation]{\mXp\ Installation}

\label{chap:installation}

In this chapter, the installation\index{installation} process will be
described, for \OSname{GNU/Linux} systems, for the \OSname{MS-Windows}
system and for the \OSname{Mac OS X} system.\\[3mm]

\fbox{\parbox{0.9\textwidth}{Note that the \mXp\ software package is
    built to be located in certain places on the destination
    computer's filesystem on the disk. However, beginning with version
    1.7.5, the software package is
    relocatable\index{relocation}. Please read
    section~\ref{sect:software-package-relocation},
    page~\pageref{sect:software-package-relocation}.}}


\renewcommand{\sectitle}{The \OSname{GNU/Linux} Platform}
\index{installation!GNU/Linux}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

The installation of \mXp\ can be performed using the source code
tarball, the binary tarball or binary distribution-specific packages.
At the moment the only distribution-specific packages being prepared
are the \OSname{Debian GNU/Linux} and \OSname{Fedora core} packages.
The naming of the packages are according to the following schema:
\smallskip

\noindent \filename{massxpert-\ver-bin.tar.gz} \smallskip

\medskip

\noindent The ``-bin'' suffix indicates that the package is a binary
package. Source packages would use the ``-src'' suffix (or none at
all), exactly the same way: \smallskip

\noindent \filename{massxpert-\ver-src.tar.gz}


\renewcommand{\sectitle}{Install From A Binary Tarball}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

To install a binary tarball, simply issue the following command as
root:
\smallskip

\noindent \promptsu\ \command{tar xvzf massxpert-version-bin.tar.gz -C
  /}\kbdEnterKey

\medskip

\noindent This command installs the package to directory
\filename{/usr/local}, which means that the program is now available
for all to use. Version \ver\ of the \mXp\ software installs the
following files and directories:

\begin{itemize}
  
\item \filename{/usr/local/bin/massxpert} {\small this is the
    binary (executable) program itself};
  
\item \filename{/usr/local/share/massxpert/pol-chem-defs}
  {\small polymer chemistry definition files};
  
\item \filename{/usr/local/share/massxpert/pol-seqs} {\small
    polymer sequence files};
  
\item \filename{/usr/local/share/massxpert/locales} {\small
    Qt~linguist-based translation files};
  
\item \filename{/usr/local/share/doc/massxpert/COPYING} {\small
    license file of the \mXp\ software};
  
\item \filename{/usr/local/share/doc/massxpert/usermanual} {\small
    user manual (HTML- and PDF-formatted files)};
  
\end{itemize}

\noindent Upon installation, if all the dependencies are already
installed on the system, the user might start the \progname{massxpert}
program right away by executing the
\filename{/usr/local/bin/massxpert} file. 

The following are the dependencies for \mXp, as obtained
using the \filename{ldd}\index{ldd} command: \\

{
\small
\begin{verbatim}
linux-gate.so.1 =>  (0xffffe000)
libQtSvg.so.4 => /usr/lib/libQtSvg.so.4 (0xb7ebf000)
libQtGui.so.4 => /usr/lib/libQtGui.so.4 (0xb77a9000)
libpng12.so.0 => /usr/lib/libpng12.so.0 (0xb7786000)
libSM.so.6 => /usr/lib/libSM.so.6 (0xb777d000)
libICE.so.6 => /usr/lib/libICE.so.6 (0xb7766000)
libXi.so.6 => /usr/lib/libXi.so.6 (0xb775e000)
libXrender.so.1 => /usr/lib/libXrender.so.1 (0xb7756000)
libXrandr.so.2 => /usr/lib/libXrandr.so.2 (0xb7750000)
libXcursor.so.1 => /usr/lib/libXcursor.so.1 (0xb7747000)
libXinerama.so.1 => /usr/lib/libXinerama.so.1 (0xb7743000)
libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0xb76d4000)
libfontconfig.so.1 => /usr/lib/libfontconfig.so.1 (0xb76a9000)
libXext.so.6 => /usr/lib/libXext.so.6 (0xb769b000)
libX11.so.6 => /usr/lib/libX11.so.6 (0xb75af000)
libQtXml.so.4 => /usr/lib/libQtXml.so.4 (0xb7556000)
libQtNetwork.so.4 => /usr/lib/libQtNetwork.so.4 (0xb74c4000)
libQtCore.so.4 => /usr/lib/libQtCore.so.4 (0xb734e000)
libz.so.1 => /usr/lib/libz.so.1 (0xb7339000)
libpthread.so.0 => /lib/i686/cmov/libpthread.so.0 (0xb7322000)
libdl.so.2 => /lib/i686/cmov/libdl.so.2 (0xb731e000)
libm.so.6 => /lib/i686/cmov/libm.so.6 (0xb72f9000)
libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0xb720d000)
libgcc_s.so.1 => /lib/libgcc_s.so.1 (0xb7202000)
libc.so.6 => /lib/i686/cmov/libc.so.6 (0xb70ba000)
libaudio.so.2 => /usr/lib/libaudio.so.2 (0xb70a4000)
libXt.so.6 => /usr/lib/libXt.so.6 (0xb7054000)
libXfixes.so.3 => /usr/lib/libXfixes.so.3 (0xb704f000)
libgthread-2.0.so.0 => /usr/lib/libgthread-2.0.so.0 (0xb704a000)
librt.so.1 => /lib/i686/cmov/librt.so.1 (0xb7041000)
libglib-2.0.so.0 => /usr/lib/libglib-2.0.so.0 (0xb6fa1000)
libexpat.so.1 => /usr/lib/libexpat.so.1 (0xb6f81000)
libXau.so.6 => /usr/lib/libXau.so.6 (0xb6f7d000)
libXdmcp.so.6 => /usr/lib/libXdmcp.so.6 (0xb6f78000)
/lib/ld-linux.so.2 (0xb7f2b000)
libpcre.so.3 => /usr/lib/libpcre.so.3 (0xb6f58000)
\end{verbatim}
}

\noindent As visible on the first lines of the output above, the main
dependency that might not be available on your system, especially if
not running the \progname{KDE} environment, are the libQt* libraries.
These should be very easily installable, as they constitute the very
core of a highly popular desktop environment used on
\OSname{GNU/Linux} computers called \progname{KDE} (\textit{``Kommon
  Desktop Environment''}).


\renewcommand{\sectitle}{Installing From A Source Tarball}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

The source is built using the CMake\index{CMake} program
(\url{http://www.cmake.org}). The build of the software takes place in
another directory than the source directory. The steps are easy:

\begin{itemize}
  
\item Unpack the source tarball with the following command as normal
  user: \smallskip
  
  \noindent \prompt\ \command{tar xvzf
    massxpert-\textsl{\ver}-src.tar.gz} \kbdEnterKey
  \smallskip
  
  \noindent This command unpacks the tarball to the current directory
  in a subdirectory named \filename{massxpert-\ver};
  
\item Now create a directory called massxpert-build with the following
  command: \smallskip

  \noindent \prompt\ \command{mkdir massxpert-build} \kbdEnterKey  
  \smallskip

\item Change to that directory:
  \smallskip
  
  \prompt\ \command{cd massxpert-build} \kbdEnterKey
  \smallskip

  and run the cmake configuration command:
  \smallskip
  
  \noindent \prompt \command{cmake ../massxpert-\ver} \kbdEnterKey
  \smallskip
  
\item Build the software:
  \smallskip

  \prompt \command{make} \kbdEnterKey
  \smallskip

\item If the build runs fine, then simply become root and issue the
  following command:
  \smallskip

  \noindent \prompt\ \command{make install} \kbdEnterKey
  \smallskip

\end{itemize}


\noindent At this point the software should have installed in the
destination tree (\filename{/usr/local} prefix). The program should be
callable immediately if the destination directory is in the path,
otherwise it will first be required to use the full pathname to call
it, like for example: \smallskip

\noindent \prompt\ \command{/home/rusconi/myprogs/bin/massxpert}
\kbdEnterKey

\renewcommand{\sectitle}{Installing A Binary Package}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

\subsubsection*{\OSname{Debian GNU/Linux} Package}

To install a \OSname{Debian GNU/Linux} package just issue the
following command:
\smallskip

\noindent \promptsu\ \command{dpkg -i}
\filename{massxpert\_\ver-1\_i386.deb} \kbdEnterKey
\smallskip

\noindent If the documentation is needed, the
\filename{massxpert-doc\_\ver-1\_i386.deb} might be installed also
using the same command line.


\subsubsection*{\OSname{Fedora core GNU/Linux} Package}

To install a \OSname{Fedora core GNU/Linux} package just issue the
following command:
\smallskip

\noindent \promptsu\ \command{rpm -ivh}
\filename{massxpert\_\ver-1\_i386.deb} \kbdEnterKey
\smallskip

\noindent Note that the \OSname{Fedora core GNU/Linux} package
\emph{does} install the documentation along with the binary, so there
is no need to as for the installation of a doc package.


\renewcommand{\sectitle}{The \OSname{Mac~OS~X} Platform}
\index{installation!Mac~OS~X}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

The \OSname{Mac~OS~X} package that is provided does not require the
installation of libraries, as these frameworks are included in the
application bundle.

The user gets a disk image file (format \fileformat{dmg}) which he
double-clicks in the Finder. This will open up the contents of the
image file. After reading the \filename{COPYING} license file, the
user drops the \filename{massXpert.app} bundle\index{massXpert.app~bundle} anywhere on the disk. Double-clicking that
\filename{massXpert.app} bundle will launch the program.

Note that by using the ``Show Package Contents'' Finder menu on that
\filename{massXpert.app} bundle\index{app bundle}, the user may browse
the bundle's contents and peruse the user manual that is located in
the \filename{Contents>Doc>UserManual} directory.


\renewcommand{\sectitle}{The \OSname{MS-Windows} Platform}
\index{installation!MS~Windows}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

In this system also, it is possible to install software in two
manners: by installing a binary package or by building-installing the
software from source.

\renewcommand{\sectitle}{Installing A Binary Package}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

To install the binary package (a file typically in the autoinstaller
\fileformat{exe} format named something like
\filename{massxpert-\ver-setup.exe}) just double-click onto the
file icon in the file manager. The program is automatically made
available in the system menu.


\renewcommand{\sectitle}{Installing From A Source Tarball}
\subsection*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{subsection}{\numberline{}\sectitle}

The building of the \mXp\ software package is in two steps: first make
sure that the system has the Qt libraries installed along with
MinGW32\index{MinGW}. The packages can be installed by browsing the
following link: \smallskip

\centerline{\url{http://trolltech.com/developer/downloads/qt/windows}}
\medskip

\noindent Be sure to select from one of the repositories a package
that also contains the MinGW package: \smallskip

\centerline{\filename{qt-win-opensource-4.3.0-mingw.exe}} 

\smallskip

\noindent When the installer asks if MinGW should be installed, say
\textbf{Yes}. Once the installation of the Qt libraries has been
performed, the system menu will have a menu \guimenu{Qt by
  Trolltech}\guimenuitem{Qt 4.2.3 (Build Debug Libraries)}. Select
that menu and answer yes to the question that is asked in a console
window. This will build the libraries in the Debug mode, so that it
will be possible to compile \mXp\ later. Once that compilation is
finished, continue with the build steps for \mXp.

To unpack the source tarball, use the 7zip package
(\url{http://www.7-zip.org/download.html}; Free Software, GNU LGPL
license) to extract the source to any location of your choice.

At this point, the steps to make the software are similar to what
described above using the CMake program for \OSname{MS-Windows}, which
is, by the way graphical and not command line. To install the
software, you should probably become administrator and issue the
following command: \smallskip

\command{make install} \kbdEnterKey
\smallskip

\noindent At this point the software should be installed. Note that in
this case no shortcut to the program is installed, the user might want
to do that manually.

\renewcommand{\sectitle}{Software Package Relocation}
\index{relocation}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\label{sect:software-package-relocation}
\addcontentsline{toc}{section}{\numberline{}\sectitle}

As mentioned earlier, the \mXp\ software package might be relocated by
copying its system directories in other places than the ones it was
built for.


\begin{figure}
  \begin{center}
    \includegraphics[width=0.75\textwidth]
    {figures/massxpert-configuration-settings-dlg.png}
  \end{center}
  \caption[\mXp\ configuration settings]{\textbf{\mXp\ configuration
      settings.} Upon running the \mXp\ software program, it might
    detect that its system directories are not located where they were
    planned to be (the package directories might have been moved, for
    example). In this case, the user is provided with the dialog
    window shown here, where he is invited to locate all the system
    directories that are part of the \mXp\ software package. Once the
    settings are saved, the program can continue its execution
    successfully.}
  \label{fig:figures/massxpert-configuration-settings-dlg}
\end{figure}

When the \mXp\ software program is run, the first thing it does is
check whether it can find all its configuration data in the system
directories where they belong (configuration data, chemistry
definition data, plugins, localization files (translation of the
software). If any of its attempts fails, the user is provided with the
dialog window shown in
Figure~\ref{fig:figures/massxpert-configuration-settings-dlg}, where
he is invited to locate all the system directories that are part of
the \mXp\ software distribution. Once the settings are saved, the
program can continue its execution successfully. The directories that
are checked upon startup of the program are: \\

\begin{itemize}

\item The data directory (where the polymer chemistry definition
  files---in \filename{pol-chem-defs}---and the polymer sequence
  files---in \filename{pol-seqs}---are located);

\item The \filename{plugins} directory (where the plugins---which are
  dynamically linked libraries---are located);

\item The \filename{locales} directory (where the translation files
  are located).

\end{itemize}

\noindent The directories listed above might be moved on the
filesystem, however \emph{their contents might not be changed}. If
there is a need to customize the data, that should be done carefully,
by changing the contents of the files, \emph{but not the structure of
  the directories}. For example, it is perfectly safe to add new
polymer chemistry definitions or to change files belonging to any
polymer chemistry definition, but it is not safe to move files around
without knowing what you do.

\renewcommand{\sectitle}{The User Manual}
\section*{\textcolor{sectioningcolor}{\sectitle}}
\addcontentsline{toc}{section}{\numberline{}\sectitle}
\index{user~manual}

Whatever the package you used to install \mXp\, binary or source, the
documentation got installed on your system (look for a
\filename{usermanual} directory somewhere in the installed
material). The documentation that was installed is nothing but the
document you are reading now. It is available both in the form of HTML
files and of one PDF file.


\cleardoublepage

