Getting started

Installing Elpi

The recommended way to install Elpi is through opam:

$ opam install elpi

This installs the elpi command-line tool used throughout this manual and the elpi findlib package that an OCaml application links against to embed the interpreter (-package elpi, see Embedding and extending Elpi).

Elpi is also packaged for Nix and for Debian and its derivatives.

In addition, every continuous-integration run produces statically linked binaries for Linux, macOS and Windows, downloadable from the project’s Actions tab. These carry no dependencies, so downloading one is often the quickest way to start experimenting.

Running a program

An Elpi program is a collection of rules kept in one or more .elpi files. Here is a complete one. Running it with -test executes the query main; the output main prints is shown below the listing:

code/hello.elpi:

1% Example used in the "Getting started" chapter: a first Elpi program.
2%
3% Run the query main with:   elpi hello.elpi -test
4% Explore it interactively:  elpi hello.elpi   (then type a goal at goal>)
5
6pred greeting -> string.
7greeting "Hello, world!".
8
9main :- greeting S, print S.

Hello, world!

The program declares one predicate, greeting, gives it a single defining rule that relates it to a string, and defines main to look that string up and print it. elpi FILE -test always runs the query main this way.

To run a different query, use -exec. The invocation elpi hello.elpi -exec p -- a b c runs the query p ["a", "b", "c"], passing whatever follows -- on the command line as a single list-of-strings argument.

With neither -test nor -exec, elpi prints a goal> prompt, reads one goal from standard input, runs it, and exits. This is the quickest way to try a query against a program without editing it, for instance to see what greeting binds its argument to:

$ elpi hello.elpi
goal> greeting S.
Success:
  S = Hello, world!

The prompt reports the answer substitution (here just S), followed by any leftover constraints and the final state, both empty in this case. Typing main. at the prompt instead would run main, printing Hello, world! and succeeding with no bindings. The prompt handles one goal per run; to try several queries, start elpi again for each, or drive the interpreter through its OCaml API (Embedding and extending Elpi).

A few command-line flags matter from the first program on:

  • -I PATH adds a directory to the search path used to resolve accumulate directives (File structure and attributes); it may be passed more than once;

  • --help lists every flag;

  • --version prints the Elpi version

Editor support

An extension for Visual Studio Code is available in the marketplace; search for “Elpi”. Besides syntax highlighting, it hosts the interactive trace browser described in Debugging and tracing.

The extension also works with elpi-lsp, the language server of Elpi, installed with opam install elpi-lsp. As you type, the editor underlines the syntax and type errors of the whole file at once; hovering over a symbol shows its type, and Go to Definition jumps to the signature of a predicate. The server speaks the standard Language Server Protocol, so other editors can use it too. How to build, configure and test it is explained in the README of the language server.

The language server also runs in a web browser, compiled to JavaScript and to WebAssembly. The Elpi repository uses it to put editable and runnable Elpi code in the slides of a Slidev presentation: each code block becomes an editor that underlines errors and shows types on hover as you type, and a runnable block also runs main and shows what it printed below the code. The example deck in webrunner/slidev shows all of this, and its README explains how to add it to your own slides.