diff options
| -rw-r--r-- | CHANGES | 4 | ||||
| -rw-r--r-- | docs/libcurl/ABI | 51 | ||||
| -rw-r--r-- | docs/libcurl/Makefile.am | 2 |
3 files changed, 56 insertions, 1 deletions
@@ -6,6 +6,10 @@ Changelog +Daniel S (5 October 2007) +- 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. + Daniel S (4 October 2007) - I enabled test 1009 and made the --local-port use a wide range to reduce the risk of failures. 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. diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index ea96cea1d..dbc04ce57 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -57,7 +57,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) -EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 ABI MAN2HTML= roffit --mandir=. < $< >$@ |