
\section{Installing Coopr}

There are several different ways that Coopr can be installed:
\begin{description}

\item[easy\_install]  Coopr releases can be directly installed using the Python \code{easy\_install} command.

\item[source]  Coopr can be installed from source.

\item[coopr\_install]  The \code{coopr\_install} command provides a one-step installation of Coopr and the Python packages that Coopr depends on.

\end{description}
The first two options are the techniques that Python developers typically
used.  The \code{easy\_install} command is the \textit{de facto} standard
python installation technique.  For example, the following
command will download Coopr and the Python packages that it depends
on, and install them in Python's site-packages directory:
\begin{lstlisting}
easy_install Coopr
\end{lstlisting}

In most cases, end-users will want to use the \code{coopr\_install}
script to install Coopr and other packages that Coopr depends on.
This is a Python script that creates a directory that contains a
\textit{virtual} Python installation, related Coor scripts, examples and
related documentation.  This installation does not require administrator
privileges, and the user can view the Coopr documentation and examples
in the installation directory.

The \code{coopr\_install} script does not rely on non-standard Python packages, so it can be run as follows:
\begin{lstlisting}
coopr_install coopr
\end{lstlisting}
On MS Windows, the \code{python} command needs to be run explicitly:
\begin{lstlisting}
python coopr_install coopr
\end{lstlisting}
This creates the \code{coopr} directory, which has the following directory structure:
\begin{verbatim}
admin      Administrative data for maintaining this distribution
bin        Scripts and executables
doc        Coopr documentation and tutorials
examples   Coopr examples
lib        Python libraries and installed packages
include    Python header files
src        Python packages whose source files can be
           modified and used directly within this virtual Python
           installation.
Scripts    Python bin directory (used on MS Windows)
util       Coopr utility scripts (including coopr_install)
\end{verbatim}
If the \code{bin} directory is put in user's \code{PATH} environment,
then the \code{bin/python} command can be used to employ Coopr and
associated packages without further configuration.  Further, Coopr's 
Python scripts are installed in the \code{bin} directory such that they 
reference this virtual Python installation directly.

If \code{coopr\_install} is executed with no installation directory,
then the script will search the user's \code{PATH} environment for the
\code{pyomo} command.  If found, the path of this command will be used
to identify the Coopr installation that is being updated or replaced.
If not found, then a default installation path is used:  \code{C:\\coopr}
on Windows and \code{./coopr} on Linux.

By default, \code{coopr\_install} installs the latest release of Coopr.  
The current development trunk can be installed using the \code{--trunk} option:
\begin{lstlisting}
coopr_install --trunk coopr
\end{lstlisting}
Also, Coopr has a stable branch, which is updated as major software
revisions are finalized.  This can be installed with the \code{--stable} option:
\begin{lstlisting}
coopr_install --trunk coopr
\end{lstlisting}

Users can reinstall Coopr using the \code{--clear} option:
\begin{lstlisting}
coopr_install --clear coopr
\end{lstlisting}
Note that this option is also needed to switch between the trunk, stable, and release
installations, since that involves a reinstallation of Coopr.  A Coopr installation can also be updated with the \code{--update} option:
\begin{lstlisting}
coopr_install --update coopr
\end{lstlisting}
This updates Coopr to the latest release, or the latest revision of trunk and
stable installations.

The \code{coopr\_install} script installs a variety of Python packages
that Coopr uses.  This script also has options for using third-party Coopr
extensions that are available on the Coopr Forum software repository~\ref{CooprForum}.
The Coopr Forum repository facilitates community involvement in Coopr
by allowing people to contribute code extensions and plugins without
going directly through the Coopr software repository.  For example,
the \code{coopr.plugins.neos} package provides a simple example of how
Coopr can be extended with plugins to enable optimization on the NEOS
optimization server~\cite{NEOS}.  This plugin package can be installed with
Coopr using the \code{--forum-pkg} option:
\begin{lstlisting}
coopr_install --forum-pkg=neos coopr
\end{lstlisting}
Multiple packages can be separated with a comma-separated list of package names.

The Python \code{setuptools} package is the \textit{de facto}
standard for deploying Python software.  This package extends Python's
\code{distutils} functionality.  A key element of this extension is the
\code{easy\_install} command, which allows the installation of Python
software from remote repositories.  In particular, the Python Package
Index (PyPI) provides a convenient repository for hosting Python packages.
The \code{easy\_install} command can easily upload and download packages
from PyPI, thereby simplifying the distribution of Packages like Coopr,
which depends on a variety of freely available packages.

Finally, here are some notes about \code{coopr\_install}:
\begin{itemize}

\item This script installs packages by downloading files from
the internet.  If you are running this from within a firewall, you
may need to set the \code{HTTP\_PROXY} environment variable to a value like
\code{http://<proxyhost>:<port>}.

\item By default, the virtual Python installation used with Coopr
exposes the packages that are installed with your Python installation.
Occasionally, this can cause conflicts between different package version.
The \code{--no-site-packages} option isolates the Coopr installation from
the Python packages that have been installed with the Python interpreter.

\end{itemize}

