How to install Xastir

The easy way

Most Linux distributions and some other systems (e.g. FreeBSD) provide pre-built Xastir binaries in their package management systems.

Installing them is usually a one-step process. Consult your OS's package management system to see if you can install Xastir this way.

Example: Ubuntu Linux

On Ubuntu, installing Xastir this way could be as simple as choosing it from the package store gui, or issuing the command sudo apt install xastir

Why you shouldn't take the easy way out

These packages are usually only available for release versions of Xastir, and lag behind the source code here on Github by a lot.

Depending on how active the package maintainers are, Xastir packages in package management systems might not even be for a recent release, especially if the distro is a "Long Term Support" release; these LTS releases tend to be extremely conservative about package updates and often do not update package versions from upstream at all during the period that the OS release is supported unless it's a critical security fix.

On the other hand these days package maintainers have been a lot better at keeping on top of our releases and even contribute to the project in the form of pull requests. Even so, Xastir "power users" have traditionally chosen to compile Xastir themselves and eschew packaged binaries, because the development version (the one available here on Github) often provides timely bug fixes and new features in between formal releases. The team rarely releases more than once a year, and sometimes as infrequently as every two years (depending on how much work we've been doing on it).

A good report, updated often, of which version is currently in package management for a variety of systems can be found at https://repology.org/project/xastir/versions .

Finally, Linux packages invariably install Xastir using the "/usr" prefix, whereas the default prefix when you build it yourself is "/usr/local". This has impact on where configuration files and maps get placed, and how Xastir's defaults get set. If you later decide to track the bleeding edge of source code you can wind up having to clean up configuration files when you switch methods.

Installing Xastir yourself, from source, in a nutshell

General build process:

0. Install all system packages required and any optional packages
1. Get the Xastir source code
2. Bootstrap the source code to create the configure script
3. Create a build directory and run configure in it with any necessary options
4. Build Xastir
5. Install the code
6. Start using Xastir

The procedure for building Xastir from source is fairly generic, and the most difficult part is assuring that you have all dependent libraries.

Installing Xastir yourself, from source, in gory detail

Install all system packages required and any optional packages

Look here for any special notes that pertain to your operating system.

On system-specific build instructions

The system-specific build instructions at http://xastir.org/index.php/Installation_Notes often have the exact command you need to install all required and optional packages on that system in one fell swoop, so you would do well to look at those notes before proceeding with the rest of this section.

However, that web site is often down and those instructions are frequently unavailable. We're working on getting a concise set of system-specific instructions written on the GitHub wiki.

Absolutely mandatory packages

The packages you absolutely must have in order to build Xastir are:

• autoconf (version 2.60 or later)
• automake (version 1.16 or later)
• gcc and all of its development headers
• glibc and its development headers
• openmotif and its development headers
• the X11 window system and X development headers
• make
• git

If you don't have at least these, you won't be able to build Xastir at all, and if this is all you have you'll get the most limited version of Xastir possible.

About library and header packaging

On some operating systems (e.g. most Linux distributions) the libraries needed to run a program and the headers needed for compiling a program that uses them are in separate packages, and that's why we list "and its development headers" above. You should look at the system-specific build instructions at System Specific Install Notes for more detailed instructions on how exactly one goes about actually installing these packages if you are unfamiliar.

Some of these packages may already be installed on your system by default, or may be installed in clusters by a meta package such as "build-essential" on Ubuntu, which installs the gcc compiler and all the libraries and headers it needs to function.

Optional packages

Installing these optional packages enables additional features in Xastir. You need both the library and development packages for any of these packages for which both are available.

Package	What it does for you
gv and ghostscript	Enables map printing
libXpm	Enables creation of map snapshots for display and printing
GraphicsMagick	Enables access to many formats of map images
curl	Enables access to the web to download maps or other data
shapelib	Enables display of vector maps in ESRI Shapefile format (requires pcre2 as well)
pcre2	Enables control of how shapefile maps are displayed
libgeotiff	Enables display of raster maps in Geotiff format
ax25-apps, ax25-doc, ax25-tools, libax25	Enables Linux kernel mode AX.25 for sharing/access of KISS TNC devices
festival	Enables text-to-speech options
Berkeley DB version 5 or 18.1	Enables caching of some online map imagery
cJSON	Enables on-line address lookup with Nominatim (also requires curl)
GPSMan and gpsmanshp	Permits downloading of GPS tracks from handheld units

Links in the list above are to the project pages for those libraries

The links above are to the main project pages for each library we list. These are useful to read about the project and what it does, or to obtain source code for building the libraries yourself.

It is now extremely rare for you to have to build any of these libraries yourself, as most operating systems just have them prebuilt in their package management system (albeit often with slight variations in the names of the package that can make them a chore to locate --- we have tried to help where we can with our System Specific Install Notes collection).

That list only includes packages we actually use directly

The list above are the libraries Xastir uses itself. Some of these libraries have their own dependencies, and we have not included those here. Most package management systems automatically pull in all the dependencies of that package when you install them, and that is the case for all of the systems for which we've got system-specific install instructions so far.

Should some system have a package management system that doesn't pull in all the packages automatically we need to document that in a system-specific install note rather than in this main list.

Alternatives to consider

In some cases, there are alternatives that can provide the same features:

• wget can be used instead of curl, but only for map download. Address lookup actually requires curl, not wget.
• ImageMagick 6 (NOT ImageMagick 7) can be used instead of GraphicsMagick, but GraphicsMagick is preferred
• The older PCRE library (sometimes called PCRE3, even though the current version is PCRE2) can be used, but is long past its end of life. PCRE2 is preferred.

Some of the packages listed above depend on other packages themselves, but the norm of modern package management systems is to install all the dependencies when the main package is installed.

Get the Xastir source code

There are two ways to get Xastir source code:

1. Get one of the source release "tarballs" from Github at https://github.com/Xastir/Xastir/releases and explode it. (Replace X.Y.Z with the release number below)

Unpacking an Xastir tarball

  mkdir -p ~/src/XASTIR
  cp Xastir-Release-X.Y.Z.tar.gz ~/src/XASTIR
  cd ~/src/XASTIR
  tar xzvf Xastir-Release-X.Y.Z.tar.gz

This gets you ONLY the source code for one single release of Xastir. The commands above will unpack the source code into the directory ~/src/XASTIR/Xastir-Release-X.Y.Z

2. Alternatively, use git to clone the Xastir repository

Git clone commands

  mkdir -p ~/src/XASTIR
  cd ~/src/XASTIR
  git  clone https://github.com/Xastir/Xastir.git

This will create a clone of the Xastir git repository in an "Xastir" subdirectory of the current directory. The Xastir source code will be in ~/src/XASTIR/Xastir

All done! You now have the latest development sources on your computer. Not only that, you have a complete copy of the entire project history and access to all prior releases.

Either way, by following one of these commands you will have a directory of Xastir source code under your ~/src directory.

Why do you have an extra XASTIR in your examples of directory names?

I chose ~/src/XASTIR as the directory into which you unpack Xastir's source code (or clone the repo) because I recommend creating a build directory in a directory parallel to the source code, and this keeps everything grouped together. There are also other Xastir repositories you might want to clone later, and having a top-level directory makes it easier to keep them all together.

You can choose to do otherwise if you know what you're doing. My recommendations are designed to keep everything in one place so it's easier to keep straight. And while I hope you don't do so, it also makes it easier to delete it all at once if you decide not to keep using Xastir.

Bootstrap the source code to create the configure script

The Xastir source code does not contain the "configure" script necessary to build Xastir. The directory must always be "bootstrapped" before proceeding.

Bootstrapping code from a tarball

If you are working from a tarball of source code and followed the path suggestions above:

      cd ~/src/XASTIR/Xastir-Release-X.Y.Z
      autoreconf -i

Bootstrapping a git clone

If you grabbed a clone from git and followed the recommendations above:

      cd ~/src/XASTIR/Xastir
      autoreconf -i

Using the "bootstrap.sh" script instead

Older install instructions told you to use the "bootstrap.sh" script. This does the same thing as "autoreconf -i", and is the old-fashioned way of getting configure created. This script still works, and you can run it from the directory where your Xastir source code by typing:

./bootstrap.sh

Successful run of the bootstrap.sh script will show the following output:

    5) Removing autom4te.cache directory...
    4) Running aclocal...
    3) Running autoheader...
    2) Running autoconf...
    1) Running automake...
   Bootstrap complete.

If you don't see "Bootstrap complete" at the end, it didn't work and the error messages output should guide you to the source of the problem (usually this only fails when you have not installed all the necessary autoconf/automake tools).

This bootstrap procedure creates the "configure" script you need in the next step.

Create a build directory and run configure in it with any necessary options

In order to build Xastir, the configure script you just created must be run. Configure tries to work out what you've got installed and whether it can find all of the pieces it needs. In many cases on Linux you can get away with running it with no options at all and it'll find everything it needs. In some cases you might need to provide it with hints about where to find things like libraries and headers. And there are a number of configure options that allow you to control whether to skip some features you don't want, even if you've got all the pieces installed that would normally enable them.

Out-of-source builds

We strongly recommend doing configuration and building of Xastir in a "build directory" rather than right in the same directory as the source code. The reason for this is that doing so leaves the source code directory completely pristine, and only creates new stuff in the build directory. This makes it much easier to clean up and start over (you can simply delete the build directory), and also makes it easier to spot when something has accidentally been changed in the source tree.

The examples below all have the same basic steps: create a new directory and move into it, then run configure in it. The only difference between them is whether you have to give any arguments to configure.

The simplest example possible

Xastir can be built with the bare minumum of external libraries. Such a build can function as an APRS client, but with minimal map support and no optional features. We do not recommend this build unless you absolutely need the bare bones.

The absolute bare minimum of external libraries was listed above. You cannot build Xastir at all without at least those.

A bare-bones Xastir install

Create a new directory in which to build, and run configure in it:

mkdir ~/MyXastirBuildDirectory
cd ~/MyXastirBuildDirectory
~/src/XASTIR/Xastir/configure

Here we're assuming you got Xastir source code from git and already bootstrapped, and the bootstrap process showed no errors.

This may be all you need, and if all you have done was install the minimum required libraries you should see configure exit with this message:

xastir X.Y.Z has been configured to use the following
options and external libraries:

MINIMUM OPTIONS:
  ShapeLib (Vector maps) .................... : no

RECOMMENDED OPTIONS:
  Xpm / Snapshots ........................... : no
  GraphicsMagick/ImageMagick (Raster maps) .. : no
  pcre (Shapefile customization) ............ : no
  Berkeley DB map caching-Raster map speedups : no
  internet map retrieval .................... : no
  Nominatim Geocoding ....................... : no

FOR ADDITIONAL FEATURES:
  AX25 (Linux Kernel I/O Drivers) ........... : no
  libproj (used by libgeotiff) .............. : no
  GeoTiff (Georeferenced TIFF files) ........ : no
  Festival (Text-to-speech) ................. : no
  GPSMan/gpsmanshp (GPS downloads) .......... : no

xastir will be installed in /usr/local/bin.
Type 'make' to build Xastir (Use 'gmake' instead on some systems).

If you've installed optional libraries and they were properly located by configure, then some of these "no" lines will have "yes" instead.

Slightly more involved examples

Most users will not want the bare minimum install of Xastir, as it is quite limited in what types of maps it can display and what features it has. Look over the list of optional libraries above, and add them to your system with your package management system.

For the most part, Xastir's configure process will automatically find any optional libraries you've installed, using exactly the same procedure as the "bare bones build" above:

Commands for configuring Xastir

mkdir ~/MyXastirBuildDirectory
cd ~/MyXastirBuildDirectory
~/src/XASTIR/Xastir/configure

However, some systems are set up to put packages in odd places where configure can't find them, and it needs some hints.

On package installation directories by package management systems

Some systems like to install the headers for "libgeotif" into "/usr/include/geotiff" instead of directly into "/usr/include". If that is the case, configure simply won't find them. In that case, one has to tell configure to tell the C preprocessor to add an additional place to look for header files. So on those systems one would have to do:

cd ~/MyXastirBuildDirectory
~/src/XASTIR/Xastir/configure CPPFLAGS="-I/usr/include/geotiff"

On most Linux systems, that's the extent of the complexity you might need.

When lots of stuff is in weird places

Similarly, on systems like FreeBSD, third-party packages do not install anything into "/usr/include" or "/usr/lib" but rather into "/usr/local/lib" or "/usr/local/include". In that case, you'd have to tell the C preprocessor and linker to look in extra places, too:

cd ~/MyXastirBuildDirectory
~/src/XASTIR/Xastir/configure CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib"

Note that systems like Macs often require add-on package managers like "homebrew" or "macports" which love to put headers and libraries in strange places where the C compiler and linker don't look by default. The techniques above apply there, too. You can stack up options, too, such as:

cd ~/MyXastirBuildDirectory
~/src/XASTIR/Xastir/configure CPPFLAGS="-I/usr/local/include -I/some/weird/place/include" LDFLAGS="-L/usr/local/lib -L/some/weird/place/lib"

When things get more complicated

On my own system, the Berkeley DB libraries are in a weird place, and GraphicsMagick will not work with the default system C compiler at all. So in my case, I have to tell configure exactly where to look for those libraries, and which compiler to use. I have to run configure as:

cd ~/MyXastirBuildDirectory
../Xastir/configure --with-bdb-incdir=/usr/local/include/db18 --with-bdb-libdir=/usr/local/lib CFLAGS="-O2 -g" CC=gcc13 CXX=g++13

Here, I've had to specify where the Berkeley headers are, where the libraries live, and what C and C++ compiler to use. Since db18.1 is the most recent version installed configure will find and use it by default.

Forcing Xastir to use the older of multiple installed versions of DB

It is critically important when building with Berkeley DB that the headers in the bdb-incdir are for the same version of Berkeley DB as the most recent version present in the library directory. If one has both Berkeley DB 5 and Berkeley DB 18.1 installed, Xastir will use the most recent version present, even if one has told it to use an older set of headers.

cd ~/MyXastirBuildDirectory
~/src/XASTIR/Xastir/configure --with-bdb-incdir=/usr/local/include/db5 --with-bdb-libdir=/usr/local/lib CFLAGS="-O2 -g" CC=gcc13 CXX=g++13 LIBS="-ldb-5.3"

The example above forces Xastir to use the older library even if a newer one is present, because it is also using the older header files per the setting of "--with-bdb-incdir".

Here, I'm telling it to look in special places when looking for Berkeley DB headers and libraries, to use a specific (non-default) compiler, to use specific compiler options (CFLAGS), and to use the Berkeley DB library "libdb-5.3" (LIBS) irrespective of any other that might be found on the system.

If you've installed ALL of the optional libraries and Xastir's configure has found them all, its output will look like this:

xastir X.Y.Z has been configured to use the following
options and external libraries:

MINIMUM OPTIONS:
  ShapeLib (Vector maps) .................... : yes

RECOMMENDED OPTIONS:
  Xpm / Snapshots ........................... : yes
  GraphicsMagick/ImageMagick (Raster maps) .. : yes (GraphicsMagick)
  pcre (Shapefile customization) ............ : yes (PCRE2)
  Berkeley DB map caching-Raster map speedups : yes
  internet map retrieval .................... : yes (libcurl)
  Nominatim Geocoding ....................... : yes

FOR ADDITIONAL FEATURES:
  AX25 (Linux Kernel I/O Drivers) ........... : yes
  libproj (used by libgeotiff) .............. : yes
  GeoTiff (Georeferenced TIFF files) ........ : yes
  Festival (Text-to-speech) ................. : yes
  GPSMan/gpsmanshp (GPS downloads) .......... : yes

xastir will be installed in /usr/local/bin.
Type 'make' to build Xastir (Use 'gmake' instead on some systems).

If you know you've installed some libraries that should have been found and the result is a "no" somewhere in that display, then go back and see the sections on what to do when the system has installed them in funny places.

One final note: every successful configure of Xastir, whether for the minimal or maximal build, ends with a big block of results like the one above. If you don't see a block of text emitted by configure that looks like this , then configure failed in some way. None of the remaining steps will work if configure failed. Stop here and fix the problem.

I don't see that block. What's wrong? Why did configure fail?

The usual reason is that one of the absolutely mandatory libraries wasn't found and configure aborted. Read the output to see what error it thought it had, and use the file config.log that gets produced to dig in detail for what exactly went wrong. Fix that and try to configure again.

Hints for reading config.log

The answer will be somewhere close to the end of that file, so start reading it from the end. Reading it from the top will be confusing, because in the process of doing all of its work there will be many things reported that look confusingly similar to errors, but are just how configure works.

When it aborts due to some missing feature, it'll dump out the actual error it received and then follow it with a big block of variable assignments. So the last error messages in config.log are the ones that will point to the real problem.

Build Xastir

Once configure has completed, has announced that it has really succeeded and that you can "make" the code, and all the options it shows as enabled are in fact the options you wanted enabled, then just build it (I'm assuming you're still in your build directory):

make

You should see a bunch of status updates about what it's doing and what file is being compiled, and when it's all done you should see no statement from "make" that it has aborted due to errors (you may see a handful of warnings, but you can safely ignore those).

Once it's all done you can make a quick test to make sure a valid executable was created by typing:

./src/xastir -V

which should respond with a version number, such as:

Xastir V2.2.3 (Release-2.2.2-210-geac1adeb)

This particular version number indicates that we're building from a git clone, that it's Version 2.2.3, and that 210 code commits have happened since the prior release 2.2.2, and that the current git commit reference is eac1adeb. You can ignore all that if you don't know what it means. The important thing that it produced a version number and not an error message.

That's it, you've built Xastir with the options that configure said you enabled.

Install the code

You've built Xastir, but it still lives in your home directory somewhere. If you want it to be generally accessible on your system, you need to install it. You must be root to do this.

cd ~/MyXastirBuildDirectory
sudo make install

Xastir will by default have installed itself into /usr/local/bin by this process (and its support files will generally have been installed into /usr/local/share/xastir).

Important

If you're running on a Linux system and have enabled AX.25 networking, you also need to do the following command to give the binary access to kernel AX.25 ports:

sudo chmod 4755 /usr/local/bin/xastir

Start using Xastir

You've got Xastir installed. Now you need to define interfaces and start using it. See Operating Quickstart for the quick-and-dirty introduction to get started, and Operating for detailed usage instructions.