
[[InstallationFAQ]]
== Installation Issues ==

Here are some of the most common issues encountered by Coopr users.
If you do not see your question answered here, the best route for
getting an answer is by engaging the Coopr community through the
link:http://groups.google.com/group/coopr-forum[coopr-forum mailing
list].

=== Python Installation ===

The standard Python distribution is built with the C language, and
thus this is sometimes called CPython.  CPython distributions are
available for all major platforms, and this is the most common
version of Python that is used in practice.  Linux and Macintosh
distributions commonly include CPython, and no additional configuration
is required to execute the Python interpreter.

On Windows platforms, CPython can be easily installed with an
installer executable.  However, the user must edit the PATH environment
variable to include the Python installation path.

Other noteworthy implementations of Python are Jython, written in
Java, and IronPython, written for the Common Language Runtime.  A
major difference between CPython, Jython and IronPython is that
they support extensions with C, Java and .NET application framework
respectively.  Coopr is developed and tested using CPython, and
these other Python implementations have not been evaluated.

Most Coopr packages are designed to work with version 2.5, 2.6 and
2.7, though some functionality only works with 2.6 and 2.7.  The
Python language underwent some rather large changes in version 3.0.
These changes are not backward-compatible with Python 2.x, and
consequently Coopr does not currently work with Python 3.x.

=== Coopr Installation ===

==== Help with `coopr_install` ====

There are numerous options to the `coopr_install` script, which can be displayed by typing:
[[shell]]
----
./coopr_install --help
----

IMPORTANT: Make sure you do ''not'' have the `PYTHONHOME` environment
variable defined prior to installing Coopr. Such a definition
interferes with the construction of the Coopr virtualized Python
environment.


==== Using Preinstalled Site Packages ====

By default, the `coopr_install` command does ''not'' mirror the
contents of the system Python installation site-packages directory.
This helps ensure the stability of the Coopr installation.  However,
there are situations where a user may want access to pre-installed
site-packages, like SciPy and/or NumPy. To enable this behavior,
simply specify the "--site-packages" option at installation.

Another option is to install these packages directly into the
virtualized Python environment created by `coopr_install`.  However,
installing Python packages can be tricky, particularly if they rely
on compiled extension packages.


==== Using the `HTTP_PROXY` Environment Variable ====

In many computing environments, it may be necessary to set the
`HTTP_PROXY` environment variable to use the `wget` and `coopr_install`
commands.  A typical value for this variable is something like
"http://foo.institution.domain:80".  Your local system administrator
can help you assess whether you need an HTTP proxy for web access.
For example, at Sandia (New Mexico only) the proxy
`http://sonproxy.sandia.gov:80` is used for the SON network, and
`http://wwwproxy.sandia.gov:80` is used for the SRN network.


==== Installing with Package XXX ====

The `-a` or `--add-package` option can be used to install Coopr
with a specified package.  That this option can specify a directory
that contains a package that needs to be installed.  Alternatively,
this option can specify a package name that is downloaded from PyPI.
Note that package installation may fail for complex packages like
SciPy that use compiled Python extensions.  For these cases, the
package needs to be installed separately, or a Python bundle like
link:http://www.pythonxy.com/[Python(x,y)] needs to be used.


==== Installing on MS Windows ====

There is a known problem with MS Windows Coopr installations.  Coopr
depends on the PyYAML package, which does not install under MS
Windows with the 64-bit Python build.  Thus, Coopr requires the
32-bit build for MS Windows.


====  Installation error: Filename ... does not start with any of these prefixes: ... ====

We have seen the error:

----
Installation error: Filename ... does not start with any of these prefixes: ...]
----
when installing on Windows.  This appears to be a limitation of the
virtual environment logic.  Specifically, this was triggered by
explicitly specifying the Python path with a lower-case drive name.
For example:
[[shell]]
----
c:\Python27\python.exe coopr_install
----
Using a capital drive name resolved this issue:
[[shell]]
----
C:\Python27\python.exe coopr_install
----


====  Installation error: Setup script exited with error: command 'gcc' failed ... ====

Several Python packages that Coopr relies on (e.g., coverage and
PyYAML) include compiled "C" extensions.  This error indicated that
the extensions did not successfully compile.  In most cases, the
root cause is that the Python C headers are not installed or available
on your system.  For Linux/UNIX users, make sure you have the
`python-devel` package installed.

=== Using Subversion with a Proxy ===

Subversion does not use the `HTTP_PROXY` environment variable to
configure its behavior. Rather, this must be done by modifying the
local subversion configuration. As expected, this differs on Windows
and Unix platforms, and is environment-specific. However, the
step-by-step process is somewhat generic. Sandia-specific instructions
can be found [sandbox:UsingSubversion here]. The same instructions
should be applicable in other environments by appropriately
substituting the name of your local proxy server.


=== Python environment variables ===

The `PYTHONPATH` and `PYTHONHOME` environment variables are used
to customize the way that Python is configured.  The `PYTHONHOME`
variable defines the location of the standard Python libraries that
are used, and `PYTHONPATH` augments the default search path for
module files.

Since Coopr is installed in a virtual Python environment, these
environment variables are generally not necessary.  We have seen
many cases where Coopr scripts failed to operate properly when these
variables were defines, so we generally recommend that the user
disable these variables before installing Coopr and executing Coopr
scripts.

// vim: set syntax=asciidoc:
