--- name: "utop" section: "1" platform: "linux" package: "utop" version: "2.15.0-1+b9" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/utop" --- # utop(1) Universal toplevel for OCaml ## NAME utop - Universal toplevel for OCaml ## SYNOPSIS **utop** \[ *options* \] \[ *object-files* \] \[ *script-file* \] ## DESCRIPTION **utop** is an enhanced toplevel for OCaml with many features, including context sensitive completion. When you start **utop** what you see is the prompt followed by a bar containing words. This is the completion bar: it contains the possible completion and is updated as you type. The highlighted word in the completion bar is the selected word. You can navigate using the keys **M-Left** and **M-Right** and select one completion using **M-down**. Here **M** represents the meta key, which is **Alt** on most systems. You can configure these bindings in the file *~/.config/lambda-term-inputrc* - see [**lambda-term-inputrc**(5)](/lambda-term-inputrc/5.md) for details. **utop** supports completion on: \* directives and directive arguments\ \* identifiers\ \* record fields\ \* variants\ \* function labels\ \* object methods Colors are by default configured for terminals with dark colors, such as white on black, so the prompt may look too bright on light-colored terminals. You can change that by setting the color profile of utop. To do that, type: UTop.set\_profile UTop.Light;; You can then add this line to your *~/.config/utop/init.ml* file. To turn off **utop**'s advanced prompt features, add the following to *init.ml* to turn off respectively (a) colors and the upper information line, and (b) the lower boxed list of possible completions: \#utop\_prompt\_dummy;;\ UTop.set\_show\_box false You can enable basic syntax highlighting in utop by writing a *~/.utoprc* file. See [**utoprc**(5)](/utoprc/5.md) for that. Vi edit mode is enabled by the command \#edit\_mode\_vi It currently supports three vi modes: normal, insert, visual mode, and you can get/set content with vim-like registers. *utop.el* is a package that provides **utop** integration with Emacs. The package allows you to run **utop** inside Emacs and to evaluate code in it straight from your source buffers (with the help of *utop-minor-mode*). The recommended way to install *utop.el* is via Emacs's built-in package manager **package.el**. More detailed installation and configuration instructions may be found on the project's code repository at *https://github.com/ocaml-community/utop*. You can start **utop** inside Emacs with **M-x utop**. The default install also has a minor mode with the following key bindings: **C-c C-s** Start a utop buffer (*utop*)\ **C-x C-e** Evaluate the current phrase (*utop-eval-phrase*)\ **C-x C-r** Evaluate the selected region (*utop-eval-region*)\ **C-c C-b** Evaluate the current buffer (*utop-eval-buffer*)\ **C-c C-k** Kill a running utop process (*top-kill*)\ **C-c C-z** Switch to utop process (*utop-switch-to-repl*) then you can run **utop** by pressing **M-x** and typing "utop". **utop** supports completion in Emacs mode. Just press **Tab** to complete a word. You can also integrate it with the tuareg, caml or typerex mode. For that add the following lines to your *~/.emacs* file: (autoload 'utop-minor-mode "utop" "Minor mode for utop" t)\ (add-hook 'tuareg-mode-hook 'utop-minor-mode) ## OPTIONS See **utop --help** for the full list of available options. There is considerable overlap with options available for [**ocaml**(1)](/ocaml/1.md). A commonly used option is **-require** *package* to load *package* into the execution environment. It is equivalent to using **#require** from inside [**utop**(1)](/utop/1.md). - **-absname** Show absolute filenames in error message. - **-I** *dir* Add *dir* to the list of include directories. - **-init** *file* Load *file* instead of the default init file. - **-labels** Use commuting label mode. - **-no-app-funct** Deactivate applicative functors. - **-noassert** Do not compile assertion checks. - **-nolabels** Ignore non-optional labels in types. - **-nostdlib** Do not add the default directory to the list of include directories. - **-ppx** *command* Pipe abstract syntax trees through the preprocessor *command*. - **-principal** Check principality of type inference. - **-safe-string** Make strings immutable. - **-short-paths** Shorten paths in types (the default). - **-no-short-paths** Do not shorten paths in types. - **-rectypes** Allow arbitrary recursive types. - **-stdin** Read script from standard input. - **-strict-sequence** Left-hand part of a sequence must have type unit. - **-unsafe** Do not compile bounds checking on array and string access. - **-version** Print version and exit. - **-vnum** Print version number and exit. - **-w** *list* Enable or disable warnings according to *list*. - **-warn-error** *list* Enable or disable error status for warnings according to *list*. See option **-w** for the syntax of *list*. Default setting is **-a+31**. - **-warn-help** Show description of warning numbers. - **-emacs** Run in emacs mode. - **-hide-reserved** Hide identifiers starting with a '\_' (the default). - **-show-reserved** Show identifiers starting with a '\_'. - **-no-implicit-bindings** Don't add implicit bindings for expressions (the default). - **-implicit-bindings** Add implicit bindings: *expr*;; -\> let \_0 = *expr*;; - **-no-autoload** Disable autoloading of files in *$OCAML\_TOPLEVEL\_PATH/autoload.* - **-require** *package* Load this package. - **-dparsetree** Dump OCaml AST after rewriting. - **-dsource** Dump OCaml source after rewriting. - **-help** Display this list of options. - **--help** Display this list of options. ## FILES *~/.config/utop/init.ml* The initialization file of the toplevel. *~/.ocamlinit* The alternative initialization file of the toplevel. *~/.utoprc* The configuration file for utop. See [**utoprc**(5)](/utoprc/5.md). *~/.config/lambda-term-inputrc* The file containing key bindings. See [**lambda-term-inputrc**(5)](/lambda-term-inputrc/5.md). ## AUTHOR Jérémie Dimino \ ## SEE ALSO [**utoprc**(5)](/utoprc/5.md), [**lambda-term-inputrc**(5)](/lambda-term-inputrc/5.md), [**ocaml**(1)](/ocaml/1.md).