Import Functions

Learn how to import functions from other plugins written in different languages and use them in your own.

To use functions from another plugin in your C++ plugin, you need to generate language-specific header files. These headers provide the necessary wrappers to call functions exported by other plugins. This guide explains how to generate these headers and how to use them in your C++ plugin.

Generating Header Files

Plugify provides a unified generator tool to automatically generate header files for importing functions from other plugins. These headers include wrapper functions that handle the function calls and parameter passing.

Steps to Generate Bindings

Using the Online Generator:

Visit plugify-gen tool to generate bindings through a user-friendly web interface. Simply upload your plugin manifest file (.pplugin) and select C++ as the target language to generate the corresponding module.

Using the Command-Line Tool:

You can also download and use the generator tool locally from the plugify-gen repository.

Example usage:

plugify-gen -manifest ./plugins/plugin_from_another_language/plugin_from_another_language.pplugin -output ./output/ -lang cpp

Integrate the Generated Module:

  • The tool will generate a module folder (e.g., plugin_from_another_language/) in the specified output directory.
  • Copy the entire generated module folder to your project's source directory.
  • Include the module's header files in your build system (CMakeLists.txt, Makefile, etc.).
  • Add the module directory to your include paths.

Project Integration

After generating the module, integrate it into your C++ project:

Copy Module to Project

Copy the generated module folder to your project's source directory:

cp -r ./output/plugin_from_another_language ./my_plugin/src/

Update CMakeLists.txt

Add the module directory to your include paths:

target_include_directories(${PROJECT_NAME} PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/plugin_from_another_language
)

Include in Source Files

Include the generated headers in your source files:

#include "plugin_from_another_language/plugin_from_another_language.hpp"

Using Generated Wrapper Functions

The generated module contains wrapper functions that allow you to call functions from the other plugin. These wrappers handle the function address lookup and parameter passing.

Example Generated Header

Here’s an example of a generated header file for a plugin named plugin_from_another_language:

plugin_from_another_language.hpp
#pragma once

#include <cstdint>
#include <plg/plugin.hpp>
#include <plg/any.hpp>

// Generated from plugin_from_another_language.pplugin by https://github.com/untrustedmodders/plugify-gen

namespace plugin_from_another_language {
    using _ParamCallback = void (*)(int32_t, float, double, const plg::vec4&, const plg::vector<int64_t>&, char, const plg::string&, char16_t, int16_t);
    extern _ParamCallback __plugin_from_another_language_ParamCallback = nullptr;
        
    inline void ParamCallback(int32_t a, float b, double c, const plg::vec4& d, const plg::vector<int64_t>& e, char f, const plg::string& g, char16_t h, int16_t k) {
        __plugin_from_another_language_ParamCallback(a, b, c, d, e, f, g, h, k);
    }
} // namespace plugin_from_another_language

How It Works

  • The wrapper function (ParamCallback) retrieves the address of the exported function using plg::GetMethodPtr or plg::GetMethodPtr2.
  • The ____plugin_from_another_language_ParamCallback delegate is set by the language module during plugin load.
  • The wrapper function directly passes the parameters to the exported function, leveraging the C calling convention.

Example: Using the Generated Header

Here’s how you can use the generated header in your C++ plugin:

plugin.cpp
#include "plugin_from_another_language.hpp" // Include the generated header

void MyPluginFunction() {
    // Call the exported function from the other plugin
    plugin_from_another_language::ParamCallback(
        42,                // int32_t a
        3.14f,             // float b
        2.718,             // double c
        {1.0f, 2.0f, 3.0f, 4.0f}, // plg::vec4 d
        {100, 200},        // plg::vector<int64_t> e
        'x',               // char f
        "Hello, Plugify!", // plg::string g
        u'✓',              // char16_t h
        10                 // int16_t k
    );
}

When is Header Generation Necessary?

Header generation is essential when importing functions from plugins written in statically-typed languages like C++ or C#. Without these headers, the compiler cannot reference the exported functions. For dynamically-typed languages like Python, header generation is not necessary because method binding happens at runtime.

Best Practices

  1. Use the Generator Tool: Always use the Plugify generator tool (online or command-line) to generate headers for imported functions.
  2. Include Generated Headers: Include the generated headers in your plugin source files to access the exported functions.
  3. Test Thoroughly: Test the imported functions to ensure they work as expected.
  4. Document Dependencies: Clearly document the plugins and functions your plugin depends on.

Conclusion

Importing functions from another plugin in C++ is straightforward when you use the Plugify generator tool to generate the necessary headers. These headers provide wrapper functions that handle function address lookup and parameter passing, making it easy to integrate functionality from other plugins. By following the steps and best practices outlined in this guide, you can create robust and interoperable plugins in the Plugify ecosystem.

Edit this page on GitHub
Export Functions
Guide to export functions from your C++ plugin to be used by other language modules within Plugify.
Build Module
Detailed instructions on building and packaging Golang language module.