Editor Support For Chapel¶

This document describes how to set up your editor to work with Chapel. If your preferred editor is not listed, consider opening an issue requesting it or pull request to add it.

Emacs
Neovim
Vim
VSCode

Emacs¶

Syntax Highlighting¶

To get syntax highlighting for Chapel in Emacs, you can use the files in the top-level highlight/emacs directory of the Chapel source tree. These files are licensed under the GPL, see highlight/emacs/LICENSE. To use them, take the following steps:

Copy/move the highlight/emacs directory to a known directory. If you installed Chapel from a package manager, you may need to download the Chapel source code to get these files.
Add the following lines to your standard .emacs or .emacs.d/init.el file:

; prepend the path to 'highlight/emacs' to your emacs load-path
(if (string= chpl-home nil)
    nil
  (add-to-list 'load-path "/path/to/chapel/highlight/emacs")
  )

; make sure that when chpl-mode is entered, (our modified) cc-mode is
; loaded
(autoload 'chpl-mode "chpl-mode" "Chpl enhanced cc-mode" t)

; make loading files with a .chpl extension put emacs into chpl-mode
(add-to-list 'auto-mode-alist '("\\.chpl$" . chpl-mode))

Language Server Support¶

With Emacs 29.1, support has been added for language server protocols via Eglot

To utilize the Chapel language server and/or chplcheck with Eglot, add the following to your .emacs or .emacs.d/init.el file (note that this assumes you have already followed the directions for syntax highlighting):

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(chpl-mode . ("chpl-language-server" "--chplcheck"))))

This will enable using the language server with a particular .chpl file by calling M-x eglot.

To automatically use Eglot and the language server with every .chpl file, additionally add the following to your .emacs file:

(add-hook 'chpl-mode-hook 'eglot-ensure)

Note

The above uses the --chplcheck flag to enable additional diagnostics from chplcheck. If you do not want to use chplcheck, you can remove this.

Neovim¶

Syntax Highlighting¶

See the Vim Syntax Highlighting section for how to setup syntax highlighting in Neovim.

Language Server Support¶

The built-in LSP API can be used to configure Chapel language server and chplcheck by adding the following to your Neovim configuration file. Note that this assumes you have already installed lspconfig.

local lspconfig = require 'lspconfig'
local configs = require 'lspconfig.configs'
local util = require 'lspconfig.util'

configs.cls = {
  default_config = {
    cmd = {"chpl-language-server"},
    filetypes = {'chpl'},
    autostart = true,
    single_file_support = true,
    root_dir = util.find_git_ancestor,
    settings = {},
  },
}
configs.chplcheck = {
  default_config = {
    cmd = {"chplcheck", "--lsp"},
    filetypes = {'chpl'},
    autostart = true,
    single_file_support = true,
    root_dir = util.find_git_ancestor,
    settings = {},
  },
}

lspconfig.cls.setup{}
lspconfig.chplcheck.setup{}
vim.cmd("autocmd BufRead,BufNewFile *.chpl set filetype=chpl")

Vim¶

Chapel support for Vim has been designed for use with Vim versions 5.08 or newer.

Syntax Highlighting¶

To get syntax highlighting for Chapel in Vim, either manually copy the files top-level highlight/vim directory of the Chapel source tree into your $HOME/.vim directory or use a plugin manager like vim-plug to install an unmanaged plugin.

Manual Installation:¶

Create a directory in the root of your home directory called .vim.
```
mkdir -p $HOME/.vim
```

Copy the relevant syntax files to your .vim directory. This command assumes your current working directory is the Chapel source tree.

cp -r highlight/vim/ftdetect \
      highlight/vim/ftplugin \
      highlight/vim/syntax \
      highlight/vim/indent \
      $HOME/.vim

Add the following lines to your standard .vimrc file:

set nocompatible           " allow for non-vi compatible features
syntax on                  " enable syntax highlighting
filetype plugin indent on  " enable filetype detection, plugins, indent
set autoindent             " turn on auto indenting

Other useful commands are available in the highlight/vim/sample-vimrc file.

Vim-Plug Installation:¶

For users of the vim-plug plugin manager, the vim Chapel support can be loaded as an unmanaged plugin. To do this, add the following line to the .vimrc, between the call plug#begin() and call plug#end() lines:

Plug '~/path/to/chapel/highlight/vim'

Where ~/path/to/chapel is the path to the Chapel repository, starting from the home directory. Chapel support should work once these changes are made without any calls to :PlugInstall, which is required for managed plugins.

Note that vim-plug uses the ~ character to identify that a plugin is a local file, so the Chapel repository, or at least the highlight/vim/ directory, must be somewhere under the home directory.

Language Server Support¶

The use the Chapel language server and chplcheck, you will need to have an extension that supports the Language Server Protocol (LSP). There are a few options for this, these instructions will use the vim-lsp extension with vim-plug.

Using vim-lsp:¶

Note that these instructions assume you have already setup Vim with Chapel syntax highlighting as described in the previous section.

Assuming you have already installed the vim-plug plugin manager, you can add the following lines to your .vimrc file, between the between the call plug#begin() and call plug#end() lines:
```
Plug 'prabirshrestha/vim-lsp'
```

After the call plug#end() line, add the following configuration. This configuration registers the Chapel language server with the vim-lsp extension and sets up some example keybindings for common LSP operations:

if executable('chpl-language-server')
    au User lsp_setup call lsp#register_server({
        \ 'name': 'cls',
        \ 'cmd': {server_info->['chpl-language-server', '--chplcheck']},
        \ 'allowlist': ['chpl'],
        \ })
endif

" Configure the lsp plugin for Chapel
" This function sets up a few example keybindings
function! s:on_lsp_buffer_enabled() abort
    setlocal omnifunc=lsp#complete
    setlocal signcolumn=yes
    if exists('+tagfunc') | setlocal tagfunc=lsp#tagfunc | endif
    nmap <buffer> gd <plug>(lsp-definition)
    nmap <buffer> gs <plug>(lsp-document-symbol-search)
    nmap <buffer> gS <plug>(lsp-workspace-symbol-search)
    nmap <buffer> gr <plug>(lsp-references)
    nmap <buffer> <leader>rn <plug>(lsp-rename)
    nmap <buffer> [g <plug>(lsp-previous-diagnostic)
    nmap <buffer> ]g <plug>(lsp-next-diagnostic)
    nmap <buffer> K <plug>(lsp-hover)
endfunction

augroup lsp_install
    au!
    autocmd User lsp_buffer_enabled call s:on_lsp_buffer_enabled()
augroup END

" Enables lsp inlay hints and adds some styling
let g:lsp_inlay_hints_enabled = 1
highlight lspInlayHintsType ctermfg=grey guifg=grey

For other configuration options for the vim-lsp extension, see the vim-lsp documentation.

Note

The above configuration assumes that the Chapel language server is installed and available in your $PATH. If this is not the case, you will need to modify the cmd field in the lsp#register_server calls to point to the correct location of the language server executable.

Make sure to open vim and run :PlugInstall to install the plugin.

VSCode¶

Syntax Highlighting¶

Syntax highlighting is provided by the Chapel Language extension. To install the extension, visit the Visual Studio Code marketplace.

Language Server Support¶

The Chapel Language extension provides builtin support for the Chapel language server and chplcheck. If chpl-language-server and chplcheck are in your $PATH, the extension will automatically use it. If not, you can either specify you CHPL_HOME in the extension settings or specify the path to the executables.

Specifying `CHPL_HOME`:¶

Open the settings for the Chapel extension and set chapel.CHPL_HOME to the path of your Chapel CHPL_HOME.

Specifying the path to the executables:¶

Open the settings for the Chapel extension and set chapel.chpl-language-server.path and chapel.chplcheck.path to the path of the Chapel language server and chplcheck executables, respectively.

Editor Support For Chapel¶

Emacs¶

Syntax Highlighting¶

Language Server Support¶

Neovim¶

Syntax Highlighting¶

Language Server Support¶

Vim¶

Syntax Highlighting¶

Manual Installation:¶

Vim-Plug Installation:¶

Language Server Support¶

Using vim-lsp:¶

VSCode¶

Syntax Highlighting¶

Language Server Support¶

Specifying CHPL_HOME:¶

Specifying the path to the executables:¶

Specifying `CHPL_HOME`:¶