Pull requests

#17 Declined
Repository
suetanvil
Branch
version-api
Repository
libgd
Branch
master

Changes how the library version is reported to client programs

Author
  1. Chris Reuter
Reviewers
Description

See the first commit message for an overview.

I'm submitting this as a pull request rather than just pushing my changes because it changes the API a little and I'd like a sanity check first.

  • Learn about pull requests

Comments (3)

  1. Chris Reuter author

    Here are my reasons for doing this:

    1. Because the build system has to generate a source file, it becomes a lot harder to compile libgd on a platform that doesn't support cmake or autotools. A simple make or crappy IDE can generally compile a bunch of C code, but getting it to do that extra step is often head-poundingly frustrating.

      (I'm currently in that boat, having given up on cmake and autotools as ways to build under MinGW/MSYS after wasting a week trying to debug them.)

    2. The current setup violates the DRY principle (i.e. each piece of code or data should have exactly one canonical copy). Each supported build system needs to set the version number its own way, possibly from a different location. This change gives us exactly one original source for this information.

    3. With this changeset, the version information is now stored as C code, so the version number in the actual shared library will always be correct. There are no intermediate steps that could potentially go wrong and screw it up. (Also, the C code is simple enough that you can parse it with a shell script if necessary, so a build tool can still get at it.)

    4. Generating gd.h from gd.h.in causes all sorts of headaches:

      • Editors and other tools can't tell it's C code from the extension
      • etags *.[ch] won't catch it.
      • It's easy to accidentally edit gd.h instead of gd.h.in
      • There's always the chance something in gd.h.in getting accidently replaced/expanded in gd.h.
    5. Right now, library users don't actually get the library version; they get the version of gd.h that the C code was compiled against. So if (e.g.) Perl's GD extension is compiled against version 2.1.0 and at some later point the shared library is updated to version 2.1.1, Perl will still report the version as being 2.1.0. With this change, that gets fixed.

    6. Related to this, client code that bypasses the header file (e.g. Ruby's FFI) currently can't get the version number from the shared library at all. With this change, it can.

    7. In general, generating code is one of those things that needs to be done carefully, lest it cause more problems than it solves. gd.h is a really minor case of that but I'm concerned that because the step is there, subsequent contributors may start adding extra complexity to it. Each such step makes makes everything harder, so I'd like to prevent that now while it's still easy to do.

    The downsides to my change:

    1. It's a tiny bit slower to look up the version.

    2. C code that depends on the version macros expanding into literals may need to be changed a little. (Binaries are fine, though.)

    I don't think either of these is a serious problem, though. The performance hit is negligable and I don't think any actual real-world code would break.

  2. Chris Reuter author

    I declined this myself and will be pushing something similar soon. The new version preserves the old definition of the GD_*_VERSION macros but does mostly the same thing.