diff --git a/docs/libcurl/ABI b/docs/libcurl/ABI index ef0caa6f265316194934ef8c49c42e2cb13410ef..0121bb03597260e426f1fee467511ea319c7c6a9 100644 --- a/docs/libcurl/ABI +++ b/docs/libcurl/ABI @@ -1,63 +1,55 @@ - _ _ ____ _ - ___| | | | _ \| | - / __| | | | |_) | | - | (__| |_| | _ <| |___ - \___|\___/|_| \_\_____| - - libcurl's binary interface - ABI - Application Binary Interface ----------------------------------- +================================== - "ABI" describes the low-level interface between an application program and a - library. Calling conventions, function arguments, return values, struct - sizes/defines and more. + "ABI" describes the low-level interface between an application program and a + library. Calling conventions, function arguments, return values, struct + sizes/defines and more. - [Wikipedia has a longer description](http://en.wikipedia.org/wiki/Application_binary_interface) + [Wikipedia has a longer description](http://en.wikipedia.org/wiki/Application_binary_interface) Upgrades -------- - In the vast majority of all cases, a typical libcurl upgrade does not break - the ABI at all. Your application can remain using libcurl just as before, - only with less bugs and possibly with added new features. You need to read - the release notes, and if they mention an ABI break/soname bump, you may - have to verify that your application still builds fine and uses libcurl as - it now is defined to work. + In the vast majority of all cases, a typical libcurl upgrade does not break + the ABI at all. Your application can remain using libcurl just as before, + only with less bugs and possibly with added new features. You need to read + the release notes, and if they mention an ABI break/soname bump, you may have + to verify that your application still builds fine and uses libcurl as it now + is defined to work. Version Numbers --------------- - In libcurl land, you really can't tell by the libcurl version number if that - libcurl is binary compatible or not with another libcurl version. + In libcurl land, you really can't tell by the libcurl version number if that + libcurl is binary compatible or not with another libcurl version. Soname Bumps ------------ - Whenever there are changes done to the library that will cause an ABI - breakage, that may require your application to get attention or possibly be - changed to adhere to new things, we will bump the soname. Then the library - will get a different output name and thus can in fact be installed in - parallel with an older installed lib (on most systems). Thus, old - applications built against the previous ABI version will remain working and - using the older lib, while newer applications build and use the newer one. + Whenever there are changes done to the library that will cause an ABI + breakage, that may require your application to get attention or possibly be + changed to adhere to new things, we will bump the soname. Then the library + will get a different output name and thus can in fact be installed in + parallel with an older installed lib (on most systems). Thus, old + applications built against the previous ABI version will remain working and + using the older lib, while newer applications build and use the newer one. - During the first seven years of libcurl releases, there have only been four - ABI breakages. + During the first seven years of libcurl releases, there have only been four + ABI breakages. - We are determined to bump the SONAME as rarely as possible. Ideally, we - never do it again. + We are determined to bump the SONAME as rarely as possible. Ideally, we + never do it again. Downgrades ---------- - Going to an older libcurl version from one you're currently using can be a - tricky thing. Mostly we add features and options to newer libcurls as that - won't break ABI or hamper existing applications. This has the implication - that going backwards may get you in a situation where you pick a libcurl - that doesn't support the options your application needs. Or possibly you - even downgrade so far so you cross an ABI break border and thus a different - soname, and then your application may need to adapt to the modified ABI. + Going to an older libcurl version from one you're currently using can be a + tricky thing. Mostly we add features and options to newer libcurls as that + won't break ABI or hamper existing applications. This has the implication + that going backwards may get you in a situation where you pick a libcurl that + doesn't support the options your application needs. Or possibly you even + downgrade so far so you cross an ABI break border and thus a different + soname, and then your application may need to adapt to the modified ABI. History -------