NOTE: This installation note is a work in progress --- I did in fact build Xastir using the steps below, but did it on a system that had already had XCode, XQuartz, and Homebrew installed for other reasons. For this reason, even though I tried to be careful here, it may have an incomplete list of packages required in the "brew install" stage simply because I already had them installed when I tried it. If you follow these guidelines and find that configure refuses to proceed because of some missing library, please let me know on the Xastir mailing list, and I'll figure out what I missed.
This article describes the process I (KM5VY) used to install Xastir on an OS X El Capitan system using the Homebrew package manager. All of the instructions on this page should be carried out inside a terminal window, which is found under the "Go->Utilities" menu in the Finder.
Contents
Preliminary steps
Please perform the following steps before proceeding to the meat of this article. These steps need only be performed once on your machine.
Install XCode command line tools
Install the XCode command line tools using the command
xcode-select --install
You may, if you like, also install the full XCode package, but you won't need any of that stuff to follow this install note, so I won't mention it further.
Install Homebrew
Before continuing with the steps on this page, install homebrew according to the directions on its web site:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Install the XQuartz package
Xastir is based on the X Window System (X11, sometimes incorrectly referred to as "X Windows"). OS X does not provide this window system by default, so you must install a special package to provide it. This package is called XQuartz, and you must install it according to the instructions on its web site. This package is provided as a "dmg" image and installs like any other OS X application.
Overview
As with all operating systems, installing Xastir on OS X boils down to a few basic steps:
- Install all the packages Xastir needs
- Get the Xastir source code
- Configure the build
- Build the code
- Install the code
Install all the packages Xastir needs
Xastir requires a C compiler and a slew of libraries. To install all of them at once, issue the following command in a terminal window:
brew install gcc openmotif graphicsmagick pcre shapelib libgeotiff proj curl berkeley-db@4 git autoconf automake
Some of these packages may depend on other packages, but homebrew will automatically resolve all interdependencies.
Note: in the command line above we are explicitly asking for a version of Berkeley DB (needed for map caching) in the 4.X range. That is because at the time of this writing Xastir's configure script (and maybe the code itself) is set up to use only versions of Berkeley DB in the 4.x range and 5.x range up to 5.3. Homebrew's default version of BDB is in the 6.x range, and will not work with Xastir yet.
Get the Xastir source code
There are two ways to get the Xastir source code: Git and GitHub releases. We highly advise you to use Git, because it enables you to keep your Xastir installation current in between releases.
Getting the source code via Git
mkdir -p ~/src cd ~/src git clone https://github.com/Xastir/Xastir.git
Your directory ~/src/Xastir now contains a complete copy of the Xastir repository, including all the history of the project, and a (hidden) directory of information that lets git work.
Your final step here is to "bootstrap" Xastir:
cd ~/src/Xastir ./bootstrap.sh
Getting the source code from a release tarball
Some users prefer only to build Xastir from "officially" released "tar" files. We discourage this, because the project only releases these files infrequently, and the files simply contain snapshots of the git repository. However, if you insist, this is how you do it:
- Open a web browser to the Latest Xastir Release page.
- Download the latest release by clicking the ".tar.gz" link next to the "Source Code" text. We will assume here that this file is saved in your ~/Downloads directory, and that the current release is "X.Y.Z" in the text below --- you will have to customize the commands below to match where you saved the file and which release you downloaded. The current release at the time of this writing was "2.1.0".
- Unpack your new tar file:
mkdir -p ~/src tar xzf ~/Downloads/Xastir-Release-X.Y.Z.tar.gz cd ~/src/Xastir-Release-X.Y.ZUnlike the code you get from Git, these tarball directories do not require bootstrapping.
Configure the build
If you've been following all the steps up until now, no matter what path you've chosen your current working directory is the directory where the Xastir source code lives, and which I'll refer to as "the top of the source tree." You will now create a "build directory" and run the configure script for Xastir, the first step in building the code.
mkdir -p build cd build ../configure CPPFLAGS="-I/usr/local/opt/berkeley-db@4/include" LDFLAGS="-L/usr/local/opt/berkeley-db@4/lib"
Note the CPPFLAGS and LDFLAGS specified here. If you leave those off or get them wrong, Xastir's configure script will not be able to find the Berkeley DB 4.x libraries and headers, and you will not have online map caching available. This is an optimization that allows you to use online map sources without having to download the same maps over and over again --- local copies are saved to your system to be used when the same map is needed again later, or when your network is down.
Configure will work for a while as it tests your system's readiness to build Xastir. When it's all done, you should see this:
xastir 2.1.0 has been configured to use the following options and external libraries: MINIMUM OPTIONS: ShapeLib (Vector maps) ................. : yes RECOMMENDED OPTIONS: -n GraphicsMagick/ImageMagick (Raster maps) : yes (GraphicsMagick) pcre (Shapefile customization) ......... : yes dbfawk (Shapefile customization) ....... : yes rtree indexing (Shapefile speedups) .... : yes map caching (Raster map speedups) ...... : yes internet map retrieval ................. : yes (libcurl) FOR THE ADVENTUROUS: AX25 (Linux Kernel I/O Drivers) ........ : no libproj (USGS Topos & Aerial Photos) ... : yes GeoTiff (USGS Topos & Aerial Photos) ... : yes Festival (Text-to-speech) .............. : no GDAL/OGR (Obtuse map formats) .......... : 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).
This installs all of the optional libraries that make sense or are available on OS X. GDAL/OGR is available on OS X but Xastir doesn't really do much with it --- it is better not to bother. AX25 networking is only available on Linux. Festival doesn't work on OS X (to our knowledge). The GPSMan support in Xastir may benefit you, but I haven't checked to see if OS X supports it. It never worked very well for me on other operating systems, and I never use it.
Build the code
If you got all the steps above completed and your configure output looks the way it should according to the last section, you're almost done. Now you just have to compile the program:
make
If you have a beefy computer with a bunch of processors, you can speed things up by telling make to run more than one process at a time. If, say, you have an 8 processor Mac, you can do
make -j8
If this completes with no errors, Xastir has been built. Note that you may see some "warning" messages from the compiler in this step. So long as they're not "errors" that cause make to exit early, you can ignore them.
Install the code
Your last step is to install Xastir so that you can use it. This will not only put the program where it can be accessed, but installs a directory of helper scripts, map data, and other necessities.
sudo make install
You will be prompted for your own password here. You must have administration rights on your computer for this to work --- if your mac is your own machine, that should already be the case. If it's one owned by your employer and locked down for your IT support staff, well, why are you building Xastir on it?
Xastir is now installed on your machine. You should be able to run it by typing "xastir &" in a terminal window. Follow the guidelines for configuring and using Xastir that are found elsewhere on this wiki.
Staying up to date
If you took our advice and used git to download the source code, you may periodically update your Xastir installation by the following means:
cd ~/src/Xastir git pull # This downloads only what has changed since the last time ./bootstrap.sh # This is not always necessary, but is a good idea cd build # This assumes you didn't delete that directory the last time you built! ../configure CPPFLAGS="-I/usr/local/opt/berkeley-db@4/include" LDFLAGS="-L/usr/local/opt/berkeley-db@4/lib" make -j8 # Here I'm just assuming you have 8 processors --- adjust accordingly sudo make install
Ignore the (many) suggestions you will find on the web or in the Xastir mailing list to use the "update-xastir" script, because that script was set up to assume that you need no options to configure to get it to work, and you need some options to get a fully capable build.
If you didn't take our advice and just downloaded a release tarball, well, then, you're out of luck --- you must essentially start over from the "Get the code" step.