1===============================================================================
2                     Modular OpenRobots Simulator Engine
3                       Copyright (c) 2009-2010 ONERA
4                       Copyright (c) 2009-2016 LAAS-CNRS
5                       Copyright (c) 2015-2016 ISAE-SUPAERO
6    Copyright held by the MORSE authors or the institutions employing them,
7    refer to the AUTHORS file for the list. The list of the contributors to
8    each file can be obtained from the commit history ('git log <file>').
9===============================================================================
10
11
12All this information can be read online:
13http://www.openrobots.org/morse/doc/stable/user/installation.html
14
15
16General requirements
17--------------------
18
19Hardware
20++++++++
21
22A decent machine is required (typically, with an Intel i5 + 4GB RAM, you
23should be comfortable).
24
25To display textures correctly in the simulator, as well as to generate images
26using the simulated cameras, you will need to have a graphics card that
27supports GLSL shading. The Blender website lists these graphic cards as
28compatible with GLSL:
29
30- ATI Radeon 9x00, Xx00, X1x00, HD2x00 and HD3x00 series and newer.  - NVidia
31  Geforce FX, 6x00, 7x00, 8x00, 9x00 and GTX 2x0 and newer.
32
33If you do not need cameras and OpenGL textures/shaders, you are advised to
34run your simulation in fastmode (refer to the simulation's Builder
35API) for vastly improved loading time and performances.
36
37Supported operating systems
38+++++++++++++++++++++++++++
39
40Only Linux (x86, x86_64) is currently officially supported. MORSE is mainly
41developed on Fedora and Ubuntu, but we don't expect problems on other
42distributions.
43
44Other UNIXes systems probably work as well (like FreeBSD or Apple MacOSX).
45
46MORSE does not currently officially support Microsoft Windows, although some
47users reported success. Testers/maintainers for Windows are welcome!
48
49Packaged versions
50-----------------
51
52morse-1.0 is available on Debian Wheezy/Ubuntu >= 13.04. You can install
53the package morse-simulator with your favorite software manager::
54
55  $ sudo apt-get install morse-simulator
56
57You can also install the Python bindings with::
58
59  $ sudo apt-get install python3-morse-simulator
60
61
62You can also easily install MORSE with:
63
64- robotpkg
65- brew (MacOSX)
66
67See their associated documentation for details.
68
69
70If you plan to use the simulator with raw sockets or text files as interface
71(for instance, to integrate MORSE with MatLab or other specific
72applications), you don't need anything else. Otherwise, you need to install
73the software for the desired middlewares.
74
75If you want to distribute your simulation in a multinode infrastructure,
76MORSE provides by default a socket service for multinode synchronization. If
77you want to use HLA, you have to first install the CERTI and PyHLA packages.
78
79Manual installation
80-------------------
81
82    The directory where MORSE is installed will be referred to as $MORSE_ROOT
83    in this document.
84
85    It is recommended to store this environment variable, as it is necessary to
86    use the Builder API scripts to generate simulation
87    scenes with custom equipped robots.
88
89Prerequisites
90+++++++++++++
91
92- cmake
93- Python (3.3 or +)
94- python-dev package
95- Blender (>= 2.65) build with Python >= 3.3. You can simply get a binary from
96  Blender website
97
98
99Installation
100++++++++++++
101
102Download the latest version of the source code. It is stored in a git
103repository::
104
105  $ git clone https://github.com/laas/morse.git
106
107You can also get a tarball version here.
108
109Go to the directory where you have previously downloaded the MORSE source.
110Then type these commands::
111
112  $ mkdir build && cd build
113  $ cmake ..
114
115By default, MORSE will install in /usr/local. You can easily change the
116install directory by giving additional parameters to cmake.  You can also
117change the installation type and disable use middleware bindings by using
118these additional parameters.
119
120- CMAKE_INSTALL_PREFIX controls where will be installed MORSE. The install
121  prefix directory is referred to as $MORSE_ROOT.
122- BUILD_CORE_SUPPORT controls the builds and install of Morse core. It is
123  ON by default
124- BUILD_DOC_SUPPORT controls the build of the documentation (require
125  sphinx)
126- BUILD_HLA_SUPPORT controls the builds of HLA support for multi-node
127  simulations in MORSE
128- BUILD_POCOLIBS_SUPPORT controls the build of pocolibs support in MORSE.
129- BUILD_YARP_SUPPORT controls the build of YARP support in MORSE.
130- BUILD_ROS_SUPPORT controls the build of ROS support in MORSE.
131- BUILD_MOOS_SUPPORT controls the build of MOOS support in MORSE.
132- PYMORSE_SUPPORT controls the build and installation of pymorse, a
133  library to interact with Morse through the socket interface. It is needed
134  for test infrastructure.
135- CMAKE_BUILD_TYPE controls the optimization stuff for C/C++ extension
136  (Release is a good choice).
137- PYTHON_EXECUTABLE indicate where the python executable is in your system
138  (must be >= 3.3)
139
140You can set up the different variables using the command line.
141For instance, to build and install MORSE with YARP support in /opt, you need something like::
142
143  $ cmake -DBUILD_YARP_SUPPORT=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt ..
144
145Or to tell MORSE where to find a Python installed in a different location::
146
147  $ cmake -DPYTHON_EXECUTABLE=/usr/local/bin/python3.3 ..
148
149Alternatively, you can use ccmake .. to change all of these parameters using a
150graphical interface. You can modify many different variables by switching to
151"advanced mode" (pressing the t key).
152
153After configuring the necessary parameters, compile with::
154
155  $ sudo make install
156
157The optional $MORSE_BLENDER environment variable can be set to let the
158simulator know where to look for Blender if it is not accessible from the
159path.
160
161You can check your configuration is ok with::
162
163  $ morse check
164
165When updating MORSE to a more recent version, you'll simply have to do::
166
167    $ git checkout [version]
168    $ cd build
169    $ make install
170
171Installation troubleshooting
172----------------------------
173
174In case of problems installing MORSE, verify the list of Frequently Asked
175Questions.
176