X-Git-Url: https://www.yuggoth.org/gitweb?p=weather.git;a=blobdiff_plain;f=INSTALL;h=6e64ce2063f4bcccfd9e241d2a3718378db66c07;hp=c95c989b3a589bfd7375b751a223b80c6865bf78;hb=840b91b4fdc7563a4c08546d6ee5de5dd93601ba;hpb=b755668b64a70bb7b0efbf1bd0aff8c310471ee1 diff --git a/INSTALL b/INSTALL index c95c989..6e64ce2 100644 --- a/INSTALL +++ b/INSTALL @@ -1,58 +1,106 @@ -BASIC UNIX INSTALLATION INSTRUCTIONS FOR THE WEATHER UTILITY - -Copyright (c) 2006 Jeremy Stanley , all rights reserved. -Licensed per terms in the LICENSE file distributed with this software. - - -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). - - -RUNNING IN PLACE - +============================================================== + Basic Unix Installation Instructions for the Weather Utility +============================================================== + +:Copyright: (c) 2006-2014 Jeremy Stanley . 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: +resulting directory:: tar xzf weather-*.tar.gz - cd weather + cd weather-* ./weather --version ./weather --help man ./weather.1 man ./weatherrc.5 - ./weather --forecast --no-conditions --city=charlotte --st=nc - ./weather ord sea + ./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, if somewhat inconvenient. - - -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" - - -CONFIGURATION - -The weatherrc file should go in /etc/ or you can save it in your -home directory as a dotfile (~/.weatherrc) to support user-specific -alias configuration and overrides of the global /etc/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/). - +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.