This is an automated email from the ASF dual-hosted git repository.
dmagda pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/master by this push:
new 1da8c31 Update README.adoc
1da8c31 is described below
commit 1da8c31375ca2f1334b03eb2840285b5071340f9
Author: Denis Magda <dma...@gridgain.com>
AuthorDate: Tue Nov 3 08:16:46 2020 -0800
Update README.adoc
ignite docs: added a troubleshooting section for the Jekyll installation
---
docs/README.adoc | 40 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 40 insertions(+)
diff --git a/docs/README.adoc b/docs/README.adoc
index 856b993..710f784 100644
--- a/docs/README.adoc
+++ b/docs/README.adoc
@@ -68,6 +68,46 @@ $ docker run -v "$PWD:/srv/jekyll" -p 4000:4000
jekyll/jekyll:latest jekyll s
Open `http://localhost:4000/docs[window=_blank]` in your browser.
+=== Troubleshooting
+
+Below are some issues you might hit during an installation of the Jekyll
environment or while building the tutorials.
+Let us know if you come across a new and found a workaround.
+
+==== MacOS: Issues with FFI library during Jekyll installation
+
+You should see an error trace similar to this:
https://github.com/ffi/ffi/issues/653
+
+Attempt to fix the problem by following this sequence of commands (typically
it's the last command only):
+
+[source, text]
+----
+brew reinstall libffi
+export LDFLAGS="-L/usr/local/opt/libffi/lib"
+export CPPFLAGS="-I/usr/local/opt/libffi/include"
+export PKG_CONFIG_PATH="/usr/local/opt/libffi/lib/pkgconfig"
+gem install --user-install bundler jekyll
+----
+
+==== MacOS: jekyll-asciidoc gem is not installed by default
+
+Try to follow this procedure to fix the issue.
+
+* Comment out the `rm -rf $tmp_dir` at the very end of the `build.sh` script,
so that the temp folder is not deleted after the execution.
+* Run `build.sh` (fails with `Could not find gem 'jekyll-asciidoc'...` error).
+* Go to `tmp/web_site` folder.
+* Run `bundle install`.
+* Revert the `build.sh` script and run it again.
+
+==== MacOS: can't build project due to inability to load openssl
+
+You should see an error like this:
+
+`LoadError:
dlopen(/Users/dmagda/.rbenv/versions/2.6.2/lib/ruby/2.6.0/x86_64-darwin18/digest/sha1.bundle,
9): Library not loaded: /usr/local/opt/openssl/lib/libssl.1.0.0.dylib
+ Referenced from:
/Users/dmagda/.rbenv/versions/2.6.2/lib/ruby/2.6.0/x86_64-darwin18/digest/sha1.bundle`
+
+Try to upgrade Ruby, rbenv to the latest version (2.7.1) and then reinstall
Jekyll. Use the official instructions:
+https://jekyllrb.com/docs/installation/
+
== How to Contribute
If you want to contribute to the documentation, add or modify the relevant
page in the `docs/_docs` directory.
