Native Plug-in Compatibility
============================

Toolchain Requirements
----------------------

Katana |version| and its third-party library dependencies are compiled with GCC
11.2.1 on Linux, and Visual Studio 2022 Version 17.5.3 on Windows.

In most cases this is an implementation detail. Katana has long separated its
SDK into a set of C++ headers and sources compiled directly into plug-in code
and a stable, compiler-agnostic C-based API that's wrapped by the C++ layer.
This separation allows a plug-in author writing a Geolib Op, for example, to
build with their choice of toolchain.

.. note::
   On Windows, there are some exceptions. As Visual Studio does not guarantee a
   stable C++ ABI from release to release, plug-in authors building plug-ins
   that link against Qt are required to build with Visual Studio 2022 Version
   17.5.3.

   We also recommend that Python C extension modules are built using Visual
   Studio 2022 Update to ensure it uses the same Visual Studio C Runtime (CRT)
   as the Python libraries shipped with Katana.

Plug-in Loading
---------------

Linux
~~~~~

Native Katana plug-ins are runtime-loaded using `dlopen(3)`_ and
``RTLD_LOCAL``. This ensures that dynamic symbols defined by your plug-in (or
its dependencies) are not used to resolve future symbol references from some
other shared object.

.. note::
   Katana's executables use ``RPATH`` entries to ensure our installation paths
   are searched for dependencies first. Bear in mind that library search paths
   specified in ``RPATH`` are scanned ahead of paths specified in
   ``LD_LIBRARY_PATH``.

Windows
~~~~~~~

Native Katana plug-ins are runtime-loaded using `LoadLibraryEx()`_ and the
``LOAD_WITH_ALTERED_SEARCH_PATH`` flag. The use of this flag means the Windows
Loader will first consider the directory of the plug-in when searching for
libraries it depends on. For more information, see the MSDN article
`Dynamic-Link Library Search Order`_.

.. _dlopen(3): http://man7.org/linux/man-pages/man3/dlopen.3.html
.. _LoadLibraryEx(): https://msdn.microsoft.com/en-gb/library/windows/desktop/ms684179(v=vs.85).aspx
.. _Dynamic-Link Library Search Order: https://msdn.microsoft.com/en-gb/library/windows/desktop/ms682586(v=vs.85).aspx

.. seealso::

    :doc:`/ExternalSoftware`