Реализация клиентов

Краткое руководство по внедрению поддержки RLS в ваш любимый редактор.

В большинстве случаев вам потребуется реализовать расширение или плагин в формате и языке, которые требуются вашим редактором. Существует два основных случая — когда уже есть поддержка LSP и когда её нет. В первом случае внедрение намного проще, к счастью, многие редакторы теперь поддерживают LSP как нативно, так и с помощью расширений.

Если поддержка LSP уже существует, вы можете получить довольно хорошую "из коробки" работу с RLS — вы получите ключевые функции, такие как автозавершение кода и переименование. Однако это недостаточное пользовательское решение. Сравнивая с полной поддержкой в редакторе, вы теряете:

• удобство обнаружения и настройки
  • нет простого в установке расширения для Rust
  • нет места для отслеживания ошибок
  • пользователь должен управлять RLS (установка, обновление, расположение и т.д.)
• неровности пользовательского опыта
  • например, нет индикатора работы RLS
• ошибки
  • вероятно, есть ошибки как в реализации клиента редактора, так и в RLS, которые не обнаруживаются в других сценариях использования
  • или несоответствия в недостаточно описанных частях LSP
  • требуется тестирование для обнаружения таких проблем
• расширения базового протокола LSP
  • RLS поддерживает дополнительные рефакторинги и поиски как расширения базового LSP## Предварительные условия

Проверьте отслеживаемый вопрос, чтобы узнать, существует ли уже поддержка или находится в разработке. Если нет, оставьте комментарий там, чтобы сообщить нам о начале работы. Если вы хотите, откройте вопрос, посвящённый вашему редактору, если он ещё не существует. Вы должны ознакомиться с вопросами с меткой clients.

Если есть вещи, которые можно исправить на стороне RLS, пожалуйста, отправьте PR или откройте вопрос.

Найдите информацию о экосистеме расширений вашего редактора — свяжитесь с сообществом, узнайте, есть ли поддержка LSP, найдите каналы поддержки и т.д.

Когда уже есть поддержка LSP

Если ваш редактор поддерживает LSP, то запуск и настройка довольно просты. Вам нужно способом запустить RLS и указать редактору, чтобы его клиент LSP подключался к нему. Надеюсь, что это всего лишь несколько строк кода. Следующим шагом является обеспечение перезапуска RLS после сбоя — клиент LSP может или может не делать это автоматически (VSCode будет делать это пять раз перед остановкой). После того как базовая поддержка будет введена, начинается тяжелая работа:* Реализация расширений протокола

• Настройка клиента.
  • Вам потребуется отправлять уведомление workspace/didChangeConfiguration, когда меняется конфигурация.
  • Для опций конфигурации см. config.rs
• Проверка и установка RLS
  • следует использовать Rustup
  • следует проверять, установлен ли RLS (rls), и если нет, устанавливать его и компоненты rust-analysis и rust-src
  • следует обеспечить возможность обновления компонента RLS
• Функции клиента
  • например, фрагменты кода, задачи сборки, подсветка синтаксиса
• Тестирование
• Убедитесь в интеграции с существующими функциями Rust
  • например, подсветка синтаксиса
  • идеально, если пользователю потребуется только одно расширение
• 'Маркетинг'
  • потому что мы хотим, чтобы люди действительно использовали это расширение
  • документация - пользователи должны знать, как установить и использовать расширение
  • держите нас в курсе статуса, чтобы мы могли правильно рекламировать его
  • обновляйте веб-сайт RLS
  • отправьте расширение в менеджер пакетов или рынок редактора## В случае отсутствия поддержки LSP

Если ваш редактор не имеет существующей поддержки LSP, вам потребуется выполнить все вышеуказанное плюс реализовать (части) LSP. Это значительная работа, но, вероятно, не так ужасна, как кажется. LSP — это довольно простой протокол JSON через stdio. Интересная часть — это привязка клиентской части протокола к функциональности вашего редактора.

Требуемая поддержка сообщений

RLS в настоящее время требует поддержки следующих сообщений. Обратите внимание, что мы часто используем далеко не все опции, поэтому даже с этим подмножеством вам не нужно реализовывать все.

Уведомления:

• exit
• initialized
• textDocument/didOpen
• textDocument/didChange
• textDocument/didSave
• workspace/didChangeConfiguration
• workspace/didChangeWatchedFiles
• cancel

Запросы:

• shutdown
• initialize
• textDocument/definition
• textDocument/references
• textDocument/completion
• completionItem/resolve
• textDocument/rename
• textDocument/documentHighlight
• workspace/executeCommand
• textDocument/codeAction
• textDocument/documentSymbol
• textDocument/formatting
• textDocument/rangeFormatting
• textDocument/hover
• workspace/symbol

Со сервера на клиент:

• workspace/applyEdit
• client/registerCapability
• client/unregisterCapability

RLS также использует некоторые персонализированные сообщения.

Ресурсы* Спецификация LSP

• contributing.md - обзор RLS и инструкции по сборке, тестированию и т.д.
• Пример реализации в VSCode - пример того, как выглядит поддержка клиента
• Отслеживание задачи## Получение помощи

Мы готовы помочь вам любым способом. Лучший способ получить помощь — оставить комментарий к задаче в этом репозитории или связаться со мной (nrc) в #rust-dev-tools на IRC.