[devel] переработанный документ SharedLibsPolicy

* [devel] переработанный документ SharedLibsPolicy
@ 2025-08-07 11:46 Anton Farygin
  2025-08-07 12:57 ` Dmitry V. Levin
  2025-08-07 14:20 ` [devel] переработанный документ SharedLibsPolicy (update 1) Anton Farygin
  0 siblings, 2 replies; 6+ messages in thread
From: Anton Farygin @ 2025-08-07 11:46 UTC (permalink / raw)
  To: ALT Linux Team development discussions

Всем привет.

Текущая версия документа |SharedLibsPolicy| в ALT Linux устарела как с 
точки зрения структуры, так и с точки зрения стиля подачи. Она написана 
сложным, перегруженным языком, что затрудняет понимание даже для опытных 
мейнтейнеров. В документе отсутствует чёткое разграничение между 
правилами, исключениями и примерами. Это приводит к неоднозначной 
трактовке, ошибкам в упаковке библиотек и затруднениям при сопровождении 
нескольких версий ABI.

Я предлагаю прочитать обновлённую версию данной политики, в которой я 
постарался сделать документ более читабельным и раскрыл некоторые 
тяжёлые для понимания моменты.

На мой взгляд я не забыл ничего из старого документа, если что-то 
заметите - напишите пожалуйста.

Текущая версия:
https://www.altlinux.org/Shared_Libs_Policy

Новая версия:

{{DraftPolicy
|responsible=PavlovKonstantin, AntonFarygin, IgorVlasenko
|metabug=repocop тесты library-pkgnames, lib-contains-devel-so
}}

== Shared Libs Policy ==

=== Определения ===

Разделяемая библиотека (shared library) — это файл с расширением .so, 
который предназначен для использования сразу несколькими программами.

Плагин — .so-файл, который загружается напрямую одним конкретным 
приложением (например, через dlopen). Такие файлы не попадают под это 
полиси.

=== Цель ===

Позволить библиотекам с разными несовместимыми ABI-версиями 
сосуществовать в системе. Это снижает риски поломок при обновлении, 
упрощает сопровождение и позволяет проводить обновления более гибко.

'''Кратко''':
''Нельзя класть новую библиотеку с новым soname в тот же бинарный пакет, 
где была старая.''

=== Библиотека (runtime часть) ===

* Каждая несовместимая версия библиотеки должна быть в отдельном 
бинарном пакете.
* Название пакета: `libfoo%abiversion`
* Если имя библиотеки заканчивается на цифру, то используется 
подчёркивание: `libfoo_%abiversion`
* В пакете не должно быть файлов с путями, не содержащими номер ABI.

Если есть общие файлы (напр., man-страницы, примеры), их нужно вынести в 
`libfoo-common`.
*Общий (-common) пакет должен быть только один — он используется всеми 
ABI-версиями библиотеки.
*-common пакет не должен включать файлы, которые зависят от ABI.
*Старый (Legacy) ABI-специфичный пакет не должен иметь жёсткой 
версионированной зависимости (Requires: с конкретной версией) от 
libfoo-common.

Пример: [https://packages.altlinux.org/sisyphus/srpms/libxmlb/specfiles/ 
libxmlb]

=== Имя исходного пакета ===

* Имя **исходного пакета (SRPM)** желательно сохранять таким же, как у 
апстрима — это упрощает отслеживание обновлений, использование 
автоматических инструментов (`repology.or`, `repocop`) и повышает 
предсказуемость.

* Однако, при обновлении библиотеки с '''ломкой ABI''', когда требуется 
сохранить в репозитории старую версию библиотеки:
   * исходный пакет со старой версией нужно **сохранять под отдельным 
именем** (например, `libfoo1`, `libfoo0`, `libfoo3.2`);
   * новый ABI собирается уже из SRPM с апстримным именем (`libfoo`), а 
старый SRPM остаётся в репозитории под переименованным именем.

* Таким образом, в репозитории могут одновременно присутствовать 
несколько SRPM, каждый из которых собирает свою версию ABI:
   - `libfoo` → собирает `libfoo2`, `libfoo-devel`, ...
   - `libfoo1` → собирает `libfoo1`

* Для бэкпортов:
   * имя SRPM должно соответствовать новому ABI;
   * старые SRPM не модифицируются;
   * оба SRPM должны собирать бинарные пакеты, которые могут быть 
установлены параллельно (если это возможно).

* Как только в репозитории **не останется ни одного пакета**, 
использующего старую версию ABI:
   * соответствующий SRPM (и его бинарные пакеты) должен быть **удалён**;
   * это уменьшает нагрузку на инфраструктуру и снижает риски путаницы;
   * наличие библиотеки в `System/Legacy libraries` не освобождает от 
этого требования — она должна быть удалена, если не используется ни 
одним другим пакетом.

* Для автоматизации отслеживания можно использовать:
   * `apt-cache rdepends libfoo1`
   * скрипты из `repocop` и `srpm-uploader`
   * веб-интерфейса [https://packages.altlinux.org 
packages.altlinux.org] → вкладка пакета '''Аналитика''' → '''Зависящие 
пакеты'''

=== development-файлы ===

* Заголовочные файлы и `.so`-файл без версии (используемый для линковки) 
должны быть вынесены в отдельный `-devel` пакет.

* По умолчанию `-devel` пакет должен быть только **один** — и он должен 
относиться к самой новой версии библиотеки:
   - `libfoo-devel`
   - или, если есть несколько версий ABI в системе: 
`libfoo%abiversion-devel`

* Поддержка нескольких `-devel` пакетов (например, `libfoo1-devel` и 
`libfoo2-devel`) допускается **только в исключительных случаях**, когда:
   - большое количество клиентов ещё не может быть пересобрано под новую 
библиотеку;
   - либо API существенно отличается, и одновременная поддержка 
действительно необходима.

* В случае одновременного существования нескольких `-devel` пакетов, они 
должны иметь явные `Conflicts:` друг с другом, чтобы исключить их 
совместную установку.

Для `.a` файлов:

* Если вместе с `.so`: `libfoo-devel-static` или 
`libfoo%abiversion-devel-static`
* Если только `.a`: просто `libfoo-devel`

Файлы, не предназначенные для линковки, а работающие как плагины 
(`dlopen`), не попадают под полиси. Пример: `libtcnative-1.so` из 
`tomcat-native`.

Об исключениях стоит сообщать в багзиллу: 
`altlinux-policy-shared-lib-contains-devel-so`

=== Пример упаковки разных ABI ===

Пакет с разными версиями ABI должен содержать только одну из них. Если 
библиотека имеет несколько .so с разными ABI — каждую версию упаковывают 
в отдельный пакет.

Пример: [https://packages.altlinux.org/sisyphus/srpms/ffmpeg/ ffmpeg]

== Как выбирать %abiversion ==

Если библиотека использует `soversion` — используем его как %abiversion.

Если `soversion` отсутствует или нестабилен — используем:

* возрастающее число: `libfoo0`, `libfoo1`
* major-версию: `libqt3`, `libqt4`
* major.minor: `libdb4.0`, `libdb4.1`
* часть soname: `libcurl4`, `libflac8`

== Что делать при ломке ABI ==

Допустим, soname изменился с N на M:

# Переименовать бинарный пакет `libfoo` → `libfooM` (или `libfooN` → 
`libfooM`)
# Проверить совместимость при установке:
   hsh-install libfoo libfooM

== Поддержка клиентов библиотеки ==

Рекомендуется иметь только один `-devel` пакет — для самой новой версии.

Если новая версия несовместима и вызывает ошибки сборки у многих пакетов 
— допустимо иметь 2 `-devel` пакета с `Conflicts` друг на друга. 
Зависимые пакеты разделяются по версии сборки.

Для `libfooM-devel` желательно прописывать:
   Provides: libfoo-devel = %EVR

== Старые версии библиотек ==

* Старые библиотеки помещаются в группу `System/Legacy libraries`.
* Они удаляются, если не используются другими пакетами.
* Такие пакеты не проходят в [[Branches|стабильные ветки]].

== Возможные проблемы ==

* Если два пакета конфликтуют по путям, они не смогут сосуществовать — 
тогда старую версию нужно удалить, а все зависимости — пересобрать.
* Проблемы apt при переименовании пакетов: 
[http://lists.altlinux.org/pipermail/devel/2009-May/171113.html пример]
* В одной программе могут оказаться разные версии одной библиотеки через 
цепочку зависимостей (libX → libZ1, libY → libZ2) — возможны трудные для 
отладки ошибки.

== Ссылки ==
* [[Shared Libs Policy Comments|Комментарий к Shared Libs Policy с 
пошаговой инструкцией]]
* [https://www.debian.org/doc/debian-policy/ch-sharedlibs.html 
https://www.debian.org/doc/debian-policy/ch-sharedlibs.html]
* [[API or ABI changing|Смена API/ABI]]
* [[Shared Libs Policy and updates|Данное полиси и обновления]]
* [[Shared Library Symbol Versioning HOWTO]]

^ permalink raw reply	[flat|nested] 6+ messages in thread