Document changes in v1.11.0 to VersionInfo and related constants

[flavorjones]

This issue exists simply to offload the details from the CHANGELOG. The issue description will be kept up-to-date as v1.11.0 nears release, and then closed. The CHANGELOG will link here to provide additional detail for anyone who's interested.

---

This release changes the metadata provided in Nokogiri::VersionInfo which also affects the output of nokogiri -v. Some related constants have also been changed. If you're using VersionInfo programmatically, or relying on constants related to underlying library versions, please read the detailed changes for Nokogiri::VersionInfo below and accept our apologies for the inconvenience.

See #1482 and #1974 for background. Also note that some of these changes were driven by long-running work to improve the compilation and installation process.

Nokogiri::VersionInfo emits different information for the key nokogiri. Previously the value was a string containing Nokogiri::VERSION, but now contains a hash:

• nokogiri/version now contains Nokogiri::VERSION
• nokogiri/cppflags now contains an array of C preprocessor flags useful to compile code against Nokogiri, libxml2, or libxslt.

Nokogiri::VersionInfo will no longer contain the following key:

• libxml/libxslt_path (see Installed gems using vendored libraries report inappropriate library paths in nokogiri -v #1482). Previously this was available only when packaged libraries were being used, and it pointed at a non-existent directory.

Nokogiri::VersionInfo emits different information for libxml/libxml2_path (see #1482 and #1788). This value previously pointed at a non-existent directory, but now points to a directory with useful contents. This key only continues to exist for the purposes of backwards-compatible integration with Nokogumbo and is planned for removal by v1.12.0. Instead, if you intend to compile against Nokogiri or the packaged libxml2 or libxslt, you should use nokogiri/cppflags (see above).

Nokogiri::VersionInfo now contains native gem metadata for libxml:

• libxml/precompiled (true if the gem installed was a native gem, otherwise false)
• libxml/iconv_enabled (true if libxml2 was built with iconv support, otherwise false)

Nokogiri::VersionInfo now contains version metadata for libxslt:

• libxslt/source (either "packaged" or "system", similar to libxml/source)
• libxslt/precompiled (true if the gem installed was a native gem, otherwise false)
• libxslt/compiled (the version of libxslt the gem was compiled against, similar to libxml/compiled)
• libxslt/loaded (the version of libxslt loaded at runtime, similar to libxml/loaded)
• libxslt/patches moved from libxml/libxslt_patches

Nokogiri::VersionInfo key libxml/libxml2_patches has been renamed to libxml/patches

These global variables are no longer be defined:

• NOKOGIRI_LIBXML2_PATH
• NOKOGIRI_LIBXSLT_PATH

These constants have been renamed:

• Nokogiri::LIBXML_VERSION is now Nokogiri::LIBXML_COMPILED_VERSION
• Nokogiri::LIBXML_PARSER_VERSION is now Nokogiri::LIBXML_LOADED_VERSION
• Nokogiri::NOKOGIRI_LIBXML2_PATCHES is now Nokogiri::LIBXML2_PATCHES
• Nokogiri::NOKOGIRI_LIBXSLT_PATCHES is now Nokogiri::LIBXSLT_PATCHES
• Nokogiri::NOKOGIRI_USE_PACKAGED_LIBRARIES is now Nokogiri::PACKAGED_LIBRARIES

These methods have been renamed and the return type changed from String to Gem::Version:

• VersionInfo#loaded_parser_version is now #loaded_libxml_version
• VersionInfo#compiled_parser_version is now #compiled_libxml_version

The JRuby gem's information now nests these keys under other_libraries:

• xerces
• nekohtml

The CRuby gem now provides information about libraries other than libxml2 and libxslt under other_libraries. Possible key values at the time this issue was published include:

• zlib
• libiconv

Nokogiri.uses_libxml? now accepts an optional requirement string which is interpreted as a Gem::Requirement and tested against the loaded libxml2 version (the value in VersionInfo key libxml/loaded). This greatly simplifies much of the version-dependent branching logic in both the implementation and the tests.

To sum these changes up, the output from CRuby when using packaged libraries was something like:

## old output!
# Nokogiri (1.10.7)
    ---
    warnings: []
    nokogiri: 1.10.7
    ruby:
      version: 2.7.0
      platform: x86_64-linux
      description: ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x86_64-linux]
      engine: ruby
    libxml:
      binding: extension
      source: packaged
      libxml2_path: "/home/flavorjones/.rvm/gems/ruby-2.7.0/gems/nokogiri-1.10.7/ports/x86_64-pc-linux-gnu/libxml2/2.9.10"
      libxslt_path: "/home/flavorjones/.rvm/gems/ruby-2.7.0/gems/nokogiri-1.10.7/ports/x86_64-pc-linux-gnu/libxslt/1.1.34"
      libxml2_patches:
      - 0001-Revert-Do-not-URI-escape-in-server-side-includes.patch
      - 0002-Remove-script-macro-support.patch
      - 0003-Update-entities-to-remove-handling-of-ssi.patch
      - 0004-libxml2.la-is-in-top_builddir.patch
      libxslt_patches: []
      compiled: 2.9.10
      loaded: 2.9.10

but when using a native gem (with precompiled libraries) now looks like:

## new output when using packaged libraries
# Nokogiri (1.11.0.rc4)
    ---
    warnings: []
    nokogiri:
      version: 1.11.0.rc4
      cppflags:
      - "-I/home/flavorjones/code/oss/nokogiri/ext/nokogiri"
      - "-I/home/flavorjones/code/oss/nokogiri/ext/nokogiri/include"
      - "-I/home/flavorjones/code/oss/nokogiri/ext/nokogiri/include/libxml2"
    ruby:
      version: 2.7.2
      platform: x86_64-linux
      gem_platform: x86_64-linux
      description: ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux]
      engine: ruby
    libxml:
      source: packaged
      precompiled: false
      patches:
      - 0001-Revert-Do-not-URI-escape-in-server-side-includes.patch
      - 0002-Remove-script-macro-support.patch
      - 0003-Update-entities-to-remove-handling-of-ssi.patch
      - 0004-libxml2.la-is-in-top_builddir.patch
      - 0005-Fix-infinite-loop-in-xmlStringLenDecodeEntities.patch
      - 0006-htmlParseComment-treat-as-if-it-closed-the-comment.patch
      - 0007-use-new-htmlParseLookupCommentEnd-to-find-comment-en.patch
      libxml2_path: "/home/flavorjones/.rvm/gems/ruby-2.7.2/gems/nokogiri-1.11.0.rc4/ext/nokogiri"
      iconv_enabled: true
      compiled: 2.9.10
      loaded: 2.9.10
    libxslt:
      source: packaged
      precompiled: false
      patches: []
      compiled: 1.1.34
      loaded: 1.1.34
    other_libraries:
      zlib: 1.2.11

and the output from using system libraries now looks like:

# Nokogiri (1.11.0.rc4)
    ---
    warnings: []
    nokogiri:
      version: 1.11.0.rc4
      cppflags:
      - "-I/home/flavorjones/.rvm/gems/ruby-2.7.2/gems/nokogiri-1.11.0.rc4/ext/nokogiri"
    ruby:
      version: 2.7.2
      platform: x86_64-linux
      gem_platform: x86_64-linux
      description: ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x86_64-linux]
      engine: ruby
    libxml:
      source: system
      iconv_enabled: true
      compiled: 2.9.10
      loaded: 2.9.10
    libxslt:
      source: system
      compiled: 1.1.34
      loaded: 1.1.34
    other_libraries: {}

[flavorjones]

Updated to note the newly-continued existence of libxml/libxml2_paths, and to introduce nokogiri/cppflags which will replace it.

[flavorjones]

Updated to note other_libraries changes, see #2146 for details.

[flavorjones]

OK, looks like this is what's shipping. Closing as the description-of-record.