Module entry 

Loading and handling of CLAP plugin entry files.

On Windows and Linux (and other non-macOS UNIXes), CLAP plugins are distributed as prebuilt dynamically-loaded libraries (usually .dll or .so files) with a .clap extension. They expose a single EntryDescriptor, which, once initialized, acts as the entry point for the host to read into the library file.

On macOS, CLAP plugins are distributed as a standard bundle, which contains the aforementioned dynamically-loaded libraries as its executable file.

CLAP plugin entries expose implementations of various standard factories, which are singletons implementing various functionalities. The most relevant is the PluginFactory, which allows to list and instantiate plugins. See the factory module documentation to learn more about factories.

Clack handles all of this functionality through the PluginEntry type, which exposes all the entry’s factory implementation, and allow the entry to be loaded in different ways:

• From a file, using PluginEntry::load.

  This is the most common usage, as it allows to load third-party CLAP entries present anywhere on the file system, which is most likely the functionality “CLAP plugin support” implies for most hosts.

• From an EntryProvider type, using PluginEntry::load_from.

  This is a more advanced usage, and it allows host implementations to not use Clack’s implementation of entry loading (which uses libloading under the hood), and implement their own instead.

  It also allows host implementations to customize Clack’s implementation of entry loading by leveraging the LibraryEntry built-in entry provider type.

• From a clack-plugin’s Entry type, using PluginEntry::load_from_clack.

  This allows to load plugins that have been statically built into the host’s binary (i.e. built-in plugins) without having to distribute them in separate files, or to perform any filesystem access or plugin discovery.

  This is also the only way to load a CLAP plugin using only safe code, since it leverages clap-plugin’s safety guarantees to enforce that plugins loaded this way cannot cause Undefined Behavior.

See the PluginEntry’s type documentation for examples.

Safety

All functions that produce PluginEntrys from a CLAP entry file or pointer are inherently unsafe.

Most APIs in this crate operate under the assumption that entries and plugins are compliant to the CLAP specification, and using a number of those APIs can easily result in Undefined Behavior if operating on non-compliant plugins.

Therefore, the safe APIs in this crate are safeguarding the host implementation, not the plugins it loads. As soon as a plugin is loaded, Undefined Behavior is possible to be triggered, regardless of the host’s implementation.

Users needing to safeguard against crashes or other kinds of UB from plugins from affecting the rest of their application should consider using additional process isolation techniques.

Plugin entry discovery

Clack itself does not implement any utilities to aid host implementations with discovering which CLAP entry files are available to be loaded on the filesystem.

However, you may use the separate clack-finder library to perform this task.

Refer to the CLAP specification for more information about standard search paths and the general discovery process.

Structs

LibraryEntrylibloading

An EntryProvider which loads an entry from a dynamic library file.

PluginEntry

A handle to a loaded CLAP plugin entry.

Enums

PluginEntryError

Errors that can occur while loading a PluginEntry.

Traits

EntryProvider

A type which can provide an entry descriptor pointer for Clack hosts to load.

Type Aliases

EntryDescriptor

A C-FFI compatible descriptor of a CLAP file’s entry point.