devel-docs/libtool-instructions.txt

   1 configure.ac libtool settings
   2 =============================
   3
   4 This is a brief description of how the various version variables at the
   5 top of configure.ac are to be set, including gimp_interface_age and
   6 gimp_binary_age.
   7
   8 See the arithmetic under the "libtool versioning" comment heading in
   9 configure.ac as a reference.
  10
  11 See https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html
  12 for definitions of libtool "current", "revision" and "age" numbers as
  13 used below.
  14
  15 When making a release
  16 ---------------------
  17
  18 (1) When making releases on the stable branch, set:
  19   gimp_micro_version += 1;
  20   gimp_interface_age += 1;
  21
  22   If gimp_binary_age is defined as a constant, set gimp_binary_age += 1;
  23   else if gimp_binary_age is defined as an m4_eval(), leave it as it is.
  24
  25   The default gimp_binary_age m4_eval() expression auto-increments
  26   itself.
  27
  28 (2) NEVER increment gimp_interface_age and gimp_binary_age by more than
  29 1 at any time for whatever reason, or you will have to wear a brown
  30 paper bag on your head to hide your face for the rest of your life. If
  31 you increment gimp_interface_age by more than 1, then the libtool
  32 "current" number is decremented which could result in incompatible
  33 library interface with existing bin programs.
  34
  35 (3) If any functions have been added, set gimp_interface_age=0. This
  36 will cause the "current" and "age" part of libtool version to bump
  37 upwards, increasing the interface number the library implements while
  38 keeping the minimum interface number supported the same as before
  39 (i.e., backwards compatible ABI).
  40
  41   Example: In GIMP 2.8.10, with gimp_minor_version=8,
  42   gimp_micro_version=10 and gimp_interface_age=10 (incremented by 1
  43   for every micro release), current=800 and age=800, which means that
  44   the libraries support interface numbers 0 through 800, and the
  45   interface DID NOT change at all between GIMP 2.8.0 to GIMP 2.8.10.
  46
  47   Example: In GIMP 2.8.12, with gimp_minor_version=8,
  48   gimp_micro_version=12 and gimp_interface_age=0, current=812 and
  49   age=812, which means that the libraries support interface numbers 0
  50   through 812, and the ABI interface DID change in backwards
  51   compatible manner at the time gimp_interface_age was set to 0.
  52
  53 (4) If backwards compatibility was broken, set gimp_binary_age=0 and
  54 gimp_interface_age=0. This will cause "age" part of libtool version to
  55 be 0, increasing the minimum interface supported to "current" part of
  56 libtool version, and making ABI backwards incompatible (the linker
  57 will not be able to use these libraries with programs compiled to work
  58 against older libraries.
  59
  60   Example: In GIMP 2.8.14, with gimp_minor_version=8,
  61   gimp_micro_version=14, gimp_binary_age=0 and gimp_interface_age=0,
  62   current=814 and age=0, which means that the libraries support
  63   interface number 814 only, which tells libtool the ABI interface
  64   changed in backwards incompatible manner at the time
  65   gimp_binary_age was set to 0.