pdjs

A JavaScript external for Pure Data based on V8.

pdjs tries to emulate Max's js object. Many JavaScript source files written for Max js should work unchanged with pdjs.

While the Max js object uses a version of Mozilla's SpiderMonkey JavaScript engine that was released in 2011 with Firefox 4.0 and thus lacks many newer language features (such as let), pdjs uses Google's V8 JavaScript engine which supports the latest ECMAScript standards and provides much better performance.

Supported platforms

• Windows x64
• Linux x64
• Linux arm64
• Linux arm
• macOS x64

Usage

You can install through deken or grab a zip from releases. Then create a js object giving it the name of a JavaScript file, e.g. js src.js, relative to your patch or absolute. You might also have to add a declare -path pdjs object so that PD can find the external. For more usage information you can consult the Max JavaScript documentation which applies to pdjs as well.

Feature support

General

There is no built-in editor like in Max, source files have to be created and edited outside of Pure Data.

Arguments

• filename
• inlets-outlets
• jsarguments

Messages

• bang
• int (there are no ints in PD)
• float
• list
• anything
• autowatch
• compile
• delprop
• editfontsize
• getprop
• loadbang
• open (Windows only)
• setprop
• statemessage
• wclose

Special function names

• msg_int
• msg_float
• list
• anything
• loadbang
• getvalueof
• setvalueof
• save
• notifydeleted

Private functions are supported.

Global functions

• cpost
• error
• include
• messnamed
• post
• require
• arrayfromargs (use Array.from(arguments) or [...arguments] instead)
• assist
• declareattribute
• embedmessage
• notifyclients
• outlet
• setinletassist
• setoutletassist

Global properties

• autowatch
• editfontsize
• inlet
• inlets
• inspector
• jsarguments (no support for jsargs message)
• Max
• maxclass
• messagename
• patcher
• outlets

Other Objects

There is no support currently for other objects such as Buffer, Dict, File, etc.

Sharing JavaScript objects across js object instances

You can pass references to JavaScript objects across js object instances using the jsobject mechanism.

There is also a special global variable called __global__ that references the same object from every js object instance. It's similar to the Global object in Max. Unlike in Max, you can also call functions contained in the __global__ object.

Building

pdjs uses CMake to build. Prebuilt V8 binaries can be downloaded from my V8 fork and pd.build is used to build the external library.

Prerequisites

• Windows: Visual Studio 2019 (any edition, older versions may work, though not tested). You need to have the Desktop development with C++ workload installed. If you want to build the Linux external from VS you'll also need the workload Linux development with C++.

• Linux:

  • g++
  • cmake 3.13 or higher (if your distro has an older version, you can grab a static build from https://github.com/Microsoft/CMake/releases)
  • ninja-build

V8 libraries

The build process expects the V8 library v8_monolith library in v8/lib/[platform], e.g. v8/lib/x64-linux. You can either download prebuilt binaries from https://github.com/mganss/v8/releases/latest or build your own. This repo contains the GN configuration files that were used to build V8 in the v8 directory.

Building

Also check out the GitHub Actions workflow definition for more details on the build process.

Windows

Open the top-level directory of the repo in VS and hit F6. The CMakeSettings.json contains 4 configurations: x64-Debug and x64-Release for Windows builds and WSL-GCC-Debug and WSL-GCC-Release for x64 Linux builds through WSL.

Linux

mkdir -p out/build/x64-linux-Debug
cmake -G Ninja \
  -DVERSION=1.0 \
  -DCMAKE_BUILD_TYPE=Debug \
  -B out/build/x64-linux-Debug -S .
cmake --build out/build/x64-linux-Debug -- -v