--- /dev/null
+-------------------
+Written by Ted T'so
+-------------------
+
+> https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
+>
+> I understood that, if there is no interface change but some implementation
+> changes, I need to bump revision. If new interface is added, for example, I
+> need to bump current while revision=0 and age++.
+
+So part of the problem here is that libtool is doing something really
+strange because they are trying to use some abstract concept that is
+OS-independent. I don't use libtool because I find it horribly
+complex and doesn't add enough value to be worth the complexity.
+
+So I'll tell you how things work with respect to Linux's ELF version
+numbering system. Translating this to libtool's wierd "current,
+revision, age" terminology is left as an exercise to the reader. I've
+looked at the libtool documentation, and it confuses me horribly.
+Reading it, I suspect it's wrong, but I don't have the time to
+experiment to confirm that the documentation is wrong and how it
+diverges from the libtool implementation.
+
+So let me explain things using the ELF shared library terminology,
+which is "major version, minor version, patchlevel". This shows up in
+the library name:
+
+ libudev.so.1.6.11
+
+So in this example, the major version number is 1, the minor version
+is 6, and the patchlevel is 11. The patchlevel is entirely optional,
+and many packages don't use it at all. The minor number is also
+mostly useless on Linux, but it's still there for historical reasons.
+The patchlevel and minor version numbers were useful back for SunOS
+(and Linux a.out shared library), back when there weren't rpm and dpkg
+as package managers.
+
+So many modern Linux shared libraries will only use the major and
+minor version numbers, e.g:
+
+ libext2fs.so.2.4
+
+The only thing you really need to worry about is the major version
+number, really. The minor version is *supposed* to change when new
+interfaces has changed (but I and most other people don't do that any
+more). But the big deal is that the major number *must* get bumped if
+an existing interface has *changed*.
+
+So let's talk about the major version number, and then we'll talk
+about why the minor version number isn't really a big deal for Linux.
+
+So if you change any of the library's function signatures --- and this
+includes changing a type from a 32-bit integer to a 64-bit integer,
+that's an ABI breakage, and so you must bump the major version number
+so that a program that was linked against libfoo.so.4 doesn't try to
+use libfoo.so.5. That's really the key --- will a program linked
+against the previous version library break if it links against the
+newer version. If it does, then you need to bump the version number.
+
+So for structures, if you change any of the existing fields, or if the
+application program allocates the structure --- either by declaring it
+on the stack, or via malloc() --- and you expand the structure,
+obviously that will cause problem, and so that's an ABI break.
+
+If however, you arrange to have structures allocated by the library,
+and struct members are always added at the end, then an older program
+won't have any problems. You can guarantee this by simply only using
+a pointer to the struct in your public header files, and defining the
+struct in a private header file that is not available to userspace
+programs.
+
+Similarly, adding new functions never breaks the ABI. That's because
+older program won't try to use the newer interfaces. So if I need to
+change an interface to a function, what I'll generally do is to define
+a new function, and then implement the older function in terms of the
+newer one. For example:
+
+extern errcode_t ext2fs_open(const char *name, int flags, int superblock,
+ unsigned int block_size, io_manager manager,
+ ext2_filsys *ret_fs);
+
+extern errcode_t ext2fs_open2(const char *name, const char *io_options,
+ int flags, int superblock,
+ unsigned int block_size, io_manager manager,
+ ext2_filsys *hret_fs);
+
+As far as the minor version numbers are concerned, the dynamic linker
+doesn't use it. In SunOS 4, if you have a DT_NEEDED for libfoo.so.4,
+and the dynamic linker finds in its search path:
+
+ libfoo.so.4.8
+ libfoo.so.4.9
+
+It will preferentially use libfoo.so.4.9.
+
+That's not how it works in Linux, though. In Linux there will be a
+symlink that points libfoo.so.4 to libfoo.so.4.9, and the linker just
+looks for libfoo.so.4. One could imagine a package manager which
+adjusts the symlink to point at the library with the highest version,
+but given that libfoo.so.4.9 is supposed to contain a superset of
+libfoo.so.4.8, there's no point. So we just in practice handle all of
+this in the package manager, or via an ELF symbol map. Or, we just
+assume that since vast majority of software comes from the
+distribution, the distro package manager will just update libraries to
+the newer version as a matter of course, and nothing special needs to
+be done.
+
+So in practice I don't bump the minor version number for e2fsprogs
+each time I add new interfaces, because in practice it really doesn't
+matter for Linux. We have a much better system that gets used for
+Debian.
+
+For example in Debian there is a file that contains when each symbol
+was first introduced into a library, by its package version number.
+See:
+
+https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/tree/debian/libext2fs2.symbols
+
+This file contains a version number for each symbol in libext2fs2, and
+it tells us what version of libext2fs you need to guarantee that a
+particular symbol is present in the library. Then when *other*
+packages are built that depend on libext2fs2, the minimum version of
+libext2fs can be calculated based on which symbols they use.
+
+So for example the libf2fs-format4 package has a Debian dependency of:
+
+Depends: libblkid1 (>= 2.17.2), libc6 (>= 2.14), libf2fs5, libuuid1 (>= 2.16)
+
+The minimum version numbers needed for libblkid1 and libuuid1 are
+determined by figuring out all of the symbols used by the
+libf2fs-format4 package, and determining the minimum version number of
+libblkid1 that supports all of those blkid functions.
+
+This gets done automatically, so I didn't have to figure this out.
+All I have in the debian/control file is:
+
+Depends: ${misc:Depends}, ${shlibs:Depends}
+
+Sorry this got so long, but hopefully you'll find this useful. How
+you bend libtool to your will is something you'll have to figure out,
+because I don't use libtool in my packages.[1]
+
+Cheers,
+
+ - Ted
+
+
+[1] If you are interested in how I do things in e2fsprogs, take a look
+at the Makefile.elf-lib, Makefile.solaris-lib, Makefile.darwin-lib,
+etc. here:
+
+https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/tree/lib
+
+This these Makefile fragments are then pulled into the generated
+makefile using autoconf's substitution rules, here:
+
+https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/tree/lib/ext2fs/Makefile.in
+
+(Search for "@MAKEFILE_ELF@" in the above Makefile.in).
+
+So when someone runs "configure --enable-elf-shlibs", they get the ELF
+shared libraries built. On BSD and MacOS systems they just have to
+run "configure --enable-bsd-shlibs", and so on.
+
+Personally, since most people don't bother to write truly portable
+programs, as their C code is full of Linux'isms, using libtool is just
+overkill, because they probably can't build on any other OS *anyway*
+so libtool's slow and complex abstraction layer is totally wasted.
+Might as well not use autoconf, automake, and libtool at all.
+
+On the other hand, if you really *do* worry about portability on other
+OS's (e2fsprogs builds on MacOS, NetBSD, Hurd, Solaris, etc.) then
+using autoconf makes sense --- but I *still* don't think the
+complexity of libtool is worth it.
+
+= Add-on =
+If you are going to be making one less major update, this is the
+perfect time to make sure that data structures are allocated by the
+library, and are (ideally) opaque to the calling application (so they
+only manipulate structure poitners). That is, the structure
+definition is not exposed in the public header file, and you use
+accessor functions to set and get fields in the structure.
+
+If you can't do that for all data structures, if you can do that with
+your primary data structure that's going to make your life much easier
+in the long term. For ext2fs, that's the file systme handle. It's
+created by ext2fs_open(), and it's passed to all other library
+functions as the first argument.
+
+The other thing you might want to consider doing is adding a magic
+number to the beginning of each structure. That way you can tell if
+the wrong structure gets passed to a library. It's also helpful for
+doing the equivalent of subclassing in C.
+
+This is how we do it in libext2fs --- we use com_err to define the
+magic numbers:
+
+ error_table ext2
+
+ec EXT2_ET_BASE,
+ "EXT2FS Library version @E2FSPROGS_VERSION@"
+
+ec EXT2_ET_MAGIC_EXT2FS_FILSYS,
+ "Wrong magic number for ext2_filsys structure"
+
+ec EXT2_ET_MAGIC_BADBLOCKS_LIST,
+ "Wrong magic number for badblocks_list structure"
+ ...
+
+And then every single structure starts like so:
+
+struct struct_ext2_filsys {
+ errcode_t magic;
+ ...
+
+struct ext2_struct_inode_scan {
+ errcode_t magic;
+ ...
+
+And then before we use any pointer we do this:
+
+ if (file->magic != EXT2_ET_MAGIC_EXT2_FILE)
+ return EXT2_ET_MAGIC_EXT2_FILE;
projects / platform / upstream / f2fs-tools.git / commitdiff