INSTALL

# -----------------------------------------------------------
#   SUAVE Installation Guide
# -----------------------------------------------------------

# Contents
- Dependencies
- Installation
- Dealing with Write Access
- Additional Options
- Un-Installation

Revision - June 22, 2015
 
HTML version, and more information is available at 
- suavecode.github.io/download
- suavecode.github.io/develop

# -----------------------------------------------------------
#   Dependencies
# -----------------------------------------------------------

# Python Version

SUAVE is developed on python versions 2.4 through 2.7.  
Let us know if you find that it works on additonal versions.


# Package Requirements

numpy, scipy, matplotlib, pip

The above can be obtained at once with the installation of python 
distributions like "Anaconda" and "Enthought"

See suavecode.github.io/download for recommendations for where
to get these packages individually.

# -----------------------------------------------------------
#   Installation
# -----------------------------------------------------------

SUAVE uses setuptools to install, or distutils if setuptools
is unavailable.

1. Navigate to the trunk directory by command line.
   This should contain 'setup.py' and directory 'SUAVE'.
   setup.py is a script that will install the package.
   
   Windows users: open the start menu and type 'cmd' to
   open a command line.
   
2. Execute the install command.
   There are two options for intalling. These commands may 
   require a sudo ('super-user-do') call.
   
   A. Full-Install
      This will build and copy the package to python's modules
      directory (known as site-packages).
      
      Command:
      $ python setup.py install
      
   B. Developer-Install (requires the setuptools package)
      This will install a link to your local SUAVE package.
      It's a nice option if you expect to be modifying source.
      
      Command:
      $ python setup.py develop

3. Test the installation
   Navigate to a different directory, and try these commands:
   
   $ python
   >>> import SUAVE
   >>> print SUAVE.__file__
   
   This should print the location of the SUAVE package.


# -----------------------------------------------------------
#   Dealing with Write Access
# -----------------------------------------------------------

If you don't have write-access to the python site-packages 
directory, you can try these approaches to install SUAVE


# -----------------------------------------------------------
#   Install to local site-packages

This involves the install option --user, and should work for 
either a full install or developer install

Full Install Command:
    $ python setup.py install --user

Developer Install Command:
    $ python setup.py develop --user	
    
    
# -----------------------------------------------------------
#   Start a local site-packages folder 

This involves creating a local directory, and setting up your
PYTHONPATH environment variable.

1. Create a local directory.  
   For example: mkdir ~/python-site-packages

2. Append this path to PYTHONPATH

   A. For Unix operating systems
      i. Append this line to your ~/.bashrc file
         export PYTHONPATH = $PYTHONPATH:~/python-site-packages
      ii. And source the bashrc file
         $ source ~/.bashrc
         
   B. For MacOS operating systems
      i. Append this line to your ~/.bash_profile file
         export PYTHONPATH = $PYTHONPATH:~/python-site-packages
      ii. And source the bashrc file
         $ source ~/.bashrc
         
   C. For Windows operating systems
      i. Open the start menu and type "environ", this opens the environment
         variable editor
      ii. Create or edit the PYTHONPATH "System" environment variable, appending
         the full path to your custom site-package directory, separating multiple
         paths with semicolons.
      iii. Open a new command line window.

3. Install SUAVE
   Using the example of the custom directoy '~/python-site-packages':

   A. Full-Install
      Command:
         $ python setup.py install --prefix=~/python-site-packages
      
   B. Developer-Install
      Command:
         $ python setup.py develop --prefix=~/python-site-packages      

       
# -----------------------------------------------------------
#   Additional Options
# -----------------------------------------------------------

Additional setup options, such as overriding the default install
location, can be found with the following commands:

python setup.py install --help
python setup.py uninstall --help
python setup.py develop --help
python setup.py --help


# -----------------------------------------------------------
#   Un-Installation
# -----------------------------------------------------------

SUAVE requires pip to uninstall.  An alternate approach is
provided further below if pip is not available.

Un-Installation with pip:

1. Navigate to the trunk directory by command line.

2. Uninstallation varies with the type of your install
   These commands may require a sudo ('super-user-do') call.
   
   A. Full-UnInstall
      Use this if you performed a full-install.
      
      Command:
      $ python setup.py uninstall
  
   B. Developer-UnInstall
      Use this if you performed a developer-install.
      
      Command:
      $ python setup.py develop --uninstall

Alternate Approach:
   Use this if you don't have the pip package.

   1. Find your site-packages folder.
      Your site-packages folder
      is typically located in your python's install directory.  
      You can find it by using the following commands.
         $ python
         >>> import site
         >>> site.getsitepackages()
 
    2. Manually delete any file including the name "SUAVE".  
       You may also check the file 'easy_install.pth' if
       it exists for references to the SUAVE package, and 
       delete them.
       
       Never said this would be pretty...  However it is a
       typical uninstall process for python packages.