VERSIONING

   1 -------------------
   2 Written by Ted T'so
   3 -------------------
   4
   5 > https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
   6 >
   7 > I understood that, if there is no interface change but some implementation
   8 > changes, I need to bump revision. If new interface is added, for example, I
   9 > need to bump current while revision=0 and age++.
  10
  11 So part of the problem here is that libtool is doing something really
  12 strange because they are trying to use some abstract concept that is
  13 OS-independent.  I don't use libtool because I find it horribly
  14 complex and doesn't add enough value to be worth the complexity.
  15
  16 So I'll tell you how things work with respect to Linux's ELF version
  17 numbering system.  Translating this to libtool's wierd "current,
  18 revision, age" terminology is left as an exercise to the reader.  I've
  19 looked at the libtool documentation, and it confuses me horribly.
  20 Reading it, I suspect it's wrong, but I don't have the time to
  21 experiment to confirm that the documentation is wrong and how it
  22 diverges from the libtool implementation.
  23
  24 So let me explain things using the ELF shared library terminology,
  25 which is "major version, minor version, patchlevel".  This shows up in
  26 the library name:
  27
  28         libudev.so.1.6.11
  29
  30 So in this example, the major version number is 1, the minor version
  31 is 6, and the patchlevel is 11.  The patchlevel is entirely optional,
  32 and many packages don't use it at all.  The minor number is also
  33 mostly useless on Linux, but it's still there for historical reasons.
  34 The patchlevel and minor version numbers were useful back for SunOS
  35 (and Linux a.out shared library), back when there weren't rpm and dpkg
  36 as package managers.
  37
  38 So many modern Linux shared libraries will only use the major and
  39 minor version numbers, e.g:
  40
  41         libext2fs.so.2.4
  42
  43 The only thing you really need to worry about is the major version
  44 number, really.  The minor version is *supposed* to change when new
  45 interfaces has changed (but I and most other people don't do that any
  46 more).  But the big deal is that the major number *must* get bumped if
  47 an existing interface has *changed*.
  48
  49 So let's talk about the major version number, and then we'll talk
  50 about why the minor version number isn't really a big deal for Linux.
  51
  52 So if you change any of the library's function signatures --- and this
  53 includes changing a type from a 32-bit integer to a 64-bit integer,
  54 that's an ABI breakage, and so you must bump the major version number
  55 so that a program that was linked against libfoo.so.4 doesn't try to
  56 use libfoo.so.5.  That's really the key --- will a program linked
  57 against the previous version library break if it links against the
  58 newer version.  If it does, then you need to bump the version number.
  59
  60 So for structures, if you change any of the existing fields, or if the
  61 application program allocates the structure --- either by declaring it
  62 on the stack, or via malloc() --- and you expand the structure,
  63 obviously that will cause problem, and so that's an ABI break.
  64
  65 If however, you arrange to have structures allocated by the library,
  66 and struct members are always added at the end, then an older program
  67 won't have any problems.  You can guarantee this by simply only using
  68 a pointer to the struct in your public header files, and defining the
  69 struct in a private header file that is not available to userspace
  70 programs.
  71
  72 Similarly, adding new functions never breaks the ABI.  That's because
  73 older program won't try to use the newer interfaces.  So if I need to
  74 change an interface to a function, what I'll generally do is to define
  75 a new function, and then implement the older function in terms of the
  76 newer one.  For example:
  77
  78 extern errcode_t ext2fs_open(const char *name, int flags, int superblock,
  79                              unsigned int block_size, io_manager manager,
  80                              ext2_filsys *ret_fs);
  81
  82 extern errcode_t ext2fs_open2(const char *name, const char *io_options,
  83                               int flags, int superblock,
  84                               unsigned int block_size, io_manager manager,
  85                               ext2_filsys *hret_fs);
  86
  87 As far as the minor version numbers are concerned, the dynamic linker
  88 doesn't use it.  In SunOS 4, if you have a DT_NEEDED for libfoo.so.4,
  89 and the dynamic linker finds in its search path:
  90
  91     libfoo.so.4.8
  92     libfoo.so.4.9
  93
  94 It will preferentially use libfoo.so.4.9.
  95
  96 That's not how it works in Linux, though.  In Linux there will be a
  97 symlink that points libfoo.so.4 to libfoo.so.4.9, and the linker just
  98 looks for libfoo.so.4.  One could imagine a package manager which
  99 adjusts the symlink to point at the library with the highest version,
 100 but given that libfoo.so.4.9 is supposed to contain a superset of
 101 libfoo.so.4.8, there's no point.  So we just in practice handle all of
 102 this in the package manager, or via an ELF symbol map.  Or, we just
 103 assume that since vast majority of software comes from the
 104 distribution, the distro package manager will just update libraries to
 105 the newer version as a matter of course, and nothing special needs to
 106 be done.
 107
 108 So in practice I don't bump the minor version number for e2fsprogs
 109 each time I add new interfaces, because in practice it really doesn't
 110 matter for Linux.  We have a much better system that gets used for
 111 Debian.
 112
 113 For example in Debian there is a file that contains when each symbol
 114 was first introduced into a library, by its package version number.
 115 See:
 116
 117 https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/tree/debian/libext2fs2.symbols
 118
 119 This file contains a version number for each symbol in libext2fs2, and
 120 it tells us what version of libext2fs you need to guarantee that a
 121 particular symbol is present in the library.  Then when *other*
 122 packages are built that depend on libext2fs2, the minimum version of
 123 libext2fs can be calculated based on which symbols they use.
 124
 125 So for example the libf2fs-format4 package has a Debian dependency of:
 126
 127 Depends: libblkid1 (>= 2.17.2), libc6 (>= 2.14), libf2fs5, libuuid1 (>= 2.16)
 128
 129 The minimum version numbers needed for libblkid1 and libuuid1 are
 130 determined by figuring out all of the symbols used by the
 131 libf2fs-format4 package, and determining the minimum version number of
 132 libblkid1 that supports all of those blkid functions.
 133
 134 This gets done automatically, so I didn't have to figure this out.
 135 All I have in the debian/control file is:
 136
 137 Depends: ${misc:Depends}, ${shlibs:Depends}
 138
 139 Sorry this got so long, but hopefully you'll find this useful.  How
 140 you bend libtool to your will is something you'll have to figure out,
 141 because I don't use libtool in my packages.[1]
 142
 143 Cheers,
 144
 145                                         - Ted
 146
 147
 148 [1] If you are interested in how I do things in e2fsprogs, take a look
 149 at the Makefile.elf-lib, Makefile.solaris-lib, Makefile.darwin-lib,
 150 etc. here:
 151
 152 https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/tree/lib
 153
 154 This these Makefile fragments are then pulled into the generated
 155 makefile using autoconf's substitution rules, here:
 156
 157 https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/tree/lib/ext2fs/Makefile.in
 158
 159 (Search for "@MAKEFILE_ELF@" in the above Makefile.in).
 160
 161 So when someone runs "configure --enable-elf-shlibs", they get the ELF
 162 shared libraries built.  On BSD and MacOS systems they just have to
 163 run "configure --enable-bsd-shlibs", and so on.
 164
 165 Personally, since most people don't bother to write truly portable
 166 programs, as their C code is full of Linux'isms, using libtool is just
 167 overkill, because they probably can't build on any other OS *anyway*
 168 so libtool's slow and complex abstraction layer is totally wasted.
 169 Might as well not use autoconf, automake, and libtool at all.
 170
 171 On the other hand, if you really *do* worry about portability on other
 172 OS's (e2fsprogs builds on MacOS, NetBSD, Hurd, Solaris, etc.) then
 173 using autoconf makes sense --- but I *still* don't think the
 174 complexity of libtool is worth it.
 175
 176 = Add-on =
 177 If you are going to be making one less major update, this is the
 178 perfect time to make sure that data structures are allocated by the
 179 library, and are (ideally) opaque to the calling application (so they
 180 only manipulate structure poitners).  That is, the structure
 181 definition is not exposed in the public header file, and you use
 182 accessor functions to set and get fields in the structure.
 183
 184 If you can't do that for all data structures, if you can do that with
 185 your primary data structure that's going to make your life much easier
 186 in the long term.  For ext2fs, that's the file systme handle.  It's
 187 created by ext2fs_open(), and it's passed to all other library
 188 functions as the first argument.
 189
 190 The other thing you might want to consider doing is adding a magic
 191 number to the beginning of each structure.  That way you can tell if
 192 the wrong structure gets passed to a library.  It's also helpful for
 193 doing the equivalent of subclassing in C.
 194
 195 This is how we do it in libext2fs --- we use com_err to define the
 196 magic numbers:
 197
 198         error_table ext2
 199
 200 ec      EXT2_ET_BASE,
 201         "EXT2FS Library version @E2FSPROGS_VERSION@"
 202
 203 ec      EXT2_ET_MAGIC_EXT2FS_FILSYS,
 204         "Wrong magic number for ext2_filsys structure"
 205
 206 ec      EXT2_ET_MAGIC_BADBLOCKS_LIST,
 207         "Wrong magic number for badblocks_list structure"
 208         ...
 209
 210 And then every single structure starts like so:
 211
 212 struct struct_ext2_filsys {
 213         errcode_t                       magic;
 214         ...
 215
 216 struct ext2_struct_inode_scan {
 217         errcode_t               magic;
 218         ...
 219
 220 And then before we use any pointer we do this:
 221
 222         if (file->magic != EXT2_ET_MAGIC_EXT2_FILE)
 223                 return EXT2_ET_MAGIC_EXT2_FILE;