diff options
| -rw-r--r-- | README.md | 187 |
1 files changed, 115 insertions, 72 deletions
@@ -1,121 +1,164 @@ -Travel::Status::DE::IRIS - Interface to IRIS based web departure monitors ---- +# db-iris - Commandline Client for DB IRIS Departure Monitor -<https://finalrewind.org/projects/Travel-Status-DE-IRIS/> +db-iris is a commandline client and Perl module for the DB IRIS departure +monitor located at iris.noncd.db.de. See the [Travel::Status::DE::IRIS +homepage](https://finalrewind.org/projects/Travel-Status-DE-IRIS/) for details. -Travel::Status::DE::IRIS and the accompanying **db-iris** program provide both -human- and machine-readable access to departure data at german train stations. -They can be used by Perl scripts or modules, on the command-line, and (via JSON -output) by other programs. +It provides both human- and machine-readable access to departure data at german +train stations via text and JSON output. -Local Installation ---- +## Installation -This will install db-iris and Travel::Status::DE::IRIS to a local directory. -They will not be made available system-wide; db-iris will not be added to -your program PATH. See the next section for system-wide installation. +You have four installation options: -All you need for this variant is **perl** (v5.14.2 or newer), **carton** -(packaged for many operating systems), and **libxml2** with development headers -(packaged as `libxml2-dev` on Debian-based Linux distributions). +* Nightly `.deb` builds for Debian-based distributions +* Installing the latest release from CPAN +* Installation from source +* Using a Docker image -After installing these, run the following command to install the remaining -dependencies: +Except for Docker, **db-iris** is available in your PATH after installation. +You can run `db-iris --version` to verify this. Documentation is available via +`man db-iris`. + +### Nightly Builds for Debian + +[lib.finalrewind.org/deb](https://lib.finalrewind.org/deb) provides Debian +packages of both development and release versions. Note that these are not part +of the official Debian repository and are not covered by its quality assurance +process. + +To install the latest release, run: ``` -carton install +wget https://lib.finalrewind.org/deb/libtravel-status-de-iris-perl_latest_all.deb +sudo dpkg -i libtravel-statusg-de-iris-perl_latest_all.deb +sudo apt --fix-broken install +rm libtravel-status-de-iris-perl_latest_all.deb ``` -You are now ready to use db-iris by providing Perl with the module paths -set up by carton and Travel::Status::DE::IRIS: +For a (possibly broken) development snapshot of the Git master branch, run: ``` -perl -Ilocal/lib/perl5 -Ilib bin/db-iris --version +wget https://lib.finalrewind.org/deb/libtravel-status-de-iris-perl_dev_all.deb +sudo dpkg -i libtravel-status-de-iris-perl_dev_all.deb +sudo apt --fix-broken install +rm libtravel-status-de-iris-perl_dev_all.deb ``` -For documentation, see `perldoc -F lib/Travel/Status/DE/IRIS.pm` and -`perldoc -F bin/db-iris`. +Note that dpkg, unlike apt, does not automatically install missing +dependencies. If a dependency is not satisfied yet, `dpkg -i` will complain +about unmet dependencies and bail out. `apt --fix-broken install` installs +these dependencies and also silently finishes the Travel::Status::DE::VRR +installation. + +Uninstallation works as usual: + +``` +sudo apt remove libtravel-status-de-iris-perl +``` -System-Wide Installation ---- +### Installation from CPAN + +Travel::Status::DE::IRIS releases are published on the Comprehensive Perl +Archive Network (CPAN) and can be installed using standard Perl module tools +such as `cpanminus`. + +Before proceeding, ensure that you have standard build tools (i.e. make, +pkg-config and a C compiler) installed. You will also need the following +libraries with development headers: + +* libdb +* libssl +* libxml2 +* zlib + +Now, use a tool of your choice to install the module. Minimum working example: + +``` +cpanm Travel::Status::DE::VRR +``` -This will install db-iris and Travel::Status::DE::IRIS in system-wide -directories in `/usr/local`, allowing them to be used on the command line and -by Perl scripts without the need to specify search paths or module directories. -Building and installation is managed by the **Module::Build** perl module. +If you run this as root, it will install script and module to `/usr/local` by +default. -For this variant, you must install Module::Build and all dependencies (see the -Dependencies section below) yourself. Many of them are packaged for Debian and -other Linux distributions. Run `perl Build.PL` to check dependency availability --- if it complains about "ERRORS/WARNINGS FOUND IN PREREQUISITES", install the -modules it mentions and run `perl Build.PL` again. Repeat this process until it -no longer complains about missing prerequisites. +### Installation from Source -You are now ready to build and install the module. +In this variant, you must ensure availability of dependencies by yourself. +You may use carton or cpanminus with the provided `Build.PL`, Module::Build's +installdeps command, or rely on the Perl modules packaged by your distribution. +On Debian 10+, all dependencies are available from the package repository. -If you downloaded a release tarball, use the following commands: +To check whether dependencies are satisfied, run: ``` perl Build.PL +``` + +If it complains about "... is not installed" or "ERRORS/WARNINGS FOUND IN +PREREQUISITES", it is missing dependencies. + +Once all dependencies are satisfied, use Module::Build to build, test and +install the module. Testing is optional -- you may skip the "Build test" +step if you like. + +If you downloaded a release tarball, proceed as follows: + +``` ./Build +./Build test sudo ./Build install ``` -If you are working with the git version, use these instead: +If you are using the Git repository, use the following commands: ``` -perl Build.PL ./Build ./Build manifest +./Build test sudo ./Build install ``` -You can now use Travel::Status::DE::IRIS and db-iris like any other perl -module. See `man Travel::Status::DE::IRIS` and `man db-iris` for documentation. +If you do not have superuser rights or do not want to perform a system-wide +installation, you may leave out `Build install` and use **db-iris** from the +current working directory instead. -Dependencies ---- +With carton: -* perl version 5.14.2 or newer -* Class::Accessor -* DateTime -* DateTime::Format::Strptime -* Geo::Distance -* List::Compare -* List::MoreUtils -* List::UtilsBy -* LWP::UserAgent -* LWP::Protocol::https -* Text::LevenshteinXS -* XML::LibXML +``` +carton exec db-iris --version +``` -Additional dependencies for building this module: +Otherwise (also works with carton): -* File::Slurp -* JSON +``` +perl -Ilocal/lib/perl5 -Ilib bin/db-iris --version +``` -Note about Text::LevenshteinXS: This module is old and unmaintained, but -appears to be packaged for slightly more distros than its successor -Text::Levenshtein::XS. If it is not available for your distro (and you do -not wish to build it), the following drop-in replacements are available: +### Running db-iris via Docker -* Text::Levenshtein::XS -* Text::Levenshtein (about 10 times slower than the XS modules) +A db-iris image is available on Docker Hub. It is intended for testing +purposes: due to the latencies involved in spawning a container for each +db-iris invocation, and the lack of persistent caching, it is less convenient +for day-to-day usage. -To use them, run: +Installation: ``` -sed -i 's/Text::LevenshteinXS/Text::Levenshtein::XS/g' Build.PL lib/Travel/Status/DE/IRIS/Stations.pm +docker pull derfnull/db-iris:latest ``` -or +Use it by prefixing db-iris commands with `docker run --rm +derfnull/db-iris:latest`, like so: ``` -sed -i 's/Text::LevenshteinXS/Text::Levenshtein/g' Build.PL lib/Travel/Status/DE/IRIS/Stations.pm +docker run --rm derfnull/db-iris:latest --version ``` -Managing stations ---- +Documentation is not available in this image. Please refer to the +[online db-iris manual](https://man.finalrewind.org/1/db-iris/) instead. + + +## Managing stations Travel::Status::DE::IRIS needs a list of train stations to operate, which is located in `share/stations.json`. There are two recommended editing methods. @@ -152,5 +195,5 @@ curl -s https://iris.noncd.db.de/iris-tts/timetable/station/DS100 return a `<station>` element with "name", "eva" and "ds100" attributes, you're good to go. -Note that although EVA numbers are often identical with UIC station IDs, -there are stations where this is not the case. +Note that although EVA numbers are often identical with UIC station IDs, this +is not always the case. Please do not rely on UIC IDs when managing stations. |