ABI.md (2497B)
1 <!-- 2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4 SPDX-License-Identifier: curl 5 --> 6 7 ABI - Application Binary Interface 8 ================================== 9 10 "ABI" describes the low-level interface between an application program and a 11 library. Calling conventions, function arguments, return values, struct 12 sizes/defines and more. 13 14 [Wikipedia has a longer description](https://en.wikipedia.org/wiki/Application_binary_interface) 15 16 ## Upgrades 17 18 A libcurl upgrade does not break the ABI or change established and documented 19 behavior. Your application can remain using libcurl just as before, only with 20 fewer bugs and possibly with added new features. 21 22 ## Version Numbers 23 24 In libcurl land, you cannot tell by the libcurl version number if that 25 libcurl is binary compatible or not with another libcurl version. As a rule, 26 we do not break the ABI so you can *always* upgrade to a later version without 27 any loss or change in functionality. 28 29 ## SONAME Bumps 30 31 Whenever there are changes done to the library that causes an ABI breakage, 32 that may require your application to get attention or possibly be changed to 33 adhere to new things, we bump the SONAME. Then the library gets a different 34 output name and thus can in fact be installed in parallel with an older 35 installed lib (on most systems). Thus, old applications built against the 36 previous ABI version remains working and using the older lib, while newer 37 applications build and use the newer one. 38 39 During the first seven years of libcurl releases, there have only been four 40 ABI breakages. 41 42 We are determined to bump the SONAME as rarely as possible. Ideally, we never 43 do it again. 44 45 ## Downgrades 46 47 Going to an older libcurl version from one you are currently using can be a 48 tricky thing. Mostly we add features and options to newer libcurls as that 49 does not break ABI or hamper existing applications. This has the implication 50 that going backwards may get you in a situation where you pick a libcurl that 51 does not support the options your application needs. Or possibly you even 52 downgrade so far so you cross an ABI break border and thus a different 53 SONAME, and then your application may need to adapt to the modified ABI. 54 55 ## History 56 57 The previous major library SONAME number bumps (breaking backwards 58 compatibility) 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