Installation feedback

[olexandr-konovalov]

I helped to a user today to install JupyterKernel under macOS. Jupyter has been installed via Anaconda, and we managed to get GAP kernel working. Several things were not clear in the initial attempt undertaken by the user before contacting me. I am listing them here: first, they may be useful for users trying to use the package; second, although they are documented in various places, may be worth to underline them more explicitly (in README.md) in this package.

0. You do not have to download this package to install it under GAP 4.9.2 (or later releases) since it is redistributed with GAP since its 4.9.2 release and is contained in the pkg subdirectory. This package does not work with GAP 4.9.1 or older releases.

1. After building GAP with ./configure; make remember to change to the pkg subdirectory and call ../bin/BuildPackages.sh there.

2. The ../bin/BuildPackages.sh script builds as many packages as possible, and will list packages for which the build failed in the file pkg/log/fail.log

3. Some packages may be listed there - please check that "crypting", "io", "json" and "zeromqinterface" packages are not in the list.

4. You can also check that jupyterkernel is loadable by loading it in GAP. This is not the way how it is used, but only a check that it can be loaded. For example, in GAP 4.9.2 this will work like below:

gap> LoadPackage("jupyterkernel");
────────────────────────────────────────────────────────────────────
Loading  crypting 0.8 (Hashes and Crypto in GAP)
by Markus Pfeiffer (http://www.morphism.de/~markusp/).
Homepage: https://gap-packages.github.io/crypting/
────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────
Loading  json 2.0.0 (Reading and Writing JSON)
by Christopher Jefferson (http://caj.host.cs.st-andrews.ac.uk/).
Homepage: https://gap-packages.github.io/json/
────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────
Loading  uuid 0.5 (RFC 4122 UUIDs)
by Markus Pfeiffer (http://www.morphism.de/~markusp/).
Homepage: https://gap-packages.github.io/uuid/
────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────
Loading  ZeroMQInterface 0.10 (ZeroMQ bindings for GAP)
by Markus Pfeiffer (http://www.morphism.de/~markusp/) and
   Reimer Behrends (http://www.mathematik.uni-kl.de/agag/mitglieder/wissenschaftliche-mitarbeiter/dr-reimer-behrends/).
Homepage: https://gap-packages.github.io/ZeroMQInterface/
────────────────────────────────────────────────────────────────────
────────────────────────────────────────────────────────────────────
Loading  JupyterKernel 0.99999 (Jupyter kernel written in GAP)
by Markus Pfeiffer (https://markusp.morphism.de/).
Homepage: http://gap-packages.github.io/JupyterKernel/
────────────────────────────────────────────────────────────────────
true
gap>

5. In case of any problems with building the required packages, refer to their documentation. In particular, the ZeroMQ library should be installed before compiling ZeroMQInterface. If you're using Homebrew on macOS, this can be achieved using brew install zmq.

6. After installing Jupyter as explained at https://jupyter.org/install, you need to register the GAP Jupyter kernel as explained here.

7. If GAP is not in your PATH, then you have to set the environment variable JUPYTER_GAP_EXECUTABLE to point to your GAP executable for Jupyter to be able to execute GAP and the script jupyter-kernel-gap that is distributed with this package in the directory bin/ needs to be in your path. For example, if GAP is installed in /Users/username/gap-4.9.2/ then you can set up symlinks in /usr/local/bin using these commands:

cd /usr/local/bin
ln -s /Users/username/gap-4.9.2/bin/gap.sh gap
ln -s /Users/username/gap-4.9.2/pkg/JupyterKernel-0.99999/bin/jupyter-kernel-gap

Note that you will have to update these symlinks when you will install a newer version of GAP in the future.

8. If everything works, then you should be able to start Jupyter by jupyter notebook and then create a new GAP notebook via its menu.

[nathancarter]

This helped a lot. I had figured out several of these things by hunting around, but the two that I would not have figured out on my own were:

1. After installing ZeroMQ, one must run BuildPackages.sh again.
2. When the package says that gap must be in your path, it does not mean the gap binary in the gap-4.9.2 directory, but the gap.sh script in the inner bin directory, aliased/linked using the word gap.

[olexandr-konovalov]

@nathancarter Thanks! About (1), not necessarily the full BuildPackages.sh but certainly go to the directory of ZeroMQInterface package and run there ./configure ; make.

[olexandr-konovalov]

My plan is to add some troubleshooting section to the README, based on some text from above, and then close this.