path: root/build.txt

= Building GPSD from source ==

This is a guide to building GPSD from a bare source tree.  It includes
guidance on how to cross-build the package.

(This file is marked up in asciidoc.)

== Check your build prerequisites ==

Necessary components for any build:

|==============================================================================
|C compiler         | gpsd and client library are written in C
|Python             | some code is generated from python scripts
|scons              | for the build recipe 
|==============================================================================

C99 conformance is required in the compiler. The C code depends on one
non-C99 feature: anonymous unions.  We could eliminate these, but the
cost would be source-level interface breakage if we have to move
structure members in and out of unions.

GPSD is normally built and tested with GCC. The shared-memory
interface relies on one GCCism, but the code is otherwise pretty
compiler-agnostic.  It is reported that clang produces a gpsd that
passes all regression tests. If -Wmissing-field-initializers or
its non-gcc equivalent is set you will get a lot of warnings; 
this is due to generated code and cannot be fixed.

You will need scons version 1.2.0 or later to build the code. The
autotools build from 2.96 and earlier versions has been dropped.

While Python is required to build GPSD from source (the build uses
some code generators in Python), it is not required to run the service
daemon.  In particular, you can cross-compile onto an embedded system
without having to take Python with you.

Having the following optional components on your system will enable
various additional capabilities and extensions:

|==============================================================================
|C++ compiler	    | allows building libgpsmm C++ wrapper for client library
|Qt 4.53+           | allows building libQgpsmm C++ wrapper for client library
|chrpath            | simplifies running the tools from the build directory
|==============================================================================

If you have libusb-1.0.0 or later, the GPSD build will autodetect
this and use it to discover Garmin USB GPSes, rather than groveling
through /proc/bus/usb/devices (which has been deprecated by the
Linux kernel team).

You can build libQgpsmm if you have Qt (specifically the (specifically
QtCore and QtNetwork modules) version 4.5.3 or higher.  You will also
need a C++ compiler supported by Qt (tested on GCC 4.4.0/mingw on
Windows and GCC 4.1.2 on linux). Please refer to Qt's documentation at
http://qt.nokia.com/doc/4.6/platform-specific.html for platform
specific building documentation

For working with DBUS, you'll need the DBUS development
headers and libraries installed.  Under Debian/Ubuntu these
are the packages libdbus-1-dev and libdbus-glib-1-dev.

Under Ubuntu, the ncurses package you want is libncurses5-dev.

For building from the source tree, or if you change the man page
source, xslt and docbook xsl style files are used to generate nroff
-man source from docbook xml.  The following packages are used in this
process:

|==============================================================================
|libxslt            | xsltproc is used to build man pages from xml
|docbook-xsl        | style file for xml to man translation
|==============================================================================

The build degrades gracefully in the absence of any of these. You should
be able to tell from configure messages which extensions you will get.

Under Ubuntu and most other Debian-derived distributions, an easy way
to pick up the prerequisites is: "apt-get build-dep gpsd"

If you are custom-building a Linux kernel for embedded deployment, you
will need some subset of the following modules:

|============================================================================
|pl2303     | Prolific Technology, Inc. PL2303 Serial Port
|ftdi_sio   | FTDI 8U232AM / FT232
|cypress_m8 | M8/CY7C64013
|cp210x     | Cygnal Integrated Products devices
|garmin_gps | Garmin USB mice including GPS-18
|cdc_am     | USB Communication Device Class Abstract Control Model interface
|============================================================================

These are listed in rough order of devices covered as of 2011; the
PL23203 by itself accounts for over 70% of deployed USB mice.  We
recommend building with pl2303, ftdi_sio, cypress_m8, and cp210x.

== How to build the software from source ==

To build gpsd for your host platform from source, simply call 'scons'
in a working-directory copy. (Cross-build is described in a later
section.)

You can specify the installation prefix, as for an autotools build, by
running "scons prefix=<installation_root>". The default value is
"/usr/local".  The envoronment variable DESTDIR also works in the 
usual way.

If your scons fails with the complaint "No tool named 'textfile'",
you need to upgrade it.  This feature was introduced during the long
interval after the 1.2.0 release; 1.2.1 and later versions will have it.

If your linker run fails with missing math symbols, see the FIXME
comment relating to implicit_links in the scons recipe; you probably
need to build with implicit_link=no.  If this happens, please report
your platform, ideally along with a way of identifying it from Python,
to the GPSD maintainers.

If you are going to use the RTCM-104 support, you should compile with
gcc4; if you don't have it installed as your default compiler, do this
by specifying CC=gcc4 before the build command.  The rtcm2.c file
confuses the gcc-3.4.[23] optimizer at -O2 level, making it generate
incorrect code.

After building, please run 'scons testregress' to test the correctness
of the build.  It is not necessary to install first, but you do need
to have "." in your $PATH to run regressions uninstalled.  Python is
required for regression tests. If any of the tests fail, you probavly
have a toolchain issue.  The most common such problem is issues with
strict C99 conformance in floating-point libraries.

Once you have verified that the code is working, "scons install" 
will install it it in the system directories. "scons uninstall" will
undo this. Note: because scons is a single-phase build system, this
may recompile everything. If you want feature-configuration options,
you need to specify them here.

To enable hotplugging of USB GPSes under Linux, you may do 'scons
udev-install' to put the appropriate udev rules and wrapper files in
place.

You will need php and php-gd installed to support the PHP web page.
included with the distribution. To install it, copy the file
'gpsd.php' to your HTML document directory. Then see the
post-installation instructions in INSTALL for how to configure it.

== Optional features ==

By giving command-line options to scons you can configure certain rarely-used
optional features in, or compile standard features out to reduce gpsd's 
footprint. "scons --help" will tell the story; look under "Local Options"
and consult the source code if in doubt.

Here are a few of the more important feature switches.  Each description
begins with the default for the xwitch.

pps=yes: for small embedded systems and those without threading,
it is possible to build gpsd without thread support if you build
with pps=no.  You'll lose support for updating the clock from PPS
pulses.

dbus=no: for systems using DBUS: gpsd includes support for shipping
fixes as DBUS notifications, but it is not compiled in by default.
Build with the option "dbus=yes" to get it working.

libQgpsmm=yes: libQgpsmm is a Qt version of the libgps/libgpsmm
pair. Thanks to the multi-platform approach of Qt, it allows the gpsd
client library to be available on all the Qt supported platforms.
Please see http://qt.nokia.com/doc/4.6/supported-platforms.html for a
status of Qt supported platforms as of version 4.6.

== Cross-building ==

The scons recipe is intended to support cross-building, in particular
for embedded deployment of the software.  A session transcript
illustrating how to do that, with some routine messages suppressed and
replaced with [...], follows.  The script assumes you're cloning from the 
GPSD project site or a mirror. Notes and explanation follow the transcript.

===========================================================================
$ git clone [...]
Cloning into gpsd...
[...]
$ cd gpsd
$ cp ../.scons-option-cache .
$ cat .scons-option-cache
libgpsmm = False
libQgpsmm = False
python = False
prefix = '/work/buildroot/output/staging/usr/'
sysroot = '/work/buildroot/output/staging/'
target = 'arm-indigo-linux-gnueabi'
$ scons 
scons: Reading SConscript files ...
[...]
Altered configuration variables:
libgpsmm = False (default True): build C++ bindings
libQgpsmm = False (default True): build QT bindings
python = False (default True): build Python support and modules.
prefix = /work/buildroot/output/staging/usr/ (default /usr/local): installation directory prefix
sysroot = /work/buildroot/output/staging (default ): cross-development system root
target = arm-indigo-linux-gnueabi (default ): cross-development target
scons: done reading SConscript files.
scons: Building targets ...
substituter(["jsongen.py"], ["jsongen.py.in"])
chmod -w jsongen.py
chmod +x jsongen.py
rm -f ais_json.i && /usr/bin/python jsongen.py --ais --target=parser > ais_json.i && chmod a-w ais_json.i
Creating 'gpsd_config.h'
arm-indigo-linux-gnueabi-gcc -o ais_json.os -c --sysroot=/work/buildroot/output/staging/ -Wextra -Wall -Wno-uninitialized -Wno-missing-field-initializers -Wcast-align -Wmissing-declarations -Wmissing-prototypes -Wstrict-prototypes -Wpointer-arith -Wreturn-type -D_GNU_SOURCE -O2 -fPIC ais_json.c
arm-indigo-linux-gnueabi-gcc -o daemon.os -c --sysroot=/work/buildroot/output/staging/ -Wextra -Wall -Wno-uninitialized -Wno-missing-field-initializers -Wcast-align -Wmissing-declarations -Wmissing-prototypes -Wstrict-prototypes -Wpointer-arith -Wreturn-type -D_GNU_SOURCE -O2 -fPIC daemon.c
Creating 'gpsd.h'
[...]
chmod -w maskaudit.py
chmod +x maskaudit.py
rm -f gps_maskdump.c && /usr/bin/python maskaudit.py -c . > gps_maskdump.c && chmod a-w gps_maskdump.c
arm-indigo-linux-gnueabi-gcc -o gps_maskdump.os -c --sysroot=/work/buildroot/output/staging/ -Wextra -Wall -Wno-uninitialized -Wno-missing-field-initializers -Wcast-align -Wmissing-declarations -Wmissing-prototypes -Wstrict-prototypes -Wpointer-arith -Wreturn-type -D_GNU_SOURCE -O2 -fPIC gps_maskdump.c
[..]
scons: done building targets.
$ file gpsd
gpsd: ELF 32-bit LSB executable, ARM, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.36, not stripped
===========================================================================

The author of this transcript notes:

The sysroot option tells the compiler and linker to use libraries and
headers from the given path as if they were placed at / prefix. During
this build the option allows linking with target ncurses (with the option
of having more packages at the --sysroot path) and including correct
headers without specifying -I and -L options.

In the options cache file gpsd is configured to install to
/work/buildroot/output/staging/usr path, so gpsd clients could be
compiled against libgps.so using /work/buildroot/output/staging as
sysroot option.

"arm-indigo-linux-gnueabi" as target means that
arm-indigo-linux-gnueabi-gcc and related tools are available in PATH;
your cross-compiler is likely to have a different target prefix.

Also, a warning about chrpath:

There's a use_chrpath option, on by default, so use of chrpath can be
turned off.  You may need to do this when cross-compiling.  The
problem is that, as of version 0.13, chrpath can only edit binaries
for the host it's running on.  There's an unmerged patch to fix this
at: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=502259

If you have to set use_chrpath=no, be aware that you won't be able 
to run the binaries in the test directory until you have installed
the shared libraries somewhere on the search path.