From 2a0269589a7dc536b2b42f0a75d7dbcacb6a4d69 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 12 Jun 2020 13:26:20 +0200 Subject: ABI.md: rename to .md and polish the markdown Closes #5562 --- docs/libcurl/ABI | 68 ------------------------------------------------ docs/libcurl/ABI.md | 63 ++++++++++++++++++++++++++++++++++++++++++++ docs/libcurl/Makefile.am | 4 +-- 3 files changed, 65 insertions(+), 70 deletions(-) delete mode 100644 docs/libcurl/ABI create mode 100644 docs/libcurl/ABI.md diff --git a/docs/libcurl/ABI b/docs/libcurl/ABI deleted file mode 100644 index c7c914202..000000000 --- a/docs/libcurl/ABI +++ /dev/null @@ -1,68 +0,0 @@ -ABI - Application Binary Interface -================================== - - "ABI" describes the low-level interface between an application program and a - library. Calling conventions, function arguments, return values, struct - sizes/defines and more. - - [Wikipedia has a longer description](https://en.wikipedia.org/wiki/Application_binary_interface) - -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 - parallel 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. - - We are determined to bump the SONAME as rarely as possible. Ideally, we - never do it again. - -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. - -History -------- - - The previous major library soname number bumps (breaking backwards - compatibility) have happened the following times: - - 0 - libcurl 7.1, August 2000 - - 1 - libcurl 7.5 December 2000 - - 2 - libcurl 7.7 March 2001 - - 3 - libcurl 7.12.0 June 2004 - - 4 - libcurl 7.16.0 October 2006 diff --git a/docs/libcurl/ABI.md b/docs/libcurl/ABI.md new file mode 100644 index 000000000..39134a1ae --- /dev/null +++ b/docs/libcurl/ABI.md @@ -0,0 +1,63 @@ +ABI - Application Binary Interface +================================== + + "ABI" describes the low-level interface between an application program and a + library. Calling conventions, function arguments, return values, struct + sizes/defines and more. + + [Wikipedia has a longer description](https://en.wikipedia.org/wiki/Application_binary_interface) + +## 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 + parallel 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. + + We are determined to bump the SONAME as rarely as possible. Ideally, we + never do it again. + +## 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. + +## History + + The previous major library soname number bumps (breaking backwards + compatibility) have happened the following times: + + 0 - libcurl 7.1, August 2000 + + 1 - libcurl 7.5 December 2000 + + 2 - libcurl 7.7 March 2001 + + 3 - libcurl 7.12.0 June 2004 + + 4 - libcurl 7.16.0 October 2006 diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 041f02ea4..8681dbdfb 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -5,7 +5,7 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2018, Daniel Stenberg, , et al. +# Copyright (C) 1998 - 2020, Daniel Stenberg, , et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms @@ -38,7 +38,7 @@ dist_m4macro_DATA = libcurl.m4 CLEANFILES = $(HTMLPAGES) $(PDFPAGES) $(TESTS) $(man_DISTMANS) \ libcurl-symbols.3 -EXTRA_DIST = $(man_MANS) ABI symbols-in-versions symbols.pl \ +EXTRA_DIST = $(man_MANS) ABI.md symbols-in-versions symbols.pl \ mksymbolsmanpage.pl CMakeLists.txt MAN2HTML= roffit --mandir=. $< >$@ -- cgit v1.2.3