aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl/ABI
diff options
context:
space:
mode:
authorDaniel Stenberg <daniel@haxx.se>2007-10-04 22:05:25 +0000
committerDaniel Stenberg <daniel@haxx.se>2007-10-04 22:05:25 +0000
commitbffa8355733160e5f0e950beecc97a75ef89c4f5 (patch)
treed46d7276affd5a98d358c354d296377f9097c9fa /docs/libcurl/ABI
parent6dd6b4d1faae3105b0414f233d3de199826f2e6a (diff)
The new file docs/libcurl/ABI describes how we view ABI breakages, soname
bumps and what the version number's significance to all that is.
Diffstat (limited to 'docs/libcurl/ABI')
-rw-r--r--docs/libcurl/ABI51
1 files changed, 51 insertions, 0 deletions
diff --git a/docs/libcurl/ABI b/docs/libcurl/ABI
new file mode 100644
index 000000000..06783b569
--- /dev/null
+++ b/docs/libcurl/ABI
@@ -0,0 +1,51 @@
+ _ _ ____ _
+ ___| | | | _ \| |
+ / __| | | | |_) | |
+ | (__| |_| | _ <| |___
+ \___|\___/|_| \_\_____|
+
+ libcurl's binary interface
+
+ABI
+
+ First, allow me to define the word for this context: ABI describes the
+ low-level interface between an application program a library. Calling
+ conventions, function arguments, return values, struct sizes/defines and
+ more.
+
+Upgrades
+
+ In the vast majority of all cases, a typical libcurl upgrade does not break
+ the ABI at all. Your application can remain using libcurl just as before,
+ only with less bugs and possibly with added new features. You need to read
+ the release notes, and if they mention an ABI break/soname bump, you may
+ have to verify that your application still builds fine and uses libcurl as
+ it now is defined to work.
+
+Version Numbers
+
+ In libcurl land, you really can't tell by the libcurl version number if that
+ libcurl is binary compatible or not with another libcurl version.
+
+Soname Bumps
+
+ Whenever there are changes done to the library that will cause an ABI
+ breakage, that may require your application to get attention or possibly be
+ changed to adhere to new things, we will bump the soname. Then the library
+ will get a different output name and thus can in fact be installed in
+ parallell with an older installed lib (on most systems). Thus, old
+ applications built against the previous ABI version will remain working and
+ using the older lib, while newer applications build and use the newer one.
+
+ During the first seven years of libcurl releases, there have only been four
+ ABI breakages.
+
+Downgrades
+
+ Going to an older libcurl version from one you're currently using can be a
+ tricky thing. Mostly we add features and options to newer libcurls as that
+ won't break ABI or hamper existing applications. This has the implication
+ that going backwards may get you in a situation where you pick a libcurl
+ that doesn't support the options your application needs. Or possibly you
+ even downgrade so far so you cross an ABI break border and thus a different
+ soname, and then your application may need to adapt to the modified ABI.