Skip to content

Commit

Permalink
Merge pull request dylan-lang#34 from cgay/dev
Browse files Browse the repository at this point in the history
doc: create initial doc, based on README.md
  • Loading branch information
cgay authored Apr 21, 2024
2 parents bbb365f + 479ff0d commit c1ef039
Show file tree
Hide file tree
Showing 6 changed files with 357 additions and 102 deletions.
104 changes: 2 additions & 102 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Dylan.

## Current Status

As of 2022-11-07, the server implements
As of 2024-04-19, the server implements

* Jump to declaration
* Jump to definition
Expand All @@ -19,104 +19,4 @@ definition" will show a list containing the generic function and its specific
methods, whereas "jump to declaration" will jump straight to the generic
function.

We are currently using version [3.15 of the LSP
protocol](https://microsoft.github.io/language-server-protocol/specifications/specification-3-15/).


## Opening Projects

The LSP server needs to be able to open a project (that is, a Dylan library)
associated with the file you're editing when you turn on LSP in your editor. It
assumes you are using a [dylan-tool](https://github.com/dylan-lang/dylan-tool)
workspace and searches for a project to open as follows:

1. If there is a `workspace.json` file and that file has a `"default-library"`
property, the specified library is opened.

2. It uses `dylan-tool` to choose a library defined in the workspace. This is
[generally](https://github.com/dylan-lang/dylan-tool/blob/292b7bf761745c9fa810511c9888f802dd787011/sources/workspaces/workspaces.dylan#L151)
the test suite library, if one exists.

Normally you shouldn't need to set any environment variables; everything is
derived from the full pathname to the `dylan-compiler` executable, which must
be on your `PATH`.

## Emacs Usage

1. Make sure the `dylan-lsp-server` executable is on your `PATH`, or customize
the `lsp-dylan-exe-pathname` elisp variable. See below for more on
customization.

1. Install [lsp-mode](https://github.com/emacs-lsp/lsp-mode) and Dylan mode.
Both of these are available from MELPA.

2. When you jump to another `.dylan` file, that file does not automatically
have LSP enabled so you must use `M-x lsp` again. To make this automatic,
add this to your emacs init file:

`(add-hook 'dylan-mode-hook 'lsp)`

3. Start emacs and make sure that `lsp-dylan.el` is loaded. For example:

`emacs --load=/path/to/lsp-dylan/lsp-dylan.el`

You will probably want to modify your Emacs init file to load the file.

4. Open a Dylan source file and type `M-x lsp` to start the client (unless you
added the hook above, in which case it started automatically).

The client starts the LSP server (the `dylan-lsp-server` executable) and
connects to it.

The emacs client has a customization group "lsp-dylan" which is a member of the
"Language Server (lsp-mode)" group, and has the following variables:

* `lsp-dylan-exe-pathname`
* `lsp-dylan-extra-command-line-options`
* `lsp-dylan-log-pathname`
* `lsp-dylan-open-dylan-release`

These are documented in the customization interface within emacs. Use `M-x
customize-group` `lsp-dylan` to customize these variables.

## Visual Studio Code Usage

These instructions were tested on Linux and macOS.

1. Install Visual Studio Code and `npm`.
2. The VS Code extension is in the folder `vscode-dylan`. It is necessary to
run `npm install` in this folder before starting the extension for the
first time, and any time a git pull updates the dependencies.
3. Open the `vscode-dylan` folder in VS Code.
4. In the debug viewlet, click the green play arrow (Launch Extension) or
press `F5`.
5. A build process will begin in 'watch mode'; whenever the source is changed,
the extension will be rebuilt. It is possible to debug the VS Code
extension in this window, set breakpoints, watch variables and so on.
6. A new VS Code window will open with the extension running.
7. Open a folder with a Dylan project in it.
8. If `dylan-lsp-server` is on the system path, it will be found. Otherwise,
open the Settings *in the new extension window*, find the Dylan section
under Extensions, and edit the path to the LSP server. The full, absolute
pathname to the executable needs to be specified. It is usually better to
set this in the 'User' scope, otherwise it will only apply to that
particular project.
9. It should now be possible to use the extension window to edit Dylan code
using LSP.
10. If the VS Code extension is changed, it is necessary to restart the
extension host, or just close and re-open the extension window.


## References

* [Intro to LSP from
Microsoft](https://docs.microsoft.com/en-us/visualstudio/extensibility/language-server-protocol)
Besides being a quick introduction, this has links to some other tools that
would help in developing VS Code integration for Dylan.

* [LSP v3.15
Specification](https://microsoft.github.io/language-server-protocol/specifications/specification-3-15/)
This is the version we are currently coding to.

* [langserver.org](https://langserver.org/) lists LSP implementations that
support at least one of the six major LSP features.
See documentation/source/index.rst for full documentation.
20 changes: 20 additions & 0 deletions documentation/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?= -v
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
35 changes: 35 additions & 0 deletions documentation/make.bat
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

if "%1" == "" goto help

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
58 changes: 58 additions & 0 deletions documentation/source/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('../../_packages/sphinx-extensions/current/src/sphinxcontrib'))
sys.path.insert(0, os.path.abspath('../../../_packages/sphinx-extensions/current/src/sphinxcontrib'))
import dylan.themes as dylan_themes


# -- Project information -----------------------------------------------------

project = 'lsp-dylan'
copyright = '2019, Peter Hull'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'dylan.domain'
]

# Necessary to make things like '.. current-module:: foo' work.
primary_domain = 'dylan'

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'
# html_theme = dylan_themes.get_html_theme_default()

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
Loading

0 comments on commit c1ef039

Please sign in to comment.