RoadMap Installation

January 2009

Full Installation Guide

Full Installation Guide

DEPENDENCIES
- GPS and gpsd
  RoadMap communicates with a GPS receiver using the NMEA 0183 protocol. RoadMap has been tested with a Garmin 38. The GPS receiver must be configured with the datum set to either NAD83 or WGS 84.
  RoadMap can connect directly to the GPS receiver using a serial port (or an emulated serial port in the case of USB receivers), but RoadMap usually communicates with the GPS receiver through gpsd, a GPS communication daemon for UNIX. Going through the intermediate daemon insulates RoadMap from some of the GPS configuration, and lets more than one program use the GPS device at once. It also allows RoadMap to use a GPS device which is connected to a different computer. The most typical setup is to have gpsd on the same computer, in which case the GPS source should be set as "gpsd://localhost".
  http://gpsd.berlios.de
  gpsd is not required when building RoadMap, and RoadMap can run without gpsd as a static map viewer or address finder.
- Desktop toolkit
  RoadMap usually uses one flavor or another of GTK or QT for its user interface. One of these toolkits must be installed. RoadMap can be built for QT/QPE, but the RoadMap makefile for QT must be modified.
- Voice support
  RoadMap optionally uses flite (festival lite) to generate voice messages. See the section "VOICE INTERFACE" for more information.
- Optional libraries
  RoadMap uses the expat library to load GPX trip and landmark files. RoadMap can be built without expat, with some loss of functionality, by changing config.mk to say: EXPAT = NO. (On Debian or Ubuntu linux systems, use "apt-get install libexpat1-dev" to install the expat library.)
  Likewise, RoadMap can sometimes use the agg library to render anti- aliased maps and street label text. If you don't have agg, RoadMap will only create horizontal labels. (Angled labels are available using a relatively crude built-in font. To use agg, you need to change the default "AGG = NO" in config.mk to choose one of the options listed there. Unfortunately those options ("rgb565", "rgba32", "bgra32", "rgb24", "bgr24") cannot currently be auto-detected, so there may be some trial-and-error involved to get the setting right. See the comments in config.mk for more tips. RoadMap requires version 2.4 or later of the agg library -- 2.3 is incompatible. If your linux distribution includes 2.3, make sure that if you install 2.4 as well, that RoadMap finds both headers and libraries from 2.4. Note: currently (as of August, 2006) the agg support is only available if you're using the GTK2 build of roadmap. (On Debian or Ubuntu linux systems, use "apt-get install libagg-dev" to install the agg library.)
  The "buildmap" program uses the shapelib library to decode the "shapefile" format). Currently, most of the maps used by RoadMap are not in that format, but some are: Canadian provinces, state boundaries, and the Digital Charts of the World. If only US maps from the census bureau are used, or if only pre-built maps are used, then there is no need for shapelib: set SHAPEFILES = NO in config.mk. (On Debian or Ubuntu linux systems, use "apt-get install libshp-dev" to install the shapefile library.)
- Miscellaneous
  RoadMap uses "aptconvert" to format the documentation (see previous section) into HTML format. Since this is an uncommon tool, a pre-converted copy of usermanual.html is provided in the RoadMap tarball.
  RoadMap can use the "convert" program from the ImageMagick package to generate the PNG versions of some of the icons on its toolbar. Pre-built copies of these PNG files are distributed, so ImageMagick is optional, and in any case is only required for building RoadMap -- it is not necessary when running RoadMap.

DIRECTORIES
RoadMap is to be installed in a few different directories, where each directory contains a specific type of file: commands, configuration files, icons and maps.
Before you install RoadMap, you must choose what installation directories to use for these files. Some of these choices are already made for you when you install a pre-built package, or are assigned default values in the makefiles (source package). This section describes the whole thing, regardless of how you install RoadMap. It also provides some information about the standard locations in the most common cases.
RoadMap supports searching through lists of directories, instead of just a single location, for each type of file.
One reason for RoadMap to support a list of directories is to define a default system-wide configuration, and at the same time to allow a specific user to install their own setup. Another reason (for the map files on a PDA) is to let the users choose the type of hardware storage that is most convenient.
Directory pathnames in most RoadMap path lists can include several "shortcut" characters:
- If a path begins with '~', then the rest of the path is relative to the users home directory (i.e, $HOME). This is similar to the behavior of many UNIX shell programs.
- If a path begins with '&', then the rest of the path is relative to the RoadMap "user configuration" directory, which is $HOME/.roadmap.
- If a list of pathnames includes a path ending with "/..." then that path, plus the entire sub-tree of (unhidden) directories beneath it are added to the list of pathnames. So if Map.Path is set with:
```
          Map.Path: /etc/roadmap,&/maps/...
```
  and ~/.roadmap/maps/moremaps/foo and ~/.roadmap/maps/.secret/bar are both actual directories, then the final list of paths used when looking for maps will be:
  - /etc/roadmap
  - $HOME/.roadmap/maps
  - $HOME/.roadmap/maps/moremaps
  - $HOME/.roadmap/maps/moremaps/foo
  /etc/roadmap will not be searched for subdirectories, because it was not specified with a trailing "/...", and nothing below ~/.roadmap/maps/.secret will be searched, because ".secret" is "hidden" in the traditional UNIX sense. The subdirectory search will follow symlinks.
  This feature can be used, for instance, to help keep maps of a single region together, by letting them be more easily put into separate directories. If a subdirectory may come and go while RoadMap is running, e.g. if it's on removeable media, then it should be named specifically in the preferences -- the complete list of subdirectories is only enumerated at startup.
EXECUTABLE FILES
The RoadMap programs should be installed in a standard executable directory. This is an easy one: the only requirement is that this directory must appear in the PATH variable (either you choose an existing directory or you add your own).
CONFIGURATION FILES
RoadMap comes with some critical configuration files (files sprites, preferences, etc..). RoadMap can find these files in a few different places, but the list cannot be changed in the user preferences since it is used to load the preferences themselves. The list can, however, be changed using the "--config=..." commandline option.
On most UNIX systems this list is:
1. /etc/roadmap,
2. /usr/local/share/roadmap (preferred path),
3. /usr/share/roadmap
4. a site-specific directory chosen at compile time, and
5. ~/.roadmap (the "user configuration" directory, which can be referred to as '&' in other path references). The specific value of the path to the "user configuration" directory is configurable, using the General.UserPath setting. The "user configuration" directory can be changed using the "--userpath=..." commandline option.
These directories are searched sequentially: any configuration item found in one directory overrides all the same items found in the directories listed before. In other words, the configuration is loaded in the following order:
1. /usr/share/roadmap (installation defaults)
2. /usr/local/share/roadmap (local site defaults)
3. /etc/roadmap (local machine defaults)
4. ROADMAP_CONFIG_DIR, chosen at compile time
5. ~/.roadmap (current user configuration)
The directory ~/.roadmap contains the user configuration: any changes the user makes while running RoadMap are saved here. The items in the user configuration take precedence over the "default" configuration defined in the "shared" directories. The user configuration directory can be referred to with the shorthand '&' in other parts of the roadmap config.
The user directory ~/.roadmap usually has two subdirectories: "trips" and "maps". "Usually", because while the directory ~/.roadmap/trips is used as the default location for the trip files, it can be changed with the General.TripsPath setting. Note that trip files can be stored anywhere, not just in that directory -- they're just more convenient for selection when stored there..
The directory ~/.roadmap/maps contains map files specific for this user. (As a general rule, users should probably share maps, since they can take a lot of space.) This directory might be used when maps are downloaded on the fly, as shared maps might not be writeable by all users.
These user configuration directories are created if they do not exist.
ICON FILES
RoadMap (the GTK version, at least) needs some icons. These icons must be placed in the operating system's standard locations. On UNIX, this usually means:
1. ~/.roadmap/pixmaps,
2. ROADMAP_CONFIG_DIR/pixmaps, chosen at compile time,
3. /usr/local/share/pixmaps or
4. /usr/share/pixmaps.
This list can be changed using the General.IconPath setting.
MAP FILES
RoadMap needs some map files to serve any useful purpose.
The location for these map files can be redefined in the user preferences (item Map.Path). The maps are a problem of their own, since they may require a huge space (up to 1.8G Bytes for the full set). It is recommended that maps be shared between users. Sharing across a network would probably be quite inefficient. In addition, care must be taken since the map format may vary between systems of different architectures. (Technically speaking, the maps contain endian-specific data.)
Maps can be located in any directory mentioned in the Map.Path preferences setting. The index file usdir.rdm must also be in one of those directories.
RoadMap will only consult a single usdir.rdm file at a time. The first usdir.rdm index file discovered by RoadMap must index any and all maps you might wish to view. This means that if you've built a subset of the maps, and a corresponding usdir.rdm file (using "buildus"), then when you build more maps, you can't create and install a second usdir.rdm file and expect RoadMap to use them both. A new usdir.rdm must be built which indexes all of the maps.
RoadMap will only read the index file once, at startup, even if a newer version becomes available. In contrast, new map files can be added to the Map.Path directories, and RoadMap will find them as needed. This means that maps kept on removeable storage devices can be used fairly easily. [ The one caveat when introducing replacement maps is that RoadMap will only try and find a map when it really needs to. RoadMap will keep a number of maps open, for easy access -- the number is controlled by "Map.Cache". You may have to visit that many other maps before RoadMap will need to reopen a map file which you've visited before but subsequently replaced. ]
(The map search paths referred to below may be changed using the "--maps=..." commandline option.)
By default, RoadMap is built to search for the following directories on most UNIX systems:
1. ~/.roadmap/maps/... (a.k.a. "&/maps") and its subdirectories,
2. ROADMAP_MAP_DIR, chosen at compile time,
3. /var/lib/roadmap/... (preferred path) and its subdirectories, and
4. /usr/lib/roadmap/... and its subdirectories.
(Note that releases prior to 1.1.0 did not search subdirectories.)
RoadMap also searches in /usr/local/share/roadmap and /usr/share/roadmap, but this is in violation of the FHS filesystem standard, since these maps are not architecture-independent.
The architecture-dependent nature of the map files is not an issue with a PDA, as these machines tend to be used standalone and not to rely on network access.

DOWNLOADING ROADMAP AND MAPS
RoadMap can be downloaded from the RoadMap web site:
http://roadmap.sourceforge.net/download.html
Previously, RoadMap came either as a set of sources, or as a set of binary files. This is no longer the case -- it is not hard to build, and there are choices to be made when building, so the source tarball is all that is currently available. (Specific systems or software distributions may offer pre-built packages.)
Because installing a full set of maps can take some time (and space!), a quick way to get a feel for RoadMap is to download and install the the "demo" tar file which contains outlines of the US state boundaries, the detailed street map of San Francisco, and a minimal directory file which will let RoadMap use them.
http://roadmap.digitalomaha.net/maps/demo_maps.tar.gz
The complete set of maps, along with the complete index file that describes them, is available here:
http://roadmap.sourceforge.net/maps.html
The full RoadMap index file (usdir.rdm) must be downloaded to use any but the demo maps -- RoadMap will not work without it.
http://roadmap.digitalomaha.net/maps/usdir.rdm.tar.gz
Please refrain from downloading all the US states at once, as the map files are huge and the bandwidth is expensive.
Installing the maps in one of the default directories (see the previous section) is recommended, but you can install them anywhere, assuming you set Map.Path accordingly in the RoadMap preferences.

INSTALLING FROM THE SOURCE TARBALL (UNIX)
To build RoadMap from the source distribution:
1. Install the development libraries for GTK+ 1.2, GTK+ 2.0 or Qt.
2. Install the shapelib and expat development libraries. Shapelib is required for building maps from some data sources (though not the US Tiger data). The "expat" library is optional, except that you won't be able to save or restore route, waypoint, or track information.
3. Unpack RoadMap's tarball:
```
          tar xzvf <tarball>
```
4. Edit the config.mk file found in the src directory, and choose one of GTK, GTK2, QT, or QT4, along with other build options, described in the comments of that file.
  Simply typing "make" will build the default selection in config.mk. (GNU make is required.)
  The complete list of options for building RoadMap is as follow. These can all be modified by editing config.mk.
  DESKTOP=GTK2|GPE|GTK|QT|QPE|QT4|QPE4|WINCE
5. Compiles RoadMap for a specific GUI environment. The GPE environment is a PDA variant of GTK2 and the QPE environment is a PDA variant of QT. (WINCE will attempt to use the arm-wince-mingw32ce cross-compiler to build RoadMap for the Windows CE environment.)
  SHAPEFILES=NO
6. Do not link buildmap with the shapelib. The side effect of this option is that some map sources cannot be converted to RoadMap files anymore. These include the Digital Charts of the World, the Canadian RNF road maps, and the US State boundary outlines. This option should only be used when the shapelib library is not available.
  EXPAT=NO
7. Do not link roadmap with the expat library. The side effect is that you cannot load or save trips or landmarks anymore.
  AGG=NO
8. Do not try to link roadmap with the agg library. This optional library, currently supported for the GTK2 and Win32 desktops, can give much prettier (anti-aliased) lines and text.
  MODE=DEBUG|PROFILE
9. Compiles RoadMap in debug mode. The PROFILE option also generates the necessary information and code for profiling.
10. run make to install roadmap:
```
          make install
```

A NOTE ABOUT THE ROADMAP ICONS
The RoadMap toolbar uses road signs as icons. These icons come with the application (in directory src/icons). The icon source set is made of a mix of PNG and XPM files. The final icon files must all be PNG.
A make script builds all the necessary files using the ImageMagick package. The icon files are built (or installed) when building (or installing) RoadMap.
The PNG icon files must be installed in one of the following directories (the order below reflects the search order):
```
          ~/.roadmap/pixmaps
          /usr/local/share/pixmaps
          /usr/share/pixmaps
```

TROUBLESHOOTING THE INSTALLATION
This section describes the most common problems encountered when installing RoadMap:
- When running "make build" a compiler error message appears, complaining that the file shapefil.h cannot be found. This typically happens if the shapelib library was not installed. The shapelib library is only used to create some map formats -- neither the TIGER maps nor the OpenStreetMap maps require shapefile support. It is possible to build RoadMap without the shapelib, using the option "SHAPEFILES=NO" in config.mk.
- After RoadMap has been installed, the display only shows the message "No map available" or a blank screen. RoadMap must be provided with a position before it can show something meaningful. It is recommended to enter a known address to setup a position. Another way to feed a position is to install a GPS device RoadMap can talk to.
- The display shows no street; lakes, parks, airport and hospitals appear as block areas. This is typical of a missing "class" file. This file, usuall "default/All", must be located in the RoadMap configuration directory. It is likely the "make install" step was not performed.
- The display is all black. RoadMap seems to find the map files and one can select streets on the screen, but it seems everything is drawn black on black. Be sure all of your configuration files are up to date, and that none are being "shadowed" by older files in your ~/.roadmap directory. This may also happen on a QPE-based PDA: this may be a problem with QPE not defining color names. Try redefining all colors in schema using the RGB syntax ('#' followed by an hexadecimal RGB value).
- Waypoints, the compass and the vehicle's location all appear as small black squares. This is typical of a missing "sprites" file. The "sprite" file must be located in one of the RoadMap configuration directories. It is likely the "make install" step was not performed.
- If things do not go any better, start roadmap with the --debug option and check what roadmap tells you it is doing.