docs/libcurl/ABI

   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