Compiling Player 3 clients and plugins

From The Player Project

(Difference between revisions)
Jump to: navigation, search
(New page: = Compiling clients and plugins in Player 3 = While clients and plugins (both drivers and interfaces) in Player 3 can still be compiled using plain old Makefiles (or any other build syste...)
 
(11 intermediate revisions not shown)
Line 1: Line 1:
-
= Compiling clients and plugins in Player 3 =
+
While clients and plugins (both drivers and interfaces) in Player 3 can still be compiled using plain old Makefiles (or any other build system, for that matter), it is now particularly easy to compile them using [http://cmake.org/ CMake]. This is because Player installs CMake modules for compiling clients, plugin drivers and plugin interfaces. The CMake modules take care of all the work of finding Player and linking to it for you.
-
 
+
-
While clients and plugins (both drivers and interfaces) in Player 3 can still be compiled using plain old Makefiles (or any other build system, for that matter), it is now particularly easy to compile them using CMake. This is because Player installs CMake modules for compiling clients, plugin drivers and plugin interfaces. The CMake modules take care of all the work of finding Player and linking to it for you.
+
The modules are installed in ${prefix}/share/cmake/Modules/. They are UsePlayerC.cmake, UsePlayerC++.cmake and UsePlayerPlugin.cmake. The Player examples installed in ${prefix}/share/player/examples/ all include CMakeLists.txt files that use these modules to compile the examples. See the README file in each directory for how to do so.
The modules are installed in ${prefix}/share/cmake/Modules/. They are UsePlayerC.cmake, UsePlayerC++.cmake and UsePlayerPlugin.cmake. The Player examples installed in ${prefix}/share/player/examples/ all include CMakeLists.txt files that use these modules to compile the examples. See the README file in each directory for how to do so.
-
== Compiling C clients ==
+
''For a tutorial on how to integrate these functions into your project, please see [[Player and CMake]]''
 +
 
 +
= Compiling C clients =
The UsePlayerC.cmake module enables compiling of C clients using the libplayerc client library. A minimal example is shown below.
The UsePlayerC.cmake module enables compiling of C clients using the libplayerc client library. A minimal example is shown below.
-
 
+
<source lang="cmake">
  SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
  SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
  INCLUDE (UsePlayerC)
  INCLUDE (UsePlayerC)
  PLAYER_ADD_PLAYERC_CLIENT (simple SOURCES simple.c)
  PLAYER_ADD_PLAYERC_CLIENT (simple SOURCES simple.c)
-
 
+
</source>
This is all that is necessary for a simple client. If your client requires extra options, such as include search paths, libraries to link to, and so on, specify these to PLAYER_ADD_PLAYERC_CLIENT() as well. Use the standard CMake commands to perform such functions as searching for libraries, using pkg-config, etc.
This is all that is necessary for a simple client. If your client requires extra options, such as include search paths, libraries to link to, and so on, specify these to PLAYER_ADD_PLAYERC_CLIENT() as well. Use the standard CMake commands to perform such functions as searching for libraries, using pkg-config, etc.
-
== Compiling C++ clients ==
+
= Compiling C++ clients =
The UsePlayerC++.cmake module enables compiling of C++ clients using the libplayerc++ client library. A minimal example is shown below.
The UsePlayerC++.cmake module enables compiling of C++ clients using the libplayerc++ client library. A minimal example is shown below.
-
 
+
<source lang="cmake">
  SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
  SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
  INCLUDE (UsePlayerC++)
  INCLUDE (UsePlayerC++)
  PLAYER_ADD_PLAYERCPP_CLIENT (camera SOURCES camera.cc)
  PLAYER_ADD_PLAYERCPP_CLIENT (camera SOURCES camera.cc)
 +
</source>
As with C clients, if your client requires extra options, specify these to PLAYER_ADD_PLAYERCPP_CLIENT(), and use the standard CMake commands for other build script functionality.
As with C clients, if your client requires extra options, specify these to PLAYER_ADD_PLAYERCPP_CLIENT(), and use the standard CMake commands for other build script functionality.
-
== Compiling plugin drivers ==
+
= Compiling plugin drivers =
The UsePlayerPlugin.cmake module provides functionality for compiling plugin drivers. A minimal example is shown below.
The UsePlayerPlugin.cmake module provides functionality for compiling plugin drivers. A minimal example is shown below.
 +
<source lang="cmake">
  SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
  SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
  INCLUDE (UsePlayerPlugin)
  INCLUDE (UsePlayerPlugin)
  PLAYER_ADD_PLUGIN_DRIVER (exampledriver SOURCES exampledriver.cc)
  PLAYER_ADD_PLUGIN_DRIVER (exampledriver SOURCES exampledriver.cc)
 +
</source>
The macro works in the same way as the client macros.
The macro works in the same way as the client macros.
-
== Compiling plugin interfaces ==
+
= Compiling plugin interfaces =
The UsePlayerPlugin.cmake module allows compiling plugin interfaces. A minimal example is shown below.
The UsePlayerPlugin.cmake module allows compiling plugin interfaces. A minimal example is shown below.
-
 
+
<source lang="cmake">
  SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
  SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
  INCLUDE (UsePlayerPlugin)
  INCLUDE (UsePlayerPlugin)
Line 49: Line 52:
  PLAYER_ADD_PLAYERC_CLIENT (example_client SOURCES example_client.c example_interface.h)
  PLAYER_ADD_PLAYERC_CLIENT (example_client SOURCES example_client.c example_interface.h)
  TARGET_LINK_LIBRARIES (example_client example)
  TARGET_LINK_LIBRARIES (example_client example)
-
 
+
</source>
This CMakeLists.txt is also compiling a C client and a plugin driver that uses the plugin interface, hence the length. It adds the ${PROJECT_BINARY_DIR} (i.e. where generated and compiled files are placed by CMake) to the include path, because the interface plugin creation involves generating some header files. The plugin interface is created first, followed by creating the driver and the client using the files generated during the interface plugin creation. The client must also be linked to the interface plugin library so that it can find the interface's XDR functions at runtime.
This CMakeLists.txt is also compiling a C client and a plugin driver that uses the plugin interface, hence the length. It adds the ${PROJECT_BINARY_DIR} (i.e. where generated and compiled files are placed by CMake) to the include path, because the interface plugin creation involves generating some header files. The plugin interface is created first, followed by creating the driver and the client using the files generated during the interface plugin creation. The client must also be linked to the interface plugin library so that it can find the interface's XDR functions at runtime.
-
== Macros ==
+
= Macros =
-
=== PLAYER_ADD_PLAYERC_CLIENT ===
+
== PLAYER_ADD_PLAYERC_CLIENT ==
'''PLAYER_ADD_PLAYERC_CLIENT (_clientName <variable args>)'''
'''PLAYER_ADD_PLAYERC_CLIENT (_clientName <variable args>)'''
Line 61: Line 64:
Macro to build a simple client. Pass source files, flags, etc. as extra args preceded by keywords as follows:
Macro to build a simple client. Pass source files, flags, etc. as extra args preceded by keywords as follows:
-
SOURCES <source file list>
+
SOURCES &lt;source file list>
-
INCLUDEDIRS <include directories list>
+
INCLUDEDIRS <include directories list>
-
LIBDIRS <library directories list>
+
LIBDIRS <library directories list>
-
LINKFLAGS <link flags list>
+
LINKFLAGS <link flags list>
-
CFLAGS <compile flags list>
+
CFLAGS <compile flags list>
 +
 
See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.
See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.
-
clientName:   The name of the executable to create.
+
;clientName
-
variable args: Information for compiling the client, such as source files and compile flags.
+
:The name of the executable to create.
 +
;variable args
 +
:Information for compiling the client, such as source files and compile flags.
-
=== PLAYER_ADD_PLAYERCPP_CLIENT ===
+
== PLAYER_ADD_PLAYERCPP_CLIENT ==
'''PLAYER_ADD_PLAYERCPP_CLIENT (_clientName <variable args>)'''
'''PLAYER_ADD_PLAYERCPP_CLIENT (_clientName <variable args>)'''
Line 78: Line 84:
Macro to build a simple client. Pass source files, flags, etc. as extra args preceded by keywords as follows:
Macro to build a simple client. Pass source files, flags, etc. as extra args preceded by keywords as follows:
-
SOURCES <source file list>
+
SOURCES &lt;source file list>
-
INCLUDEDIRS <include directories list>
+
INCLUDEDIRS <include directories list>
-
LIBDIRS <library directories list>
+
LIBDIRS <library directories list>
-
LINKFLAGS <link flags list>
+
LINKFLAGS <link flags list>
-
CFLAGS <compile flags list>
+
CFLAGS <compile flags list>
 +
 
See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.
See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.
-
clientName:   The name of the executable to create.
+
;clientName
-
variable args: Information for compiling the client, such as source files and compile flags.
+
:The name of the executable to create.
 +
;variable args
 +
:Information for compiling the client, such as source files and compile flags.
-
=== PLAYER_ADD_PLUGIN_DRIVER ===
+
== PLAYER_ADD_PLUGIN_DRIVER ==
'''PLAYER_ADD_PLUGIN_DRIVER (_driverName <variable args>)'''
'''PLAYER_ADD_PLUGIN_DRIVER (_driverName <variable args>)'''
Line 95: Line 104:
Macro to build a plugin driver. Pass source files, flags, etc. as extra args preceded by keywords as follows:
Macro to build a plugin driver. Pass source files, flags, etc. as extra args preceded by keywords as follows:
-
SOURCES <source file list>
+
SOURCES &lt;source file list>
-
INCLUDEDIRS <include directories list>
+
INCLUDEDIRS <include directories list>
-
LIBDIRS <library directories list>
+
LIBDIRS <library directories list>
-
LINKFLAGS <link flags list>
+
LINKFLAGS <link flags list>
-
CFLAGS <compile flags list>
+
CFLAGS <compile flags list>
 +
 
See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.
See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.
-
driverName:   The name of the driver library to create.
+
;driverName
-
variable args: Information for compiling the driver, such as source files and compile flags.
+
:The name of the driver library to create.
 +
;variable args
 +
:Information for compiling the driver, such as source files and compile flags.
-
=== PLAYER_ADD_PLUGIN_INTERFACE ===
+
== PLAYER_ADD_PLUGIN_INTERFACE ==
'''PLAYER_ADD_PLUGIN_INTERFACE (_interfName _interfDef <variable args>)'''
'''PLAYER_ADD_PLUGIN_INTERFACE (_interfName _interfDef <variable args>)'''
Line 112: Line 124:
Macro to build a plugin interface. This macro will create generated sources prefixed with the interface name. These files will be named <interface>_interface.h and <interface>_xdr.h. Pass source files, flags, etc. as extra args preceded by keywords as follows:
Macro to build a plugin interface. This macro will create generated sources prefixed with the interface name. These files will be named <interface>_interface.h and <interface>_xdr.h. Pass source files, flags, etc. as extra args preceded by keywords as follows:
-
SOURCES <source file list>
+
SOURCES &lt;source file list>
-
INCLUDEDIRS <include directories list>
+
INCLUDEDIRS <include directories list>
-
LIBDIRS <library directories list>
+
LIBDIRS <library directories list>
-
LINKFLAGS <link flags list>
+
LINKFLAGS <link flags list>
-
CFLAGS <compile flags list>
+
CFLAGS <compile flags list>
 +
 
See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.
See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.
-
interfName:   The name of the interface library (not the interface itself!) to create.
+
;interfName
-
interfDef:     The interface definition file.
+
:The name of the interface library (not the interface itself!) to create.
-
variable args: Information for compiling the driver, such as source files and compile flags.
+
;interfDef
 +
:The interface definition file.
 +
;variable args
 +
:Information for compiling the driver, such as source files and compile flags.
 +
 
 +
[[Category:Documentation]]
 +
[[Category:Tutorials]]
 +
[http://custom-essay.ws/index.php essay papers]

Latest revision as of 13:37, 15 August 2011

While clients and plugins (both drivers and interfaces) in Player 3 can still be compiled using plain old Makefiles (or any other build system, for that matter), it is now particularly easy to compile them using CMake. This is because Player installs CMake modules for compiling clients, plugin drivers and plugin interfaces. The CMake modules take care of all the work of finding Player and linking to it for you.

The modules are installed in ${prefix}/share/cmake/Modules/. They are UsePlayerC.cmake, UsePlayerC++.cmake and UsePlayerPlugin.cmake. The Player examples installed in ${prefix}/share/player/examples/ all include CMakeLists.txt files that use these modules to compile the examples. See the README file in each directory for how to do so.

For a tutorial on how to integrate these functions into your project, please see Player and CMake

Contents

Compiling C clients

The UsePlayerC.cmake module enables compiling of C clients using the libplayerc client library. A minimal example is shown below.

 SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
 INCLUDE (UsePlayerC)
 PLAYER_ADD_PLAYERC_CLIENT (simple SOURCES simple.c)

This is all that is necessary for a simple client. If your client requires extra options, such as include search paths, libraries to link to, and so on, specify these to PLAYER_ADD_PLAYERC_CLIENT() as well. Use the standard CMake commands to perform such functions as searching for libraries, using pkg-config, etc.

Compiling C++ clients

The UsePlayerC++.cmake module enables compiling of C++ clients using the libplayerc++ client library. A minimal example is shown below.

 SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
 INCLUDE (UsePlayerC++)
 PLAYER_ADD_PLAYERCPP_CLIENT (camera SOURCES camera.cc)

As with C clients, if your client requires extra options, specify these to PLAYER_ADD_PLAYERCPP_CLIENT(), and use the standard CMake commands for other build script functionality.

Compiling plugin drivers

The UsePlayerPlugin.cmake module provides functionality for compiling plugin drivers. A minimal example is shown below.

 SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
 INCLUDE (UsePlayerPlugin)
 PLAYER_ADD_PLUGIN_DRIVER (exampledriver SOURCES exampledriver.cc)

The macro works in the same way as the client macros.

Compiling plugin interfaces

The UsePlayerPlugin.cmake module allows compiling plugin interfaces. A minimal example is shown below.

 SET (CMAKE_MODULE_PATH /home/geoff/share/cmake/Modules)
 INCLUDE (UsePlayerPlugin)
 INCLUDE (UsePlayerC)
 
 INCLUDE_DIRECTORIES (${PROJECT_BINARY_DIR})
 PLAYER_ADD_PLUGIN_INTERFACE (example 128_example.def SOURCES eginterf_client.c)
 # Note the use of files generated during the PLAYER_ADD_PLUGIN_INTERFACE step
 PLAYER_ADD_PLUGIN_DRIVER (example_driver SOURCES eginterf_driver.cc example_interface.h example_xdr.h)
 PLAYER_ADD_PLAYERC_CLIENT (example_client SOURCES example_client.c example_interface.h)
 TARGET_LINK_LIBRARIES (example_client example)

This CMakeLists.txt is also compiling a C client and a plugin driver that uses the plugin interface, hence the length. It adds the ${PROJECT_BINARY_DIR} (i.e. where generated and compiled files are placed by CMake) to the include path, because the interface plugin creation involves generating some header files. The plugin interface is created first, followed by creating the driver and the client using the files generated during the interface plugin creation. The client must also be linked to the interface plugin library so that it can find the interface's XDR functions at runtime.

Macros

PLAYER_ADD_PLAYERC_CLIENT

PLAYER_ADD_PLAYERC_CLIENT (_clientName <variable args>)

Include: UsePlayerC

Macro to build a simple client. Pass source files, flags, etc. as extra args preceded by keywords as follows:

SOURCES <source file list>
INCLUDEDIRS <include directories list>
LIBDIRS <library directories list>
LINKFLAGS <link flags list>
CFLAGS <compile flags list>

See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.

clientName
The name of the executable to create.
variable args
Information for compiling the client, such as source files and compile flags.

PLAYER_ADD_PLAYERCPP_CLIENT

PLAYER_ADD_PLAYERCPP_CLIENT (_clientName <variable args>)

Include: UsePlayerC++

Macro to build a simple client. Pass source files, flags, etc. as extra args preceded by keywords as follows:

SOURCES <source file list>
INCLUDEDIRS <include directories list>
LIBDIRS <library directories list>
LINKFLAGS <link flags list>
CFLAGS <compile flags list>

See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.

clientName
The name of the executable to create.
variable args
Information for compiling the client, such as source files and compile flags.

PLAYER_ADD_PLUGIN_DRIVER

PLAYER_ADD_PLUGIN_DRIVER (_driverName <variable args>)

Include: UsePlayerPlugin

Macro to build a plugin driver. Pass source files, flags, etc. as extra args preceded by keywords as follows:

SOURCES <source file list>
INCLUDEDIRS <include directories list>
LIBDIRS <library directories list>
LINKFLAGS <link flags list>
CFLAGS <compile flags list>

See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.

driverName
The name of the driver library to create.
variable args
Information for compiling the driver, such as source files and compile flags.

PLAYER_ADD_PLUGIN_INTERFACE

PLAYER_ADD_PLUGIN_INTERFACE (_interfName _interfDef <variable args>)

Include: UsePlayerPlugin

Macro to build a plugin interface. This macro will create generated sources prefixed with the interface name. These files will be named <interface>_interface.h and <interface>_xdr.h. Pass source files, flags, etc. as extra args preceded by keywords as follows:

SOURCES <source file list>
INCLUDEDIRS <include directories list>
LIBDIRS <library directories list>
LINKFLAGS <link flags list>
CFLAGS <compile flags list>

See the examples directory (typically, ${prefix}/share/player/examples) for example CMakeLists.txt files.

interfName
The name of the interface library (not the interface itself!) to create.
interfDef
The interface definition file.
variable args
Information for compiling the driver, such as source files and compile flags.

essay papers

Personal tools