Using Macaulay2 with jupyter and vscode (discussion)

I (Mike Stillman) will be meeting with Paul Zinn-Justin and John Cobb at Fields about May 19-20, 2025 (and hopefully with Doug Torrance remotely). Here we will record what is the "best" way to use jupyter with M2, either in a browser, or through vscode. Additionally, we will be working on the vscode Macaulay2 extension, as well as nascent Macaulay2 language server, which Doug has started.

We can use this wiki page to record what we do, and to get ideas from others.

Issues for us to consider (please add to this list) to improve the installation and usage of the vscode extension, and/or the jupyter M2 kernel/notebook server.

Notes on installing jupyter

See gist for notes about installing on MacOS (most of this is relevant for any system). (Note the section on "Disable Line output wrapping" is done automatically now).

After installing homebrew, python in homebrew, M2, here is basically what is to be done. todo: are there other useful packages in python to install into this venv too?

mkdir ~/m2-venv
cd ~/m2-venv
python3 -m venv venv
source venv/bin/activate
# or
source ~/m2-venv/venv/bin/activate
# at this point, you can move to another directory
python --version
pip install jupyter jupyterlab
pip install git+https://github.com/d-torrance/Macaulay2-Jupyter-Kernel.git@notebook-7
jupyter kernelspec list
python -m m2_kernel.install
jupyter kernelspec list

Notes on installing vscode Macaulay2 extension

Notes on working with the M2 LSP (Language server protocol), for use in any editor that supports the protocol, including vscode and emacs.

Installation

The current draft of the language server is available from the pull request #3687. One way to obtain it is to run the following from your clone of the Macaulay2 source repository:

git fetch https://github.com/d-torrance/M2 lsp
git checkout lsp

Then, if /path/to/M2 is the path to the top directory of your clone of the Macaulay2 source repository, run the following inside Macaulay2 to install the language server:

installPackage("JSONRPC", FileName => "/path/to/M2/M2/Macaulay2/packages/JSONRPC.m2")
installPackage("LanguageServer", FileName => "/path/to/M2/M2/Macaulay2/packages/LanguageServer.m2")

Finally, copy the file /path/to/M2/M2/Macaulay2/packages/LanguageServer/M2-language-server to some directory in your PATH. In the end, the following should work:

command -v M2-language-server

Working with Emacs

Beginning with version 29, Emacs has been distributed with an LSP client, EGLOT (Emacs polyGLOT). To configure Emacs to work with the Macaulay2 language server, run the following:

(require 'eglot)
(add-to-list 'eglot-server-programs '(M2-mode "M2-language-server"))

Then, inside a Macaulay2 code buffer, run M-x eglot. You should be greeted with a "Connected!" message in the minibuffer.

Currently, the only working feature is "signature help". If you point your cursor on a word, you should see basic documentation (if available) for that word in the minibuffer. This uses Emacs's built-in ElDoc minor mode.

Working with VS Code

To get basic support for the LSP server in VS Code, run the following from your clone of the vscode-macaulay2 repository:

git fetch https://github.com/d-torrance/vscode-macaulay2 lsp
git checkout lsp

Then fire up VS Code, open the vscode-macaulay folder. In the terminal, run:

npm install

Then press F5 to start debugging. It should open up a second VS Code window that says [Extension Development Host] at the top. VS Code should connect to the LSP server automatically upon opening an .m2 file.

This is currently still buggy. Ctrl+Shift+Space, which is supposed to trigger the signature help feature, results in an error ("Header must provide a Content-Length property", which doesn't make sense because it does provide this property!).