Adding Externals Support (Devs)

For Developers of Pd Objects

This section is intended for those developing Pd objects and looking to add the object to pd4web. If this doesn't apply to you, feel free to skip this section.

pd4web: Adding Support to Externals

pd4web consists of a set of tools accessible via a Python module named pd4web. Internally, pd4web utilizes EMSCRIPTEN to compile external components into dynamic static libraries.

To integrate a new library, you must create a CMakeLists.txt. It's highly recommended to use pd.cmake due to assumptions made (such as the TARGET name convention like earplug~ becoming earplug_tilde and others). After creating the CMakeLists.txt for the library you need, you can submit a PR that modifies Externals.yaml within Sources/pd4web/Libraries. In this file, simply add a new entry similar to the provided example. This will make the library compatible with pd4web.

This is an example of how to define a library in the Externals.yaml file:

  - Name: cyclone # name of the pd library
    Source: GITHUB # source
    Developer: porres # in this case, Github user name
    Repository: pd-cyclone # in this case, Github Repo
    Version: cyclone_0.7-0 # version (tag name of stable commit hash)

Below the complete fields for enviroment.

Key Name	Description
Name	With name you specify the name of the library, for example else, cyclone, timbreIdLib.
Developer	The username of the user where the repository is hosted. For example porres.
Repository	The name of the repository where it is hosted. For example pd-else.
Source	The download source, it must be GITHUB_RELEASES or GITHUB_TAGS.

Building the CmakeLists.txt

The CMakeLists.txt file is the most important file for the compilation of the external. It defines the external's name, the source files, and the dependencies. The following is an example of a CMakeLists.txt file for the earplug~ library/object.

cmake_minimum_required(VERSION 3.25)
project(earplug~)
set(LIB_DIR "${PD4WEB_EXTERNAL_DIR}/${PROJECT_NAME}")

pd_add_external(earplug~ "${LIB_DIR}/earplug.c")

Note that, pd_add_external is a function provided by the pd.cmake module. The first argument is the external's name, and the second argument is the source file.

The LIB_DIR variable is used to define the external's directory. This directory will be ${PD4WEB_EXTERNAL_DIR} followed by the library external name defined in the Externals.yaml file.

PD4WEB_EXTERNAL_DIR is a variable that points to the directory where the external's source files are located. It is defined in the CMakeLists.txt generated by pd4web (you don't need to define it).