===============================================================================
                         Modular OpenRobots Simulator Engine
                          (c) LAAS/ONERA 2009-2010 LAAS 2011-2013
===============================================================================


All this information can be read online:
http://www.openrobots.org/morse/doc/stable/user/installation.html


Requirements - What you need to install before
----------------------------------------------

Hardware
++++++++

To display textures correctly in the simulator, as well as to generate images
using the simulated cameras, you will need to have a graphics card that
supports GLSL shading. The Blender website lists these graphic cards as
compatible with GLSL:

- ATI Radeon 9x00, Xx00, X1x00, HD2x00 and HD3x00 series and newer.
- NVidia Geforce FX, 6x00, 7x00, 8x00, 9x00 and GTX 2x0 and newer.

Supported operating systems
+++++++++++++++++++++++++++

Only Linux (x86, x86_64) is currently officially supported. MORSE is mainly
developed on Fedora and Ubuntu, but we don't expect problems on other
distributions.

Other UNIXes systems probably work as well (like FreeBSD or Apple MacOSX).

MORSE does not currently support Microsoft Windows, although it may work
(testers/maintainers for Windows are welcome!).

Required software
+++++++++++++++++

- Python (3.2 or +) compiled with the ``--with-wide-unicode`` flag
- Blender 2.61 or superior build with Python 3.2
- MORSE source code

.. note::
  If you install Python by hand, it is important to specify the
  ``--with-wide-unicode`` flag, since Blender expects this behaviour.
  Otherwise, there will be an incompatibility of types when using additional
  middlewares.

If you plan to use the simulator with raw sockets of text files as "middleware",
you don't need anything else. Otherwise, you need to install the software for
other middlewares. Installation details for each supported middleware is
detailed at the end of this document.

Installation
------------

.. note::
    The directory where MORSE is installed will be referred to as ``$MORSE_ROOT`` in this document.

It is recommended to store this environment variable, as it is necessary to
use the :doc:`scene builder script <../dev/builder>` to generate equipped
robots.

Manually
++++++++

Download the latest version of the source code. It is stored in a ``git``
repository::

  $ git clone http://github.com/laas/morse.git

Once you have a copy of the repository, you can get to the last stable
version (0.6) by using ::

  $ git checkout 0.6

You can get a `tarball version here <https://github.com/laas/morse/tarball/0.6>`_.


Go to the directory where you have previously downloaded the MORSE source.
Then type these commands::

  $ mkdir build && cd build
  $ cmake ..

By default, MORSE will install in ``/usr/local``. You can easily change that
by launching ``ccmake`` instead of ``cmake``.
When using ``ccmake``, it is also possible to select the optional HLA support,
and middleware bindings for YARP and Pocolibs.

- ``CMAKE_INSTALL_PREFIX`` controls where will be installed MORSE. The install
  prefix directory is referred to as ``$MORSE_ROOT``.
- ``BUILD_CORE_SUPPORT`` controls the builds and install of Morse core. It is
  ON by default
- ``BUILD_DOC_SUPPORT`` controls the build of the documentation (require
  sphinx)
- ``BUILD_HLA_SUPPORT`` controls the builds of HLA support for multi-node
  simulations in MORSE.
- ``BUILD_POCOLIBS_SUPPORT`` controls the build of pocolibs support in MORSE.
- ``BUILD_YARP2_SUPPORT`` controls the build of YARP support in MORSE.
- ``BUILD_ROS_SUPPORT`` controls the build of ROS support in MORSE.
- ``BUILD_MOOS_SUPPORT`` controls the build of MOOS support in MORSE.
- ``CMAKE_BUILD_TYPE`` controls the optimization stuff for C/C++ extension
  (Release is a good choice). ::

  $ sudo make install

You can set up the different variables using the command line.
For instance, to build and install MORSE with YARP support in ``/opt``, you need something like::

  $ cmake -DBUILD_YARP2_SUPPORT=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt ..

The optional ``$MORSE_BLENDER`` environment variable can be set to let the
simulator know where to look for Blender if it is not accessible from the
path.

Packages manager
++++++++++++++++

MORSE is available through some package manager. See their associated
documentation.

.. toctree::
    :glob:
    :maxdepth: 1

    installation/package_manager/*

You can check your configuration is ok with::

  $ morse check

.. note::
    When updating MORSE to a more recent version, you'll simply have to do::

    $ git checkout [version]
    $ cd build
    $ make install

Installation of ROS support for MORSE
-------------------------------------

MORSE is based on Blender and requires Python 3.2. Python 3 is
partially supported by **ROS Fuerte** from patch release 1.8.15,
which was rolled out on 20/07/2012. Any ROS Fuerte installation
from that day on works fine with MORSE.


#. Install ROS Fuerte if needed: http://www.ros.org/wiki/ROS/Installation

#. Install Python 3.2 using your system package manager (available in Ubuntu >=
   11.04) or manually from the sources, and make sure your ``$PYTHONPATH``
   variable includes the Python3.2 libraries.

#. Install ``PyYAML`` with Python3 support (package ``python3-yaml`` on
   Debian/Ubuntu, or you can get the sources from http://pyyaml.org/. Install
   the source by running ``python3.2 setup.py install`` to be sure to have the
   Python 3 libraries.

#. Install rospkg using Python3.2:

   ``git clone git://github.com/ros/rospkg.git``

   ``cd rospkg``

   ``sudo python3.2 setup.py install``

#. Done. You can start having fun with MORSE!


To get a working setup suitable for using **ROS Electric** or **Diamondback**
with MORSE, please follow the instructions online:
http://www.openrobots.org/morse/doc/latest/user/installation/mw/ros.html


Installation of YARP support for MORSE
--------------------------------------

For the YARP bindings

- YARP version (2.2.5 or +) (warning, there is a known issue with yarp-2.3.0,
  don't try to use MORSE with this version. The issue has been fixed with
  yarp-2.3.1).
- YARP python binding
- ACE ( 5.6.3 or +, required for YARP)
- SWIG (2.0.4, required to compile the Python bindings)

Instructions to create YARP-Python bindings are `here
<http://eris.liralab.it/wiki/YARP_and_Python>`_.  To properly use simulated
cameras with yarp < 2.3.2, you need to apply the patch from
``patches/yarp.i.diff``.


Note that the easiest way to install YARP is probably to use ``robotpkg`` (see
`robotpkg homepage <http://homepages.laas.fr/mallet/robotpkg>`_ for more
information). Follow the instructions on installing ``robotpkg``. Then add
the environment variable ``ROBOTPKG_BASE`` to your shell.  Then to install
``YARP`` ::

  $ cd $ROBOTPKG_BASE/robotpkg/middleware/yarp
  $ make update

Afterwards, add the following settings in ``${ROBOTPKG_BASE}/etc/robotpkg.conf`` ::

  $ echo "PKG_OPTIONS.py-yarp+= python3" >> ${ROBOTPKG_BASE}/etc/robotpkg.conf

and then install the YARP python bindings bindings ::

  $ cd $ROBOTPKG_BASE/robotpkg/middleware/py-yarp
  $ make update


Compiling the YARP Python binding will create two files: ``yarp.py`` and
``_yarp.so``, and install them in
``$ROBOTPKG_BASE/lib/python3.2/site-packages/`` You'll need to set the
environment variable ``PYTHONPATH`` to
``$ROBOTPKG_BASE/lib/python3.2/site-packages/`` to let python find the YARP
module.

If you are not using robotpkg to install YARP, then make sure to copy the
files ``yarp.py`` and ``_yarp.so`` to your Python lib directory
(``/usr/lib/python3.2/site-packages/``) or at some place reachable from your
``PYTHONPATH`` environment variable.

.. warning::
    The name of the installation directory may be different depending on
     your Linux distribution. If you use Ubuntu or similar distributions,
     replace the directory name of ``python3.2/site-packages`` for
     ``python3/dist-packages``. Make sure to indicate the correct path
     used in your computer for all Python 3 libraries.


Installation of Pocolibs support for MORSE
------------------------------------------

To build Pocolibs bindings (the LAAS-CNRS middleware), you need to
install Pocolibs on your system.

The recommended way to do it is through ``robotpkg`` (see `robotpkg homepage
<http://homepages.laas.fr/mallet/robotpkg>`_ for more information).

To install::

  $ cd $ROBOTPKG_BASE/robotpkg/middleware/pocolibs
  $ make update


Installation of MOOS support for MORSE
--------------------------------------


To build the MOOS middleware, you need to install MOOS and pymoos on your system.

Additional information on MOOS and pymoos can be found at `MOOS homepage <http://www.robots.ox.ac.uk/~mobile/MOOS/wiki/pmwiki.php>`_ and `pymoos homepage <http://pymooos.sourceforge.net/>`_.

To install MOOS to your home directory::

    $ cd ~/
    $ svn co svn://login2.robots.ox.ac.uk/MOOS/trunk MOOS
    $ cd MOOS
    $ cmake .
    $ make

Pymoos requires the Boost Python library compiled for Python 3.  The
binaries available in most repositories are currently compiled for
version 2.7.   The latest version of the Boost source code (currently
1.47)  can be downloaded from `Boost <http://http://www.boost.org>`_.
To install::

    $ ./bootstrap.sh --prefix=path/to/installation/prefix --with-python-version=3.2
    $ ./b2 install

Finally pymoos can be installed by::

    $ cd ~/
    $ svn co https://pymooos.svn.sourceforge.net/svnroot/pymooos pymoos
    $ cd pymoos
    $ cmake .
    $ make
    $ sudo make install

When running ``cmake`` for pymoos make sure to select the MOOS support option.


Installation of HLA support for MORSE
-------------------------------------

The High Level Architecture (HLA) is a standard framework that supports
simulations composed of different simulation components. Some introductory
courses about HLA are available `here <http://www.ecst.csuchico.edu/~hla/>`_.

The HLA implementation on which the multi-node version of MORSE is build is
the `CERTI <https://savannah.nongnu.org/projects/certi>`_. To install the CERTI,
follow the `Building CERTI <http://www.nongnu.org/certi/certi_doc/Install/html/build.html>`_
documentation.

The CVS version tagged "CERTI-MORSE-0_4" is the version tested at the moment of
the MORSE 0.4 release. If you are facing some mistakes with the head cvs version,
try to checkout the CERTI-MORSE-0_4 version::

$ cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/certi checkout -r CERTI-MORSE-0_4 certi

You also have to create the corresponding Python binding in order to have
MORSE able to use the CERTI. The PyHLA binding can be installed following these
`instructions <http://www.nongnu.org/certi/PyHLA/manual/node6.html>`_.
Depending on your system configuration, you may have to configure PyHLA to use
the Python 3.2 executable and libraries.

Then you will have to update your PYTHONPATH so that MORSE will find the PyHLA
components.
