
== Overview ==

The link:https://software.sandia.gov/trac/coopr/downloader[Coopr download
site] includes Coopr installers for MS Windows and Unix platforms.
Coopr is available open-source under the link:https://software.sandia.gov/trac/coopr/wiki/Licensing[BSD license].  It requires
Python version 2.6 or 2.7.  Coopr requires the installation of
several freely available Python libraries, and it can optionally
employ other libraries, including Python extension libraries for
commercial optimization software.

The <<Options,Installation Options>> chapter outlines different ways that Coopr can be installed:

* <<Option1,Option 1>>: Use `easy_install` to install Coopr as a site package in your system Python installation
* <<Option2,Option 2>>: Use the MS Windows installer to install Coopr in your system Python installation
* <<Option3,Option 3>>: Use the `coopr_install` script to install a Coopr release in a virtual Python installation 
* <<Option4,Option 4>>: Use the `coopr_install` script to install the Coopr trunk in a virtual Python installation

Additional installation details are provided in subsequent chapters:

* <<Prerequisites,Prerequisites>>: Packages that you may need to install and run Coopr
* <<InstallationFAQ,Installation Issues>>:  Helpful information for resolving issues with Coopr installation.
* <<Platforms,Platform Notes>>:  Documentation of platform-specific issues, especially for installation.
* <<Solvers,Solver Notes>>:  Documentation for third-party solvers that can be called from Coopr.


[[Options]]
== Installation Options ==

[[Option1]]
=== Install a Coopr Release with the `easy_install` Script ===

A standard way to install Python packages like Coopr is to install
them as a Python site package.  This generally requires administrative
privileges, since Python is installed in system directories that
are not accessible to general users.  Additionally, this requires
internet access to download Coopr and the packages it depends on.

Coopr can be installed with the following two steps:

.  Download and install the `setuptools` package
+
[[shell]]
----
wget http://peak.telecommunity.com/dist/ez_setup.py
python ez_setup.py
----
+
.  Run `easy_install` to install Coopr:
+
[[shell]]
----
easy_install Coopr
----

The `easy_install` command downloads and installs Coopr from
link:http://pypi.python.org/pypi[PyPI], which is the Python community's web-based
service for hosting Python packages.  This command handles package
dependencies automatically, so there are no additional steps required
to install Coopr.

Notes:

* The first step can be skipped if `setuptools` is already installed.
* The `pip` package is now generally recommended over `setuptools`.  If `pip` is installed, you can install Coopr with
+
[[shell]]
----
pip install Coopr
----
* You need to specify the `HTTP_PROXY` environment to install from PyPI through a proxy server.
* Coopr scripts are installed with other Python commands.  You may need to add the directory for Python commands to your `PATH` environment to execute these scripts.



[[Option2]]
=== Install a Coopr Release with the MS Windows Installer ===

WARNING: Coopr's MS Windows installer has not worked reliably for many users.  We do not recommend that you use this installation option at this time.  

A Coopr installer is available for MS Windows.  This script installs
each Coopr Python package into the  as a Python site package.  This
generally requires administrative privileges, since Python is
installed in system directories that are not accessible to general
users.  However, this does not require internet access;  the MS
Windows installer includes the Python packages that are needed to
run Coopr.

MS Windows installer customizes the installation process as
follows:

* The registry is checked to see if a previous Coopr installation needs to be uninstalled
* The user can optionally install additional Python packages that are used by Coopr (e.g. PyYAML and PyQt)
* A log of the install process is captured to help diagnose errors
* The user's environment is adapted to add the Coopr binary directory to the user's path

Notes:

* Download the Coopr installer from the
link:https://software.sandia.gov/trac/coopr/downloader[Coopr download
site]
* This package may need to executed with administrator privileges 



[[Option3]]
=== Install a Coopr Release with the `coopr_install` Script ===

The `coopr_install` script installs Coopr in a virtual Python
environment.  This environment is an isolated Python installation
that depends on the system Python installation, but which mimics a
complete Python installation.  A virtual Python environment can be
created by a user in their directory without requiring administrative
privileges.

Coopr can be installed with the following two steps:

1. Download the `coopr_install` script from the
link:https://software.sandia.gov/trac/coopr/downloader[Coopr download
site]
1. Run `coopr_install` to install a Coopr release:
+
[[shell]]
----
python coopr_install coopr
----

The `coopr_install` command installs Coopr from a cached version
of this software that is integrated into the `coopr_install` script
itself.  Consequently, this installation process does not require
internet access.  Additionally, this command installs the associated
packages that depends on, so there are no additional steps required
to install Coopr.  This script creates the virtual Python environment
in the `coopr` directory, and the Coopr scripts are installed in
the `coopr/bin` directory.

Notes:

* On MS Windows, this script cannot install all of the Python
packages that Coopr depends on.  Thus, this installer is not
recommended for that platform.



[[Option4]]
=== Install the Coopr Trunk with the coopr_install Script ===

The `coopr_install` script also includes options that allow Coopr
packages to be directly checked out from its subversion repository.
These options are useful for advanced users who interact closely
with the core developers, as well as users who wish to obtain updates
for Coopr packages that are under very active development. Running
`coopr_install` requires internet access to download Coopr and the
packages it depends on, and it also requires the installation
of the subversion software.


Coopr can be installed with the following two steps:

 1. Download the `coopr_install` package from the
 link:https://software.sandia.gov/trac/coopr/downloader[Coopr
 download site]
 1. Run `coopr_install` to install Coopr.  For example
+
[[shell]]
----
python coopr_install --trunk coopr
----
+
installs the trunk branches of Coopr packages.

Although these options perform subversion checkouts, read-only
access to the subversion repository does not require a password.
The `coopr_install` command handles package dependencies automatically, so there
are no additional steps required to install Coopr.  This script
creates the virtual Python environment in the `coopr` directory,
and the Coopr scripts are installed in the `coopr/bin` directory.

Notes:

* You need to specify the `HTTP_PROXY` environment to install from PyPI through a proxy server.
* The `coopr_install` script can be directly downloaded from link:https://software.sandia.gov/coopr_install[] 
* The subversion software may need to be configured to work a proxy server on your network.
* The subversion software is commonly available on Linux and MacOS, but it is not preinstalled with MS Windows.


// vim: set syntax=asciidoc:
