Перейти к основному содержимому

О внешних компонентах

Некоторые инструменты из набора ОПИ в своей работе используют внешние компоненты (AddIn) - динамические библиотеки на Rust, содержащие функции, реализация которых средствами 1С/OS затруднительна или невозможна. Несмотря на то, что при работе с функционалом ОПИ прямое взаимодействие с внешними компонентами не встречается, само их наличие сопряжено с некоторыми проблемами и неочевидными особенностями. Они описаны в этом разделе

Совместимость​

Все внешние компоненты, добавляемые в ОПИ, собираются под x64 и x32 версии Windows и Linux. Они хранятся в специальных zip-архивах, состоящих из четырех файлов библиотек - по одному для каждой из платформ соответственно. Однако на обеих платформах присутствуют свои ограничения по совместимости с конкретными версиями ОС и системными библиотеками

Хранение в репозитории​

Собранные zip-архивы и макеты Template.addin для 1С не хранятся в истории веток main и stable — они вынесены в orphan-ветку addins, чтобы не раздувать основную историю Git.

В этой ветке лежит одна актуальная сборка под текущую разработку в main. После клонирования main файлы по прежним путям (src/ru/OInt/addins/*.zip, src/en/OInt/addins/*.zip, **/CommonTemplates/*/Template.addin) в рабочем каталоге отсутствуют. Подтянуть их:

# Windows
src\addins\sync-addins.bat

# Linux / macOS / CI
bash src/addins/sync-addins.sh

Ветка stable содержит код последнего опубликованного релиза. Бинарники с addins рассчитаны на main и для stable могут не подойти (расхождение BSL-обёрток и нативного API). Работая со stable, соберите компоненты из src/addins на коммите этой ветки (build.bat) или возьмите архивы из соответствующего релиза.

Windows​

Релизные сборки компонент на Windows выполняются актуальным инструментарием MSVC. При этом в результирующие .dll могут попадать ссылки на функции системных библиотек Windows (kernel32, bcrypt, ws2_32 и др.), доступные только начиная с Windows 8 и Windows Server 2012. На более старых системах компоненты из стандартного релиза ОПИ могут не загружаться или завершаться с ошибкой при обращении к таким функциям

Для самостоятельной сборки компонент под Windows 7 / Server 2008 R2 в репозитории есть каталог src/addins/legacy-win7 со скриптами setup-win7-build-env.bat и build-win7-package.bat. Сборка использует nightly Rust с целевыми платформами win7-windows-msvc и может занимать заметно больше времени, чем стандартная. Готовый zip-архив можно использовать как пакет внешней компоненты или заменить им соответствующий архив из релиза в зависимости от используемой поставки. Подробнее в README.md этого каталога

Linux​

На Linux компоненты зависимы от наличия в системе трех вещей: glibc, gcc* и OpenSSL**

* Касается CLI и OneScript версий
** Касается библиотек, использующих функционал TLS

glibc​

glibc — библиотека C, которая обеспечивает системные вызовы и основные функции, такие как open, malloc, printf и т.д. Она всегда есть в дистрибутивах Linux на платформе x86, но может отличаться номером версии. Минимальная версия для работы компонент ОПИ - 2.18. Это соответствует таким дистрибутивам как CENTOS 7, RHEL 7, Fedora 19, Debian 8 и Ubuntu 12.04 (около 2013-2014 г.). На более старых дистрибутивах библиотеки, использующие внешние компоненты, работать не будут

gcc​

От версии набора компиляторов gcc зависит наличие в системе нужной версии библиотеки libstdc++.so.6, которая необходима для работы движка внешних компонент в CLI и OSPX версиях ОПИ. Минимальная версия - 7.5.0. Это соответствует CentOS 8, RHEL 8, Fedora 28, Debian 10 и Ubuntu 20.04, а также может быть настроено и на более низких версиях при доступности devtoolset-7

OpenSSL​

Библиотеки, имеющие функционал связанный с TLS, для его реализации линкуются к системным библиотекам OpenSSL версии 3.x - libssl.so.3 и libcrypto.so.3. Это относительно новая версия, которая используется по умолчанию в дистрибутивах, начиная с CENTOS 9, RHEL 9, Fedora 36, Debian 12 и Ubuntu 22.04 (около 2022-2023 г.). Для работы в более старых дистрибутивах, использующих OpenSSL 1.1 или старше, OpenSSL 3.x должен быть установлен или собран из исходников отдельно

Информация об использовании​

Информацию о том, что библиотека использует внешние компоненты, можно найти на первой странице ее документации по подобным сноскам:

Для реализации некоторых функции в этой библиотеке используется внешняя компонента
Пожалуйста, ознакомьтесь с разделом "О внешних компонентах" перед началом работы
Для работы этой библиотеки на Linux необходим OpenSSL 3.x
Узнать больше: "Об использовании OpenSSL во внешних компонентах"

Их отсутствие, в свою очередь, означает, что внешние компоненты при реализации библиотеки не использовались

Внешние компоненты НаКлиенте в версии для 1С:Предприятие​

Работа с методами, использующими внешние компоненты, в версии для 1С:Предприятие доступна как на стороне сервера, так и на стороне клиента. Но, в отличии от серверного варианта, где использование компонент скрыто и происходит бесшовно, в клиентском варианте внешние компоненты требуют обязательной интерактивной установки на конкретной клиентской машине. Этот процесс начинается при первом вызове функции для каждой используемой компоненты и сопровождается выводом диалогового окна, а также исключением с информацией о необходимости вызвать ранее запущенную функцию повторно

Кроме автоматической установки компонент по необходимости, выбранные компоненты могут также быть установлены на конкретном клиенте заранее через обработку Панель управления (ОПИ)

warning

При обновлении Открытого пакета интеграций до новой версии, компоненты на клиенте необходимо установить заново через панель управления (пошаговая инструкция присутствует на форме обработки). В противном случае новые функции, реализованные в коде 1С, могут оказаться несовместимы с функциями компонент, которые остались на клиентской машине после предыдущей установки

FAQ​

Некоторые вопросы о работе и реализации внешних компонент, несвязанные напрямую с работой ОПИ

1. Можно ли пересобрать внешние компоненты?

Можно. Исходный код на Rust лежит в репозитории по пути src/addins. Собранные компоненты должны быть помещены в zip-архив с файлом манифеста. Скрипт build.bat кладёт архивы в четыре рабочих каталога и описывает процесс релизной сборки. Чтобы опубликовать результат в ветку addins, используйте src/addins/publish-addins.bat; для получения уже опубликованных бинарников после клонирования main — sync-addins.bat / sync-addins.sh (см. Хранение в репозитории). Для поставки конечному пользователю можно также заменить архив из релиза. Для Windows 7 / Server 2008 R2 используйте отдельный каталог legacy-win7 — см. раздел Windows

2. Можно ли пересобрать внешние компоненты, зависимые от OpenSSL, под OpenSSL 1.1/1.1.1k?

Мои попытки сделать это не увенчались успехом: даже при успешной линковке libssl.so.1.1, зависимости проекта на Rust (в частности, native-tls) требуют функций, которые в OpenSSL 1.1. еще не реализованы или были изменены в 3.x. Понижение версий крейтов до предела, на котором уже начинаются проблемы с безопасностью, не помогли. Однако, если вы знаете, как это обойти, то я буду очень рад, если вы напишите об этом в Issues

3. Почему OpenSSL слинкован динамически, а не статически?

Статическая линковка (помещение заранее собранного OpenSSL внутрь компоненты) сопряжена со множеством проблем: потенциальные конфликты при одновременной работе нескольких .so со статической линковкой, пытающихся использовать общие системные ресурсы одновременно (ERR_STATE, /dev/random и др.), раздувание размера файлов из-за необходимости иметь копию OpenSSL в каждой из компонент, невозможность обновить версию OpenSSL без пересборки проектов и др. В связи с этим, от статической линковки было решено отказаться

4. Можно ли увидеть полный список зависимостей конкретной компоненты?

В каталоге исходников каждой из компонент лежит файл dependencies.log - это вывод ldd и strings | grep GLIBC для x64 версии .so после сборки. Выглядит он примерно вот так:


"MAIN ---" 
	linux-vdso.so.1 (0x00007ffe4cd2e000)
	libssl.so.3 => not found
	libcrypto.so.3 => not found
	libm.so.6 => /lib64/libm.so.6 (0x00007f1ed1fb9000)
	libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f1ed1d99000)
	libc.so.6 => /lib64/libc.so.6 (0x00007f1ed19c2000)
	libdl.so.2 => /lib64/libdl.so.2 (0x00007f1ed17be000)
	/lib64/ld-linux-x86-64.so.2 (0x00007f1ed2562000)
GLIBC_2.2.5
GLIBC_2.3
GLIBC_2.3.4
GLIBC_2.14
GLIBC_2.17

Также, вы можете получить эту информацию самостоятельно, распаковав zip-архив с файлами библиотек и применив эти же (или другие) инструменты анализа к .so файлу, соответствующему вашей платформе

Техническая информация о сборке и разработке​

  • Все компоненты - cdylib на Rust, основанные на крейте addin1c от medigor
  • Сборка под Linux происходит при помощи zigbuild на OracleLinux 9.1 (WSL)
  • Profile.release:
	lto = "fat"
	codegen-units = 1
	panic = "unwind"
	strip = true
	opt-level = "z"