cc7cb0a613
Since the next version will require Python 3.9 or later due to relying on the zoneinfo module, go ahead and clean up code that supported earlier versions of the interpreter as well as updating documentation accordingly.
107 lines
4.7 KiB
Plaintext
107 lines
4.7 KiB
Plaintext
==============================================================
|
|
Basic Unix Installation Instructions for the Weather Utility
|
|
==============================================================
|
|
|
|
:Copyright: (c) 2006-2024 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
|
|
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.
|