| 1 |
ABI - Application Binary Interface |
| 2 |
================================== |
| 3 |
|
| 4 |
"ABI" describes the low-level interface between an application program and a |
| 5 |
library. Calling conventions, function arguments, return values, struct |
| 6 |
sizes/defines and more. |
| 7 |
|
| 8 |
[Wikipedia has a longer description](https://en.wikipedia.org/wiki/Application_binary_interface) |
| 9 |
|
| 10 |
Upgrades |
| 11 |
-------- |
| 12 |
|
| 13 |
In the vast majority of all cases, a typical libcurl upgrade does not break |
| 14 |
the ABI at all. Your application can remain using libcurl just as before, |
| 15 |
only with less bugs and possibly with added new features. You need to read |
| 16 |
the release notes, and if they mention an ABI break/soname bump, you may have |
| 17 |
to verify that your application still builds fine and uses libcurl as it now |
| 18 |
is defined to work. |
| 19 |
|
| 20 |
Version Numbers |
| 21 |
--------------- |
| 22 |
|
| 23 |
In libcurl land, you really can't tell by the libcurl version number if that |
| 24 |
libcurl is binary compatible or not with another libcurl version. |
| 25 |
|
| 26 |
Soname Bumps |
| 27 |
------------ |
| 28 |
|
| 29 |
Whenever there are changes done to the library that will cause an ABI |
| 30 |
breakage, that may require your application to get attention or possibly be |
| 31 |
changed to adhere to new things, we will bump the soname. Then the library |
| 32 |
will get a different output name and thus can in fact be installed in |
| 33 |
parallel with an older installed lib (on most systems). Thus, old |
| 34 |
applications built against the previous ABI version will remain working and |
| 35 |
using the older lib, while newer applications build and use the newer one. |
| 36 |
|
| 37 |
During the first seven years of libcurl releases, there have only been four |
| 38 |
ABI breakages. |
| 39 |
|
| 40 |
We are determined to bump the SONAME as rarely as possible. Ideally, we |
| 41 |
never do it again. |
| 42 |
|
| 43 |
Downgrades |
| 44 |
---------- |
| 45 |
|
| 46 |
Going to an older libcurl version from one you're currently using can be a |
| 47 |
tricky thing. Mostly we add features and options to newer libcurls as that |
| 48 |
won't break ABI or hamper existing applications. This has the implication |
| 49 |
that going backwards may get you in a situation where you pick a libcurl that |
| 50 |
doesn't support the options your application needs. Or possibly you even |
| 51 |
downgrade so far so you cross an ABI break border and thus a different |
| 52 |
soname, and then your application may need to adapt to the modified ABI. |
| 53 |
|
| 54 |
History |
| 55 |
------- |
| 56 |
|
| 57 |
The previous major library soname number bumps (breaking backwards |
| 58 |
compatibility) have happened the following times: |
| 59 |
|
| 60 |
0 - libcurl 7.1, August 2000 |
| 61 |
|
| 62 |
1 - libcurl 7.5 December 2000 |
| 63 |
|
| 64 |
2 - libcurl 7.7 March 2001 |
| 65 |
|
| 66 |
3 - libcurl 7.12.0 June 2004 |
| 67 |
|
| 68 |
4 - libcurl 7.16.0 October 2006 |