===============
``mod version``
===============


.. rust:module:: rgpot_core::version
   :index: 0
   :vis: pub

   Version of the loaded library, for callers to check against the header
   they compiled with.
   
   ``rgpot.h`` stamps ``RGPOT_VERSION`` and ``RGPOT_VERSION_MAJOR`` / ``_MINOR`` /
   ``_PATCH`` at generation time; these functions report the same numbers
   from the shared object actually loaded. The C ABI follows semver: a
   caller built against major M runs on any library of major M whose minor
   is at least the header's.
   
   The ABI stamp is separate from the crate version: see
   ``rgpot_abi_stamp()`` and ``rgpot_abi_compatible()``.
   
   .. code-block:: c

      if (rgpot_version_major() != RGPOT_VERSION_MAJOR ||
          rgpot_version_minor() < RGPOT_VERSION_MINOR) {
        fprintf(stderr, "rgpot %s loaded, built against %s\n",
                rgpot_version(), RGPOT_VERSION);
        abort();
      }


   .. rust:use:: rgpot_core::version
      :used_name: self


   .. rust:use:: rgpot_core
      :used_name: crate


   .. rust:use:: std::os::raw::c_char
      :used_name: c_char


   .. rubric:: Variables


   .. rust:variable:: rgpot_core::version::RGPOT_ABI_LAYOUT_REVISION
      :index: 0
      :vis: pub
      :toc: const RGPOT_ABI_LAYOUT_REVISION
      :layout: [{"type":"keyword","value":"const"},{"type":"space"},{"type":"name","value":"RGPOT_ABI_LAYOUT_REVISION"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"}]

      Layout revision of this build.

   .. rust:variable:: rgpot_core::version::RGPOT_ABI_VERSION_MAJOR
      :index: 0
      :vis: pub
      :toc: const RGPOT_ABI_VERSION_MAJOR
      :layout: [{"type":"keyword","value":"const"},{"type":"space"},{"type":"name","value":"RGPOT_ABI_VERSION_MAJOR"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"}]

      ABI major of this build.

   .. rust:variable:: rgpot_core::version::RGPOT_ABI_VERSION_MINOR
      :index: 0
      :vis: pub
      :toc: const RGPOT_ABI_VERSION_MINOR
      :layout: [{"type":"keyword","value":"const"},{"type":"space"},{"type":"name","value":"RGPOT_ABI_VERSION_MINOR"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"}]

      ABI minor of this build.

   .. rubric:: Functions


   .. rust:function:: rgpot_core::version::rgpot_abi_compatible
      :index: 0
      :vis: pub
      :layout: [{"type":"keyword","value":"unsafe"},{"type":"space"},{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"rgpot_abi_compatible"},{"type":"punctuation","value":"("},{"type":"name","value":"stamp"},{"type":"punctuation","value":": "},{"type":"operator","value":"*"},{"type":"keyword","value":"const"},{"type":"space"},{"type":"link","value":"rgpot_abi_stamp_t","target":"rgpot_abi_stamp_t"},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"i32","target":"i32"}]

      Return nonzero when the loaded library can serve a caller built with
      ``stamp``: equal major, equal layout revision, and a library minor at least
      the caller's. A null ``stamp`` is not compatible.
      
      **Safety**
      
      ``stamp`` must be null or point to a readable ``rgpot_abi_stamp_t``.

   .. rust:function:: rgpot_core::version::rgpot_abi_stamp
      :index: 0
      :vis: pub
      :layout: [{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"rgpot_abi_stamp"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"rgpot_abi_stamp_t","target":"rgpot_abi_stamp_t"}]

      Compatibility identity of the loaded library.
      
      Compare it with the ``RGPOT_ABI_*`` macros of the header the caller
      compiled with, or pass the caller's own stamp to
      ``rgpot_abi_compatible``.

   .. rust:function:: rgpot_core::version::rgpot_source_revision
      :index: 0
      :vis: pub
      :layout: [{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"rgpot_source_revision"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"operator","value":"*"},{"type":"keyword","value":"const"},{"type":"space"},{"type":"link","value":"c_char","target":"c_char"}]

      Source revision the loaded library was built from (a git short hash), or
      an empty string when the build had no revision to record.
      
      The pointer refers to static storage: never free it.

   .. rust:function:: rgpot_core::version::rgpot_version
      :index: 0
      :vis: pub
      :layout: [{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"rgpot_version"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"operator","value":"*"},{"type":"keyword","value":"const"},{"type":"space"},{"type":"link","value":"c_char","target":"c_char"}]

      Full version string of the loaded library, e.g. ``"3.5.1"``.
      
      The pointer refers to static storage: never free it.

   .. rust:function:: rgpot_core::version::rgpot_version_major
      :index: 0
      :vis: pub
      :layout: [{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"rgpot_version_major"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"u32","target":"u32"}]

      Major version of the loaded library.

   .. rust:function:: rgpot_core::version::rgpot_version_minor
      :index: 0
      :vis: pub
      :layout: [{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"rgpot_version_minor"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"u32","target":"u32"}]

      Minor version of the loaded library.

   .. rust:function:: rgpot_core::version::rgpot_version_patch
      :index: 0
      :vis: pub
      :layout: [{"type":"keyword","value":"extern"},{"type":"space"},{"type":"literal","value":"C"},{"type":"space"},{"type":"keyword","value":"fn"},{"type":"space"},{"type":"name","value":"rgpot_version_patch"},{"type":"punctuation","value":"("},{"type":"punctuation","value":")"},{"type":"space"},{"type":"returns"},{"type":"space"},{"type":"link","value":"u32","target":"u32"}]

      Patch version of the loaded library.

   .. rubric:: Structs and Unions


   .. rust:struct:: rgpot_core::version::rgpot_abi_stamp_t
      :index: 1
      :vis: pub
      :toc: struct rgpot_abi_stamp_t
      :layout: [{"type":"keyword","value":"struct"},{"type":"space"},{"type":"name","value":"rgpot_abi_stamp_t"}]

      Compatibility identity of the rgpot-core C ABI.
      
      The numbers move with the layout of the exported structs and the
      signatures of the exported functions, not with the crate version.

      .. rust:variable:: rgpot_core::version::rgpot_abi_stamp_t::abi_major
         :index: 2
         :vis: pub
         :toc: abi_major
         :layout: [{"type":"name","value":"abi_major"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"}]

         Incompatible changes increment this value.

      .. rust:variable:: rgpot_core::version::rgpot_abi_stamp_t::abi_minor
         :index: 2
         :vis: pub
         :toc: abi_minor
         :layout: [{"type":"name","value":"abi_minor"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"}]

         Additive compatible changes increment this value.

      .. rust:variable:: rgpot_core::version::rgpot_abi_stamp_t::layout_revision
         :index: 2
         :vis: pub
         :toc: layout_revision
         :layout: [{"type":"name","value":"layout_revision"},{"type":"punctuation","value":": "},{"type":"link","value":"u16","target":"u16"}]

         Struct and function-layout revision for this ABI major.