README.md

Language Server Protocol (LSP) for Fantom v0.0.2

---

Overview

StarLord is a Language Server Protocol (LSP) implementation for Fantom.

This pre-alpha / proof of concept version has support for:

• Standalone Fantom files
• Tracking file operations (incremental updates, renames, and deletes)
• Fantom Projects (via build.fan files and LSP Workspaces)
• Reporting compilation errors and warnings (via LSP Diagnostics)
• Class outline views (via LSP Document Symbols)

Language Servers (such as the Fantom LSP) are standalone programs that are started by IDEs and text editors (the Language Clients) to provide editing hints. All communication between client and server is done over std out and std in.

Note that LSPs generally do not provide syntax highlighting.

Usage

StarLord is distributed as a standalone (Fantom) application - just download it from GitHub and unzip it.

Install an LSP Client feature / plugin into your favourite IDE / text editor and configure it to use the unzipped afxStarLord Fantom app. Some example text editor configurations are given below.

StarLord needs to find the pods that your Fantom projects are dependant on, and each project may need different pods from different locations. For this, each project uses its own Fantom Env.

• Project Envs default to using environment variables
• fan.props files can be used to configure a PathEnv
• fpm.props files are also supported for FPM integration (FPM not in included in default StarLord download.)

For example, place this fan.props in your project directory to compile against the default suite of core pods in your Fantom home directory.

# fan.props to compile against Fantom core pods
# this dir should point to FAN_HOME env var
path=/Apps/fantom-1.0.78

Or use a fan.props similar to this one to compile against a SkySpark installation.

# fan.props to compile against SkySpark and its var dir
path=/Temp/skyspark-3.1.4; /Temp/skyspark-3.1.4/var

Or, if you already have Fantom setup on your development machine, you may copy afxStarLord.pod to <FAN_HOME>/lib/fan/ and lic/lic-starlord.props to <FAN_HOME>/lic/ and forgo the fan.props.

IDE / Text Editor Integration

These examples assume StarLord had been unzipped into C:\StarLord\ - update them so they point to where StarLord has actually been unzipped.

Eclipse IDE

Eclipse IDE uses the LSP4E Plugin, so install that first.

Visit Help -> Install New Software... and enter the LSP4E p2 repository URL http://download.eclipse.org/lsp4e/snapshots/. The latest snapshot release (from September 2022) is needed to ensure errors and warnings are displayed to overcome this issue.

Create an "External Tool Configuration" with the following:

• Name - Fantom LSP
• Location - C:\Apps\Java\bin\java.exe
• Arguments - -cp C:\StarLord\lib\java\sys.jar -Dfan.home=C:\StarLord fanx.tools.Fan afxStarLord

Visit Window -> Preferences -> General -> Content Types and Add Child to create a new Fantom Source File entry under Text. Add a file association of *.fan.

Visit Window -> Preferences -> General -> Editors -> File Associations and make the "Generic Text Editor" the default editor.

Visit Window -> Preferences -> Language Servers, click Add, and associate the "Text / Fantom Source File" with the new "Fantom LSP" external tool configuration.

When editing Fantom files, make sure to open with the Generic Text Editor and not the default Text Editor - because LSP4E only works with the Generic Text Editor.

Kate Editor

Kate Editor is a little complicated to setup because you have to first create syntax highlighting and bind the LSP to the syntax.

Save this file as C:\Users\<username>\AppData\Local\org.kde.syntax-highlighting\syntax\fantom.xml and restart Kate.

<!--
This Kate Editor syntax highlighting file is purposely blank.
It is just used to get a highlighting context so it may be assigned to an LSP.
-->
<language name="Fantom" section="XXX" extensions="*.fan" kateversion="5.53" mimetype="text/fantom">
</language>

Visit Settings -> Configure Kate -> Open/Save -> Modes & Filetypes and an entry of XXX/Fantom should now appear.

Visit Settings -> Configure Kate -> Plugins and enable LSP Client.

Visit Settings -> Configure Kate -> LSP Client -> User Server Settings and enter the following, but obviously swap the actual location of your Fantom sys.jar.

{
  "servers": {
    "fantom": {
      "command": ["java", "-cp", "C:\\StarLord\\lib\\java\\sys.jar", "-Dfan.home=C:\\StarLord", "fanx.tools.Fan", "afxStarLord"],
      "url": "https://www.fantomfactory.com/",
      "highlightingModeRegex": "Fantom"
    }
  }
}

Sublime Text

Sublime Text uses LSP for Sublime Text

Visit Tools -> Command Palette -> Package Control: Install Package -> Fantom and install. This installs a Fantom highlighter that the LSP binds to.

Visit Tools -> Command Palette -> Package Control: Install Package -> LSP and install.

Visit Tools -> Command Palette -> Preferences: LSP Settings and in the user settings (the editor on the right), enter this.

{
  "log_server": ["panel"],

  "clients": {
    "Fantom LSP": {
      "enabled": true,
      "command": ["java", "-cp", "C:\\StarLord\\lib\\java\\sys.jar", "-Dfan.home=C:\\StarLord", "fanx.tools.Fan", "afxStarLord"],
      "selector": "source.fan",
      "schemes": ["file"],
    }
  }
}

Visit Tools -> LSP -> Toggle Diagnostics Panel to view errors and warnings.

Notes

StarLord tracks changes to files as you type, but only compiles and updates the outline view when a document is saved - the same as the F4 IDE.

As per standard Fantom compilation, compiled pods are output to lib/fan/ of the current working directory, which is usually where fan.props is located. Set the outPodDir field in your build.fan to change this.

Debug logging to a file maybe enabled by updating the StarLord command to:

["java", "-cp", "C:\\StarLord\\lib\\java\\sys.jar", "-Dfan.home=C:\\StarLord", "fanx.tools.Fan", "afxStarLord", "-debug", "-logToFile", "-logFile", "C:\\path\\to\\starlord-logs.txt"],

Java, JNI, and DotNet compilation steps are not enabled.