DOCSEARCHbyAlgolia
Submit Docs

FsAutoComplete Documentation

repository·main·Indexed 19 days ago

https://github.com/ionide/fsautocomplete

A Language Server Protocol (LSP) implementation providing F# intelligence, including intellisense, linting, and formatting. It integrates FSharp.Compiler.Service, Ionide.ProjInfo, FSharpLint, and Fantomas. Documentation covers the communication protocol, LSP endpoints, configuration settings, OpenTelemetry tracing with Jaeger, and guides for developers to create new code fixes.

Tokens
3K
Snippets
7
Records
15
Agent score
67%

What's inside FsAutoComplete

  1. Overview of FsAutoComplete

    main

    FsAutoComplete (FSAC) is a backend service that provides rich editing and intellisense features for F# by implementing the Language Server Protocol (LSP). It serves as the language intelligence engine for various editor extensions.

    It integrates several key technologies:

    • FSharp.Compiler.Service: Provides F# language information.
    • Ionide.ProjInfo: Handles project and solution management.
    • FSharpLint: Provides linting features.
    • Fantomas: Provides F# code formatting.

  2. FsAutoComplete Documentation Overview

    main

    FsAutoComplete is a language server providing F# and potentially other .NET language support. The documentation is organized into three main areas:

    • Communication Protocol: Details the LSP (Language Server Protocol) implementation, including endpoints, custom notifications, initialization options, startup flags, and editor settings.
    • OpenTelemetry: Instructions on how to enable and visualize distributed traces for monitoring the language server.
    • Creating a New Code Fix: A guide for developers looking to extend the server by adding new code fixes or quick actions.

  3. Run unit tests for a new code fix

    main

    The scaffolding process includes a single focused test to allow for rapid verification of your new code fix. You can run this test using either dotnet test or dotnet run targeting the LSP test project.

    Option 1: Using dotnet test

    dotnet test -f net8.0 ./test/FsAutoComplete.Tests.Lsp/FsAutoComplete.Tests.Lsp.fsproj

    Option 2: Using dotnet run

    dotnet run -f net8.0 --project ./test/FsAutoComplete.Tests.Lsp/FsAutoComplete.Tests.Lsp.fsproj

  4. Configure LSP endpoints, settings, and communication

    main

    For details on how to integrate with the Language Server Protocol, refer to the Communication Protocol documentation. This includes information on:

    • Supported LSP endpoints
    • Custom endpoints
    • Notifications
    • Startup options
    • Initialization options
    • Settings

  6. Scaffold a new code fix

    main

    To create a new code fix (also known as a quick fix or code action), use the provided FAKE target to automate the generation of implementation, signature, and unit test files. This command also handles the necessary registration in the LSP server and the test suite.

    Run the following command, replacing YourCodeFixName with the name of your fix:

    dotnet fsi build.fsx -- -p ScaffoldCodeFix YourCodeFixName

    This process generates:

    • An implementation file.
    • A signature file.
    • A dedicated standalone unit test file.

    It also automatically updates:

    • src/FsAutoComplete/LspServers/AdaptiveState.fs (LSP registration)
    • test/FsAutoComplete.Tests.Lsp/CodeFixTests/Tests.fs (Test registration)

  9. Prepare a code fix for Pull Request

    main

    Before submitting a pull request for a new code fix, follow these cleanup and formatting steps:

    1. Clean up code: Remove any extraneous code or comments left over from the scaffolded sample code.
    2. Format source: Run the Fantomas formatter to ensure proper code style:
      dotnet fantomas src
    3. **Unfocus tests**: Ensure you have removed any focused tests (e.g., using Expecto's focus feature), as focused tests will cause the continuous integration (CI) build to fail.

  10. Start FsAutoComplete with command-line options

    main

    When launching the FsAutoComplete language server, you can use the following flags and environment variables to configure its behavior:

    Command-line Flags

    • --state-directory <dir>: Specifies a workspace-specific directory for storing language server state.
    • --verbose: Enables additional logging output to stderr.
    • --otel-exporter-enabled: Enables OpenTelemetry trace export.

    Environment Variables

    • DOTNET_ROOT: Sets the dotnet SDK root used when searching for references for FSX scripts.

  11. Export traces with Jaeger

    main

    FsAutoComplete uses System.Diagnostics.Activity to create traces. To visualize these traces using Jaeger, follow these steps:

    1. Run Jaeger via Docker: Start a Jaeger instance with OTLP enabled to receive traces.
    2. Configure Environment: Set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable to point to your Jaeger collector (typically http://localhost:4317).
    3. Enable Tracing in FsAutoComplete: Start the process with the --otel-exporter-enabled flag.
    4. Inspect Traces: Perform actions in your editor (e.g., opening documents, saving, or getting tooltips) and then visit http://localhost:16686/ to view the captured traces.
    # 1. Run Jaeger
docker run -d --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=9411 \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 14250:14250 \
  -p 14268:14268 \
  -p 14269:14269 \
  -p 9411:9411 \
  jaegertracing/all-in-one:latest

# 2. Configure Environment
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"

# 3. Start FsAutoComplete
dotnet fsautocomplete --otel-exporter-enabled

  12. Configure Automatic Workspace Initialization

    main

    You can enable automatic workspace loading by sending the AutomaticWorkspaceInit option within the initializationOptions of the LSP initialize request.

    When set to true, FsAutoComplete starts loading the workspace automatically without requiring explicit fsharp/workspacePeek and fsharp/workspaceLoad calls. It selects the top workspace based on these rules:

    1. All projects if no .sln files are found.
    2. The single .sln file if exactly one is found.
    3. The .sln file with the most projects if multiple are found.

    This is intended for clients that do not support custom workspace-selection UIs.