Merge pull request OpenAssetIO#1342 from feltech/work/1324-stubCppPlugin

Add SimpleCppManager

Author: feltech

.github/workflows/integrations.yml

@@ -193,3 +193,36 @@ jobs:
         env:
           CMAKE_PREFIX_PATH: ${{ github.workspace }}/dist
           CMAKE_TOOLCHAIN_FILE: ${{ github.workspace }}/.conan/conan_paths.cmake
+
+      # TODO(DF): SimpleCppManager should (also) be tested as part of
+      # Python e2e tests, once we fix loading C++ plugins from Python.
+
+      - name: Build/install SimpleCppManager
+        run: >
+          ${{ matrix.config.preamble }}
+
+          cd examples/manager/SimpleCppManager
+
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
+          -DOPENASSETIO_ENABLE_TESTS=ON
+          -DOPENASSETIO_GLIBCXX_USE_CXX11_ABI=OFF
+
+          cmake --build build --parallel --config RelWithDebInfo
+
+          cmake --install build --prefix '${{ github.workspace }}/dist/plugins'
+          --config RelWithDebInfo
+
+        env:
+          CMAKE_PREFIX_PATH: ${{ github.workspace }}/dist
+
+      - name: Test SimpleCppManager with simpleResolver
+        run: >
+          python '${{ github.workspace }}/examples/host/simpleResolver/simpleResolver.py'
+          openassetio-mediacreation:identity.DisplayName simplecpp://test/entity/1
+          | grep 'Test Entity 1'
+
+        env:
+          PYTHONPATH: ${{ github.workspace }}/dist/${{ matrix.config.site-packages }}
+          OPENASSETIO_LOGGING_SEVERITY: 1
+          OPENASSETIO_PLUGIN_PATH: ${{ github.workspace }}/dist/plugins
+          OPENASSETIO_DEFAULT_CONFIG: ${{ github.workspace }}/examples/manager/SimpleCppManager/tests/resources/openassetio_config.toml

CMakeLists.txt

@@ -205,6 +205,8 @@ cmake_dependent_option(
     OFF
 )
 
+option(OPENASSETIO_ENABLE_SIMPLECPPMANAGER "Build the SimpleCppManager example" OFF)
+
 # Enable clang-format formatting check.
 option(OPENASSETIO_ENABLE_CLANG_FORMAT "Enable clang-format check during build" OFF)
 
@@ -339,11 +341,12 @@ if (OPENASSETIO_ENABLE_PYTHON)
     message(STATUS "Python relative install dir        = ${OPENASSETIO_PYTHON_SITEDIR}")
     message(STATUS "Generate .pyi stubs                = ${OPENASSETIO_ENABLE_PYTHON_STUBGEN}")
 endif ()
+message(STATUS "Build SimpleCppManager             = ${OPENASSETIO_ENABLE_SIMPLECPPMANAGER}")
 message(STATUS "Create test targets                = ${OPENASSETIO_ENABLE_TESTS}")
 if (OPENASSETIO_ENABLE_TESTS)
     message(STATUS "Create Python venv during tests    = ${OPENASSETIO_ENABLE_PYTHON_TEST_VENV}")
     message(STATUS "Enable ABI diff check test         = ${OPENASSETIO_ENABLE_TEST_ABI}")
-endif()
+endif ()
 message(STATUS "Warnings as errors                 = ${OPENASSETIO_WARNINGS_AS_ERRORS}")
 message(STATUS "Interprocedural optimization       = ${OPENASSETIO_ENABLE_IPO}")
 message(STATUS "Enable PIC for static libs         = ${OPENASSETIO_ENABLE_POSITION_INDEPENDENT_CODE}")
@@ -367,3 +370,7 @@ message(STATUS "Linter: cmake-lint                 = ${OPENASSETIO_ENABLE_CMAKE_
 # Recurse to library targets
 
 add_subdirectory(src)
+
+if (OPENASSETIO_ENABLE_SIMPLECPPMANAGER)
+    add_subdirectory(examples/manager/SimpleCppManager)
+endif ()

CMakePresets.json

@@ -33,7 +33,8 @@
         "enable-tests"
       ],
       "cacheVariables": {
-        "OPENASSETIO_ENABLE_PYTHON_STUBGEN": "OFF"
+        "OPENASSETIO_ENABLE_PYTHON_STUBGEN": "OFF",
+        "OPENASSETIO_ENABLE_SIMPLECPPMANAGER": "OFF"
       }
     },
     {
@@ -104,7 +105,8 @@
       "hidden": true,
       "cacheVariables": {
         "OPENASSETIO_ENABLE_PYTHON": "ON",
-        "OPENASSETIO_ENABLE_C": "ON"
+        "OPENASSETIO_ENABLE_C": "ON",
+        "OPENASSETIO_ENABLE_SIMPLECPPMANAGER": "ON"
       }
     },
     {

README.md

@@ -9,13 +9,12 @@ workflows in content creation tooling.
 
 > - 👋 Come chat with us on [ASWF Slack](https://academysoftwarefdn.slack.com/archives/C03Q36QS8N4)
 >   or our [mailing list](https://lists.aswf.io/g/openassetio-discussion).
-> - 🧰 Get started with the API [docs](https://openassetio.github.io/OpenAssetIO),
+> - 🧰 Get started with the [API docs](https://openassetio.github.io/OpenAssetIO),
 >   Manager plugin [template](https://github.com/OpenAssetIO/Template-OpenAssetIO-Manager-Python),
->   [OpenAssetIO-MediaCreation](https://github.com/OpenAssetIO/OpenAssetIO-MediaCreation#readme)
+>   and [MediaCreation](https://github.com/OpenAssetIO/OpenAssetIO-MediaCreation#readme)
 >   for post-production workflows.
-> - 📖 Or see some examples: Ayon [manager plugin](https://github.com/ynput/ayon-openassetio-manager-plugin/tree/main#readme),
->   USD [Asset Resolver prototype](https://github.com/OpenAssetIO/usdOpenAssetIOResolver#readme),
->   OTIO [media linker](https://github.com/OpenAssetIO/otio-openassetio)
+> - 📖 Or see some [examples](examples/README.md) in the OpenAssetIO
+>   ecosystem.
 > - 👀 You can follow the development effort [here](https://github.com/orgs/OpenAssetIO/projects/1/views/7)
 >   and the longer term roadmap [here](ROADMAP.md).
 
@@ -239,4 +238,4 @@ During this period, one may assume that the `x` above is synonymous with
 major version, and the `y` with minor version, for the purpose of
 compatibility. This means patch versions will be rolled into minor
 versions, but you may still consult the [release
-notes](./RELEASE_NOTES.md) for specific compatibility information.
+notes](./RELEASE_NOTES.md) for specific compatibility information.

RELEASE_NOTES.md

@@ -4,11 +4,21 @@ Release Notes
 v1.0.0-beta.x.x
 ---------------
 
+### New Features
+
+- Added SimpleCppManager - a minimal C++ manager and plugin example
+  implementation, useful for testing C++ plugin support in hosts. This
+  has minimal API support, so [Basic Asset Library (BAL)](https://github.com/OpenAssetIO/OpenAssetIO-Manager-BAL)
+  should still be preferred as a test manager when Python is available.
+  [#1324](https://github.com/OpenAssetIO/OpenAssetIO/issues/1324)
+
 ### Improvements
 
 - Added singular overload of `managementPolicy` for convenience.
   [#856](https://github.com/OpenAssetIO/OpenAssetIO/issues/856)
 
+- Updated the `simpleResolver` example host to support C++ plugins.
+  [#1324](https://github.com/OpenAssetIO/OpenAssetIO/issues/1324)
 
 v1.0.0-beta.2.2
 ---------------

cmake/ThirdParty.cmake

@@ -68,10 +68,12 @@ if (OPENASSETIO_ENABLE_PYTHON)
         # varying installation structures were used (eg GitHub Actions
         # runners).
         if (WIN32) # Should not use 'bin' for Windows
-            set(OPENASSETIO_PYTHON_SITEDIR "Lib/site-packages")
+            set(OPENASSETIO_PYTHON_SITEDIR "Lib/site-packages"
+                CACHE STRING "Python site-packages directory" FORCE)
         else ()
             set(OPENASSETIO_PYTHON_SITEDIR
-                "lib/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages")
+                "lib/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages"
+                CACHE STRING "Python site-packages directory" FORCE)
         endif ()
     endif ()
 

examples/README.md

@@ -0,0 +1,100 @@
+# Examples
+
+There is an ever-growing list of example OpenAssetIO hosts and manager
+plugins. They cover a large range, including reference implementations,
+testing utilities, proof of concepts, and production integrations.
+
+## This repository
+
+In this repository you can find simple examples of host applications
+and manager plugins that make use of OpenAssetIO.
+
+### Hosts
+
+#### simpleResolver
+
+The [simpleResolver](host/simpleResolver/README.md) is a Python
+command-line tool that can take an entity reference and a list of
+trait IDs, `resolve` them, and present the results as a dictionary
+in the terminal.
+
+### Managers
+
+#### SimpleCppManager
+
+The [SimpleCppManager](manager/SimpleCppManager/README.md) is a C++
+OpenAssetIO manager plugin that provides functionality for a limited
+cross-section of the OpenAssetIO API. Its "database" of entities is
+taken directly from the settings provided by the host. It is designed to
+be used for testing C++ plugin support in host applications.
+
+## Other OpenAssetIO projects
+
+### Python manager plugin template
+
+The [Python manager plugin template](https://github.com/OpenAssetIO/Template-OpenAssetIO-Manager-Python)
+provides a documentation-by-example implementation of a Python manager
+plugin.
+
+### Jupyter notebooks
+
+An ever-expanding collection of [Jupyter](https://jupyter.org/)
+notebooks is available as
+[examples in the MediaCreation](https://github.com/OpenAssetIO/OpenAssetIO-MediaCreation/tree/main/examples)
+repository. These demonstrate core OpenAssetIO concepts alongside the
+wider ecosystem, in particular as it relates to the VFX and media
+creation industry, through executable Python snippets. The pre-rendered
+notebooks can be viewed directly in GitHub, so downloading to execute
+locally is not required.
+
+### Basic Asset Library
+
+The [Basic Asset Library
+(BAL)](https://github.com/OpenAssetIO/OpenAssetIO-Manager-BAL) is a
+Python OpenAssetIO manager and plugin that is designed to enable host
+applications to test their integration against a wide spectrum of
+possible asset management system archetypes. It is designed to be fully
+puppetable, with responses controlled by a JSON configuration file. BAL
+is used extensively by the team for internal testing and demos of
+OpenAssetIO. Note that it is not intended as a reference implementation.
+
+### USD Ar2 shim plugin
+
+The [USD Asset Resolver plugin](https://github.com/OpenAssetIO/usdOpenAssetIOResolver#readme)
+allows OpenAssetIO plugins to be used within the USD ecosystem, by
+adapting the Ar2 API to the OpenAssetIO API.
+
+### OpenTimelineIO media linker plugin
+
+The [OTIO media linker](https://github.com/OpenAssetIO/otio-openassetio)
+plugin allows OpenAssetIO entity references to be recognised within
+OTIO documents, and resolved to their file path when the document is
+loaded.
+
+## External projects
+
+### Nuke
+
+[Nuke](https://www.foundry.com/products/nuke-family/nuke) is the
+industry-leading commercial compositing tool by Foundry. As of
+version [15.1](https://campaigns.foundry.com/products/nuke-family/whats-new),
+Nuke has built-in support for OpenAssetIO as a headline feature.
+
+### Ayon manager plugin
+
+[Ayon by Ynput](https://ynput.io/ayon/) is an open source asset
+management system that forms part of Ynput's pipeline-as-service
+offering. Their
+[manager plugin](https://github.com/ynput/ayon-openassetio-manager-plugin)
+is available on GitHub.
+
+### Blender OpenAssetIO demo script
+
+[Blender](https://www.blender.org/) is an open source 3D digital content
+creation tool.
+
+The [Blender relationships demo script](https://github.com/elliotcmorris/openassetio-relationships-blender)
+adds UI elements to Blender that allow a user to load external geometry
+from an asset management system, and pick alternative proxy
+representations of that geometry by querying OpenAssetIO entity
+relationships.

examples/host/simpleResolver/simpleResolver.py

@@ -28,9 +28,12 @@
 from openassetio.errors import BatchElementException
 from openassetio.access import ResolveAccess
 from openassetio.hostApi import HostInterface, ManagerFactory
-from openassetio.errors import ConfigurationException
+from openassetio.errors import ConfigurationException, OpenAssetIOException
 from openassetio.log import ConsoleLogger, SeverityFilter
-from openassetio.pluginSystem import PythonPluginSystemManagerImplementationFactory
+from openassetio.pluginSystem import (
+    PythonPluginSystemManagerImplementationFactory,
+    CppPluginSystemManagerImplementationFactory,
+)
 
 
 # pylint: disable=missing-function-docstring,no-self-use,invalid-name
@@ -147,20 +150,31 @@ def main():
     # used in standalone situations such as this.
     logger = SeverityFilter(ConsoleLogger())
 
-    # The Python plugin system can load manager implementations
-    # defined outside of the API package.
-    impl_factory = PythonPluginSystemManagerImplementationFactory(logger)
-
     # The HostInterface implementation we supply that identifies
     # ourselves to the manager
     host_interface = SimpleResolverHostInterface()
 
+    # The C++ plugin system can load manager implementations
+    # defined outside of the API package.
+    impl_factory = CppPluginSystemManagerImplementationFactory(logger)
+
     # Initialize the default manager as configured by $OPENASSETIO_DEFAULT_CONFIG
     # See: https://openassetio.github.io/OpenAssetIO/classopenassetio_1_1v1_1_1host_api_1_1_manager_factory.html#a8b6c44543faebcb1b441bbf63c064c76
     # All API/Manager messaging is channeled through the supplied logger.
-    manager = ManagerFactory.defaultManagerForInterface(host_interface, impl_factory, logger)
+    try:
+        manager = ManagerFactory.defaultManagerForInterface(host_interface, impl_factory, logger)
+    except OpenAssetIOException:
+        # Exceptions occur when configuration exists, but loading the
+        # config file or the plugin fails. E.g. if the config file
+        # specifies the identifier of a Python plugin, but we tried to
+        # locate and load a C++ plugin.
+        # If a C++ plugin was not found, try the Python plugin system.
+        impl_factory = PythonPluginSystemManagerImplementationFactory(logger)
+        manager = ManagerFactory.defaultManagerForInterface(host_interface, impl_factory, logger)
 
     if not manager:
+        # Manager will be None only if OPENASSETIO_DEFAULT_CONFIG is
+        # not set.
         raise ConfigurationException(
             "No default manager configured, "
             f"check ${ManagerFactory.kDefaultManagerConfigEnvVarName}"

examples/host/simpleResolver/test_simpleResolver.py

@@ -33,7 +33,7 @@
 
 
 class Test_simpleResolver_errors:
-    def test_when_lib_initialization_fails_then_error_written_to_stderr_and_return_code_non_zero(
+    def test_when_no_config_then_error_written_to_stderr_and_return_code_non_zero(
         self, monkeypatch
     ):
         monkeypatch.delenv("OPENASSETIO_DEFAULT_CONFIG", raising=False)
@@ -45,6 +45,18 @@ def test_when_lib_initialization_fails_then_error_written_to_stderr_and_return_c
         assert result.stderr.splitlines() == expected_message
         assert result.returncode == 1
 
+    def test_when_bad_config_then_error_written_to_stderr_and_return_code_non_zero(
+        self, monkeypatch
+    ):
+        monkeypatch.setenv("OPENASSETIO_DEFAULT_CONFIG", "/some/bad/path")
+        result = execute_cli()
+        expected_message = [
+            "ERROR: Could not load default manager config from '/some/bad/path', file does not"
+            " exist."
+        ]
+        assert result.stderr.splitlines() == expected_message
+        assert result.returncode == 1
+
     def test_when_env_set_and_no_args_then_usage_printed_and_return_code_is_one(
         self, test_config_env  # pylint: disable=unused-argument
     ):