= 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. Some hints for people building binary packages are in packaging/readme.txt. (This file is marked up in asciidoc.) == Quick start == You can download the lastest gpsd tarball from: http://download.savannah.gnu.org/releases/gpsd/ Under Linux, assuming you have all your build prerequisites in place, these lines will do, and need to be run as root: tar -xzf gpsd-X.YY.tar.gz cd gpsd-X.YY scons && scons check && sudo scons udev-install If you get any errors, you need to read the detailed instructions that follow. If 'scons' fails, it is possible that your target system has moved to Python 3 and removed the program 'python'. Python.org says that if you have an installed Python, there should be a program in your path called 'python'. This is specified in PEP 394. This rule is not always followed. You can work around this by linking python3 to python like this ln -s /usr/bin/python3 /usr/bin/python Both 'scons' and 'gpsd' work fine on either Python 2 or Python 3. Which python you have installed should be transparent to the user, if python is installed correctly. Occasionally, builds may fail in completely bizarre ways due to a corrupted scons database. This seems to relate to ^Cing the build at an inopportune moment. If you suspect that, see "Reverting to a clean state" below and then try again. == Supported platforms == Native-build success should be expected on the following platforms, provided you have the prerequisites listed in the next section installed: * Any desktop or server Linux distribution. * OpenWRT and derivatives such as CeroWRT. * FreeBSD, NetBSD, OpenBSD * Android, using the official Google toolchain from the NDK We consider failure to build and function on any of these platforms a serious bug; if you encounter it, please complain on the development list . Port difficulty to any system conforming to POSIX-2001.1 should be minimal. A Cygwin port is in progress but not complete. Cross-compilation to embedded Linuxes (in addition to the OpenWRT family) is usually fairly straightforward. An illustrative build transcript is included at the end of this file. == Check your build prerequisites == Necessary components for any build: |============================================================================ |C compiler | gpsd and client library are written in C |scons | for executing the build recipe |Python2.x(x>=6) or 3.y(y>=2) | for scons and some helper scripts |============================================================================ On Gentoo, a basic build only requires this package: |============================================================================ |dev-util/scons | for executing the build recipe |============================================================================ === C compiler === C99 conformance is required in the compiler. The C code depends on one C11 feature (supported by GCC, clang, and pretty much any C compiler that also speaks C++): anonymous unions. We could eliminate these, but the cost would be source-level interface breakage if we have to move certain structure members in and out of unions. Some portions of the code using shared-memory segments are improved by the C11 stdatomic.h features for lockless concurrency. These are: the SHM export mode in shmexport.c, the code for writing clock corrections to NTP in ntpshmwrite.c, and the code for reading NTP corrections in ntpshmread.c. These features have been supported in GCC since 4.7 and clang since 3.1. GPSD is normally built and tested with GCC. Do not compile with a version older than 4.1.1; there are several known issues with older versions, including (a) non-standards-conformant floating-point generation that messes up regression testing, (b) a compiler bug affecting RTCM2 code generation, (c) the option -Wno-missing-field-initializers is unavailable, leading to a flood of warnings (this is due to generated code and cannot be fixed). clang produces a gpsd that passes all regression tests. === Python === You will need Python 2.x at minor version 6 or later or Python 3 at at minor version 3 or later. 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. You will need both basic Python and (if your package system makes the distinction) the Python development package used for building C extensions. Usually these are called "python" and "python-dev". You will know you are missing the latter if your compilation fails because of a missing Python.h. The xgps and xgpsspeed clients will only be installed if these Python extensions are installed: |============================================================================ |python-gi | Python bindings for gobject-introspection libraries |python-gi-cairo | Python bindings for Cairo toolkit under GI |=========================================================================== On Gentoo systems those packages are named: |============================================================================ |dev-python/pygobject |dev-python/pycairo |============================================================================ The ubxtool and zerk clients will only be installed if this Python extension is installed: |============================================================================ |pyserial | Python Serial Port extension |=========================================================================== On Gentoo systems that package is named: |============================================================================ |dev-python/pyserial |============================================================================ === Scons === You will need scons version 2.3.0 (from 2013-03-02) or later to build the code. === Optional build components === 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 |libcap | Capabilities library, improved security under Linux |(n)curses | curses screen-painting library, used by cgps and gpsmon |pps-tools | adds support for the KPPS API, for improved timing |libusb | Userspace access to USB devices |============================================================================ On Gentoo systems those packages are named: |============================================================================ |dev-qt/qtcore | Basic Qt |dev-qt/qtnetwork | Qt network components |sys-libs/libcap | Capabilities library |sys-libs/ncurses | curses screen-painting library, used by cgps and gpsmon |net-misc/pps-tools | adds support for the KPPS API, for improved timing |virtual/libusb | Userspace access to USB devices |============================================================================ 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 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. Under Fedora, it's ncurses-devel. Depending on how your distribution packages ncurses you may also require libtinfo5, a separate terminfo library. On some older versions of Ubuntu (notably 11.10) there is a packaging defect that may cause your build to blow up in SCons. It's a missing package info file for the tinfo library. To fix this, install the file packaging/tinfo.pc in /usr/lib/pkgconfig/tinfo.pc. 13.10 fixed this. We've seen a report that compiling on the Raspberry Pi fails with a complaint about curses.h not being found. You need to install Raspbian's curses development library if this happens. If your kernel provides the RFC 2783 KPPS (kernel PPS) API, gpsd will use that for extra accuracy. Many Linux distributions have a package called "pps-tools" that will install KPPS support and the timepps.h header file. We recommend you do that. If your kernel is built in the normal modular way, this package installation will suffice. 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 |xmlto | DocBook formatter program |asciidoc | DocBook front end with lighter markup |============================================================================ On Gentoo systems those packages are named: |============================================================================ |app-text/xmlto | DocBook formatter program |app-text/asciidoc | DocBook front end with lighter markup |dev-libs/libxslt | pulled in by asciidoc |app-text/docbook-xsl-stylesheets | pulled in by asciidoc |============================================================================ The build degrades gracefully in the absence of any of these. You should be able to tell from scons 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". Note that your sources.list will need "deb-src" lines for this, not just "deb" lines. 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 |pps-gpio | For KPPS support on ARM systems |pps-ldisc | For KPPS support with RS-232 ports |pps_parport | For KPPS support with a parallel port |============================================================================ These are listed in rough order of devices covered as of 2013; the PL23203 by itself accounts for over 70% of deployed USB mice. We recommend building with pl2303, ftdi_sio, cypress_m8, and cp210x. We've received a bug report that suggests the Python test framework requires legacy PTY support (CONFIG_LEGACY_PTYS) from the Linux kernel. You should make sure you're in the 'dialout' group in order to have permission to use these devices. == 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.) To clean the built files, call 'scons -c' . To clean scons' cache, call 'scons sconsclean'. Run 'rm -f .sconsign.dblite' to clear the scons database. Doing all three should return your working directory to a near pristine state as far as building is concerned. Some user created files may remain, and source code changes will not have been reverted.. You can specify the installation prefix, as for an autotools build, by running "scons prefix=". The default value is "/usr/local". The environment variable DESTDIR also works in the usual way. 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, while building, you see a complaint that looks like this: -------------------------------------------------------------------- I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd -------------------------------------------------------------------- it means the xmlto document formatter is failing to fetch a stylesheet it needs over the network. Probably this means you are doing a source build on a machine without live Internet access. The workaround for this is to temporarily remove xmlto from your command path so GPSD won't try building the documentation. The actual fix is to install DocBook on your machine so there will be a local copy of the stylesheet where xmlto can find it. After building, please run 'scons check' to test the correctness of the build. It is not necessary to install first. Python is required for regression tests. If any of the tests fail, you probably have a toolchain issue. The most common such problem is failures of 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 generator 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. == The leapseconds cache == Early in your build, the recipe will try to go over the Internet to one of several sources of current data on the leap-second offset in order to ensure that the file leapseconds.cache is up to date. This, in turn, is used to build a timebase.h include file. This procedure may fail if you are building in a network that requires an authenticating web proxy. If that occurs, the build will time out with a warning and a suggestion to use the leapfetch=no build option. Building with leapfetch=no may, in unusual circumstances, result in reported GPS time being off by a second or more. The circumstances are: 1. It has been less than 20 minutes since power-up; the GPS has not yet received the current leapsecond offset as part of the periodic ephemeris download. 2. One or more leap-second offset increments have been issued between when your GPSD source tree was cloned from the repository (or leapsecond.cache was later updated) and now. Leap-second increments, compensating for minute and unpredictable changes in the Earth's rotation, are occasionally issued by international time authorities. Note that the same failure can occur with any GPSD installation. But by refreshing leapseconds.cache you reduce the error window for leap-second offset bumps to affect your installation so that it begins as late as possible, at your build time rather than from when the source tree was copied. If you have had a leap-second transition, the following regression tests will break: bu303-climbing.log bu303-moving.log bu303-nofix.log bu303-stillfix.log bu303b-nofix.log italk-binary.log navcom.log ublox-aek-4t.log ublox-lea-4t.log ublox-sirf1.log There is no help for this other than a test rebuild. The problem is that these devices rely on the build-time leap-second offset; you'll see times one second off. Other GPSes either return leap-second-corrected time or the test loads include a leapsecond-offset report before any time is reported. == 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 switch. 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_export=no: for systems using DBUS: gpsd includes support for shipping fixes as DBUS notifications, compiled in by default. This may lead to complaint messages during testing on systems that don't support DBUS. Build with the option "dbus_export=no" to disable it qt=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. minimal=no: people building for extremely constrained environments may want to set this. It changes the default for all boolean (feature) options to false; thus, you get *only* the options you specify on the command line. Thus, for example, if you want to turn off all features except socket export and nmea0183, ------------------------------------------------ scons minimal=yes socket_export=yes nmea0183=yes ------------------------------------------------ will do that. ----------------------------------------------- scons minimal=yes gpsd=False gpsdclients=False ----------------------------------------------- generates only libgps.a ----------------------------------------------- scons minimal=yes shared=True gpsd=False gpsdclients=False ----------------------------------------------- generates only libgps.so == Port and toolchain testing == 'scons check' will run a comprehensive regression-test suite. You should do this, at minimum, every time you build from source on a new machine type. GPSD does enough bit-twiddling and floating point that it is very sensitive to toolchain problems; you'll want to be sure those aren't going to bite you in production. So that the tests will run fast and be easy to do often, we make the test framework shove data through the pty and socket layers *way* faster than would ever occur in production. If you get regression-test failures that aren't repeatable and look like the test framework is sporadically failing to feed the last line or two of test loads, try using the slow=yes option with scons check. If that fails, try increasing the delay value via the WRITE_PAD environment variable (above the value reported in the test output). If you have to do this, please report your experience to the GPSD maintainers. Both the builds and the tests are highly parallelizable via the scons -j option, which can gain a substantial speedup on a multicore machine. Because the output from the various jobs is interleaved, it may be more difficult to understand error results with multiple jobs. In that event, simply rerun without the -j option for more straightforward output. If coveraging is enabled (coveraging=yes), then Python programs run during testing are run via Python coveraging. This prefixes the relevant commands with the content of the python_coverage option, whose default value of "coverage run" is appropriate if the standard Python coverage package is installed and accessible in the command path. It can be set to a different value if necessary, or set to the empty string to disable Python coveraging. The latter happens automatically (with a message) if the tool cannot be found. When running multiple jobs with "-j", if python_coverage has its default value, "--parallel" is automatically appended to the command. With a non-default setting, accommodating parallelism is the user's responsibility. For instructions on how to live-test the software, see the file INSTALL. == Reverting to a clean state == The scons equivalent of 'make clean' is 'scons -c' or 'scons --clean'. This will revert your source tree to a clean state nearly as though you had just cloned or downloaded it; some scons housekeeping stuff is left in place. If you interrupted a regression test, 'scons testclean' will remove generated test programs. You can run 'scons sconsclean' to remove most of the configuration state that scons keeps. Be aware, however, that doing this can confuse scons; you may need to run 'scons --config=force' afterwards to make your build succeed. At the time of this writing, you can also remove all the scons state with "rm -rf .scon*", though that could change in a future release of scons. This method does not "confuse scons". If you use any of these actions in combination with "scons -c", do the latter first, as removing scons's state may change its notions of what needs to be cleaned. If you're building in a clone of the git repository, you can use "git clean -dxf" to remove all untracked files. Note, however, that this will remove any files you have created on your own, in addition to build products and scons temporaries. You can alternatively use "git clean -dxn" to see what would be removed without actually removing anything, or "git clean -dxi" to remove things selectively. Using "git clean" after "scons -c" usually results in a fairly short list. == Notes on Android: Samuel Cuella reports: I use the official google toolchain from the Android NDK (Native Development Kit). You can also use the toolchain from code sourcery I guess. I cross-compile from a "regular" (with GNU userland) linux box. People who port software from linux to android tend to use either the NDK or code sourcery's. If you are going to include "official" guidelines, I would go for recommending the official toolchain from the NDK. Here are the scons switches I use: scons wordsize=32 snapshot=off arch=arm sample=shell scons -j3 prefix=/usr libdir=$prefix/lib udevdir=/lib/udev gpsd_user=gpsd gpsd_group=uucp socket_export=1 nmea0183=1 sirf=1 With the following environment variables: TOOL_HOME=/home/samuel/android-official-last/ export TOOL_PREFIX=${TOOL_HOME}/bin/arm-linux-androideabi export CXX=$TOOL_PREFIX-g++ export AR=$TOOL_PREFIX-ar export RANLIB=$TOOL_PREFIX-ranlib export CC=$TOOL_PREFIX-gcc export LD=$TOOL_PREFIX-ld export CCFLAGS="-march=armv7-a -mtune=cortex-a8 -mfpu=vfp" export ARM_TARGET_LIB=${TOOL_HOME}/sysroot scons wordsize=32 snapshot=off arch=arm sample=shell == 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 ---- Edit .scons-options-cache (may not exist) and add lines, describing what your target architecture and build preferences are. ---- $ 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. You may also find it useful to set manbuild=no. == Autostarting the daemon == The preferred way to start gpsd is on-demand by a hotplug script detecting USB device activations. Look at the gpsd.rules and gpsd.hotplug files to see how this is accomplished. Relevant productions in the build recipe are "udev-install" and "udev-uninstall"; relevant build options include "udevdir". If you for some reason need to start gpsd unconditionally at boot time (in particular, if you need to support RS232 devices) there's a model init.d script under packaging/deb and a systemd setup under systemd/. // end