liquidsoul / langserver-swift

A Swift implementation of the open Language Server Protocol.

Swift Language Server

Overview

A Swift implementation of the open Language Server Protocol. The Language Server protocol is used between a tool (the client) and a language smartness provider (the server) to integrate features like auto complete, goto definition, find all references and alike into the tool.

Currently this implementation is used by Swift for Visual Studio Code.

Prerequisites

Swift

• Swift version 3.1.1
• The toolchain that comes with Xcode 8.3.2 (Apple Swift version 3.1 (swiftlang-802.0.53 clang-802.0.42))

macOS

• macOS 10.12 (Sierra) or higher
• Xcode Version 8.3.2 (8E2002) or higher using one of the above toolchains (Recommended)

Linux

• Coming Soon

Build

% cd <path-to-clone>
% swift build -Xswiftc -target -Xswiftc x86_64-apple-macosx10.11

or with Xcode

% cd <path-to-clone>
% swift package generate-xcodeproj --xcconfig-overrides settings.xcconfig

Test

% cd <path-to-clone>
% swift test -Xswiftc -target -Xswiftc x86_64-apple-macosx10.11

Debug and Development

The language server itself relies on a language server client to interact with it. This server has been developed to work with Visual Studio Code. Though it should be noted that any client that implements the protocol should work and is thusly supported.

An example workflow for interactively debugging the language server while using it with the Visual Stuio Code client is provided in this section. The instructions are devided into two sections. The first section explains how to generate and configure an Xcode project for debugging. The second section explains how to configure the Visual Studio Code plugin to use the debug executable.

Xcode (e.g., langserver-swift)

In the directory containing the clone of this repository use SwiftPM to generate an Xcode project.

% git clone https://github.com/RLovelett/langserver-swift.git
% cd langserver-swift
% swift package generate-xcodeproj --xcconfig-overrides settings.xcconfig

Since the language server client, e.g., VSCode, will actually launch the language server LLDB needs to be told to wait for the application to launch. This can be configured in Xcode after opening the generated project in Xcode. See the screenshot below.

The next step is to build the executable and launch LLDB. Both of these steps can be performed by going to "Product > Run" or the keyboard shortcut ⌘R. After building completes, Xcode should report something like "Waiting to attach to LanguageServer : LanguageServer".

One final step is to determine the TARGET_BUILD_DIR. This is used to tell the VSCode extension in the next section where the debug language server is located.

From a terminal whose current working directory contains the Xcode project previously generated by SwiftPM you can get this information from xcodebuild.

% xcodebuild -project langserver-swift.xcodeproj -target "LanguageServer" -showBuildSettings | grep "TARGET_BUILD_DIR"
   TARGET_BUILD_DIR = /Users/ryan/Library/Developer/Xcode/DerivedData/langserver-swift-gellhgzzpradfqbgjnbtkvzjqymv/Build/Products/Debug

Take note of this value it will be used later.

VSCode (e.g., vscode-swift)

Open the directory containing the clone of the Visual Studio Code extension in Visual Studio Code.

% git clone https://github.com/RLovelett/vscode-swift.git
% code .

Start the TypeScript compiler or the build task (e.g., ⇧⌘B or Tasks: Run Build Task).

Now open src/extension.ts and provide the value of TARGET_BUILD_DIR for the debug executable. The change should be similar to the patch that follows.

diff --git a/src/extension.ts b/src/extension.ts
index b5ad751..7970ae1 100644
--- a/src/extension.ts
+++ b/src/extension.ts
@@ -13,7 +13,7 @@ export function activate(context: ExtensionContext) {
         .get("languageServerPath", "/usr/local/bin/LanguageServer");

     let run: Executable = { command: executableCommand };
-    let debug: Executable = run;
+    let debug: Executable = { command: "${TARGET_BUILD_DIR}/LanguageServer" };
     let serverOptions: ServerOptions = {
         run: run,
         debug: debug

NOTE: Make sure the ${TARGET_BUILD_DIR} is populated with the value you generated in the Xcode section. It is not an environment variable so that will not be evaluated.

Once this is complete you should be able to open the VSCode debugger and and select Launch Extension. This should start both the language server (Xcode/Swift) and the extension (VScode/TypeScript) in debug mode.

Caveats

1. As noted above you might not be able to capture all the commands upon the language server initially starting up. The current hypothesis is that it takes a little bit of time for LLDB (the Swift debugger) to actually attach to the running process so a few instructions are missed.

One recommendation is to put a break-point in handle.swift as this is likely where the server is getting into to trouble.

2. Messages are logged to the Console.app using the me.lovelett.langserver-swift sub-system. One place to look the raw language server JSON-RPC messages is there.