README.md

learn-ocaml.el

Summary

learn-ocaml.el is an Emacs frontend for students using learn-ocaml.

Dependencies

Emacs

(version 25.1 or later)

learn-ocaml-client

• Browse the Releases page of learn-ocaml.
• Download the latest version (≥ 0.13.0) of learn-ocaml-client from the Release Assets.
• For Windows 10, the Linux binary should be compatible with WSL.
• Rename the binary to just learn-ocaml-client (instead of e.g. learn-ocaml-client-linux-x86_64)
• Add the executable bit to the binary (chmod a+x learn-ocaml-client)
• (Optional) Put the learn-ocaml-client binary in your PATH.

Note: beyond learn-ocaml-client, you may want to install a comprehensive OCaml/Emacs environment (with Tuareg, Merlin, Company): for details, see https://github.com/erikmd/tapfa-init.el (in French)

Installation (using MELPA)

MELPA is a repository of Emacs packages. Skip this step if you already use MELPA. Otherwise, add the following to your .emacs and restart Emacs:

(require 'package)
;; (setq gnutls-algorithm-priority "NORMAL:-VERS-TLS1.3") ; see remark below
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize)

Remark: If you have Emacs 26.1 (which is precisely the packaged version in Debian 10), you may get the error message Failed to download 'melpa' archive during the package refresh step. This is a know bug (debbug #34341) which has been fixed in Emacs 26.3 and 27.1, while a simple workaround consists in uncommenting the line (setq gnutls-algorithm-priority "NORMAL:-VERS-TLS1.3") above in your .emacs.

Then, run M-x package-refresh-contents RET followed by M-x package-install RET learn-ocaml RET to install and byte-compile learn-ocaml.

Usage

Enable the minor mode in any buffer:

M-x learn-ocaml-mode RET

Follow the instructions regarding the server URL and token (which will automatically be stored in ~/.config/learnocaml/client.json).

Open the LearnOCaml menu or directly start an exercise from the *learn-ocaml-exercise-list* buffer.

Then, the learn-ocaml-mode will automatically be activated when opening .ml buffers using tuareg-mode and the following keybindings will be available:

• (learn-ocaml-grade): C-c C-m C-m (= C-c RET RET)

• (learn-ocaml-display-exercise-list): C-c C-m C-l (= C-c RET C-l) or C-c C-m l (= C-c RET l)

Known limitations

• When used jointly with Merlin, if the learn-ocaml exercise contains a nonempty prelude, Merlin may trigger errors such as Unbound value foo although foo is defined in the server exercise. Note that this issue does not impact the learn-ocaml.el grading feature which already works in this use case. But ultimately, we will provide a dedicated support to workaround this Merlin issue, which thus occurs if the server exercise provides some prelude.ml and/or prepare.ml code.

Feedback

Bug reports and suggestions are very welcome: feel free to open a new issue or PR.

Developer docs

• Setup the learn-ocaml.el dev environment by following these refs:
  • GH: erikmd/tapfa-init.el (opam (2.x) + OCaml (4.12.0) + GNU Emacs (≥ 25.1) + Tuareg + Merlin)
  • git-scm.com/download (Git)
  • Gist: Magit (Magit)
  • Gist: Resources for elisp dev (which-key + helpful + edebug-x + Tutorials)
  • GH: erikmd/docker-examples (Docker)
• Use the Makefile to start the test environment:
  run make help to list the available Makefile commands.
• Browse the tests/README.md file for further details.

Authors and Acknowledgments

learn-ocaml.el has been developed in University Toulouse III by Erik Martin-Dorel, Manuel Cabarcos Baulina, and Louis Ayroles, thanks to the support of the OCaml Software Foundation.

License

learn-ocaml.el is a free software distributed under the MIT License.