INSTALL

   1 ==============================================================
   2  Basic Unix Installation Instructions for the Weather Utility
   3 ==============================================================
   4
   5 :Copyright: (c) 2006-2014 Jeremy Stanley <fungi@yuggoth.org>. Permission
   6             to use, copy, modify, and distribute this software is
   7             granted under terms provided in the LICENSE file distributed
   8             with this software.
   9
  10 .. contents::
  11
  12 Prerequisites
  13 -------------
  14 You need the Python interpreter installed somewhere in your path (most
  15 modern UNIX derivatives come with one already). If you need to get
  16 Python, it can be obtained from http://www.python.org/ but chances are
  17 your operating system at least provides some sort of native package for
  18 it, which you should probably install in whatever means is recommended
  19 by your OS vendor/distributor. The script is tested with recent 2.x and
  20 3.x Python versions, attempting to maintain forward/backward
  21 compatability with the interpreter, so bug reports or patches to ensure
  22 this continues to be the case are most welcome.
  23
  24 Running in Place
  25 ----------------
  26 An easy way to try it out is to unpack the tarball and change to the
  27 resulting directory::
  28
  29    tar xzf weather-*.tar.gz
  30    cd weather-*
  31    ./weather --version
  32    ./weather --help
  33    man ./weather.1
  34    man ./weatherrc.5
  35    ./weather --forecast rdu
  36    ./weather clt gso
  37
  38 ...and so on. The weather utility, included Python module and
  39 documentation are all fully functional when kept together in one
  40 directory, without needing to install these components to other
  41 locations within the filesystem hierarchy.
  42
  43 Installing the Utility
  44 ----------------------
  45 The file named weather should be made executable and put somewhere in
  46 your path (/usr/local/bin/ or ~/bin/ for example). Similarly, weather.py
  47 needs to be somewhere in Python's include path. You can see your Python
  48 interpreter's default include path by running::
  49
  50    python -c 'import sys ; print(sys.path)'
  51
  52 If the correlation data files are to be used (airports, places,
  53 stations, zctas, zones), they need to be in your current working
  54 directory or a directory mentioned within the "default" section's
  55 "datapath" option of the weatherrc file.
  56
  57 Configuration
  58 -------------
  59 The weatherrc file should go in /etc/ or /etc/weather/ for global
  60 configuration. You can save it in your home directory as a dotfile
  61 (~/.weather/weatherrc or ~/.weatherrc) to support user-specific alias
  62 configuration and overrides of the global weatherrc file.
  63
  64 Manuals
  65 -------
  66 Optionally, the weather.1 and weatherrc.5 files can be placed in sane
  67 locations for TROFF/NROFF manual files on your system (for example,
  68 /usr/local/share/man/ or ~/man/).
  69
  70 Updating Correlation Sets
  71 -------------------------
  72 The version control repository and tarballs are occasionally updated
  73 with refreshed correlation sets (the files which track what the nearest
  74 stations and weather zones are to various places). If you find you need
  75 to generate updated correlation sets yourself, however, it can be done.
  76
  77 You'll need to retrieve the most recent source databases from the
  78 different sites mentioned in the comments at the top of a recent
  79 correlation data file--each one includes a comment block with a list of
  80 the origins and checksums of the data files used along with the date and
  81 time they were built. You'll also want to generate recent slist and
  82 zlist files (look at the comments at the top of each for the shell
  83 commands used to generate them). You probably also need the most recent
  84 overrides.conf from the weather source repository or tarball, since that
  85 contains known corrections for errors in the original data. Put all of
  86 these files in your current working directory and then call::
  87
  88     weather --build-sets
  89
  90 Then wait, and wait, and wait some more. After loading and analyzing the
  91 source data, it will guess an upper-bound for the number of great-arc
  92 distance calculations it may have to perform and attempt to give you a
  93 progress bar indicating percent completion. If you're lucky, it will
  94 finish successfully also generate some automated quality assurance
  95 analysis of the results (mostly checking for obviously bad airports,
  96 stations, zones). If you are UNlucky, it will break, which is not
  97 terribly uncommon because the government-provided source data is often
  98 misformatted or gets sudden schema changes requiring updates to the
  99 parsing routines in weather.
 100
 101 If you're using a system-wide (for example, distribution packaged) copy
 102 of weather and its data, you may want to place the new airports,
 103 stations, places, zctas and zones files into your ~/.weather directory
 104 and make use of the setpath configuration or command-line options to
 105 override where weather looks for them. See the weather(1) and
 106 weatherrc(5) manpages for details.