Added troubleshooting section to readme
Change-Id: I146cbcd6b7c46f2fb81f9431841a0aa6efd430d8
diff --git a/Changes b/Changes
index 5b5a855..f5fc334 100755
--- a/Changes
+++ b/Changes
@@ -1,4 +1,4 @@
-0.40 2020-12-03
+0.40 2020-12-07
- Modernize ES and fix in-loops.
- add roll() method to state object.
- Fix wrong hint-mirror behaviour in Firefox.
@@ -15,6 +15,7 @@
- Fix requirement of KorAP.vc in docgroupref
(which broke the vc demo).
- Improve RegEx-Button in vc builder.
+ - Added 'Troubleshooting' section to Readme.
0.39 2020-10-07
- Add information on secret file to Readme.
diff --git a/README.md b/README.md
index e1aeac8..414087f 100644
--- a/README.md
+++ b/README.md
@@ -26,12 +26,17 @@
## Setup for Development
-To fetch the latest version of Kalamar ...
+To install the latest version of Kalamar, first fetch the resource ...
```shell
$ git clone https://github.com/KorAP/Kalamar
```
+... and follow the steps below.
+
+If you have any problems with installing Kalamar,
+see the *Troubleshooting* section.
+
### Generate Static Asset Files
To generate the static asset files (scripts, styles, images ...),
@@ -64,8 +69,10 @@
Kalamar uses the [Mojolicious](http://mojolicio.us/) framework,
that expects a Perl version of at least 5.16.
-The recommended environment is based on [Perlbrew](http://perlbrew.pl/)
-with [App::cpanminus](http://search.cpan.org/~miyagawa/App-cpanminus/).
+On Windows [Strawberry Perl](http://strawberryperl.com/) is recommended.
+An environment based on [Perlbrew](http://perlbrew.pl/) is recommended,
+if available. The installation guide requires
+[App::cpanminus](http://search.cpan.org/~miyagawa/App-cpanminus/) as well.
Some perl modules are not on CPAN yet, so you need to install them from GitHub.
The easiest way to do this is using
@@ -105,7 +112,6 @@
(see [Kustvakt](https://github.com/KorAP/Kustvakt) for further information)
or by using the environment variable `KALAMAR_API`.
-
## Configuration
The basic configuration file is `kalamar.conf`. To define derivations,
@@ -215,6 +221,48 @@
- `Piwik`: For integrating Matomo/Piwik
+## Troubleshooting
+
+### `make` not available under Windows
+
+Instead of running
+
+```shell
+$ perl Makefile.PL
+$ make test
+```
+
+it is also possible to run the test suite using `prove`.
+
+```shell
+$ prove -lr t
+```
+
+### Problem installing Crypt::Random::Source on Windows
+
+[Crypt::Random::Source](https://metacpan.org/pod/Crypt::Random::Source)
+recently removed support for C<rand> as a random source,
+which may lead to missing sources in tests under certain operating systems.
+You should be able to force install
+[Crypt::Random::Source](https://metacpan.org/pod/Crypt::Random::Source),
+though this environment is not recommended for production:
+
+```shell
+$ cpanm -f Crypt::Random::Source
+```
+
+### Problem installing Mojolicious::Plugin::MailException on Windows
+
+Some versions of
+[Mojolicious::Plugin::MailException](https://metacpan.org/pod/Mojolicious::Plugin::MailException)
+have a
+[minor bug](https://github.com/dr-co/libmojolicious-plugin-mail_exception/pull/13)
+in the test suite, so a force install may be necessary.
+
+```perl
+$ cpanm -f Mojolicious::Plugin::MailException
+```
+
## COPYRIGHT AND LICENSE
### Original Software