INSTALL

   1 Here are the steps for installing gpsd and verifying its performance:
   2
   3 0. gpsd has a core set of prerequisites that are required for any
   4 configuration of the package, and then additional features and tests
   5 have additional prerequisites.
   6
   7 Necessary components for any build:
   8
   9 C compiler              -> gpsd and client library are written in C
  10 Python                  -> some code is generated from python scripts
  11 Python GTK-2 binding    -> the main test client, xgps, needs this
  12
  13 The C code depends on one non-C99 feature: anonymous unions.  We could
  14 eliminate these, but the cost would be source-level interface breakage
  15 if we have to move structure members in and out of unions.
  16
  17 You will need Python 2.6 or 2.4+ & simplejson.  The Python code in
  18 GPSD is 2.4-compatible except that you need either the json library
  19 module from 2.6 or the functionally equivalent simplejson backport.
  20 Note that while Python is required to *build* GPSD (the build uses
  21 some code generators in Python), it is not required to run the service
  22 daemon.  In particular, you can cross-compile onto an embeddeed system
  23 without having to take Python with you.
  24
  25 Having the following optional components on your system will enable
  26 various additional capabilities and extensions:
  27
  28 C++ compiler           -> libgpsmm C++ wrapper for the library
  29 pthreads library       -> support for PPS timekeeping on serial GPSes
  30 DBUS                   -> gpsd will issue DBUS notifications
  31 ncurses                -> a test client and the GPS monitor depend on this
  32 libusb-1.0.x or later  -> better USB device discovery
  33 Qt + qmake             -> libQgpsmm depends on this
  34
  35 If you have libusb-1.0.0 or later, the GPSD build will autodetect
  36 this and use it to discover Garmin USB GPSes, rather than groveling
  37 through /proc/bus/usb/devices (which has been deprecated by the
  38 Linux kernel team).
  39
  40 For working with DBUS, you'll need the DBUS development
  41 headers and libraries installed.  Under Debian/Ubuntu these
  42 are the packages ibdbus-1-dev and libdbus-glib-1-dev.
  43
  44 For building from the source tree, or if you change the man page
  45 source, xslt and docbook xsl style files are used to generate nroff
  46 -man source from docbook xml.  The following packages are used in this
  47 process:
  48
  49 libxslt                -> xsltproc is used to build man pages from xml
  50 docbook-xsl            -> style file for xml to man translation
  51
  52 The build degrades gracefully in the absence of any of these. You should
  53 be able to tell from configure messages which extensions you will get.
  54
  55 Under Ubuntu and most other Debian-derived, an easy way to pick up
  56 the prerequisites is: "apt-get build-dep gpsd"
  57
  58 If you are going to modify the build, you will need these:
  59
  60 autoconf 2.61 or later
  61 automake 1.10 or later
  62 libtool 2.26 or later
  63 pkg-config
  64
  65 Once you have fetched the software prerequisites:
  66
  67 1. Start by making sure you can get data from your GPS, otherwise the later
  68 steps will be very frustrating.  In this command
  69
  70       stty -F /dev/ttyXXX ispeed 4800 && cat </dev/ttyXXX
  71
  72 replace ttyXXX with the filename of the port.  This will probably be
  73 either /dev/ttyUSB0 or /dev/ttyS0.  When you run this command, you
  74 should see text lines beginning with $ come to stdout (possibly after
  75 a short initial burst of binary garbage).  If you don't see this, you
  76 may have OS-level problems with your serial support, but more likely
  77 have the wrong device.  Look again.
  78
  79 2. Ensure that device permissions will enable gpsd to read from and
  80 write to GPS devices even after it drops root privileges.  If you are
  81 running Fedora Core or Ubuntu you can skip this step, as the stock
  82 configuration has the right properties.
  83
  84 gpsd requires two things: (1) that GPS devices have group read and
  85 write enabled, and (2) all of them are have the same group ID as a
  86 prototypical device, typically /dev/ttyS0 under Linux or /dev/tty00
  87 under *BSD. It does not actually matter what the owning group is,
  88 as gpsd will look this up on startup.  Alternatively, (3), you can
  89 set a fallback group with the enable-gpsd-group in case the prototype
  90 is not found: this should be the "dialout" group (or functional equivalent)
  91 that has write access to serial devices.
  92
  93 Before dropping privileges, gpsd will ensure that it has access to
  94 devices given to it on the command line by forcing their group read
  95 and write permissions on.
  96
  97 On a Linux with udev, check the files in /etc/udev/permissions.d to
  98 ensure that /dev/tty* devices are all created with the same group
  99 and with 0660 permissions.
 100
 101 When gpsd drops privileges, its default is to set uid to 'nobody' and
 102 group to the owning group of the prototype device (the configure
 103 option --enable-gpsd-user=foo will cause gpsd to change to 'foo'
 104 instead).
 105
 106 If your system has the Linux hotplug facility installed you can skip
 107 the permission-setting part; the hotplug scripts will force the
 108 permissions for you.  You still have to make sure all the tty devices
 109 are in the same group.
 110
 111 3. Install prerequisites
 112
 113 Under Debian and Ubuntu ou can get all the build prerequisites
 114 installed with "apt-get build-dep gpsd".
 115
 116 Note: if you are going to use the RTCM-104 support, you should compile
 117 with gcc4; if you don't have it installed as your default
 118 compiler, do this by specifying CC=gcc4 before the configure
 119 command.  The rtcm2.c file confuses the gcc-3.4.[23] optimizer
 120 at -O2 level, making it generate incorrect code.
 121
 122 4. Build gpsd from source (skip this step if you have installed GPSD
 123 from a binary package).  As usual, the sequence is:
 124
 125      ./configure && make
 126
 127 Mac OS X users may need to do "./configure --x-includes=/usr/X11R6/include"
 128
 129 5. Start gpsd.  You'll need to give it as an argument a path to
 130 a serial or USB port with a GPS attached to it.
 131
 132 6. Once gpsd is running, telnet to port 2947. You should see a
 133 greeting line that's a JSON object describing GPSD's version.
 134 Now plug in your GPS (or AIS receiver, or RTCM2 receiver).
 135
 136 7. Type '?WATCH={"enable":true,"json"};' to start raw and
 137 watcher modes.  You should see lines beginning with '{' that are
 138 JSON objects representing reports from your GPS; these are packet
 139 translations in GPSD protocol.
 140
 141 8. Start the xgps client.  Calling it with no arguments should do the right
 142 thing.  You should see a GUI panel with position/velocity-time information,
 143 and a satellite display.  The displays won't look very interesting until
 144 the GPS acquires satellite lock.
 145
 146 9. Now that you've verified that the code is working, "make install"
 147 will install it it in the system directories.  "make uninstall" will
 148 undo this.
 149
 150 (You won't need to "make install" if you installed from a binary package.)
 151
 152 10. To enable hotplugging of USB GPSes under Linux, do a 'make udev-install' or
 153 equivalent to put the appropriate udev rules and wrapper files in place.
 154
 155 11. Check out the list of supported hardware at
 156
 157    http://gpsd.berlios.de/hardware.html
 158
 159 If your GPS isn't on the list, please send us information to add a new
 160 line to the table.  Directions are included on that page.
 161
 162 We can also use updates of the latest version number known to work with
 163 hardware already supported.
 164
 165 12. Note for small embedded systems and those without threading.  It is
 166 possible to build gpsd without thread support if you configure with
 167 --disable-pps.  You'll lose support for updating the clock from PPS pulses.
 168
 169 13. Note for systems using DBUS: gpsd includes support for shipping fixes
 170 as DBUS notifications, but it is not compiled in by default.  Configure
 171 with the option "--enable-dbus" to get it working.
 172
 173 14. The distribution includes a PHP script that you can use to
 174 generate a PHP status page for your GPS.  You will need php and php-gd
 175 installed.  To install it, copy the file 'gpsd.php' to your HTTP
 176 document directory.  The first time it's invoked, it will generate a
 177 file called 'gpsd_config.inc' containing configuration information;
 178 edit to taste.  Note that for the Google Maps feature work you need
 179 to set a valid Google API key in your config file.
 180
 181 15. libQgpsmm is a Qt version of the libgps/libgpsmm pair. Thanks to
 182 the multi-platform approach of Qt, it allows the gpsd client library
 183 to be available on all the Qt supported platforms.  Please see
 184 http://qt.nokia.com/doc/4.6/supported-platforms.html for a status of
 185 Qt supported platforms as of version 4.6.
 186
 187 You can build libQgpsmm if you have qmake and Qt (specifically the
 188 (specifically QtCore and QtNetwork modules) version 4.5.3 or higher.
 189 You will also need a C++ compiler supported by Qt (tested on GCC
 190 4.4.0/mingw on Windows and GCC 4.1.2 on linux).
 191
 192 Building is done through a standard Qt .pro project file:
 193 - Go to the libQgpsmm subdirectory of gpsd and execute "qmake"
 194   to create the Makefiles
 195 - execute "make" to build the library
 196 - execute "make install" or equivalent to copy libgpsmm.h and the library
 197   to the appropriate location for your platform.
 198
 199 Specifically for linux: You can specify the installation prefix by
 200 running "qmake PREFIX=<installation_root>". Default value is
 201 "/usr/local".
 202
 203 Please refer to Qt's documentation at
 204 http://qt.nokia.com/doc/4.6/platform-specific.html for platform specific
 205 building documentation
 206
 207 16. There are regression tests to verify proper operation of gpsd, and
 208 it can be useful to run these to verify that all is well.  To run the
 209 regression tests, first build gpsd from sources, and then run "make
 210 check".  It is not necessary to install first, but you do need
 211 to have "." in your $PATH to run regressions uninstalled.  Python is
 212 required for regression tests.
 213
 214 17. If you installed from a .deb under Debian or a Debian-derived
 215 system, you may need to `dpkg-reconfigure -plow gpsd' to enable the
 216 hotplug magic ("Start gpsd automatically").
 217
 218 18. Note for people using gpsd as time source for ntpd: In case you're
 219 using dhcp3-client to configure your system, make sure you disable
 220 /etc/dhcp3/dhclient-exit-hooks.d/ntp as dhclient would restart
 221 ntpd with an automatically created ntp.conf otherwise - and gpsd
 222 would not be ablt to talk with ntpd anymore.