Skip to content

platform-help.md

Latest commit

 

History

History
191 lines (148 loc) · 11.4 KB

platform-help.md

File metadata and controls

191 lines (148 loc) · 11.4 KB
Raw

Справка платформы 1С: сборка корпуса и подключение

Справка платформы (синтаксис-помощник) питает hover, completion и разрешение имён по платформенным типам и методам. Анализатор читает её из корпуса — каталога-пакета с JSON и манифестом. Этот документ описывает два действия:

  1. собрать корпус из установленной платформы 1С;
  2. указать на него анализатору в конфигурации или переменной окружения.

Общее описание секции [platform_help] и остальных источников — в configuration/PROJECT_CONFIGURATION.md.

Корпус собирается из установленной у вас платформы 1С. Тексты справки — материал 1С, он не покрыт лицензиями проекта; публикация собранного корпуса — вопрос ваших прав на справку 1С. См. LICENSING.md и NOTICE.md, который кладётся в каждый пакет.

Что нужно

  • Установленная платформа 1С:Предприятие.
  • Каталог установки, в котором лежат оба архива справки: shcntx_ru.hbk и shlang_ru.hbk. Подойдёт каталог версии или его подкаталог bin: архивы ищутся сначала рядом с указанным каталогом, затем в его bin.
    • Windows: C:\Program Files\1cv8\<версия>\bin
    • Linux: /opt/1cv8/x86_64/<версия> (или его bin)
  • Бинарь анализатора. Ниже он называется bsl-analyzer; при запуске из исходников это cargo run -p bsl-analyzer --bin bsl-analyzer-app --.

Внешние программы (7z и т. п.) не нужны: архивы читаются самим анализатором.

Сборка корпуса

bsl-analyzer platform-help package
    (--hbk-dir <КАТАЛОГ> | --corpus <ФАЙЛ.json>)
    -o <НОВЫЙ_КАТАЛОГ>
    --corpus-id <ИМЯ_СБОРКИ>
    [--platform-version <ВЕРСИЯ>]
Флаг Назначение
--hbk-dir Каталог с shcntx_ru.hbk и shlang_ru.hbk (см. выше).
--corpus Вместо архивов — уже готовый корпус JSON, упаковывается как есть. Ровно один из --hbk-dir / --corpus обязателен.
-o, --output Новый каталог пакета. Он не должен существовать: существующий каталог не перезаписывается.
--corpus-id Стабильное имя сборки, например platform-help-8.3.27.2214. Обязателен.
--platform-version Версия платформы корпуса. По умолчанию берётся из имени каталога установки, если оно является номером версии (8.3.27.2214); иначе версия в манифесте не указывается.

Windows (PowerShell):

bsl-analyzer platform-help package `
  --hbk-dir "C:\Program Files\1cv8\8.3.27.2214\bin" `
  -o "D:\platform-help\8.3.27.2214" `
  --corpus-id platform-help-8.3.27.2214

Linux:

bsl-analyzer platform-help package \
  --hbk-dir /opt/1cv8/x86_64/8.3.27.2214 \
  -o ~/platform-help/8.3.27.2214 \
  --corpus-id platform-help-8.3.27.2214

Команда печатает манифест в JSON. Корпус перед записью проверяется на пригодность: пакет, который анализатор отверг бы, не создаётся.

Что получится

Каталог <НОВЫЙ_КАТАЛОГ> с тремя файлами:

Файл Содержимое
platform_data.json Корпус справки.
manifest.json schema_version (1), corpus_id, platform_version (может отсутствовать), extractor_version, corpus_file (platform_data.json), sha256 корпуса.
NOTICE.md Уведомление о том, что тексты корпуса — материал 1С.

Публикация

Пакет — обычные статические файлы; выложить его можно в любое доступное вам место, откуда их отдают по HTTP(S): веб-сервер, объектное хранилище, раздел релизов репозитория, общий сетевой каталог (для него подойдёт путь, URL не нужен). Требования для доступа по URL:

  • manifest.json и platform_data.json лежат в одном каталоге: корпус берётся по имени corpus_file относительно адреса манифеста;
  • манифест не больше 1 МиБ, корпус не больше 512 МиБ.

Проект не публикует корпус и не обещает его публикацию.

Подключение корпуса

Через конфигурацию

source = "external" и ровно один из двух ключей: path или url.

Локальный путь:

[platform_help]
source = "external"
path = "platform-help/8.3.27.2214"

path — каталог пакета с manifest.json, сам manifest.json либо отдельный platform_data.json (без манифеста версия справки считается неизвестной). Относительный путь отсчитывается от каталога файла конфигурации.

Адрес в сети:

[platform_help]
source = "external"
url = "https://example.org/platform-help/8.3.27.2214/manifest.json"

url — адрес manifest.json, а не каталога и не корпуса. Анализатор скачивает манифест и корпус, сверяет SHA-256 и только после этого сохраняет копию в кэше пользователя отдельно для этого адреса. Если адрес позже недоступен, используется последний валидный пакет того же адреса с предупреждением в журнале; если его нет — справки нет.

Пустое значение, оба ключа сразу или ни одного — ошибка конфигурации.

Через переменную окружения

export BSL_PLATFORM_HELP_CORPUS=/path/to/platform-help/8.3.27.2214
$env:BSL_PLATFORM_HELP_CORPUS = "D:\platform-help\8.3.27.2214"
export BSL_PLATFORM_HELP_CORPUS=https://example.com/platform-help/manifest.json

Значение — локальный путь (каталог пакета, manifest.json или platform_data.json) либо http://- или https://-адрес manifest.json. Адрес грузится тем же загрузчиком, что и url в [platform_help]: лимиты размера, SHA-256, кэш для этого адреса и откат на последний валидный пакет того же адреса. Пустое или состоящее из пробелов значение считается незаданным.

  • Схема http:// и https:// обрабатывается одинаково (регистр схемы не важен); http:// передаёт данные без шифрования. Молчаливого отката на встроенные факты нет.
  • Значение, похожее на URL, но не являющееся http://- или https://-адресом (https:/host/m.json, http:/host/m.json, https//host/m.json, //user:pw@host/m.json, user:pw@host/m.json, ftp://…), не считается путём: это ошибка конфигурации, значение в журнал не печатается. Путь с буквой диска (C:/help) и путь, лишь упоминающий схему (./https://x), остаются путями; значение с ?, # или @ тоже считается адресом, поэтому путь с такими символами задаётся через [platform_help] с path, а не переменной.
  • Переменная действует лишь когда в конфигурации нет секции [platform_help]: заданная секция всегда имеет приоритет, а непустая переменная при этом игнорируется с предупреждением в журнале.
  • Библиотека bsl-platform без приложения читает из переменной только путь; https://-адрес даёт явную ошибку в help_missing_reason, а не попытку прочитать файл с таким именем.
  • В журнал и сообщения об ошибках адрес попадает без user:password@, строки запроса и фрагмента: остаются схема, хост и путь.

Как убедиться, что источник подхватился

При запуске (LSP, analyze, MCP) в журнал пишется одна строка:

  • выбор источника переменной BSL_PLATFORM_HELP_CORPUS, уровень info — platform help source chosen by the environment variable с полем source;
  • переменная задана при наличии [platform_help], уровень warn — BSL_PLATFORM_HELP_CORPUS is ignored: the configuration has a [platform_help] section, which decides the source;
  • успех, уровень info — platform help loaded с полями source (external (<путь или url без userinfo и query>)), origin=external, location, platform_version, digest (SHA-256 корпуса), status, types, methods;
  • отказ, уровень warn — platform help unavailable; platform lookups and docs are empty с полем reason: причина (нет файла, не сошёлся SHA-256, адрес недоступен и т. п.).

Если принадлежащий адресу кэш использован вместо свежей загрузки, дополнительно пишется предупреждение serving the last valid package downloaded from this URL.

Источник выбирается один раз при запуске: после смены [platform_help] или переменной перезапустите сервер. Явно заданный источник другим не подменяется: если он не загрузился, справки нет, а анализатор продолжает работу.