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

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

Katana |version| and its third-party library dependencies are compiled with GCC
4.8.2 on Linux, and Visual Studio 2015 Update 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 build with Visual Studio 2015 Update 3.

   We also recommend that Python C extension modules are built using Visual
   Studio 2015 Update to ensure it uses the same Visual Studio C Runtime (CRT)
   as the Python libraries shipped with Katana. As the default compiler for
   building Python 2.7 C extensions is Visual Studio 2008, it may be necessary
   to override distutils/setuptools' choice of compiler when building an
   extension module.  See `distutils API Reference`_ for further information.

.. _distutils API Reference: https://docs.python.org/2.7/distutils/apiref.html#module-distutils.msvccompiler

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`