.. index:: installation, download

.. _install:

=============================
FMS download and installation
=============================

.. note::
    Latest stable version of FMS is |release|.

Installing FMS
==============

.. warning:: 

    If you installed from source (see below) and a previous version of FMS is 
    installed on your system, *uninstall it*
    prior to installing the new version. Really. I mean it. See
    `Uninstalling FMS`_ below for detailed instructions about
    uninstallation.

.. index:: 
    single: requirements, yaml

Requirements
------------

- A working installation of the Python language (http://www.python.org), version
  should be 2.4 or greater.

- The PyYaml library (http://pyyaml.org/) is necessary to read configuration
  files. Note that installing FMS with the pip_ installer would automatically
  install PyYaml if it is missing on your system.

.. index::
    pair: linux; installation
    pair: unix; installation
    pair: BSD; installation

Linux and BSD distributions
---------------------------

Installing with pip
~~~~~~~~~~~~~~~~~~~
The preferred way to install FMS is to use pip_ (Pip Installs Python). You may
even choose to install it in a `Virtual environment`_ to isolate it.

Whichever environment you chose, simply::

    $ pip install fms

And you're done. You may even upgrade an FMS installation::

    $ pip install -U fms

.. _Virtual environment: http://guide.python-distribute.org/virtualenv.html

Installing from source
~~~~~~~~~~~~~~~~~~~~~~

I cannot imagine any good reason not to benefit of pip_ goodness, unless you want
to get the source to contribute. Anyway, it is possible to install from source.

Get the source package (see `getting FMS sources`_ below), uncompress it wherever
you think is a suitable place (``usr/local/src/`` might seem a clever choice,
though). 

``cd`` to the newly created directory.  Then run this command (as root) from a
command prompt::

    $ python setup.py install


As an alternative, you may just copy or link the ``fms`` directory in your
Python's installation ``site-packages`` directory.

In addition, you may move the ``startfms.py`` script somewhere on your path.

To check that anything went well, ``cd`` to the tests directory and run::

	$ python runalltests.py

.. index::
    pair: windows; installation

.. _pip: http://guide.python-distribute.org/installation.html#pip-info

Windows
-------

If you use ActivePython_, your best bet is to install FMS through the PyPM
installer, as you would do for any other third-party package.

.. _ActivePython: http://www.activestate.com/activepython/downloads

Otherwise, you can install a binary package from the github download section.

First, make sure you installed Python and YAML (see requirements_ above).

Get the Windows FMS installer from `FMS main repository`_ download section and put it
somewhere on the desktop, then double-click on it. Leave the default answers to
all the questions (or be prepared to remember what you did, to swear, and to
cry... That is, unless you really know what you are doing, of course). 

Then you may run FMS from IDLE or from the command line. The command line is
the prefered way to run FMS.

Running FMS from the command line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you choosed to run FMS from the command line, then get a command prompt, cd
to FMS's installation directory [1]_ and try::

    python startfms.py

(To get a command prompt, go to ``Start`` then ``Run`` and type in ``cmd`` in
the box).

If all goes well, you should get this output::

    Usage: startfms.py [options] [command] simulationconffile

    runs a Financial Market Simulator simulation

    Options:
      -h, --help            show this help message and exit
      -v, --verbose         Set logging level to 'info'. Overrided by --loglevel.
      -L LEVEL, --loglevel=LEVEL
                            Set logging level to LEVEL: debug, info, warning,
                            error, critical.
    CRITICAL - fms - Missing command name.

If instead you get an error message yelling that the system is unable to find
something called ``python`` on your machine, then the python executable is
probably not on the search path of your system. Read below to know how to add it.

If it did not run as expected
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On Windows machines, the Python installation is usually placed in
``C:\PythonXY``, where X and Y stand for the major and minor Python version
number. For an example, the installation directory for Python 2.6 would be
``C:\Python26``. To add this directory to your path, right-click on the `My
computer` icon on your desktop, and go to `Properties`. In the pop-up dialogue
window, click on the `Advanced` tab and then on the `Environment Variables`
button.  In the new dialogue that pops up, click on the `Path` variable in the
`System Variables` box then click the `Edit` button. 

Then add the following at the end of the string in the `Variable value`
textbox::

    C:\Python26\;

Do not forget the trailing backslash !

Note that you should adapt to the version of python you installed, and to the path where you installed it. It might as well be::

    C:\Program Files\Python26\;

Then, start or go to a command prompt, and try::

    python

You should get something like::

    Python 2.6.1 (r261:67517, Dec 4 2008, 16:51:00) [MSC v.1500 32 bit (Intel)]
    on win32
    Type "help", "copyright", "credits" or "license" for more information.
    >>>

Congratulations! Python is succesfully installed on your machine.
Then, at the Python prompt (the ``>>>``), try::

    import yaml

The answer should be nothing, and you should be at the python prompt again. YAML
is correctly installed as well. Enter ``exit()`` at the prompt to leave Python.
You may now go back to the `running FMS from the command line`_ section.

Running FMS from IDLE
~~~~~~~~~~~~~~~~~~~~~

IDLE stands for Integrated DeveLopment Environment, and is mainly used on
Windows systems. Once Python is installed on your system, IDLE might be started
from the Python submenu in the main menu.

Although it is meant as a development environment, IDLE is able to run scripts
(passing options and arguments to them). See IDLE documentation for detailed
information on how to run scripts from IDLE.

.. index:: uninstall

Uninstalling FMS
================

Uninstalling on Linux and BSD
-----------------------------

If you installed FMS with pip_, then simply::

    $ pip uninstall fms

And you're done.

If you installed from source, ``cd`` to your Python's installation
``site-packages`` directory, and remove fms directory and egg-info file::

	$ rm -r fms*

Then remove the ``startfms.py`` script from where it was installed, probably
``/usr/bin/`` or ``/usr/local/bin/`` on Unix. 

Uninstalling on Windows
-----------------------

On Windows, if you used a binary installer, you may uninstall FMS directly
from the application managing all installed programs. Otherwise, go to your
Python installation directory (usually ``C:\Python26``), then to the
``Site-packages`` directory, and delete anything fms-related in it (probably a
directory called ``fms``).

You're done. Thanks for giving FMS a try !

Getting FMS sources
===================

.. index:: source, git

If you need to get packaged sources of FMS, either as a zip file or a tarball,
then go to `FMS main repository`_ and use the download facilities.

In addition, you may clone the source repository of FMS. As it is managed with
`the git VCS`_, you need first to install it, then to get the repository run::

    $ git clone git://github.com/jcbagneris/fms.git

If you develop new classes or squash bugs, consider sending a patch, or asking
for pull access on the repository.

.. _the git VCS: http://git.or.cz
.. _FMS main repository: https://github.com/jcbagneris/fms

-------------------

.. rubric:: Footnotes

.. [1] Which should be the ``Scripts`` directory in you Python installation
    directory, i.e. ``C:\Python26\Scripts``
