1 Here are the steps for installing gpsd and verifying its performance:
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.
7 Necessary components for any build:
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
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.
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.
25 Having the following optional components on your system will enable
26 various additional capabilities and extensions:
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
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
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.
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
49 libxslt -> xsltproc is used to build man pages from xml
50 docbook-xsl -> style file for xml to man translation
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.
55 Under Ubuntu and most other Debian-derived, an easy way to pick up
56 the prerequisites is: "apt-get build-dep gpsd"
58 If you are going to modify the build, you will need these:
60 autoconf 2.61 or later
61 automake 1.10 or later
65 Once you have fetched the software prerequisites:
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
70 stty -F /dev/ttyXXX ispeed 4800 && cat </dev/ttyXXX
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.
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.
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.
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.
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.
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'
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.
111 3. Install prerequisites
113 Under Debian and Ubuntu ou can get all the build prerequisites
114 installed with "apt-get build-dep gpsd".
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.
122 4. Build gpsd from source (skip this step if you have installed GPSD
123 from a binary package). As usual, the sequence is:
127 Mac OS X users may need to do "./configure --x-includes=/usr/X11R6/include"
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.
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).
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.
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.
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
150 (You won't need to "make install" if you installed from a binary package.)
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.
155 11. Check out the list of supported hardware at
157 http://gpsd.berlios.de/hardware.html
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.
162 We can also use updates of the latest version number known to work with
163 hardware already supported.
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.
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.
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.
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.
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).
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.
199 Specifically for linux: You can specify the installation prefix by
200 running "qmake PREFIX=<installation_root>". Default value is
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
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.
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").
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.