A Complete Guide to Swift Development on Linux

In October 2018, Apple announced work on Language Server Protocol support for Swift. A month later, a second post introduced SourceKit-LSP.

The news was music for Linux developers’ ears. Each announcement proved a step toward Swift autocomplete working with any editor and platform.

In this tutorial, you’ll take the Language Server Protocol (LSP) for a spin using the Visual Studio Code (VSCode) editor on Linux. You’ll get a fell of using VSCode on Linux, compiling the LSP extensions for VSCode and finally debugging your Swift application using the LLDB debugger.

Getting Started

This tutorial requires a basic understanding of Linux and shell script.

To begin, download and install Swift on your Linux system. Go to the Swift website and download the recommended toolchain for your version of Linux.

As of this writing, Apple only supports Ubuntu, so the tutorial will use that distribution.

Once you’ve downloaded the toolchain, navigate to its directory in a terminal window. Replace FILE with the name of the file you downloaded:

sudo apt-get install curl clang libicu-dev git libatomic1 libicu60 libxml2 libcurl4 zlib1g-dev libbsd0 tzdata libssl-dev libsqlite3-dev libblocksruntime-dev libncurses5-dev libdispatch-dev -y
mkdir ~/swift
tar -xvzf FILE -C ~/swift

This step installs the required dependencies and unpacks the toolchain to ~/swift.

To use Swift in your shell, you have to tell your shell where to find it. Open ~/.bashrc in your favorite editor. Then add the following line, replacing FILE with the name of the directory you unpacked Swift into:

export PATH="~/swift/FILE/usr/bin:$PATH"

That’s it! You’ve installed Swift on your system. To ensure everything works, close and reopen your terminal. Next type:

swift --version

The output should look similar to the following:

Swift version 5.3-dev (LLVM d59da0cbc0, Swift ff36b5ede8)
Target: x86_64-unknown-linux-gnu

Next, download the materials for this project by clicking the Download Materials button at the top or bottom of this page. Unzip the file, then navigate to the Starter/ folder. Next run:

swift run

This will build and run the project.

It’s a simple web application programming interface (API) that can store and retrieve TODOs. Once you see Server starting on http://localhost:8080, your server is available. You can check it by executing the following

curl http://localhost:8080/

in a new terminal tab. This should return It works!. If it does, then everything is in place for the next steps.

Time to explore the power of the Language Server Protocol!

Introducing the Language Server Protocol

The Language Server Protocol (LSP) is a protocol created by Microsoft. It allows for standardized communication between a language and an editor or tool so that editors can support all languages with LSP at once. Gone are the days of implementing support for each language separately.

The protocol is like a simplified version of HTTP:

• Each message consists of a header and a content part.
• The header has a required Content-Length field for the content size in bytes, as well as an optional Content-Type field.
• The content uses JSON-RPC to describe the structure of requests, responses and notifications.

For example, imagine you’re editing the following Swift file:

protocol MyProtocol { }

struct MyStruct: My

After you begin typing : My to conform MyStruct to MyProtocol, your editor will send the following textDocument/completion request to the LSP server:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "textDocument/completion", // 1
    "params": {
        "textDocument": { // 2
            "uri": "file://Users/jari/Example.swift"
        },
        "position": { // 3
            "line": 2,
            "character": 19
        }
    }
}

Here’s what the request asks of your LSP server:

1. method tells the server what kind of command you’re sending. In this case, it’s completion.
2. textDocument tells the server what file it should be looking at.
3. position tells the server where exactly in the file it should be looking. Both values are zero-based.

After receiving the request, the LSP server — in your case SourceKit-LSP — will figure out possible completions and send the following response:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "label": "MyProtocol", // 1
            "kind": 8, // 2
            "insertText": "Protocol" // 3
        }
    ]
}

id links this response to the request. The fields in result do the following:

1. label indicates what text to show in the autocomplete window.
2. The kind of result tells the editor what kind of completion it is. This can change behavior. 8 indicates Interface, which is used for Swift protocols.
3. insertText is the actual text value that will be inserted at the cursor position. In this case, My is stripped since it’s already typed.

This approach allows the editor to serve autocomplete without it knowing you’re working on Swift files. Likewise, the LSP server will never know what editor you’re using. Pretty sneaky of you!

Combining Swift and the Language Server Protocol

Now that you know the basics of LSP, it’s time to work on your machine. If you don’t have VSCode installed, do so by following the instructions from the VSCode docs.

To install SourceKit-LSP, run the following commands in your Downloads directory:

curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash - # You can skip this command if you already have node installed.
sudo apt-get install -y nodejs # Same goes for this command.
git clone https://github.com/apple/sourcekit-lsp.git
cd sourcekit-lsp/

These commands install NodeJS and clone the sourcekit-lsp repo.

To build the sourcekit-lsp project, run the following command but replace FILE with the name of your toolchain and YOURUSER with your username:

swift package update  #1 
swift build -Xcxx -I/home/YOURUSER/swift/FILE/usr/lib/swift #2 
sudo mv .build/x86_64-unknown-linux-gnu/debug/sourcekit-lsp /usr/local/bin #3

These commands do the following:

1. Update the Swift packages to the latest versions required.
2. Build SourceKit-LSP from the source. The -I flag adds an extra directory where the C++ compiler will look for .h files.
3. Move the built binary to /usr/local/bin so VSCode can use it.

Next, navigate to the Editors/vscode directory. This directory contains all you need to create a VSCode extension that enables SourceKit-LSP.

To build and enable the extension, run the following command:

npm run createDevPackage && \
code --install-extension out/sourcekit-lsp-vscode-dev.vsix

This uses node and npm to create and install the extension into VSCode.

Go ahead and use it! Navigate back to your Todos/Starter directory and run the following:

rm -rf .build/
code .

This removes the .build directory because of a bug that causes LSP to crash if one already exists and start VSCode in the current directory.

Finally, update the following setting and restart VSCode. You can find your settings by pressing Control-+ and searching for the name of the setting.

"sourcekit-lsp.toolchainPath": "/home/YOURUSER/swift/FILE"

Run swift build, and give yourself a pat on the back. You successfully installed SourceKit-LSP for VSCode :]

To check if everything worked, open Sources/App/Controllers/TodoController.swift in VSCode and hover over any of the keywords. VSCode should now show a hover card with the related documentation. Awesome!