ocamllabs/ vscode-ocaml-platform

(v1.8.4) 6 months ago

CSS

HTML

OCaml

JavaScript

View on GitHub

Need help with vscode-ocaml-platform?

Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

ocamllabs

228 Stars

35 Forks

ISC License

1.6K Commits

43 Opened issues

Description

Visual Studio Code extension for OCaml

Services available

Need anything else?

Contributors list

Readme

VSCode OCaml Platform

Name: vscode-ocaml-platform
Brand: vscode-ocaml-platform
SKU: //ocamllabs/vscode-ocaml-platform
Rating: 2.32 (228 reviews)

Visual Studio Code extension for OCaml and relevant tools.

You are strongly encouraged to read the "Getting Started" section below because the rest of the document assumes you have read it.

If you have read "Getting Started" section in full and have issues, please read FAQ at the end of this document.

Getting started

Installation

Installing "OCaml Language Server" (also called OCaml-LSP):

Install ocaml-lsp-server package as usual with a package manager of your choice: OPAM or esy. Installation instructions by package manager are available here.

Make sure to install the packages in the sandbox (OPAM switch or esy sandbox) you use for compiling your project.

Optionally:

When you hover the cursor over OCaml code, the extension shows you the type of the code. To get nicely formatted types, install ocamlformat-rpc package.
Install ocamlformat package if you want source code formatting support.

Note: Formatting support also requires having
```
.ocamlformat
```
file in your project root directory.

Install this extension from the VSCode Marketplace. VSCode extension installations instructions are available here.

Now you should have everything necessary installed. Let's get started with writing code.

Setting up the extension for your project

Open your OCaml/ReasonML project (
```
File > Add Folder to Workspace...
```
).
Configure the extension to use the desired sandbox (OPAM switch or esy sandbox). You can pick it by

either calling VSCode command "OCaml: Select a Sandbox for this Workspace" (one can do this from VSCode Command Palette - Ctrl+P or on MacOS Cmd+Shift+P)
or clicking on the package icon at the bottom of VSCode window and picking your sandbox from the menu

What's a sandbox? A sandbox is like an isolated environment for your project, so everything you install is just installed inside this environment and not globally on your system.

Build your project with Dune to get go-to-definition, auto-completion, etc.

Important note: OCaml Language Server has its information about the files from the last time your built your project.

Caveat 1: Because of the note above, during active development of your project, we advise building your project with dune in a polling mode using the option

--watch

. This rebuilds your project whenever a file is changed in your project. For example, run

dune build --watch --terminal-persistence=clear-on-rebuild

in your VSCode integrated terminal.

Caveat 2: Save the currently open file to get latest diagnostics (error and warning squiggly underlining). For example, if you created a module

in some file, and you still get an error that it's "unbound" (i.e., not found) in the current file, save the file to get up-to-date diagnostics, assuming you built your project after adding

or are running build in a polling mode, and make sure that error isn't a stale error.

By this point, you should have a working OCaml development editor ready. If you're on Windows or use ReasonML/ReScript/BuckleScript, see subsections below.

In case of problems: Look at FAQ at the end of the document. If that doesn't help:

if you don't understand how to the extension works or how to make it work correctly, create a new discussion in the repository Discussions tab.
if the extension seems to misbehave, file an issue in the repository Issues tab.

Windows

Install OCaml for Windows and make sure the

ocaml-env

program is accessible on the PATH (

ocaml-env

is in the

usr/local/bin

folder relative to the installation directory).

ReasonML / ReScript / BuckleScript

ReasonML, as an alternative syntax for OCaml, is supported out-of-the-box, as long as

reason

is installed in your environment.

The new ReScript syntax (

res

and

resi

files) is not supported, you should use rescript-vscode instead.

If you're looking for a way to use OCaml or ReasonML syntax in a ReScript project, you'll need to install

ocaml-lsp

in your environment. We recommend using Esy for this:

Install esy

npm install esy --global

Add
```
esy.json
```
to the project root with following content:

{
  "dependencies": {
    "@opam/ocaml-lsp-server": "*",
    "@opam/ocamlfind-secondary": "*",
    "@opam/reason": "*",
    "ocaml": "4.6.x"
  }
}

Install and build packages

esy

Features

Syntax highlighting
- ATD
- Cram tests
- Dune
- Menhir
- Merlin
- META
- OASIS
- OCaml
- OCamlbuild
- OCamlFormat
- OCamllex
- opam
- ReasonML
- Eliom
Indentation rules
Snippets
- Dune
- OCaml
- OCamllex
Task Provider
- Dune

Configuration

This extension provides options in VSCode's configuration settings. You can find the settings under

File > Preferences > Settings

| Name | Description | Default | | ---------------------------------- | ------------------------------------------------------------------------------------------------------- | ------- | |

ocaml.sandbox

| Determines where to find the sandbox for a given project |

null

| |

ocaml.dune.autoDetect

| Controls whether dune tasks should be automatically detected. |

true

| |

ocaml.trace.server

| Controls the logging output of the language server. Valid settings are

off

messages

, or

verbose

. |

off

| |

ocaml.useOcamlEnv

| Controls whether to use ocaml-env for opam commands from OCaml for Windows. |

true

| |

ocaml.terminal.shell.linux

| The path of the shell that the sandbox terminal uses on Linux |

null

| |

ocaml.terminal.shell.osx

| The path of the shell that the sandbox terminal uses on macOS |

null

| |

ocaml.terminal.shell.windows

| The path of the shell that the sandbox terminal uses on Windows |

null

| |

ocaml.terminal.shellArgs.linux

| The command line arguments that the sandbox terminal uses on Linux |

null

| |

ocaml.terminal.shellArgs.osx

| The command line arguments that the sandbox terminal uses on macOS |

null

| |

ocaml.terminal.shellArgs.windows

| The command line arguments that the sandbox terminal uses on Window |

null

| |

ocaml.repl.path

| The path of the REPL that the extension uses |

null

| |

ocaml.repl.args

| The REPL arguments that the extension uses |

null

ocaml.terminal.shell.*

ocaml.terminal.shellArgs.*

null

, the configured VSCode shell and shell arguments will be used instead.

ocaml.repl.path

ocaml.repl.args

null

, the default REPL is used instead. The default REPL used depends on the packages installed in your current sandbox:

If
```
dune build
```
passes and the current sandbox has
```
utop
```
installed, the REPL will be
```
dune utop
```
If
```
dune build
```
fails and the current sandbox has
```
utop
```
installed, the REPL will be
```
utop
```
Else, the REPL will be
```
ocaml
```

If a REPL already exists, it will be used instead, so if you installed

utop

after openning a REPL, or if you fixed your project compilation, you will need to re-open the REPL to change it.

Commands

An easy way to see what commands are offered by the extension in the currently open file, you can invoke VSCode Command Palette and search for commands with prefix

OCaml:

| Name | Description | Keyboard Shortcuts | | ---------------------------- | ------------------------------------------- | ------------------ | |

ocaml.select-sandbox

| Select sandbox for this workspace | | |

ocaml.server.restart

| Restart language server | | |

ocaml.open-terminal

| Open a terminal (current sandbox) | | |

ocaml.open-terminal-select

| Open a terminal (select a sandbox) | | |

ocaml.current-dune-file

| Open Dune File (located in the same folder) | | |

ocaml.switch-impl-intf

| Switch implementation/interface |

Alt+O

| |

ocaml.open-repl

| Open REPL | | |

ocaml.evaluate-selection

| Evaluate Selection |

Shift+Enter

FAQ

I installed ocaml-lsp-server, but the extension still cannot find it.

Make sure you installed the the language server in the sandbox used by the extension.

OPAM: If you're using opam, make sure that you're using correct switch when installing the extension by running opam switch to see the current switch and check the sandbox set for the current VSCode workspace (see "Setting up the extension for your project" section to learn more about picking a sandbox for the extension).

I am getting Unbound module ... error. What should I do?

Make sure the module should be visible, e.g., there is no typo in the module name, you added the module to libraries stanza in your dune file, etc.
Make sure you have up-to-date diagnostics (error and warning squiggly underlining). Diagnostics are sent when the file open, when file is edited, and when it is saved. Save the file containing the error to make sure the error isn't stale.
Make sure you have built your project after adding that module to your environment. We suggest adhering to Caveat 1 in "Setting up the extension for your project" section. If you haven't built it, build it and go to step 2.
If you are sure there must be a problem with the extension, file an issue.

If this section doesn't contain the problem you managed to resolve, and you think this may help others, consider adding the problem and its solution here by creating a Pull Request.