Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/plugdata-team/plugdata/llms.txt

Use this file to discover all available pages before exploring further.

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

1
Step 1: Add Your Source Files
2
You have two options:
3
Option A: Add to externals target (recommended)
4
Edit Libraries/CMakeLists.txt and add your sources to the externals target:
5
add_library(externals STATIC 
    ${ELSE_SOURCES} 
    ${CYCLONE_SOURCES} 
    ${PDLUA_SOURCES}
    # Add your external here:
    path/to/your/external.c
)
6
Option B: Add to ELSE folder (automatic)
7
Place your .c files in Libraries/ELSE/Source/ or Libraries/pd-else/Source/Audio/:
8
cp myexternal.c Libraries/pd-else/Source/Audio/
9
All .c files in these folders are automatically compiled (see Libraries/CMakeLists.txt:215-241).
10
Step 2: Register Setup Function
11
Edit Source/Pd/Setup.cpp and add your setup function declaration and call.
12
Add declaration (in the extern "C" block around line 725):
13
extern "C" {

// ... existing declarations ...

void myexternal_setup();  // Add your declaration

}
14
Call setup function in one of these initialization functions:
15
void Setup::initialiseELSE()
{
    // ... existing setup calls ...
    
    myexternal_setup();  // Add your setup call
    
    // ... more setup calls ...
}
16
Step 3: Rebuild
17
cd build
cmake --build .

​
Setup Function Locations

Choose where to call your setup function based on desired namespace: 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:
1
Step 1: Create External Source
2
Create Libraries/pd-else/Source/Audio/mygain~.c:
3
#include "m_pd.h"

static t_class *mygain_tilde_class;

typedef struct _mygain_tilde {
    t_object x_obj;
    t_float x_gain;
    t_float x_f;  // dummy float for signal inlet
} t_mygain_tilde;

t_int *mygain_tilde_perform(t_int *w)
{
    t_mygain_tilde *x = (t_mygain_tilde *)(w[1]);
    t_sample *in = (t_sample *)(w[2]);
    t_sample *out = (t_sample *)(w[3]);
    int n = (int)(w[4]);
    t_float gain = x->x_gain;
    
    while (n--)
        *out++ = *in++ * gain;
    
    return (w+5);
}

void mygain_tilde_dsp(t_mygain_tilde *x, t_signal **sp)
{
    dsp_add(mygain_tilde_perform, 4, x,
        sp[0]->s_vec, sp[1]->s_vec, sp[0]->s_n);
}

void mygain_tilde_float(t_mygain_tilde *x, t_float f)
{
    x->x_gain = f;
}

void *mygain_tilde_new(t_floatarg f)
{
    t_mygain_tilde *x = (t_mygain_tilde *)pd_new(mygain_tilde_class);
    x->x_gain = f;
    outlet_new(&x->x_obj, &s_signal);
    return (x);
}

void mygain_tilde_setup(void)
{
    mygain_tilde_class = class_new(gensym("mygain~"),
        (t_newmethod)mygain_tilde_new, 0,
        sizeof(t_mygain_tilde),
        CLASS_DEFAULT,
        A_DEFFLOAT, 0);
    
    CLASS_MAINSIGNALIN(mygain_tilde_class, t_mygain_tilde, x_f);
    class_addmethod(mygain_tilde_class, (t_method)mygain_tilde_dsp,
        gensym("dsp"), A_CANT, 0);
    class_addfloat(mygain_tilde_class, mygain_tilde_float);
}
4
Step 2: Declare Setup Function
5
Add to Source/Pd/Setup.cpp:
6
extern "C" {

// Around line 1232, with other ELSE declarations:
void mygain_tilde_setup();

}
7
Step 3: Call Setup Function
8
Add to Setup::initialiseELSE() in Source/Pd/Setup.cpp:
9
void Setup::initialiseELSE()
{
    pdlink_setup();
    pdlink_tilde_setup();
    
    // Add after other setup calls:
    mygain_tilde_setup();
    
    knob_setup();
    above_tilde_setup();
    // ... rest of ELSE externals ...
}
10
Step 4: Build and Test
11
cd build
cmake --build .
12
Test in plugdata:
13
[osc~ 440]
|
[mygain~ 0.5]
|
[dac~]

​
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

​
Next Steps

Building from Source

Learn the complete build process

Lua Scripting

Create externals using Lua scripting

Build docs developers (and LLMs) love

Get started for freeTalk to us