1= Building GPSD from source = 2 3This is a guide to building GPSD from a bare source tree. It includes 4guidance on how to cross-build the package. 5 6Some hints for people building binary packages are in 7packaging/README.PACKAGERS. 8 9(This file is marked up in asciidoc.) 10 11== Quick start == 12 13You can download the most recent development snapshot from: 14https://gitlab.com/gpsd/gpsd/tree/master 15 16You can download the lastest gpsd tarball from: 17http://download.savannah.gnu.org/releases/gpsd/ 18 19Under Linux, assuming you have all your build prerequisites in place, 20these lines will do, and need to be run as root: 21 22 tar -xzf gpsd-X.YY.tar.gz 23 cd gpsd-X.YY 24 scons && scons check && sudo scons udev-install 25 26If you get any errors, you need to read the detailed instructions that follow. 27 28If 'scons' fails, it is possible that your target system has moved to 29Python 3 and removed the program 'python'. Python.org says that if 30you have an installed Python, there should be a program in your path 31called 'python'. This is specified in PEP 394. This rule is not always 32followed. You can work around this by linking python3 to python like 33this 34 35 ln -s /usr/bin/python3 /usr/bin/python 36 37Both 'scons' and 'gpsd' work fine on either Python 2 or Python 3. Which 38python you have installed should be transparent to the user, if python 39is installed correctly. 40 41Occasionally, builds may fail in completely bizarre ways due to a 42corrupted scons database. This seems to relate to ^Cing the build at 43an inopportune moment. If you suspect that, see "Reverting to a clean 44state" below and then try again. 45 46== Supported platforms == 47 48Native-build success should be expected on the following platforms, 49provided you have the prerequisites listed in the next section 50installed: 51 52* Any desktop or server Linux distribution. 53* OpenWRT and derivatives such as CeroWRT. 54* FreeBSD, NetBSD, OpenBSD 55* Android, using the official Google toolchain from the NDK 56 57We consider failure to build and function on any of these platforms a 58serious bug; if you encounter it, please complain on the development 59list <gpsd-dev@nongnu.org>. 60 61Port difficulty to any system conforming to POSIX-2001.1 should be minimal. 62 63A Cygwin port is in progress but not complete. 64 65Cross-compilation to embedded Linuxes (in addition to the OpenWRT family) 66is usually fairly straightforward. An illustrative build transcript 67is included at the end of this file. 68 69== Check your build prerequisites == 70 71Necessary components for any build: 72 73|============================================================================ 74|C compiler | gpsd and client library are written in C 75|scons | for executing the build recipe 76|Python2.x(x>=6) or 3.y(y>=2) | for scons and some helper scripts 77|============================================================================ 78 79On Gentoo, a basic build only requires this package: 80 81|============================================================================ 82|dev-util/scons | for executing the build recipe 83|============================================================================ 84 85=== C compiler === 86 87C99 conformance is required in the compiler. The C code depends on one 88C11 feature (supported by GCC, clang, and pretty much any C compiler 89that also speaks C++): anonymous unions. We could eliminate these, 90but the cost would be source-level interface breakage if we have to 91move certain structure members in and out of unions. 92 93Some portions of the code using shared-memory segments are improved by 94the C11 stdatomic.h features for lockless concurrency. These are: the 95SHM export mode in shmexport.c, the code for writing clock corrections 96to NTP in ntpshmwrite.c, and the code for reading NTP corrections in 97ntpshmread.c. These features have been supported in GCC since 4.7 and 98clang since 3.1. 99 100GPSD is normally built and tested with GCC. Do not compile with a version 101older than 4.1.1; there are several known issues with older versions, 102including (a) non-standards-conformant floating-point generation that 103messes up regression testing, (b) a compiler bug affecting RTCM2 code 104generation, (c) the option -Wno-missing-field-initializers is 105unavailable, leading to a flood of warnings (this is due to generated 106code and cannot be fixed). 107 108clang produces a gpsd that passes all regression tests. 109 110If you get a build failure including the text "error adding symbols: 111DSO missing from command line" or the complaint "ERROR: CC doesn't 112work", you nay have tripped over stale data in the builder's 113configuration cache. Clean the directory with "scons -c" then manually 114remove .sconsign.*dblite and retry your build. 115 116=== Python === 117 118You will need Python 2.x at minor version 6 or later or Python 3 at 119at minor version 3 or later. 120 121While Python is required to build GPSD from source (the build uses 122some code generators in Python), it is not required to run the service 123daemon. In particular, you can cross-compile onto an embedded system 124without having to take Python with you. 125 126scons finds the python used for scons separately from the python that 127should be used for the target. It seems to look for the target python 128as "python", which as above is supposed to exist per python norms. 129However, some packaging systems avoid a bare python, preferring to 130bind a program to a particular release as it is built. On systems 131without a "python" command, invoking scons as: 132 scons target_python=python3.7 133seems to help. 134 135You will need both basic Python and (if your package system makes the 136distinction) the Python development package used for building C 137extensions. Usually these are called "python" and "python-dev". You 138will know you are missing the latter if your compilation fails 139because of a missing Python.h. 140 141The xgps and xgpsspeed clients will only be installed if these Python 142extensions are installed: 143 144|=========================================================================== 145|python-gi | Python bindings for gobject-introspection libraries 146|python-gi-cairo | Python bindings for Cairo toolkit under GI 147|=========================================================================== 148 149On Gentoo systems those packages are named: 150|============================================================================ 151|dev-python/pygobject 152|dev-python/pycairo 153|============================================================================ 154 155The ubxtool and zerk clients will only be usable in direct-serial mode 156if this Python extension is installed: 157 158|=========================================================================== 159|pyserial | Python Serial Port extension 160|=========================================================================== 161 162On Gentoo systems that package is named: 163|============================================================================ 164|dev-python/pyserial 165|============================================================================ 166 167=== Scons === 168 169You will need scons version 2.3.0 (from 2013-03-02) or later to build the code. 170 171=== Optional build components === 172 173Having the following optional components on your system will enable 174various additional capabilities and extensions: 175 176|============================================================================ 177|C++ compiler | allows building libgpsmm C++ wrapper for client library 178|Qt 4.53+ | allows building libQgpsmm C++ wrapper for client library 179|libcap | Capabilities library, improved security under Linux 180|(n)curses | curses screen-painting library, used by cgps and gpsmon 181|pps-tools | adds support for the KPPS API, for improved timing 182|libusb | Userspace access to USB devices 183|============================================================================ 184 185On Gentoo systems those packages are named: 186 187|============================================================================ 188|dev-qt/qtcore | Basic Qt 189|dev-qt/qtnetwork | Qt network components 190|sys-libs/libcap | Capabilities library 191|sys-libs/ncurses | curses screen-painting library, used by cgps and gpsmon 192|net-misc/pps-tools | adds support for the KPPS API, for improved timing 193|virtual/libusb | Userspace access to USB devices 194|============================================================================ 195 196If you have libusb-1.0.0 or later, the GPSD build will autodetect 197this and use it to discover Garmin USB GPSes, rather than groveling 198through /proc/bus/usb/devices (which has been deprecated by the 199Linux kernel team). 200 201You can build libQgpsmm if you have Qt (specifically QtCore and 202QtNetwork modules) version 4.5.3 or higher. You will also need a C++ 203compiler supported by Qt (tested on GCC 4.4.0/mingw on Windows and GCC 2044.1.2 on linux). Please refer to Qt's documentation at 205http://qt.nokia.com/doc/4.6/platform-specific.html for platform 206specific building documentation 207 208For working with DBUS, you'll need the DBUS development 209headers and libraries installed. Under Debian/Ubuntu this 210is the package libdbus-1-dev. 211 212Under Ubuntu, the ncurses package you want is libncurses5-dev. Under 213Fedora, it's ncurses-devel. Depending on how your distribution 214packages ncurses you may also require libtinfo5, a separate terminfo 215library. 216 217On some older versions of Ubuntu (notably 11.10) there is a packaging 218defect that may cause your build to blow up in SCons. It's a missing 219package info file for the tinfo library. To fix this, install the file 220packaging/tinfo.pc in /usr/lib/pkgconfig/tinfo.pc. 13.10 fixed this. 221 222We've seen a report that compiling on the Raspberry Pi fails with 223a complaint about curses.h not being found. You need to install 224Raspbian's curses development library if this happens. 225 226If your kernel provides the RFC 2783 KPPS (kernel PPS) API, gpsd will 227use that for extra accuracy. Many Linux distributions have a package 228called "pps-tools" that will install KPPS support and the timepps.h 229header file. We recommend you do that. If your kernel is built in 230the normal modular way, this package installation will suffice. 231 232For building from the source tree, or if you change the man page 233source, xslt and docbook xsl style files are used to generate nroff 234-man source from docbook xml. The following packages are used in this 235process: 236 237|============================================================================ 238|libxslt | xsltproc is used to build man pages from xml 239|docbook-xsl | style file for xml to man translation 240|xmlto | DocBook formatter program 241|asciidoc | DocBook front end with lighter markup 242|============================================================================ 243 244On Gentoo systems those packages are named: 245 246|============================================================================ 247|app-text/xmlto | DocBook formatter program 248|app-text/asciidoc | DocBook front end with lighter markup 249|dev-libs/libxslt | pulled in by asciidoc 250|app-text/docbook-xsl-stylesheets | pulled in by asciidoc 251|============================================================================ 252 253The build degrades gracefully in the absence of any of these. You should 254be able to tell from scons messages which extensions you will get. 255 256Under Ubuntu and most other Debian-derived distributions, an easy way 257to pick up the prerequisites is: "apt-get build-dep gpsd". Note 258that your sources.list will need "deb-src" lines for this, not 259just "deb" lines. 260 261If you are custom-building a Linux kernel for embedded deployment, you 262will need some subset of the following modules: 263 264|============================================================================ 265|pl2303 | Prolific Technology, Inc. PL2303 Serial Port 266|ftdi_sio | FTDI 8U232AM / FT232 267|cypress_m8 | M8/CY7C64013 268|cp210x | Cygnal Integrated Products devices 269|garmin_gps | Garmin USB mice including GPS-18 270|cdc_am | USB Communication Device Class Abstract Control Model interface 271|pps-gpio | For KPPS support on ARM systems 272|pps-ldisc | For KPPS support with RS-232 ports 273|pps_parport | For KPPS support with a parallel port 274|============================================================================ 275 276These are listed in rough order of devices covered as of 2013; the 277PL23203 by itself accounts for over 70% of deployed USB mice. We 278recommend building with pl2303, ftdi_sio, cypress_m8, and cp210x. 279 280We've received a bug report that suggests the Python test framework 281requires legacy PTY support (CONFIG_LEGACY_PTYS) from the Linux 282kernel. You should make sure you're in the 'dialout' group in order 283to have permission to use these devices. 284 285== How to build the software from source == 286 287To build gpsd for your host platform from source, simply call 'scons' 288in a working-directory copy. (Cross-build is described in a later 289section.) 290 291To clean the built files, run 'scons -c' or 'scons --clean'. 292Run 'rm -f .sconsign.*dblite' to clear the scons 293database. Doing both should return your working directory to a 294near pristine state as far as building is concerned. Some user created 295files may remain, and source code changes will not have been reverted.. 296 297When in doubt, restart with a clean copy of the source. 298 299You can specify the installation prefix, as for an autotools build, by 300running "scons prefix=<installation_root>". The default value is 301"/usr/local". The environment variable DESTDIR also works in the 302usual way. 303 304If your linker run fails with missing math symbols, see the FIXME 305comment relating to implicit_links in the scons recipe; you probably 306need to build with implicit_link=no. If this happens, please report 307your platform, ideally along with a way of identifying it from Python, 308to the GPSD maintainers. 309 310If, while building, you see a complaint that looks like this: 311 312-------------------------------------------------------------------- 313I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd 314-------------------------------------------------------------------- 315 316it means the xmlto document formatter is failing to fetch a stylesheet it 317needs over the network. Probably this means you are doing a source 318build on a machine without live Internet access. The workaround 319for this is to temporarily remove xmlto from your command path so GPSD 320won't try building the documentation. The actual fix is to install 321DocBook on your machine so there will be a local copy of the 322stylesheet where xmlto can find it. 323 324After building, please run 'scons check' to test the correctness 325of the build. It is not necessary to install first. Python is 326required for regression tests. If any of the tests fail, you probably 327have a toolchain issue. The most common such problem is failures of 328strict C99 conformance in floating-point libraries. 329 330Once you have verified that the code is working, "scons install" 331will install it it in the system directories. "scons uninstall" will 332undo this. Note: because scons is a single-phase build system, this 333may recompile everything. If you want feature-configuration options, 334you need to specify them here. 335 336To enable hotplugging of USB GPSes under Linux, you may do 'scons 337udev-install' to put the appropriate udev rules and wrapper files in 338place. 339 340You will need php and php-gd installed to support the PHP web page 341generator included with the distribution. To install it, copy the file 342'gpsd.php' to your HTML document directory. Then see the 343post-installation instructions in INSTALL.adoc for how to configure it. 344 345== Leap Seconds == 346 347The header gpsd.h contains the value BUILD_LEAPSECONDS. This is set, 348at release time, to the leap second value current at that time. 349 350Ideally gpsd would be reading the standard leapseconds.cache file 351provided by most distributions for the current leap second. 352 353Most of the drivers supply the current leap second, after the GNSS 354receiver sends it in a message to gpsd. But none of the standard NMEA 3550183 messages supply the current leap second. Thus the need for a fall 356back leap second value. 357 358The leap second value is mainly used to check for invalid UTC time from 359the GNSS receiver. If the receiver is affected by the GPS Week Number 360Roll Over (WKNO) bug, then the UTC time it reports will be off by 1024 361weeks. 362 363All GNSS receivers may be using the wrong leap second internally on 364startup. This may happen if it has been less than about 12 minutes since 365power-up; the receiver has not yet received the current leapsecond 366offset as part of the periodic almanac download. Page 18, subframe 4, 367of the almanac contains the leap second data. 368 369The gpsd daemon may be using the wrong leap second internally if 370the compiled in leap second is no longer valid, and the GNSS receiver 371has not reported the current leap second to gpsd. 372 373== Optional features == 374 375By giving command-line options to scons you can configure certain rarely-used 376optional features in, or compile standard features out to reduce gpsd's 377footprint. "scons --help" will tell the story; look under "Local Options" 378and consult the source code if in doubt. 379 380Here are a few of the more important feature switches. Each description 381begins with the default for the switch. 382 383pps=yes: for small embedded systems and those without threading, 384it is possible to build gpsd without thread support if you build 385with pps=no. You'll lose support for updating the clock from PPS 386pulses. 387 388dbus_export=no: for systems using DBUS: gpsd includes support for 389shipping fixes as DBUS notifications, compiled in by default. This 390may lead to complaint messages during testing on systems that don't 391support DBUS. Build with the option "dbus_export=no" to disable it 392 393qt=yes: libQgpsmm is a Qt version of the libgps/libgpsmm 394pair. Thanks to the multi-platform approach of Qt, it allows the gpsd 395client library to be available on all the Qt supported platforms. 396Please see http://qt.nokia.com/doc/4.6/supported-platforms.html for a 397status of Qt supported platforms as of version 4.6. 398 399minimal=no: people building for extremely constrained environments 400may want to set this. It changes the default for all boolean (feature) 401options to false; thus, you get *only* the options you specify on the 402command line. Thus, for example, if you want to turn off all features 403except socket export and nmea0183, 404 405------------------------------------------------ 406scons minimal=yes socket_export=yes nmea0183=yes 407------------------------------------------------ 408 409will do that. 410 411----------------------------------------------- 412scons minimal=yes gpsd=False gpsdclients=False 413----------------------------------------------- 414 415generates only libgps.a 416 417----------------------------------------------- 418scons minimal=yes shared=True gpsd=False gpsdclients=False 419----------------------------------------------- 420 421generates only libgps.so 422 423 424== Port and toolchain testing == 425 426'scons check' will run a comprehensive regression-test suite. You 427should do this, at minimum, every time you build from source on a new 428machine type. GPSD does enough bit-twiddling and floating point that 429it is very sensitive to toolchain problems; you'll want to be sure 430those aren't going to bite you in production. 431 432So that the tests will run fast and be easy to do often, we make the test 433framework shove data through the pty and socket layers *way* faster 434than would ever occur in production. If you get regression-test 435failures that aren't repeatable and look like the test framework is 436sporadically failing to feed the last line or two of test loads, try 437using the slow=yes option with scons check. If that fails, try 438increasing the delay value via the WRITE_PAD environment variable 439(above the value reported in the test output). If you have to do this, 440please report your experience to the GPSD maintainers. 441 442Both the builds and the tests are highly parallelizable via the scons 443-j option, which can gain a substantial speedup on a multicore machine. 444Because the output from the various jobs is interleaved, it may be more 445difficult to understand error results with multiple jobs. In that event, 446simply rerun without the -j option for more straightforward output. 447 448If coveraging is enabled (coveraging=yes), then Python programs run 449during testing are run via Python coveraging. This prefixes the relevant 450commands with the content of the python_coverage option, whose default 451value of "coverage run" is appropriate if the standard Python coverage 452package is installed and accessible in the command path. It can be 453set to a different value if necessary, or set to the empty string to 454disable Python coveraging. The latter happens automatically (with a 455message) if the tool cannot be found. When running multiple jobs with 456"-j", if python_coverage has its default value, "--parallel" is automatically 457appended to the command. With a non-default setting, accommodating 458parallelism is the user's responsibility. 459 460For instructions on how to live-test the software, see the file INSTALL.adoc. 461 462== Reverting to a clean state == 463 464The scons equivalent of 'make clean' is 'scons -c' or 'scons 465--clean'. This will revert your source tree to a clean state nearly as 466though you had just cloned or downloaded it; some scons housekeeping 467stuff is left in place. 468 469If you interrupted a regression test, 'scons testclean' will remove 470generated test programs. 471 472You can run 'scons sconsclean' to remove most of the configuration 473state that scons keeps. Be aware, however, that doing this can 474confuse scons; you may need to run 'scons --config=force' afterwards 475to make your build succeed. At the time of this writing, you can also 476remove all the scons state with "rm -rf .scon*", though that could change 477in a future release of scons. This method does not "confuse scons". 478If you use any of these actions in combination with "scons -c", do the 479latter first, as removing scons's state may change its notions of what 480needs to be cleaned. 481 482If you're building in a clone of the git repository, you can use 483"git clean -dxf" to remove all untracked files. Note, however, that 484this will remove any files you have created on your own, in addition 485to build products and scons temporaries. You can alternatively use 486"git clean -dxn" to see what would be removed without actually removing 487anything, or "git clean -dxi" to remove things selectively. Using 488"git clean" after "scons -c" usually results in a fairly short list. 489 490== Notes on Android: 491 492Samuel Cuella reports: 493 494I use the official google toolchain from the Android NDK (Native 495Development Kit). You can also use the toolchain from code sourcery I 496guess. I cross-compile from a "regular" (with GNU userland) linux box. 497 498People who port software from linux to android tend to use either the 499NDK or code sourcery's. 500 501If you are going to include "official" guidelines, I would go for 502recommending the official toolchain from the NDK. 503 504Here are the scons switches I use: 505 506scons wordsize=32 snapshot=off arch=arm sample=shell 507 508scons -j3 prefix=/usr libdir=$prefix/lib udevdir=/lib/udev 509gpsd_user=gpsd gpsd_group=uucp socket_export=1 510nmea0183=1 sirf=1 511 512With the following environment variables: 513 514TOOL_HOME=/home/samuel/android-official-last/ 515export TOOL_PREFIX=${TOOL_HOME}/bin/arm-linux-androideabi 516export CXX=$TOOL_PREFIX-g++ 517export AR=$TOOL_PREFIX-ar 518export RANLIB=$TOOL_PREFIX-ranlib 519export CC=$TOOL_PREFIX-gcc 520export LD=$TOOL_PREFIX-ld 521 522export CCFLAGS="-march=armv7-a -mtune=cortex-a8 -mfpu=vfp" 523export ARM_TARGET_LIB=${TOOL_HOME}/sysroot 524 525scons wordsize=32 snapshot=off arch=arm sample=shell 526 527== Cross-building == 528 529The scons recipe is intended to support cross-building, in particular 530for embedded deployment of the software. A session transcript 531illustrating how to do that, with some routine messages suppressed and 532replaced with [...], follows. The script assumes you're cloning from the 533GPSD project site or a mirror. Notes and explanation follow the transcript. 534 535---- 536$ git clone [...] 537Cloning into gpsd... 538[...] 539$ cd gpsd 540---- 541 542Edit .scons-options-cache (may not exist) and add lines, describing 543what your target architecture and build preferences are. 544 545---- 546$ cat .scons-option-cache 547libgpsmm = False 548libQgpsmm = False 549python = False 550prefix = '/work/buildroot/output/staging/usr/' 551sysroot = '/work/buildroot/output/staging/' 552target = 'arm-indigo-linux-gnueabi' 553$ scons 554scons: Reading SConscript files ... 555[...] 556Altered configuration variables: 557libgpsmm = False (default True): build C++ bindings 558libQgpsmm = False (default True): build QT bindings 559python = False (default True): build Python support and modules. 560prefix = /work/buildroot/output/staging/usr/ (default /usr/local): installation directory prefix 561sysroot = /work/buildroot/output/staging (default ): cross-development system root 562target = arm-indigo-linux-gnueabi (default ): cross-development target 563scons: done reading SConscript files. 564scons: Building targets ... 565substituter(["jsongen.py"], ["jsongen.py.in"]) 566chmod -w jsongen.py 567chmod +x jsongen.py 568rm -f ais_json.i && /usr/bin/python jsongen.py --ais --target=parser > ais_json.i && chmod a-w ais_json.i 569Creating 'gpsd_config.h' 570arm-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 571arm-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 572Creating 'gpsd.h' 573[...] 574chmod -w maskaudit.py 575chmod +x maskaudit.py 576rm -f gps_maskdump.c && /usr/bin/python maskaudit.py -c . > gps_maskdump.c && chmod a-w gps_maskdump.c 577arm-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 578[..] 579scons: done building targets. 580$ file gpsd 581gpsd: ELF 32-bit LSB executable, ARM, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.36, not stripped 582---- 583 584The author of this transcript notes: 585 586The sysroot option tells the compiler and linker to use libraries and 587headers from the given path as if they were placed at / prefix. During 588this build the option allows linking with target ncurses (with the option 589of having more packages at the --sysroot path) and including correct 590headers without specifying -I and -L options. 591 592In the options cache file gpsd is configured to install to 593/work/buildroot/output/staging/usr path, so gpsd clients could be 594compiled against libgps.so using /work/buildroot/output/staging as 595sysroot option. 596 597"arm-indigo-linux-gnueabi" as target means that 598arm-indigo-linux-gnueabi-gcc and related tools are available in PATH; 599your cross-compiler is likely to have a different target prefix. 600 601You may also find it useful to set manbuild=no. 602 603== Autostarting the daemon == 604 605The preferred way to start gpsd is on-demand by a hotplug script 606detecting USB device activations. Look at the gpsd.rules and 607gpsd.hotplug files to see how this is accomplished. Relevant 608productions in the build recipe are "udev-install" and 609"udev-uninstall"; relevant build options include "udevdir". 610 611If you for some reason need to start gpsd unconditionally at 612boot time (in particular, if you need to support RS232 devices) 613there's a model init.d script under packaging/deb and a systemd 614setup under systemd/. 615 616// end 617