API or ABI changing

Смена API/ABI

Для начала надо бы уяснить, что такое API, и что такое ABI.

API - Application Programming Interface - это, образно говоря, набор объявлений типов, констант, прототипов функций библиотеки и вспомогательных макросов - то есть то, что лежит в .h файлах библиотеки, и используется при сборке исходного кода.

ABI - Application Binary Interface - это, образно говоря, набор функций, которые экспортируются из библиотеки, вместе с их параметрами, соглашениями вызова и т.д. Это используется при запуске программы.

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

Изменение API происходят на уровне исходного кода, и, становятся заметны только когда ломают сборку. Изменения API не всегда приводят к изменению ABI (и, соответственно, к несовместимости бинарного кода).

Как правило, в большинстве случаев (для которых и писалась SharedLibPolicy), изменение ABI происходит при неизменности API, то есть старые пакеты всего лишь надо пересобрать с новыми библиотеками.

Бывают также случаи, когда меняется API - то есть становятся несовместимыми devel-пакеты старой и новой библиотек. В таком случае приходится патчить исходный код каждой программы, использующей эту библиотеку, что обычно делается на уровне апстрима. Как правило, апстрим библиотеки при смене API публикует рекомендации по "переезду" со старой версии на новую (обычно сводящуюся к замене имен функций или структур).

Также можно рассмотреть случаи, когда изменился API и ABI, но совместимость с приложениями, собранными со старыми версиями библиотек осталась (допустим, была добавлена новая функция, которой не было в старой версии библиотеки). В таком случае правильным будет добавление версионирования символов, и soname менять вообще не надо.

В общем, каждый конкретный случай индивидуален, но вот что можно использовать в качестве критерия смены soname:

• Изменения соглашения вызова, количества параметров, типа параметров у какой-нибудь из существующих функций.
• Изменения структур (добавление/удаление/перемещение/изменение полей структур), используемых библиотекой.
• Удаление существующих функций

Критерий необходимости каких-то особых действий по смене API:

• Удаление полей структур, входящих в публичный API
• Удаление (или переименование) макросов или функций, или типов,

входящих в публичный API.

• Смена сигнатуры вызова функций, изменение количества и типов

параметров, типа возвращаемого значения и т.п. В общем, все, что ведет к невозможности пересборки с новой библиотекой без доделки исходного кода приложений.

В случае, когда ничего старого не меняется, а добавляется только новое - достаточно только версионирования символов.

Всё это касается языка С. Для С++ все гораздо хуже, там ABI очень хрупкий, и ломается очень легко, что приводит к необходимости смены soname практически всегда.

Damir Shayhutdinov damir at altlinux.org

Ссылки

• http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++