INSTALL

   1 ==============================================================
   2  Basic Unix Installation Instructions for the Weather Utility
   3 ==============================================================
   4
   5 :Copyright: (c) 2006-2012 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/).