.. 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``