RoadMap Installation

January 2009

= 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:

           + /etc/roadmap,
           + /usr/local/share/roadmap (preferred path),
           + /usr/share/roadmap
           + a site-specific directory chosen at compile time, and
           + ~/.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:

        + /usr/share/roadmap (installation defaults)
        + /usr/local/share/roadmap (local site defaults)
        + /etc/roadmap (local machine defaults)
        + ROADMAP_CONFIG_DIR, chosen at compile time
        + ~/.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:

           + ~/.roadmap/pixmaps,
           + ROADMAP_CONFIG_DIR/pixmaps, chosen at compile time,
           + /usr/local/share/pixmaps or
           + /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:

           + ~/.roadmap/maps/... (a.k.a. "&/maps") and its subdirectories,
           + ROADMAP_MAP_DIR, chosen at compile time,
           + /var/lib/roadmap/... (preferred path) and its subdirectories, and
           + /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:

     + Install the development libraries for GTK+ 1.2, GTK+ 2.0 or Qt.

     + 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.

     + Unpack RoadMap's tarball:

```
        tar xzvf <tarball>
```

     + 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

     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

     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

     Do not link roadmap with the expat library.  The side effect
     is that you cannot load or save trips or landmarks anymore.

     : AGG=NO

     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

     Compiles RoadMap in debug mode.  The PROFILE option also
     generates the necessary information and code for profiling.

     + 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.



