← Previous → Next Contents

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

Installation instructions for supported platforms

Assumptions

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

Mandatory library dependencies

The "tested" versions of libraries cited below are merely the versions that were demonstrated to work at the time of the last XTide release, for information in case a compatibility issue arises.

In addition to the minimal set of X11 libraries that pretty much everyone has, you need the following libraries:

Debian/Ubuntu users can install the dependencies by doing this:
sudo apt-get install xorg-dev libxaw3dxft8-dev libpng-dev
and then building libtcd from source (configure; make; sudo make install).

The interactive client requires that the Schumacher fonts be installed with X11.  These fonts are always included with the X11 distribution, but their installation is frequently optional.

tide and xttpd can be compiled in the absence of X11 libraries and libXpm.  However, 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.16).  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.

Downloading

Mandatory:  You need the XTide source code distribution, available in bzipped tar format at http://www.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 http://www.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 bzipped tar format at http://www.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.bz2.  With GNU tar, you can unpack it as follows:

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

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

bzip2 -dc harmonics-dwf-YYYYMMDD-free.tar.bz2 | 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.bz2

Elsewhere:

bzip2 -dc wvs.tar.bz2 | tar xvf -

Unpacking the sources

Under Linux and any other system with GNU tar:

tar xvf xtide-2.xyz.tar.bz2

Elsewhere:

bzip2 -dc xtide-2.xyz.tar.bz2 | 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.  However, 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.  However, 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

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.

Mac OS X

2016-01:  New maintainer David Strubbe reports that working, up-to-date build scripts are available from MacPorts.

Android

The XTide distribution does not provide a complete Android app, but the basis for such an app, libxtide, can be built using the NDK.  An example script for cross-compiling libpng, libtcd, libxtide, tide, and xttpd for Android on x86 or x86_64 Linux is in the XTide distribution as scripts/Android/build.sh.  App developers can follow the example of MX Tides to add a JNI layer and GUI.

The tide and xttpd binaries produced by build.sh can be run from a shell prompt on a rooted device.  Pointing a web browser at xttpd on the loopback address (http://127.0.0.1/) is a quick and dirty way to get a GUI.  (Change for XTide 2.15:  Android's xttpd now runs in the terminal instead of forking into the background, but otherwise works normally.)

Cygwin

XTide can be compiled and run using Cygwin, which is an emulated Unix environment for Windows that is free for typical non-commercial users.  The Cygwin distribution and its full license terms are available from http://www.cygwin.com/.

Cygwin packages are all versioned separately, so there is no baseline "Cygwin version" against which to test XTide.  Testing was most recently performed with XTide 2.15 using the collection of packages that was current as of 2016-01-23.  As of then, the quirks apparent after brief testing were as follows:

  1. Had to specify LDFLAGS="-L/usr/local/lib" explicitly.
  2. If only building certain of the programs, you must type (e.g.) 'make tide.exe' instead of 'make tide'.  'make tide' causes the automake-generated makefile to do something silly.

DOS + DJGPP

[A prebuilt DOS binary for the command-line client is available in http://www.flaterco.com/xtide/files.html#contrib.  It is usable in a DOS box under any 32-bit version of Windows and in DOSBox under 64-bit Windows.]

Don't laugh:  the DOS binary works better under Windows than the native Windows one does.

A DOS binary for the command-line client tide can be built using DJGPP.  The following instructions were last validated on 2016-01-25 with XTide 2.15 and DJGPP 2.05.

First things first

If using hard-core DOS, both a Long File Name (LFN) driver and a DPMI provider must be installed.  Recommended:

If using a DOS box (CMD.EXE) in a 32-bit version of Windows, LFN and DPMI should just work.

Unzipping

When unpacking zip files, use the unzip32.exe that is distributed with DJGPP to prevent file names from getting broken.

File names on NTFS must be created in the DOS namespace.  Linux ntfs-3g doesn't do that.  Similarly, the LFN implementation in Linux vfat is not entirely compatible with doslfn.  It only works reliably if you mount the vfat partition with the option shortname=winnt.

Environment

For the validation build, the following DJGPP files were installed (unzipped in C:\DJGPP):

-rw-r--r--  1 dave users  8842737 Jan 22 17:34 bnu2251br3.zip
-rw-r--r--  1 dave users    71339 Jan 22 17:36 csdpmi7b.zip
-rw-r--r--  1 dave users  2509574 Jan 22 17:32 djdev205.zip
-rw-r--r--  1 dave users   603760 Jan 22 17:32 djtzn205.zip
-rw-r--r--  1 dave users 28597989 Jan 22 17:39 gcc530b.zip
-rw-r--r--  1 dave users 13008311 Jan 22 17:38 gpp530b.zip
-rw-r--r--  1 dave users  8391218 Jan 22 17:37 gtxt192b.zip
-rw-r--r--  1 dave users   405500 Jan 22 17:35 mak41br2.zip
-rw-r--r--  1 dave users  1293982 Jan 22 17:37 png1610b.zip
-rw-r--r--  1 dave users   194774 Jan 22 17:37 zlib128br2.zip

Environment variables:

SET PATH=C:\DJGPP\BIN;%PATH%
SET DJGPP=C:\DJGPP\DJGPP.ENV
SET TZ=:America/New_York

The environment variable TZ should be set to the zoneinfo identifier that is appropriate for your system clock.  For example,

      SET TZ=:America/New_York
  or  SET TZ=:America/Los_Angeles
  or  SET TZ=:UTC
If this is not done, predictions will still be technically correct, but XTide will have the wrong idea of the current time when deciding what range of predictions to generate.

Dependencies

Building tide

  1. Ensure that scripts/DOS/Makefile.dj2 contains the correct path to the libtcd build directory.
  2. Do make -f scripts\DOS\Makefile.dj2.

The following behaviors will differ from the default Unix behaviors:

Windows + Visual Studio

[A prebuilt Windows binary for the command-line client is available in http://www.flaterco.com/xtide/files.html#contrib.  It still runs in a DOS box, but is compatible with 64-bit Windows.]

When built with Visual Studio, XTide has to use an undesirable workaround for the absence of the Time Zone Database, and the resulting binary might not run on a different version of Windows.  On 32-bit Windows, the DOS+DJGPP build is simply better.  On 32- or 64-bit Windows, best results are obtained using Cygwin or a Linux VM.

The following instructions were last validated on 2016-01-25 with XTide 2.15 and Visual Studio Community 2015 with Update 1 under Windows 10 64-bit.

For Windows and Visual Studio, a script that builds zlib, libpng, libtcd, libxtide, and finally tide is available in the XTide distribution as scripts\VS\build.bat.

  1. Do [Windows Logo Thingy Formerly Known as Start Menu] → All Apps → Visual Studio 2015 (folder) → VS2015 x64 Native Tools Command Prompt.  To prevent inexplicable file system permissions problems, right click it and run as Administrator.  (Ha ha... That was a little Windows in-joke.  Now that we have UAC, the only way to prevent inexplicable file system permissions problems is to use a FAT32 file system.)
  2. Unpack the zlib, libpng, libtcd, and XTide distributions under the current working directory.
  3. Copy xtide...\scripts\VS\build.bat to the working directory and edit it so that the version numbers specified at the top agree with what you have.
  4. build

As configured, the following behaviors will differ from the default Unix behaviors:

For example, you could put the following in an xtide.conf file in the current working directory:

C:\Documents and Settings\Mumble\Foo\harmonics-free.tcd;C:\Documents and Settings\Mumble\Foo\harmonics-nonfree.tcd

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: 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" 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: Using a DJGPP-built tide program in a DOS box in a 32-bit version of Windows, I get

harmonics.tcd: No such file or directory (ENOENT).
But the file is THERE!

A: When you do dir /X, you should see this:

  12/24/2012  03:15 PM         1,937,557 HARMON~1.TCD harmonics.tcd
If it says harmonics.tcd but not also HARMON~1.TCD, then the file was created in the wrong namespace.  Recreate the file in a DOS box and confirm that HARMON~1.TCD then appears with dir /X.

Q: Using a DJGPP-built tide program in a DOS box in a 32-bit version of Windows, I get "Your platform appears to have broken time zone support.  You need to get the DJGPP zoneinfo package and unpack it in C:\DJGPP."  But C:\DJGPP\zoneinfo is THERE!

A:

Q: DOS again...  I unzipped the files under Linux into a vfat (FAT) file system, and now I've got problems in DOS like missing header file, broken time zones....

A: Yup.  There's something incompatible in the LFN implementations.  Don't ask me why, but this only works reliably if you mount the vfat partition with the option shortname=winnt.


← Previous → Next Contents