The new file docs/libcurl/ABI describes how we view ABI breakages, soname

                                  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.

                                  _   _ ____  _

                              ___| | | |  _ \| |

                             / __| | | | |_) | |

                            | (__| |_| |  _ <| |___

                             \___|\___/|_| \_\_____|

                          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.

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=. < $< >$@