← Previous → Next Contents

Prospect Harbor Pt. Light, Prospect Harbor, Maine, 1998-06-14

Installation instructions for Unix-like platforms

Assumptions

These installation instructions assume basic familiarity with the Unix command line and that you are building from sources obtained from https://flaterco.com/xtide/files.html.  If this is a big ask, there are other options:

Mandatory library dependencies

You need complete installations (not just binaries) of the standard core set of X11 libraries plus the following:

Unfortunately, Linux distributions in the Debian and Fedora families default to installing only the binaries of shared libraries.  Users of Debian, Ubuntu, and other apt-based distributions can install the complete versions by doing this:
sudo apt-get install xorg-dev libxaw3dxft8-dev libpng-dev libsystemd-dev
On Fedora, Amazon Linux, and other rpm-based distributions, you would need to install libX11-devel, Xaw3d-devel, zlib-devel, libpng-devel, and systemd-devel.

After installing those packages, build libtcd from source (configure; make; sudo make install).

tide and xttpd can be compiled in the absence of X11 libraries and libXpm, but you still need the other stuff.

Optional libraries

The configure script will look for Xaw3dXft, Xaw3d, or Xaw, in that order.

  Plain Athena Widgets (Xaw) (tested ver. 1.0.12 / X11R7.7) can be forced using --disable-3d.
  Xaw3d (tested ver. 1.6.2) is a fork from an old version of Athena Widgets that offers improved scrollbars and a different look for buttons.  Versions 1.6 through 1.6.2 appeared in Q1 2012; prior to that, version 1.5E had been frozen since 2003.  Some issues that were subsequently fixed in Athena Widgets, such as long menus running off the screen, were fixed differently in Xaw3d.  (This affects the Set Time dialog, where the list of years to choose from can be quite long.)
 

Xaw3dXft is a fork from Xaw3d 1.5E that uses FreeType fonts.  The primary site is http://sourceforge.net/projects/sf-xpaint/files/libxaw3dxft/.  If font quality is important, Xaw3dXft is the best choice.  It also fixes the problem with long menus in the Set Time dialog.

Xaw3dXft ver. 1.6.2d made breaking changes to the API.  XTide 2.15 will work with 1.6.2d but no earlier version.  XTide 2.14 works with several earlier versions but fails to build with 1.6.2d.

I recommend configuring Xaw3dXft with the following options:  --enable-internationalization --enable-multiplane-bitmaps --enable-gray-stipples --enable-arrow-scrollbars

XTide will link with libgps if a compatible version is found on the system (tested ver. 3.0–3.24).  If a GPS is present and working, XTide will zoom in on your current location automatically.

XTide will link with libdstr if a compatible version is found on the system (tested ver. 1.0).  If no compatible libdstr is present, a local copy of Dstr 1.0 will be rolled into libxtide.

The interactive client has a soft dependency on the Schumacher fonts.  These old fonts are canonically included with X11, but their installation has been made optional in some Linux distributions.
Arch:  pacman -S xorg-fonts-misc
Gentoo:  emerge font-schumacher-misc

Downloading

Mandatory:  You need the XTide source code distribution, available in compressed tar format at https://flaterco.com/xtide/files.html#xtide.

Mandatory:  You need at least one harmonics file.  Harmonics files contain the data that are required for XTide to predict tides for different locations.  Harmonics files are available at https://flaterco.com/xtide/files.html#harmonicsfiles.

Optional:  If you want to enable XTide to draw coastlines on the map, you will also have to download the World Vector Shoreline (WVS) files, which are available in compressed tar format at https://flaterco.com/xtide/files.html#WVS.

Installing a harmonics file

You will download a file with a name similar to harmonics-dwf-YYYYMMDD-free.tar.xz.  With GNU tar, you can unpack it as follows:

tar xvf harmonics-dwf-YYYYMMDD-free.tar.xz

With another tar that does not include builtin support for xz, you need to do this instead:

xzcat harmonics-dwf-YYYYMMDD-free.tar.xz | tar xvf -

Unpack the archive in a temporary directory, then move the TCD file to a permanent location, e.g., /usr/local/share/xtide, and make it world readable:

mkdir /usr/local/share/xtide
chmod 755 /usr/local/share/xtide
chmod 644 harmonics-dwf-YYYYMMDD-free.tcd
mv harmonics-dwf-YYYYMMDD-free.tcd /usr/local/share/xtide

The tar file also includes a change log and the disclaimers and terms applying to the data.

Installing the World Vector Shoreline files (optional)

  1. Create a directory to contain the WVS files.
  2. Change your current working directory to that directory.
  3. Unpack the tar file in that directory.

Under Linux and any other system with GNU tar:

tar xvf wvs.tar.xz

Elsewhere:

xzcat wvs.tar.xz | tar xvf -

Unpacking the sources

Under Linux and any other system with GNU tar:

tar xvf xtide-2.xyz.tar.xz

Elsewhere:

xzcat xtide-2.xyz.tar.xz | tar xvf -

Configuring

I.  Specify the location of the harmonics file(s)

There are two ways to do this.

  1. The first way is by setting the environment variable HFILE_PATH.

    export HFILE_PATH=/usr/local/share/xtide/harmonics.tcd
    

    In the event that you have more than one harmonics file that you wish to use simultaneously, list them separated by colons.

    export HFILE_PATH=/usr/local/share/xtide/harmonics-free.tcd:/usr/local/share/xtide/harmonics-nonfree.tcd
    

    Alternately, make sure that they are by themselves in a special directory and specify that directory as the value of HFILE_PATH.  If an element of HFILE_PATH is a directory, XTide will attempt to load every file in that directory (so be sure that they are all harmonics files!)

    If you are installing as root, then it is recommended that you add this definition to a system-wide script such as /etc/profile if you have one.  In Debian/Ubuntu, system-wide environment variables can be added to /etc/environment.

  2. The other way is by creating the file /etc/xtide.conf.  The environment variable, if set, takes precedence over the config file.

    If a configuration file is used, the first line should consist of the value that would be assigned to HFILE_PATH:

    /usr/local/share/xtide/harmonics-free.tcd:/usr/local/share/xtide/harmonics-nonfree.tcd

II.  Specify the location of the World Vector Shoreline files (optional)

Either set the environment variable WVS_DIR to the name of that directory or supply the directory name as the second line of the configuration file /etc/xtide.conf.

III.  Run the configure script

bash-3.1$ ./configure

XTide is packaged with the popular and portable GNU automake, so all usual GNU tricks should work.  Help on configuration options can be found in the CONFIGURE-HELP file or obtained by entering ./configure --help.

The web server xttpd is not necessary to use tide or xtide, so most users needn't worry about it.  But if you plan to run it, there is additional configuration at this point.

(New in XTide 2.15)  If your system uses systemd instead of init, you must configure with --enable-systemd to be able to run xttpd as a systemd service.

To change the user and/or group under which xttpd tries to run (the defaults are nobody/nobody), provide the options --with-xttpd-user=user and/or --with-xttpd-group=group to configure.  If you want to run xttpd but you don't have root, you will have to set these to your own username and the name of some group to which you belong.

bash-3.1$ ./configure --with-xttpd-user=xttpd --with-xttpd-group==xttpd

You can also set the webmaster address for xttpd this way.

bash-3.1$ ./configure --with-webmaster="somebody@somewhere.else"

IV.  Other optional and alternative configurables

--enable-time-workaroundWork around Y2038 problem; disable time zones.  See Appendix A — Historical predictions and Y2038 compliance.
--enable-gnu-attributesUse with g++ -Wall -Wextra to make warnings smarter.
--enable-semicolon-pathsepUse ; instead of : to separate names in HFILE_PATH (good idea if they begin with C:\).
--enable-local-filesLocate xtide.conf, .xtide.xml, and .disableXTidedisclaimer files in current working directory.
--disable-3dUse only genuine Athena Widgets.
--enable-lm_hardLink with libm_hard instead of libm (for ARM Android).
--enable-moon-age(Experimental) Replace calendar mode moon phase column with moon age.

You can change the compile-time defaults (colors, etc.) set in libxtide/config.hh if you so choose, but the easiest way to set all of those things is with the control panel in the interactive XTide program.

The e-mail address for feedback in xttpd can also be changed by setting the environment variable XTTPD_FEEDBACK, in lieu of the configure option mentioned above.

Compiling and installing binaries

On Slackware:

$ make
$ su
# make install

On Debian/Ubuntu:

$ make
$ sudo make install

(With GNU make you can say make -j 8 to run 8 compiles in parallel if you want to speed it up.)

Systemd integration (XTide 2.15)

If xttpd was built with --enable-systemd, additional steps are needed to complete the installation.

Special cases

Fast and dangerous Linux/GCC build of all related packages

Bash scripts to build and install all XTide-related packages in one shot will be placed in the separate FunkyBuilds package available from https://flaterco.com/xtide/files.html#FunkyBuilds.  The details of this process depend on the Linux distribution and change frequently as the distributions are updated, so these scripts are not for the Linux novice.

Don't have X11

If you don't have any version of X11 installed and just want to compile xttpd or tide, generate a Makefile using ./configure --without-x.

CPU-constrained platforms

There are some CPU bottlenecks that are observable only on very old hardware.  Real time estimates in the following are from a 166 MHz Pentium PC:

The -aa setting that formerly could be used to speed up drawing on true color displays by disabling anti-aliasing was retired in XTide version 2.12.

Troubleshooting

Q: On a full desktop Linux distribution, configure unexpectedly says:

WARNING: Building tide and xttpd without X11; not building xtide.

A: You need complete installations (not just binaries) of the dependencies.  Unfortunately, Linux distributions in the Debian and Fedora families default to installing only the binaries.  See the installation instructions for further details.

Q: XTide compiles, but when I try to run it I get an error like the following about libtcd, libdstr, or libxtide:

error while loading shared libraries: libtcd.so.0: cannot open shared object file: No such file or directory

A: This happens when g++ found the shared library but your dynamic linker didn't.  There are several possible fixes.

First, try running ldconfig as root (sudo ldconfig on Debian-like distros).  This will fix the problem if the dynamic linker has a stale cache of the directory to which the libraries were installed.  But if the libraries were installed to a directory that is not in the dynamic linker's search path, it won't make any difference.

If the libraries were installed to a nonstandard directory, the least invasive fix is to add that directory to the environment variable LD_LIBRARY_PATH.  For example, if you find the library in /usr/local/lib, you would add this to your .bashrc (if using bash):

export LD_LIBRARY_PATH=/usr/local/lib
Or you would add this to your .cshrc (if using csh or tcsh):
setenv LD_LIBRARY_PATH /usr/local/lib

An alternative is to hard-code the directory into the executable using magic GNU linker switches:  configure with LDFLAGS="-Wl,-rpath,/usr/local/lib,--disable-new-dtags" and rebuild XTide.

Another alternative is to edit the system configuration to add the nonstandard directory to the dynamic linker's search path.  On Slackware, you just add the directory to /etc/ld.so.conf.  Debian/Ubuntu prefer to add files in the subdirectory /etc/ld.so.conf.d.  After making the change, run ldconfig again to update the cache.

Finally, if all else fails, you could link statically with the missing libraries.

Q: When compiling XTide, I get thousands of warnings of the form "warning: 'auto_ptr' is deprecated".

A: To suppress these nuisance warnings in GCC, use CPPFLAGS="-Wno-deprecated-declarations" or upgrade to GCC 4.6 or newer.

Q: When compiling XTide, I get an error involving xml-something or lex.xml.c.

A: Do make xmlclean and then try again.

Q: When running XTide, I get the following warnings regardless what I do or do not do with the font settings:

Warning: Missing charsets in String to FontSet conversion
Warning: Unable to load any usable fontset

A: These warnings come from libXt.  When the property XtDefaultFontSet is not in the X server resource database, libXt-1.3.0 does the following:

/* Should really do XListFonts, but most servers support this */
f = XCreateFontSet(display, "-*-*-*-R-*-*-*-120-*-*-*-*,*",

The warnings occur when the pattern -*-*-*-R-*-*-*-120-*-*-*-* resolves to a font that does not supply the character set needed by the plain old C locale, which is either ISO 8859-1 or just US-ASCII:

$ xlsfonts -u -fn '-*-*-*-R-*-*-*-120-*-*-*-*' | head -1
-daewoo-gothic-medium-r-normal--16-120-100-100-c-160-ksc5601.1987-0

The warnings can be fixed in two ways.  Option 1 is to change the order of the X server's font path so that -*-*-*-R-*-*-*-120-*-*-*-* resolves to a usable font; e.g.:

$ xset +fp /usr/share/fonts/100dpi
$ xlsfonts -u -fn '-*-*-*-R-*-*-*-120-*-*-*-*' | head -1
-adobe-courier-bold-r-normal--17-120-100-100-m-100-iso8859-1

The font path can be changed on a more permanent basis by adding or modifying FontPath entries in /etc/X11/xorg.conf.

Option 2 is to set XtDefaultFontSet to a pattern that resolves to a usable font; e.g.:

$ xrdb -merge <<< 'XtDefaultFontSet: -adobe-courier-*-r-*-*-*-180-*-*-*-*-iso8859-1'

XtDefaultFontSet can be set on a more permanent basis typically by adding a line to ~/.Xresources or /etc/X11/xinit/.Xresources.


← Previous → Next Contents