49a6ebe760
* INSTALL: Add a new section documenting the way in which newer correlation data sets can be rebuilt and substituted for officially distributed copies.
107 lines
4.7 KiB
Plaintext
107 lines
4.7 KiB
Plaintext
==============================================================
|
|
Basic Unix Installation Instructions for the Weather Utility
|
|
==============================================================
|
|
|
|
:Copyright: (c) 2006-2014 Jeremy Stanley <fungi@yuggoth.org>. Permission
|
|
to use, copy, modify, and distribute this software is
|
|
granted under terms provided in the LICENSE file distributed
|
|
with this software.
|
|
|
|
.. contents::
|
|
|
|
Prerequisites
|
|
-------------
|
|
You need the Python interpreter installed somewhere in your path (most
|
|
modern UNIX derivatives come with one already). If you need to get
|
|
Python, it can be obtained from http://www.python.org/ but chances are
|
|
your operating system at least provides some sort of native package for
|
|
it, which you should probably install in whatever means is recommended
|
|
by your OS vendor/distributor. The script is tested with recent 2.x and
|
|
3.x Python versions, attempting to maintain forward/backward
|
|
compatability with the interpreter, so bug reports or patches to ensure
|
|
this continues to be the case are most welcome.
|
|
|
|
Running in Place
|
|
----------------
|
|
An easy way to try it out is to unpack the tarball and change to the
|
|
resulting directory::
|
|
|
|
tar xzf weather-*.tar.gz
|
|
cd weather-*
|
|
./weather --version
|
|
./weather --help
|
|
man ./weather.1
|
|
man ./weatherrc.5
|
|
./weather --forecast rdu
|
|
./weather clt gso
|
|
|
|
...and so on. The weather utility, included Python module and
|
|
documentation are all fully functional when kept together in one
|
|
directory, without needing to install these components to other
|
|
locations within the filesystem hierarchy.
|
|
|
|
Installing the Utility
|
|
----------------------
|
|
The file named weather should be made executable and put somewhere in
|
|
your path (/usr/local/bin/ or ~/bin/ for example). Similarly, weather.py
|
|
needs to be somewhere in Python's include path. You can see your Python
|
|
interpreter's default include path by running::
|
|
|
|
python -c 'import sys ; print(sys.path)'
|
|
|
|
If the correlation data files are to be used (airports, places,
|
|
stations, zctas, zones), they need to be in your current working
|
|
directory or a directory mentioned within the "default" section's
|
|
"datapath" option of the weatherrc file.
|
|
|
|
Configuration
|
|
-------------
|
|
The weatherrc file should go in /etc/ or /etc/weather/ for global
|
|
configuration. You can save it in your home directory as a dotfile
|
|
(~/.weather/weatherrc or ~/.weatherrc) to support user-specific alias
|
|
configuration and overrides of the global weatherrc file.
|
|
|
|
Manuals
|
|
-------
|
|
Optionally, the weather.1 and weatherrc.5 files can be placed in sane
|
|
locations for TROFF/NROFF manual files on your system (for example,
|
|
/usr/local/share/man/ or ~/man/).
|
|
|
|
Updating Correlation Sets
|
|
-------------------------
|
|
The version control repository and tarballs are occasionally updated
|
|
with refreshed correlation sets (the files which track what the nearest
|
|
stations and weather zones are to various places). If you find you need
|
|
to generate updated correlation sets yourself, however, it can be done.
|
|
|
|
You'll need to retrieve the most recent source databases from the
|
|
different sites mentioned in the comments at the top of a recent
|
|
correlation data file--each one includes a comment block with a list of
|
|
the origins and checksums of the data files used along with the date and
|
|
time they were built. You'll also want to generate recent slist and
|
|
zlist files (look at the comments at the top of each for the shell
|
|
commands used to generate them). You probably also need the most recent
|
|
overrides.conf from the weather source repository or tarball, since that
|
|
contains known corrections for errors in the original data. Put all of
|
|
these files in your current working directory and then call::
|
|
|
|
weather --build-sets
|
|
|
|
Then wait, and wait, and wait some more. After loading and analyzing the
|
|
source data, it will guess an upper-bound for the number of great-arc
|
|
distance calculations it may have to perform and attempt to give you a
|
|
progress bar indicating percent completion. If you're lucky, it will
|
|
finish successfully also generate some automated quality assurance
|
|
analysis of the results (mostly checking for obviously bad airports,
|
|
stations, zones). If you are UNlucky, it will break, which is not
|
|
terribly uncommon because the government-provided source data is often
|
|
misformatted or gets sudden schema changes requiring updates to the
|
|
parsing routines in weather.
|
|
|
|
If you're using a system-wide (for example, distribution packaged) copy
|
|
of weather and its data, you may want to place the new airports,
|
|
stations, places, zctas and zones files into your ~/.weather directory
|
|
and make use of the setpath configuration or command-line options to
|
|
override where weather looks for them. See the weather(1) and
|
|
weatherrc(5) manpages for details.
|