Installation

Standard install procedure

To install Player in the default location (/usr/local), follow these steps:

1. Download the latest Player source tarball (player-<version>.tgz) from SourceForge.

2. Uncompress and expand the tarball:
   $ tar xzvf player-<version>.tgz

3. `cd' into Player's source directory:
   $ cd player-<version>

4. Create a subdirectory called `build' and enter it:
   $ mkdir build
$ cd build

5. To configure Player with default settings:
   $ cmake ../
   

6. Compile Player:
   $ make

7. Install Player. By default, Player will be installed in /usr/local so you need to become root for this step. Remember to return to your normal user ID afterwards.
   $ make install
   Executables (e.g., the Player utilities) are in /usr/local/bin, libraries (e.g., libplayercore, libplayerdrivers) are in /usr/local/lib, and so on.

pkg-config paths

The pkg-config meta-data files (they have the extension .pc) are installed by default to /usr/local/lib/pkgconfig. On some systems (notably RedHat), this directory is not in the default search path for pkg-config. You can check like so:

$ pkg-config --libs playercore

You should get something like (exact results vary by system):

-lplayercore -lltdl -lpthread -lplayercommon

If instead you get this:

Package playercore was not found in the pkg-config search path.
Perhaps you should add the directory containing `playercore.pc'
to the PKG_CONFIG_PATH environment variable
No package 'playercore' found


then you need to add /usr/local/lib/pkgconfig to your PKG_CONFIG_PATH. E.g., in bash:

$ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH

Otherwise you will not be able to compile programs that use any of Player's libraries.

Customized installations

Player uses CMake for its build system. You can use CMake's GUI configuration editor to change the build options:

$ ccmake ../

You can also specify options on the command line using `cmake' and the -D option:

$ cmake -D CMAKE_INSTALL_PREFIX="\<destination directory\>" ../

Installation prefix

The most important option is CMAKE_INSTALL_PREFIX, used to change the installation directory from the default (which varies from system to system, but is usually /usr/local). You should use an absolute path, i.e. a complete path starting with a '/'.

For example, you might want to install Player in your home directory because you don't have root access:

$ cmake -D CMAKE_INSTALL_PREFIX="/home/gerkey/ps" ../
$ make
$ make install

Now the executables are in /home/gerkey/ps/bin, the libraries are in /home/gerkey/ps/lib, and so on.

Note:

You may have to change various environment variables if you install Player somewhere other than the default location. Variables that may need modification include: PATH, LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH on Mac OS X), and PKG_CONFIG_PATH. More information on local installations can be found here.

Selecting which drivers to build

By default, all drivers that can be built on your system will be compiled and linked into libplayerdrivers. CMake determines which drivers will be built by running tests against your system to see which prerequisites are satisfied. You'll see output during these tests telling you what's going on. A summary is printed by CMake when it's done, telling you which drivers will not be built, and why. You can check the file CMakeFiles/CMakeError.log for detailed information about which tests failed and why.

You can override this default behavior by using ccmake to enable and disable certain drivers. For every driver foo, there will be an option in ccmake ENABLE_DRIVER_FOO that can be switched on or off. You can also pass the option on the command line to cmake. For example, to prevent compilation of the sicklms400 driver:

$ cmake -D ENABLE_DRIVER_SICKLMS400=OFF ../

You can also set the value to ON to enable a driver foo that has been disabled by default. But keep in mind that such a driver is probably disabled for a reason; don't be surprised if it does not compile. And note that this will not force compilation of a driver whose prerequisites have not been met.

The order of these options on the command line does not matter.