Adding drivers to Player 3

From The Player Project

(Difference between revisions)
Jump to: navigation, search
m (Reverted edits by Jeraldinesewell (talk) to last revision by Herronrobertson)
 
(10 intermediate revisions not shown)
Line 1: Line 1:
-
= Adding a driver to Player 3 =
+
Player 3 uses [http://cmake.org CMake] for its build system. CMake is a modern, cross-platform build system. For details on general use of CMake, see the [http://cmake.org/cmake/help/cmake2.6docs.html CMake documentation] and the [http://www.cmake.org/Wiki/CMake CMake wiki].
-
== Driver source code ==
+
-
See example. More needs to be written here.
+
One of the features of CMake is powerful macros. These macros allow the creation of highly-customised build systems. Player makes use of a large number of macros to reduce the amount of build script code that must be written throughout the build scripts. In particular, it has a set of macros specifically aimed at compiling Player drivers. In contrast to the old autotools-based build scripts, adding a driver in Player 3 is very simple and typically only involves the modification of one file, adding as little as two lines of code.
-
== Build the driver ==
+
This tutorial leads the user through the process of adding a new driver to the Player SVN, creating a patch, and submitting the patch to the Player patch tracker for consideration.  If you want to submit your driver for inclusion into Player, your source code must be under an appropriate license, and have license headers at the top of each source directory.
-
Player 3 uses [http://cmake.org CMake] for its build system. CMake is a modern, cross-platform build system. For details on general use of CMake, see the [http://cmake.org/cmake/help/cmake2.6docs.html CMake documentation] and the [http://www.cmake.org/Wiki/CMake CMake wiki].
+
''For more information on writing a Player driver, see [[Writing a Player driver]].''
-
One of the features of CMake is powerful macros. These macros allow the creation of highly-customised build systems. Player makes use of a large number of macros to reduce the amount of build script code that must be written throughout the build scripts. In particular, it has a set of macros specifically aimed at compiling Player drivers. In contrast to the old autotools-based build scripts, adding a driver in Player 3 is very simple and typically only involves the modification of one file, adding as little as two lines of code.
+
== Checking out the latest code ==
 +
If want to submit your driver for inclusion in Player, the Player developers prefer that your submission is a patch against the latest SVN version of Player. See the [[Download]] page for instructions on how to check out the latest version of Player, and then work from that directory. If you do not want to submit your code to Player, you may ignore this step and work from whichever code version you wish.
 +
 
 +
== Add your driver ==
 +
=== File Hierarchy ===
 +
To add a driver to the build scripts, first determine where your driver will be placed. All Player drivers are stored under server/drivers/. They are divided into directories based on the interface provided by the driver (multi-interface drivers are typically placed under mixed/). If your driver has more than one source file, create a subdirectory below its interface directory for it. Place the driver source file(s) in the appropriate directory.  For example, the "roboteq" driver is a driver for a DC motor controller, and its primary functionality is exposed through the position2d interface.  This means it should go in a subdirectory in the position folder; i.e.
-
To add a driver to the build scripts, first determine where your driver will be placed. All Player drivers are stored under server/drivers/. They are divided into directories based on the interface provided by the driver (multi-interface drivers are typically placed under mixed/). If your driver has more than one source file, create a subdirectory below its interface directory for it. Place the driver source file(s) in the appropriate directory.
+
<pre>
 +
server/
 +
|--drivers/
 +
  |--position/
 +
      |--roboteq/
 +
        |--roboteq.cc
 +
        |--CMakeLists.txt
 +
</pre>
 +
 +
=== Driver CMakeLists.txt files===
In each directory there is a file called CMakeLists.txt. This is the build script for that directory, and is where you must put the calls to the Player macros for compiling your driver. If this file does not exist (typically the case when you have created a dedicated subdirectory for your driver), you must create it.
In each directory there is a file called CMakeLists.txt. This is the build script for that directory, and is where you must put the calls to the Player macros for compiling your driver. If this file does not exist (typically the case when you have created a dedicated subdirectory for your driver), you must create it.
-
In the CMakeLists.txt file, add the commands to build your driver. A full list of the Player macros available is given below. In addition, any standard CMake commands can be used. At a minimum, you must add a call to PLAYERDRIVER_OPTION() first, before any other macros are called, and a call to PLAYERDRIVER_ADD_DRIVER() as the final step. PLAYERDRIVER_OPTION() initialises the option used to determine if your driver will build. PLAYERDRIVER_ADD_DRIVER() actually adds your driver to the list of drivers to build. For example, the cmvision driver is added using just the following two lines of script code:
+
In the CMakeLists.txt file, add the commands to build your driver. A full list of the Player macros available is available at [[Player Driver Macros]]. In addition, any standard CMake commands can be used. At a minimum, you must add a call to PLAYERDRIVER_OPTION() first, before any other macros are called, and a call to PLAYERDRIVER_ADD_DRIVER() as the final step. PLAYERDRIVER_OPTION() initialises the option used to determine if your driver will build. PLAYERDRIVER_ADD_DRIVER() actually adds your driver to the list of drivers to build. For example, the cmvision driver is added using just the following two lines of script code:
 +
<pre>
  PLAYERDRIVER_OPTION (cmvision build_cmvision ON)
  PLAYERDRIVER_OPTION (cmvision build_cmvision ON)
  PLAYERDRIVER_ADD_DRIVER (cmvision build_cmvision CFLAGS "-DUSE_METEOR" SOURCES cmvision.cc conversions.c P2CMV.cc)
  PLAYERDRIVER_ADD_DRIVER (cmvision build_cmvision CFLAGS "-DUSE_METEOR" SOURCES cmvision.cc conversions.c P2CMV.cc)
 +
</pre>
The first macro is declaring the driver name (cmvision), the variable used to hold its build/don't build setting (build_cmvision), and enabling building of it by default. If it is disabled by default (by specifying OFF instead of ON), then an optional message can also be provided explaining why. This message will be shown in the list of drivers output when Player is configured.
The first macro is declaring the driver name (cmvision), the variable used to hold its build/don't build setting (build_cmvision), and enabling building of it by default. If it is disabled by default (by specifying OFF instead of ON), then an optional message can also be provided explaining why. This message will be shown in the list of drivers output when Player is configured.
Line 23: Line 38:
The second macro adds the cmvision driver to the list of drivers to build or not build. Which list it is added to is determined by the value of build_cmvision. The remaining arguments to this macro can vary in number and are keyworded to determine their purpose. They include all the information needed for the actual compilation of the driver, such as source files, libraries to link to, extra compile flags, and so on. For a full list of keywords that can be used, see the documentation for PLAYERDRIVER_ADD_DRIVER().
The second macro adds the cmvision driver to the list of drivers to build or not build. Which list it is added to is determined by the value of build_cmvision. The remaining arguments to this macro can vary in number and are keyworded to determine their purpose. They include all the information needed for the actual compilation of the driver, such as source files, libraries to link to, extra compile flags, and so on. For a full list of keywords that can be used, see the documentation for PLAYERDRIVER_ADD_DRIVER().
 +
=== Directory CMakeLists.txt files ===
If you have placed your driver in a dedicated subdirectory, it is vital that you add that subdirectory to the parent's list of directories to build. In the parent directory, open the CMakeLists.txt file and add a call to the ADD_SUBDIRECTORY() CMake command. Calls to this command should go at the beginning of the CMakeLists.txt file, and should be alphabetically ordered by directory name. For example, this is the CMakeLists.txt from the localisation/ directory:
If you have placed your driver in a dedicated subdirectory, it is vital that you add that subdirectory to the parent's list of directories to build. In the parent directory, open the CMakeLists.txt file and add a call to the ADD_SUBDIRECTORY() CMake command. Calls to this command should go at the beginning of the CMakeLists.txt file, and should be alphabetically ordered by directory name. For example, this is the CMakeLists.txt from the localisation/ directory:
-
ADD_SUBDIRECTORY (amcl)
+
<pre>
 +
ADD_SUBDIRECTORY (amcl)
   
   
-
PLAYERDRIVER_OPTION (fakelocalize build_fakelocalize ON)
+
PLAYERDRIVER_OPTION (fakelocalize build_fakelocalize ON)
-
PLAYERDRIVER_ADD_DRIVER (fakelocalize build_fakelocalize SOURCES fakelocalize.cc)
+
PLAYERDRIVER_ADD_DRIVER (fakelocalize build_fakelocalize SOURCES fakelocalize.cc)
-
 
+
</pre>
-
There are many other macros that can also be used to set up a driver's compilation. These perform functions such as searching for libraries, finding include paths, and similar. See below for a full documented list of these macros. In addition, any normal CMake commands can be used between the calls to PLAYERDRIVER_OPTION() and PLAYERDRIVER_ADD_DRIVER(). There are numerous examples in the drivers already present in Player, many of which perform many checks to find the information they need to compile. Look at other CMakeLists.txt files for examples when writing your own.
+
-
 
+
-
== Player's driver macros ==
+
-
 
+
-
=== PLAYERDRIVER_ADD_DRIVER ===
+
-
 
+
-
'''PLAYERDRIVER_ADD_DRIVER (_name _cumulativeVar <variable args>)'''
+
-
 
+
-
Add a driver to the list of drivers to be built or not built. Only call this once you have determined the final value of cumulativeVar. 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>
+
-
 
+
-
;name
+
-
:Driver name.
+
-
;cumulativeVar
+
-
:The option used in the called CMakeLists.txt to check if the driver has been enabled.
+
-
 
+
-
=== PLAYERDRIVER_ADD_EXTRA ===
+
-
 
+
-
'''PLAYERDRIVER_ADD_EXTRA (_name)'''
+
-
 
+
-
Add some extra code to compile and link into playerdrivers. 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>
+
-
 
+
-
=== PLAYERDRIVER_OPTION ===
+
-
 
+
-
'''PLAYERDRIVER_OPTION (_name _cumulativeVar _defaultValue [reason])'''
+
-
 
+
-
Add an option to enable/disable a driver.
+
-
IMPORTANT: This macro initialises _cumulativeVar, so it must be called before any other PLAYERDRIVER macros.
+
-
 
+
-
;name
+
-
:Driver name.
+
-
;cumulativeVar
+
-
:The option used in the calling CMakeLists.txt to check if the driver has been enabled.
+
-
;defaultValue
+
-
:Set to ON or OFF depending on if the driver should be built by default.
+
-
;reason
+
-
:Give a reason for disabling to the user. If not provided, a standard reason will be given.
+
-
 
+
-
=== PLAYERDRIVER_REQUIRE_OS ===
+
-
 
+
-
'''PLAYERDRIVER_REQUIRE_OS (_name _cumulativeVar <variable args>)'''
+
-
 
+
-
Require a certain OS.
+
-
 
+
-
;name
+
-
:Driver name.
+
-
;cumulativeVar
+
-
:The option used in the calling CMakeLists.txt to check if the driver has been enabled.
+
-
;variable args
+
-
:OS variables to check for (see FindOS.cmake in the cmake/internal/ dir for a list of what variable is set on each OS).
+
-
 
+
-
=== PLAYERDRIVER_REJECT_OS ===
+
-
 
+
-
'''PLAYERDRIVER_REJECT_OS (_name _cumulativeVar <variable args>)'''
+
-
 
+
-
Prevent building on a certain OS.
+
-
 
+
-
;name
+
-
:Driver name.
+
-
;cumulativeVar
+
-
:The option used in the calling CMakeLists.txt to check if the driver has been enabled.
+
-
;variable args
+
-
:OS variables to check for (see FindOS.cmake in the cmake/internal/ dir for a list of what variable is set on each OS).
+
-
 
+
-
=== PLAYERDRIVER_REQUIRE_PKG ===
+
-
 
+
-
'''PLAYERDRIVER_REQUIRE_PKG (_name _cumulativeVar _package _includeDirs _libDirs _linkLibs _linkFlags _cFlags [_version])'''
+
-
 
+
-
Check if a required package is available using pkg-config. If a minimum version is required, supply it as an optional argument with no spaces. For example, ">=0.9.6".
+
-
 
+
-
;name
+
-
:Driver name.
+
-
;cumulativeVar
+
-
:The option used in the calling CMakeLists.txt to check if the driver has been enabled.
+
-
;package
+
-
:Name (and possibly version) of the package to look for.
+
-
;includeDirs
+
-
:Name of the variable to receive the include directories.
+
-
;libDirs
+
-
:Name of the variable to receive the library directories.
+
-
;linkLibs
+
-
:Name of the variable to receive the libraries to link to.
+
-
;linkFlags
+
-
:Name of the variable to receive the link flags.
+
-
;cFlags
+
-
:Name of the variable to receive the compile flags.
+
-
 
+
-
=== PLAYERDRIVER_REQUIRE_HEADER ===
+
-
 
+
-
'''PLAYERDRIVER_REQUIRE_HEADER (_name _cumulativeVar _header)'''
+
-
 
+
-
Check if a required C header file is available. If extra include directories are necessary for the check, set them using CMAKE_REQUIRED_INCLUDES. If extra include files must be included for the check to succeed, specify them as extra arguments.
+
-
 
+
-
;name
+
-
:Driver name.
+
-
;cumulativeVar
+
-
:The option used in the calling CMakeLists.txt to check if the driver has been enabled.
+
-
;header
+
-
:Name of the header file to look for.
+
-
 
+
-
=== PLAYERDRIVER_REQUIRE_HEADER_CPP ===
+
-
 
+
-
'''PLAYERDRIVER_REQUIRE_HEADER_CPP (_name _cumulativeVar _header)'''
+
-
 
+
-
Check if a required C++ header file is available. (CMake will try to compile a small program using C++ with a #include<_header> line.) See the CheckIncludeFileCXX.cmake module for extra variables that may modify how this macro runs.
+
-
 
+
-
;name
+
-
:Driver name.
+
-
;cumulativeVar
+
-
:The option used in the calling CMakeLists.txt to check if the driver has been enabled.
+
-
;header
+
-
:Name of the header file to look for.
+
-
 
+
-
=== PLAYERDRIVER_REQUIRE_FUNCTION ===
+
-
 
+
-
'''PLAYERDRIVER_REQUIRE_FUNCTION (_name _cumulativeVar _function)'''
+
-
 
+
-
Check if a required function is available on the system.
+
-
;name
+
There are many other macros that can also be used to set up a driver's compilation. These perform functions such as searching for libraries, finding include paths, and similar. See [[Player Driver Macros]] for a full documented list of these macros. In addition, any normal CMake commands can be used between the calls to PLAYERDRIVER_OPTION() and PLAYERDRIVER_ADD_DRIVER(). There are numerous examples in the drivers already present in Player, many of which perform many checks to find the information they need to compile. Look at other CMakeLists.txt files for examples when writing your own.
-
:Driver name.
+
-
;cumulativeVar
+
-
:The option used in the calling CMakeLists.txt to check if the driver has been enabled.
+
-
;function
+
-
:Name of the function to look for.
+
-
=== PLAYERDRIVER_REQUIRE_LIB ===
+
== Creating a Patch ==
 +
The easiest way to create a patch to submit to Player is to use the "svn diff" command.  After you've added the source files to Player and ensured that the driver builds cleanly, run "svn up" to make sure you're patching against the latest version of Player.  Then, use the "svn add" command to add your new driver source files to version control, i.e.
-
'''PLAYERDRIVER_REQUIRE_LIB (_name _cumulativeVar _library _function _path)'''
+
<pre>
 +
$ svn add server/drivers/position/roboteq
 +
</pre>
-
Check if a required library is available on the system.
+
The "svn add" command works recursively, so if all of your new files are in the same directory, adding the directory itself should be sufficient.  It is also possible to use "svn add" on individual files.
-
;name
+
Once the source has been added to version control, you can use Subversion's "diff" functionality. The "diff" command will create a diff file between the latest HEAD revision and any local changes that were made. To generate the patch, run the following command from the root directory of the player source:
-
:Driver name.
+
-
;cumulativeVar
+
-
:The option used in the calling CMakeLists.txt to check if the driver has been enabled.
+
-
;library
+
-
:Name of the library to look for.
+
-
;function
+
-
:Function to check the library with.
+
-
;path
+
-
:Location where the library is expected to be.
+
-
=== PLAYERDRIVER_ADD_DEFINEOPTION ===
+
<pre>
 +
$ svn diff > patchfile.patch
 +
</pre>
-
'''PLAYERDRIVER_ADD_DEFINEOPTION (_cumulativeVar _option _defaultValue _type _desc)'''
+
This command puts all of the new changes into a file called "patchfile.patch."  Obviously, you may give this file any name you want.  After generating this file, please be sure to review it to make sure all of your new files have been added, and that no extra files have been added by mistake.
-
Add an option that can be set to ON or OFF by the user and a #define set accordingly in driver_config.h.
+
== Submitting your patch ==
 +
Now that the patch has been generated, see the directions on the [[Contributing]] page for directions on how to upload a patch to the patch tracker.  Again, all licensing guidelines apply, and the Player developers may ask you to clarify or edit the licensing or source of your new driver. If this happens, don't be discouraged, the developers want to work with you and include all useful drivers into Player to benefit the community.
-
;cumulativeVar
+
[[Category:Documentation]]
-
:The option used in the calling CMakeLists.txt to check if the driver has been enabled.
+
[[Category:Tutorials]]
-
;option
+
[http://custom-essay-writing-service.org/index.php custom writing]
-
:The name of the option. This is what the user will see as well as what should be used in code.
+
-
;defaultValue
+
-
:The default value of the option.
+
-
;type
+
-
:The option type. This must be one of the CMake option types: BOOL, INT or STRING.
+
-
;desc
+
-
:A brief description of the option, for the user's information.
+

Latest revision as of 15:55, 23 August 2011

Player 3 uses CMake for its build system. CMake is a modern, cross-platform build system. For details on general use of CMake, see the CMake documentation and the CMake wiki.

One of the features of CMake is powerful macros. These macros allow the creation of highly-customised build systems. Player makes use of a large number of macros to reduce the amount of build script code that must be written throughout the build scripts. In particular, it has a set of macros specifically aimed at compiling Player drivers. In contrast to the old autotools-based build scripts, adding a driver in Player 3 is very simple and typically only involves the modification of one file, adding as little as two lines of code.

This tutorial leads the user through the process of adding a new driver to the Player SVN, creating a patch, and submitting the patch to the Player patch tracker for consideration. If you want to submit your driver for inclusion into Player, your source code must be under an appropriate license, and have license headers at the top of each source directory.

For more information on writing a Player driver, see Writing a Player driver.

Contents

Checking out the latest code

If want to submit your driver for inclusion in Player, the Player developers prefer that your submission is a patch against the latest SVN version of Player. See the Download page for instructions on how to check out the latest version of Player, and then work from that directory. If you do not want to submit your code to Player, you may ignore this step and work from whichever code version you wish.

Add your driver

File Hierarchy

To add a driver to the build scripts, first determine where your driver will be placed. All Player drivers are stored under server/drivers/. They are divided into directories based on the interface provided by the driver (multi-interface drivers are typically placed under mixed/). If your driver has more than one source file, create a subdirectory below its interface directory for it. Place the driver source file(s) in the appropriate directory. For example, the "roboteq" driver is a driver for a DC motor controller, and its primary functionality is exposed through the position2d interface. This means it should go in a subdirectory in the position folder; i.e.

server/
|--drivers/
   |--position/
      |--roboteq/
         |--roboteq.cc
         |--CMakeLists.txt


Driver CMakeLists.txt files

In each directory there is a file called CMakeLists.txt. This is the build script for that directory, and is where you must put the calls to the Player macros for compiling your driver. If this file does not exist (typically the case when you have created a dedicated subdirectory for your driver), you must create it.

In the CMakeLists.txt file, add the commands to build your driver. A full list of the Player macros available is available at Player Driver Macros. In addition, any standard CMake commands can be used. At a minimum, you must add a call to PLAYERDRIVER_OPTION() first, before any other macros are called, and a call to PLAYERDRIVER_ADD_DRIVER() as the final step. PLAYERDRIVER_OPTION() initialises the option used to determine if your driver will build. PLAYERDRIVER_ADD_DRIVER() actually adds your driver to the list of drivers to build. For example, the cmvision driver is added using just the following two lines of script code:

 PLAYERDRIVER_OPTION (cmvision build_cmvision ON)
 PLAYERDRIVER_ADD_DRIVER (cmvision build_cmvision CFLAGS "-DUSE_METEOR" SOURCES cmvision.cc conversions.c P2CMV.cc)

The first macro is declaring the driver name (cmvision), the variable used to hold its build/don't build setting (build_cmvision), and enabling building of it by default. If it is disabled by default (by specifying OFF instead of ON), then an optional message can also be provided explaining why. This message will be shown in the list of drivers output when Player is configured.

The second macro adds the cmvision driver to the list of drivers to build or not build. Which list it is added to is determined by the value of build_cmvision. The remaining arguments to this macro can vary in number and are keyworded to determine their purpose. They include all the information needed for the actual compilation of the driver, such as source files, libraries to link to, extra compile flags, and so on. For a full list of keywords that can be used, see the documentation for PLAYERDRIVER_ADD_DRIVER().

Directory CMakeLists.txt files

If you have placed your driver in a dedicated subdirectory, it is vital that you add that subdirectory to the parent's list of directories to build. In the parent directory, open the CMakeLists.txt file and add a call to the ADD_SUBDIRECTORY() CMake command. Calls to this command should go at the beginning of the CMakeLists.txt file, and should be alphabetically ordered by directory name. For example, this is the CMakeLists.txt from the localisation/ directory:

ADD_SUBDIRECTORY (amcl)
 
PLAYERDRIVER_OPTION (fakelocalize build_fakelocalize ON)
PLAYERDRIVER_ADD_DRIVER (fakelocalize build_fakelocalize SOURCES fakelocalize.cc)

There are many other macros that can also be used to set up a driver's compilation. These perform functions such as searching for libraries, finding include paths, and similar. See Player Driver Macros for a full documented list of these macros. In addition, any normal CMake commands can be used between the calls to PLAYERDRIVER_OPTION() and PLAYERDRIVER_ADD_DRIVER(). There are numerous examples in the drivers already present in Player, many of which perform many checks to find the information they need to compile. Look at other CMakeLists.txt files for examples when writing your own.

Creating a Patch

The easiest way to create a patch to submit to Player is to use the "svn diff" command. After you've added the source files to Player and ensured that the driver builds cleanly, run "svn up" to make sure you're patching against the latest version of Player. Then, use the "svn add" command to add your new driver source files to version control, i.e.

$ svn add server/drivers/position/roboteq

The "svn add" command works recursively, so if all of your new files are in the same directory, adding the directory itself should be sufficient. It is also possible to use "svn add" on individual files.

Once the source has been added to version control, you can use Subversion's "diff" functionality. The "diff" command will create a diff file between the latest HEAD revision and any local changes that were made. To generate the patch, run the following command from the root directory of the player source:

$ svn diff > patchfile.patch

This command puts all of the new changes into a file called "patchfile.patch." Obviously, you may give this file any name you want. After generating this file, please be sure to review it to make sure all of your new files have been added, and that no extra files have been added by mistake.

Submitting your patch

Now that the patch has been generated, see the directions on the Contributing page for directions on how to upload a patch to the patch tracker. Again, all licensing guidelines apply, and the Player developers may ask you to clarify or edit the licensing or source of your new driver. If this happens, don't be discouraged, the developers want to work with you and include all useful drivers into Player to benefit the community. custom writing

Personal tools