1                                  _   _ ____  _
2                              ___| | | |  _ \| |
3                             / __| | | | |_) | |
4                            | (__| |_| |  _ <| |___
5                             \___|\___/|_| \_\_____|
6
7                          libcurl's binary interface
8
9ABI - 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
19Upgrades
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
28Version 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
33Soname 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
46Downgrades
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
56History
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
70