docs/libcurl/ABI

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