Adding drivers to Player 3

From The Player Project

(Difference between revisions)
Jump to: navigation, search
Line 1: Line 1:
-
= Adding a driver to Player 3 =
+
= Driver source code =
-
== Driver source code ==
+
See example. More needs to be written here.
See example. More needs to be written here.
-
== Build the driver ==
+
= Build the driver =
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].
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].
Line 32: Line 31:
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.
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 ==
+
= Player's driver macros =
-
=== PLAYERDRIVER_ADD_DRIVER ===
+
== PLAYERDRIVER_ADD_DRIVER ==
'''PLAYERDRIVER_ADD_DRIVER (_name _cumulativeVar <variable args>)'''
'''PLAYERDRIVER_ADD_DRIVER (_name _cumulativeVar <variable args>)'''
Line 50: Line 49:
:The option used in the called CMakeLists.txt to check if the driver has been enabled.
:The option used in the called CMakeLists.txt to check if the driver has been enabled.
-
=== PLAYERDRIVER_ADD_EXTRA ===
+
== PLAYERDRIVER_ADD_EXTRA ==
'''PLAYERDRIVER_ADD_EXTRA (_name)'''
'''PLAYERDRIVER_ADD_EXTRA (_name)'''
Line 61: Line 60:
CFLAGS <compile flags list>
CFLAGS <compile flags list>
-
=== PLAYERDRIVER_OPTION ===
+
== PLAYERDRIVER_OPTION ==
'''PLAYERDRIVER_OPTION (_name _cumulativeVar _defaultValue [reason])'''
'''PLAYERDRIVER_OPTION (_name _cumulativeVar _defaultValue [reason])'''
Line 77: Line 76:
:Give a reason for disabling to the user. If not provided, a standard reason will be given.
:Give a reason for disabling to the user. If not provided, a standard reason will be given.
-
=== PLAYERDRIVER_REQUIRE_OS ===
+
== PLAYERDRIVER_REQUIRE_OS ==
'''PLAYERDRIVER_REQUIRE_OS (_name _cumulativeVar <variable args>)'''
'''PLAYERDRIVER_REQUIRE_OS (_name _cumulativeVar <variable args>)'''
Line 90: Line 89:
:OS variables to check for (see FindOS.cmake in the cmake/internal/ dir for a list of what variable is set on each OS).
: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 ==
'''PLAYERDRIVER_REJECT_OS (_name _cumulativeVar <variable args>)'''
'''PLAYERDRIVER_REJECT_OS (_name _cumulativeVar <variable args>)'''
Line 103: Line 102:
:OS variables to check for (see FindOS.cmake in the cmake/internal/ dir for a list of what variable is set on each OS).
: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 ==
'''PLAYERDRIVER_REQUIRE_PKG (_name _cumulativeVar _package _includeDirs _libDirs _linkLibs _linkFlags _cFlags [_version])'''
'''PLAYERDRIVER_REQUIRE_PKG (_name _cumulativeVar _package _includeDirs _libDirs _linkLibs _linkFlags _cFlags [_version])'''
Line 126: Line 125:
:Name of the variable to receive the compile flags.
:Name of the variable to receive the compile flags.
-
=== PLAYERDRIVER_REQUIRE_HEADER ===
+
== PLAYERDRIVER_REQUIRE_HEADER ==
'''PLAYERDRIVER_REQUIRE_HEADER (_name _cumulativeVar _header)'''
'''PLAYERDRIVER_REQUIRE_HEADER (_name _cumulativeVar _header)'''
Line 139: Line 138:
:Name of the header file to look for.
:Name of the header file to look for.
-
=== PLAYERDRIVER_REQUIRE_HEADER_CPP ===
+
== PLAYERDRIVER_REQUIRE_HEADER_CPP ==
'''PLAYERDRIVER_REQUIRE_HEADER_CPP (_name _cumulativeVar _header)'''
'''PLAYERDRIVER_REQUIRE_HEADER_CPP (_name _cumulativeVar _header)'''
Line 152: Line 151:
:Name of the header file to look for.
:Name of the header file to look for.
-
=== PLAYERDRIVER_REQUIRE_FUNCTION ===
+
== PLAYERDRIVER_REQUIRE_FUNCTION ==
'''PLAYERDRIVER_REQUIRE_FUNCTION (_name _cumulativeVar _function)'''
'''PLAYERDRIVER_REQUIRE_FUNCTION (_name _cumulativeVar _function)'''
Line 165: Line 164:
:Name of the function to look for.
:Name of the function to look for.
-
=== PLAYERDRIVER_REQUIRE_LIB ===
+
== PLAYERDRIVER_REQUIRE_LIB ==
'''PLAYERDRIVER_REQUIRE_LIB (_name _cumulativeVar _library _function _path)'''
'''PLAYERDRIVER_REQUIRE_LIB (_name _cumulativeVar _library _function _path)'''
Line 182: Line 181:
:Location where the library is expected to be.
:Location where the library is expected to be.
-
=== PLAYERDRIVER_ADD_DEFINEOPTION ===
+
== PLAYERDRIVER_ADD_DEFINEOPTION ==
'''PLAYERDRIVER_ADD_DEFINEOPTION (_cumulativeVar _option _defaultValue _type _desc)'''
'''PLAYERDRIVER_ADD_DEFINEOPTION (_cumulativeVar _option _defaultValue _type _desc)'''

Revision as of 05:40, 29 June 2009

Contents

Driver source code

See example. More needs to be written here.

Build the driver

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.

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.

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:

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().

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 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

Invalid language.

You need to specify a language like this: <source lang="html4strict">...</source>

Supported languages for syntax highlighting:

4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, asm, asp, autoconf, autohotkey, autoit, avisynth, awk, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, cpp, cpp-qt, csharp, css, cuesheet, d, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, erlang, f1, fo, fortran, freebasic, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, hicest, hq9plus, html4strict, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, lisp, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, oobas, oracle11, oracle8, oxygene, oz, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, plsql, postgresql, povray, powerbuilder, powershell, progress, prolog, properties, providex, purebasic, python, q, qbasic, rails, rebol, reg, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, sql, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, vala, vb, vbnet, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, z80, zxbasic

Personal tools