Source

gazebo / doc / install.html

Full commit

/**
@page install Installation (Linux)

Gazebo relies on a number of third-party libraries that make
installation a little bit tricky.  If things go wrong, please check
the archives of the Gazebo <a
href="http://sourceforge.net/mailarchive/forum.php?forum_id=33909">mailing
list</a>.  Please read the instructions below @b carefully before
reporting posting to the mailing list.

<b> These are the Linux installation instructions, OS X users should
go install_osx "here". </b>


\section install_required Required 3rd Party Libraries

See \ref prerequisites

\section install_prepare Preparing your system

The default install path for many source packages (Gazebo included) is:
@verbatim
/usr/local
/usr/local/bin
/usr/local/include
/usr/local/lib
@endverbatim

In some Linux distributions, however, these paths are not searched by
default, leading to problems when compiling and linking some packages.
We therefore recommend that you configure your system with some
additional paths (added to your .bashrc script, for example):

@verbatim
export PATH=/usr/local/bin:$PATH
export CPATH=/usr/local/include:$CPATH
export LIBRARY_PATH=/usr/local/lib:$LIBRARY_PATH
@endverbatim

The first line sets the executable path; the second sets the path for
C and C++ header files; the third line sets the library search path.
You will also need to set two more paths:

@verbatim
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
@endverbatim 

This line sets the pkg-config path (a neat utility for mananging
source dependencies).


@section install_ Global Installation (requires root access)

@verbatim
$ tar xvzf gazebo-<version>.tar.gz
$ cd gazebo-<version>
$ scons
@endverbatim
Note that scons will fail if any of the required packages are missing.
Once Gazebo has been built, it can be installed: 
@verbatim
$ su
$ scons install
$ exit
@endverbatim

Gazebo is now ready to run; try:
@verbatim
$ gazebo /usr/local/share/gazebo/worlds/pioneer.world
@endverbatim

@section install_local Local installation (does not require root access)

Some developers prefer to install Gazebo in our home directory (e.g.,
/home/[username]/local) rather than in a system directory.  This is
useful if you are working on shared machines and/or lack root access.
Naturally, local installs can make it a bit tricky for Gazebo (and
other packages) to find the right headers, libs and so on.  Here,
then, is the recommended way to do it:
 
- Pick a spot for "local" installs; for me it is
 "/home/[username]/local".  The install scripts will create relevant
 subdirs under this, such as:
@verbatim
/home/[username]/local/bin
/home/[username]/local/include
/home/[username]/local/lib
@endverbatim
 
- Set up the necessary compiler paths in your .bashrc (or whatever)
  script; e.g.:
@verbatim
export PATH=~/local/bin:$PATH
export CPATH=~/local/include:$CPATH
export LIBRARY_PATH=~/local/lib:$LIBRARY_PATH
@endverbatim
The first line sets the executable path; the second sets the path for C
and C++ header files; the third line sets the library search path.
 
- Set up some additional paths in your .bashrc (or whatever):
@verbatim
export PKG_CONFIG_PATH=~/local/lib/pkgconfig:$PKG_CONFIG_PATH
@endverbatim 
This line sets the pkg-config path (for applications using
pkg-config, which will be everything in the Player/Stage/Gazebo
project pretty soon)

- Build and install Gazebo using the "prefix" argument:
@verbatim
$ scons prefix=/home/[username]/local install
@endverbatim

Everything should now work seamlessly, and your locally installed
packages will be used in preference to any system-wide defaults.

\section config_file Configuration File

Gazebo needs some system information in order to load plugins, texture files, models, etc. This information is place in gazeborc file in the user's home directory. This file also will have other properties of this machine, work around for incomplete graphics drivers, etc. The file is called <tt>.gazeborc</tt> and typical contains:

\verbatim
<?xml version="1.0"?>
<gazeborc>
  <gazeboPath>/usr/local/share/gazebo</gazeboPath>
  <ogrePath>/home/nate/local/lib/OGRE</ogrePath>
  <RTTMode>PBuffer</RTTMode>
</gazeborc>
\endverbatim

If this file does not exist, then the builder will automatically create the file with appropriate values. If the file does exist, the builder will not overwrite it.
RTTMode can have three values: "Copy", "PBuffer" and "FBO". "Copy" is the oldest and most basic method, "PBuffer" is newer and "FBO" is the lastest shiny new RTT method. The availability of those methods depends on the graphic card drivers. If the driver are old chances are that only "Copy" work with decent performance and without artifacts. If the driver support them, using the newest method will give better framerates. Gazebo uses PBuffer by default. 
With the current version of fglrx driver there is no performance difference between FBO and Copy modes and Copy has more functionalities.

\section uninstall Uninstall 

To uninstall Gazebo, all we have to do is clean the installation of our SVN copy. This is done with the -c switch.

@verbatim
$ su
$ scons -c install
$ exit
@endverbatim

If you installed a local copy, simply: 

@verbatim
$ scons -c install
@endverbatim


*/