fac09516fc | ||
---|---|---|
examples/custom-utop | ||
man | ||
src | ||
syntax | ||
utils | ||
.gitignore | ||
CHANGES.md | ||
LICENSE | ||
Makefile | ||
README.md | ||
_oasis | ||
_tags | ||
configure | ||
dist | ||
myocamlbuild.ml | ||
opam | ||
setup.ml | ||
style.css | ||
utoprc-dark | ||
utoprc-light |
README.md
utop - a universal toplevel for OCaml
utop is an improved toplevel for OCaml. It can run in a terminal or in Emacs. It supports line edition, history, real-time and context sensitive completion, colors, and more.
It integrates with the tuareg and typerex modes in Emacs.
Installation via opam
The easiest and recommended way of installing utop is via opam:
$ opam install utop
If you want to build it manually, you should install all the dependencies listed in the next section.
Dependencies
- OCaml (>= 3.12)
- findlib
- react
- lwt (>= 2.4.0) built with react support
- Camomile (>= 0.8)
- zed (>= 1.2)
- lambda-term (>= 1.2)
For building the development version, you also need to install oasis (>= 0.3.0).
utop also requires OCaml compiler libraries. Since OCaml 4.00 they are already installed, for previous versions:
- if you are using debian, they are available as the package ocaml-compiler-libs,
- if you are using godi, they are installed by default,
- if you installed ocaml by hand, you can run the script
utils/install-compiler-libs.sh
.
Installation from sources
To build and install utop:
$ ./configure
$ make
$ make install
Documentation and manual pages (optional)
To build the documentation:
$ make doc
It will then be installed by make install
.
Tests (optionnal)
To build and execute tests:
$ ./configure --enable-tests
$ make test
Usage
To use utop, simply run:
$ utop
utop display a bar after the prompt which is used to show possible
completions in real-time. You can navigate in it using M-left
and
M-right
, and select one completion using M-tab
. The M
denotes
the meta key, which is Alt
most of the time.
Customization
Colors
To add colors to utop, copy one of the files utoprc-dark
or
utoprc-light
to ~/.utoprc
. utoprc-dark
is for terminals with
dark colors (such as white on black) and utoprc-light
is for
terminals with light colors (such as black on white).
Prompt
You can customize the prompt of utop by setting the reference
UTop.prompt
.
Key bindings
Key bindings in the terminal can be changed by writing a
~/.lambda-term-inputrc
file. For example:
[read-line]
C-left: complete-bar-prev
C-right: complete-bar-next
C-down: complete-bar
If manual pages are correctly installed you can see a description of this file by executing:
$ man 5 lambda-term-inputrc
Integration with emacs
To use utop in emacs, first you need to make sure emacs can find the
command utop
and the file utop.el
. If you installed utop via opam
you can copy-paste this code into you ~/.emacs
file:
;; Setup environment variables using opam
(dolist (var (car (read-from-string (shell-command-to-string "opam config env --sexp"))))
(setenv (car var) (cadr var)))
;; Update the emacs path
(setq exec-path (split-string (getenv "PATH") path-separator))
;; Update the emacs load path
(push (concat (getenv "OCAML_TOPLEVEL_PATH") "/../../share/emacs/site-lisp") load-path)
;; Automatically load utop.el
(autoload 'utop "utop" "Toplevel for OCaml" t)
Then you can execute utop inside emacs with: M-x utop
.
Integration with the tuareg/typerex mode
You can replace the default toplevel used by the tuareg or typerex
mode by utop, for that add the following lines to your ~/.emacs
file:
(autoload 'utop-setup-ocaml-buffer "utop" "Toplevel for OCaml" t)
(add-hook 'tuareg-mode-hook 'utop-setup-ocaml-buffer)
(add-hook 'typerex-mode-hook 'utop-setup-ocaml-buffer)
You can also complete text in a tuareg or typerex buffer using the
environment of the toplevel. For that bind the function
utop-edit-complete
to the key you want.
Common error
If you get this error when running utop in a terminal or in emacs this
means that the environment variable CAML_LD_LIBRARY_PATH
is not set
correctly:
Fatal error: cannot load shared library dlllwt-unix_stubs
Reason: dlopen(dlllwt-unix_stubs.so, 138): image not found
It shall point to the directory stublibs
inside your ocaml installation.
Creating a custom utop-enabled toplevel
If you want to create a custom toplevel with utop instead of the
classic one you need to link it with utop and its dependencies and
call UTop_main.main
in the last linked unit. You also need to pass
the -thread
switch when linking the toplevel.
The easiest way to do that is by using ocamlfind:
$ ocamlfind ocamlmktop -o myutop -thread -linkpkg -package utop myutop_main.cmo
Where myutop_main.ml
contains:
let () = UTop_main.main ()
You can also use the ocamlc
sub-command instead of ocamlmktop
, in
this case you need to pass these thee extra arguments:
-linkall
to be sure all units are linked into the produced toplevel-package compiler-libs.toplevel
-predicates create_toploop
With the last option ocamlfind will generate a small ocaml unit,
linked just before myutop_main.cmo
, which will register at startup
packages already linked in the toplevel so they are not loaded again
by the #require
directive. It does the same with the ocamlmktop
sub-command.
For example:
$ ocamlfind ocamlc -o myutop -thread -linkpkg -linkall -predicates create_toploop \
-package compiler-libs.toplevel,utop myutop.cmo
Note that if you are not using ocamlfind, you will need to do that
yourself. You have to call Topfind.don't_load
with the list of all
packages linked with the toplevel.
A full example using ocamlbuild is provided in the examples/custom-utop directory.