Adding Custom Externals

Plugdata allows you to compile custom Pure Data externals directly into the plugin, making them available in both plugin and standalone versions.

Overview

Unlike traditional Pure Data where externals are loaded as shared libraries, plugdata statically compiles externals into the application. This ensures:

✅ Externals work in plugin hosts (DAWs)
✅ No external file dependencies
✅ Consistent behavior across platforms
✅ Better performance and security

Quick Start

Setup Function Locations

Choose where to call your setup function based on desired namespace:

libpd_init_pdlua (Recommended)

Called in Setup::initialisePdLua() (Source/Pd/Setup.cpp:1399-1402). Best for:

Standalone externals
No namespace prefix required
Independent objects

Example:

void Setup::initialisePdLua(char const* datadir, char* vers, int const vers_len, 
                             void (*register_class_callback)(char const*))
{
    pdlua_setup(datadir, vers, vers_len, register_class_callback);
    
    myexternal_setup();  // Available as [myexternal]
}

initialiseELSE

Called in Setup::initialiseELSE() (Source/Pd/Setup.cpp:1473). Note:

Externals registered here are available under both the plain name and else/ prefix:

[myexternal] ✅
[else/myexternal] ✅

Example:

void Setup::initialiseELSE()
{
    pdlink_setup();
    pdlink_tilde_setup();
    
    myexternal_setup();  // Available as [myexternal] and [else/myexternal]
    
    // ... rest of ELSE setup ...
}

initialiseCyclone

Similar to ELSE, but for Cyclone compatibility. Note: Externals available as [myexternal] and [cyclone/myexternal].

Complete Example

Let’s add a simple gain external:

Multi-File Externals

For externals with multiple source files:

Libraries/CMakeLists.txt

list(APPEND MY_EXTERNAL_SOURCES
    path/to/myexternal.c
    path/to/myexternal_helper.c
    path/to/myexternal_dsp.c
)

add_library(externals STATIC 
    ${ELSE_SOURCES}
    ${CYCLONE_SOURCES}
    ${PDLUA_SOURCES}
    ${MY_EXTERNAL_SOURCES}
)

Including Headers

For externals needing additional headers:

Libraries/CMakeLists.txt

target_include_directories(externals PRIVATE
    ${ELSE_INCLUDES}
    path/to/your/headers
)

Platform-Specific Code

Use preprocessor directives for platform-specific code:

#ifdef _WIN32
    // Windows-specific code
#elif __APPLE__
    // macOS-specific code
#elif __linux__
    // Linux-specific code
#endif

Common Issues

Undefined Reference Errors

undefined reference to 'myexternal_setup'

Solution: Ensure setup function is declared in extern "C" block and definition matches exactly.

External Not Found

... couldn't create

Solution: Verify setup function was called and class name matches object name.

Multiple Definition Errors

multiple definition of 'myexternal_setup'

Solution: Check that source file isn’t added twice in CMakeLists.txt.

Code References

Key files for adding externals:

External targets: Libraries/CMakeLists.txt:453-454
ELSE auto-compilation: Libraries/CMakeLists.txt:215-241
Setup declarations: Source/Pd/Setup.cpp:159-1321
initialiseELSE: Source/Pd/Setup.cpp:1473-1829
initialisePdLua: Source/Pd/Setup.cpp:1399-1402

Getting Started

Core Concepts

User Guide

Objects Reference

Advanced

Resources

Adding Custom Externals

Overview

Quick Start

Setup Function Locations

libpd_init_pdlua (Recommended)

initialiseELSE

initialiseCyclone

Complete Example

Multi-File Externals

Including Headers

Platform-Specific Code

Common Issues

Undefined Reference Errors

External Not Found

Multiple Definition Errors

Code References

Next Steps

Building from Source

Lua Scripting

​Overview

​Quick Start

​Setup Function Locations

​libpd_init_pdlua (Recommended)

​initialiseELSE

​initialiseCyclone

​Complete Example

​Multi-File Externals

​Including Headers

​Platform-Specific Code

​Common Issues

​Undefined Reference Errors

​External Not Found

​Multiple Definition Errors

​Code References

​Next Steps

Building from Source

Lua Scripting

Overview

Quick Start

Setup Function Locations

libpd_init_pdlua (Recommended)

initialiseELSE

initialiseCyclone

Complete Example

Multi-File Externals

Including Headers

Platform-Specific Code

Common Issues

Undefined Reference Errors

External Not Found

Multiple Definition Errors

Code References

Next Steps