   [1]<- Previous [2]-> Next [3]Contents

   [4]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
   [5]https://flaterco.com/xtide/files.html.  If this is a big ask, there
   are other options:
     * Binary packages for some platforms are available under [6]contrib
       files, but you need to be careful about out-of-date packages.
     * Kelly Bellis wrote detailed, step-by-step instructions from the
       perspective of a Windows user running Ubuntu in a virtual machine.
       The merged documentation (this online documentation plus Mr.
       Bellis' value added) is provided in a [7].chm file (Microsoft
       Compiled HTML Help).  Last rev 20190309 for XTide 2.15.2.

  Mandatory library dependencies

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

     * [8]libXpm
     * [9]zlib (a.k.a. libz), prerequisite of libpng
     * [10]libpng
     * [11]libtcd

   Debian/Ubuntu users can install the dependencies by doing this:
   sudo apt-get install xorg-dev libxaw3dxft8-dev libpng-dev
   libsystemd-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, but you still need the other stuff.

  Optional libraries

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

   [Xaw-sample.png]   Plain Athena Widgets (Xaw) (tested ver. 1.0.12 /
   X11R7.7) can be forced using --disable-3d.
   [Xaw3d-sample.png]   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-sample.png]

   Xaw3dXft is a fork from Xaw3d 1.5E that uses FreeType fonts.  The
   primary site is
   [12]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 [13]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 [14]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
   compressed tar format at
   [15]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
   [16]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
   [17]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/xti
de/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-nonfr
ee.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 [18]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 [19]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-workaround Work around Y2038 problem; disable time
   zones.  See [20]Appendix A -- Historical predictions and Y2038
   compliance.
   --enable-gnu-attributes Use with g++ -Wall -Wextra to make warnings
   smarter.
   --enable-semicolon-pathsep Use ; instead of : to separate names in
   HFILE_PATH (good idea if they begin with C:\).
   --enable-local-files Locate xtide.conf, .xtide.xml, and
   .disableXTidedisclaimer files in current working directory.
   --disable-3d Use only genuine Athena Widgets.
   --enable-lm_hard Link 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 [21]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.
     * make install-systemd will install xttpd.socket and xttpd.service
       into /lib/systemd/system.
     * If a port or address other than the default port 80 is to be used,
       edit /lib/systemd/system/xttpd.socket per [22]systemd
       documentation.
     * If you want to provide the environment variables HFILE_PATH or
       XTTPD_FEEDBACK to xttpd, create the environment file
       /etc/sysconfig/xttpd per [23]systemd documentation.  If necessary,
       the path /etc/sysconfig/xttpd can be changed by editing
       xttpd.service, or the environment variables can be specified
       directly therein using Environment= instead of EnvironmentFile=.
     * make enable-systemd does the following final steps:
          + systemctl enable xttpd.socket xttpd.service
          + systemctl start xttpd.socket xttpd.service
     * If something goes wrong, make barf-systemd will dump the log for
       inspection (journalctl -b -p debug --no-pager).

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
   [24]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:
     * Updating the map in the location chooser takes between 0 and 20
       seconds depending on how much of the world has to be redrawn.  To
       avoid the lag when zoomed out, don't install the optional [25]World
       Vector Shoreline database.
     * On the first run, libXaw3dXft bogs down for minutes trying to
       process exposure events on the long text of the disclaimer window.
       Since the disclaimer is normally read once and then disabled for
       future runs, one can either put up with it that one time or avoid
       the problem by building with libXaw3d or libXaw instead of
       libXaw3dXft.
     * Redrawing a default-sized tide graph takes about 1 second, which
       seems slow when one is scrolling forward or backward.  Graph
       drawing is faster if an 8-bit display mode (PseudoColor visual) is
       used, but anti-aliasing and transparency are available only in true
       color modes.

   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 fil
e: 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.
     __________________________________________________________________

   [26]<- Previous [27]-> Next [28]Contents

References

   1. https://flaterco.com/xtide/sysreq.html
   2. https://flaterco.com/xtide/ports.html
   3. https://flaterco.com/xtide/xtide.html#contents
   4. https://flaterco.com/
   5. https://flaterco.com/xtide/files.html
   6. https://flaterco.com/xtide/files.html#contrib
   7. https://flaterco.com/files/xtide/XTide%20v2.15.2%20Help%20b20190309.chm
   8. http://www.x.org/
   9. http://www.zlib.net/
  10. http://www.libpng.org/pub/png/libpng.html
  11. https://flaterco.com/xtide/files.html#libtcd
  12. http://sourceforge.net/projects/sf-xpaint/files/libxaw3dxft/
  13. http://www.catb.org/gpsd/
  14. https://flaterco.com/util/index.html
  15. https://flaterco.com/xtide/files.html#xtide
  16. https://flaterco.com/xtide/files.html#harmonicsfiles
  17. https://flaterco.com/xtide/files.html#WVS
  18. http://www.gnu.org/software/automake/automake.html
  19. http://www.freedesktop.org/wiki/Software/systemd/
  20. https://flaterco.com/xtide/time_t.html
  21. https://flaterco.com/xtide/advanced.html#cp
  22. http://www.freedesktop.org/software/systemd/man/systemd.socket.html#ListenStream=
  23. http://www.freedesktop.org/software/systemd/man/systemd.exec.html#EnvironmentFile=
  24. https://flaterco.com/xtide/files.html#FunkyBuilds
  25. https://flaterco.com/xtide/installation.html#WVS
  26. https://flaterco.com/xtide/sysreq.html
  27. https://flaterco.com/xtide/ports.html
  28. https://flaterco.com/xtide/xtide.html#contents
