libpd

Pure Data as an embeddable audio synthesis library

Copyright (c) Peter Brinkmann & the libpd team 2010-2025

Documentation

For documentation of libpd, see the wiki: https://github.com/libpd/libpd/wiki

If you are using Processing, iOS, or Android, see our companion repositories:

• puredatap5
• pd-for-ios
• pd-for-android

Getting libpd

The preferred method to download libpd is to use git.

Do not download libpd as a zip or tar.gz file from GitHub.

The "Download ZIP" button may look like a good idea, but currently Github does not include submodule files when compiling zip files. This means the zip file is missing the main pd source files and you will not be able to build libpd, with errors such as: No rule to make target pure-data/src/d_arithmetic.o or No such file or directory: pure-data/extra/bonk~/bonk~.c.

To download libpd & check out the pure-data submodule, do the following:

git clone --recurse-submodules https://github.com/libpd/libpd.git

You should now have a libpd directory and the libpd/pure-data directory should contain the pd sources.

Note: If your version of git does not support "--recurse-submodules", you can run the git submodule commands in the libpd directory itself after cloning:

cd libpd
git submodule update --init --recursive

For most uses, it is recommended to check out the latest stable release version via a git tag. For example, to switch to libpd version 0.8.3 after cloning:

git checkout 0.8.3
git submodule update

The master branch contains the latest libpd development and can be considered generally stable. However, we make no guarantees. :)

Repository Layout

pure-data

The directory containing the sources of Pd Vanilla and it's standard externals. This is a git submodule of Miller Puckette's official Pd git repository:

git://git.code.sf.net/p/pure-data/pure-data

libpd_wrapper

This directory contains the source files that make up the core of libpd.

Android.mk, Makefile, libpd.xcodeproj, libpd_csharp.sln, .classpath, .project

Build support for various platforms. Feel free to improve the build system in any way you see fit.

cpp, csharp, java, jni, objc, python

Glue for using libpd with C++, C#, Java, Objective-C, and Python. Feel free to improve or add support for other languages such as Lua.

samples

Small sample programs and tests in the various supported languages.

libs

The build result location and required software libraries for the various supported languages.

Building libpd

Core build requirments:

• Unix command shell: bash, dash, etc
• C compiler chain: gcc/clang & make

Note: The various language wrappers may have additional requirements.

Currently the main Makefile builds a dynamic lib on Windows (in MinGW), Linux, & macOS and has the following targets:

• libpd: build the libpd C core, default if no target is specified
• csharplib: build libpdcsharp
• javalib: build libpdnative and the jni wrapper
• javadoc: generate Java HTML documentation
• javasrc: create a Java source jar
• clean: remove object files
• clobber: remove linked library files
• install: install libpd C library and C/C++* headers, set location with prefix= (default: /usr/local)
• uninstall: remove libpd C library and C/C++ headers, set location with prefix= (default: /usr/local)

* C++ headers are only installed if the C utility layers were built as well (ie. UTIL=true), see below.

Makefile options allow for conditional compilation of libpd util and pd extra externals sources into libpd as well as other options:

• UTIL=true: compile utilities in libpd_wrapper/util (default)
• EXTRA=true: compile pure-data/extra externals which are then inited in libpd_init() (default)
• MULTI=true: compile with multiple instance support
• DOUBLE=true: compile with double-precision support
• DEBUG=true: compile with debug symbols & no optimizations
• STATIC=true: compile static library (in addition to shared library)
• FAT_LIB=true: compile universal "fat" lib with multiple architectures (macOS only)
• LOCALE=false: do not set the LC_NUMERIC number format to the default "C" locale* (default)
• PORTAUDIO=true: compile with portaudio support (currently JAVA jni only)
• JAVA_HOME=/path/to/jdk: specify the path to the Java Development Kit

To build the libpd C core with default options:

make

To build libpd without the util libs and extra externals:

make UTIL=false EXTRA=false

Note: The C++ wrapper requires UTIL=true as it uses the ringbuffer.

* See the Known Issues section for more info.

If you need to add custom search paths to the CFLAGS or LDFLAGS, you can specify them when building via the ADDITIONAL_* variables:

make ADDITIONAL_CFLAGS="-I/usr/local/include" \
     ADDITIONAL_LDFLAGS="-L/usr/local/lib"

Once libpd has built successfully, the compiled libraries will be found in the libs directory.

Linux & BSD

Install the core build requirements using your distribution's package manager. For Debian, you can install the compiler chain, autotools, & gettext with:

sudo apt install build-essentials

If you want to cross-compile for other architectures, you need additional packages and set the CC environment variable for the architecture. Examples using Debian based amd64 distribution:

For 32bit Intel:

sudo apt install gcc-i686-linux-gnu
make CC=i686-linux-gnu-gcc

For 32bit ARM:

sudo apt install gcc-arm-linux-gnueabi
make CC=arm-linux-gnueabi-gcc

For 64bit ARM:

sudo apt install gcc-aarch64-linux-gnu
make CC=aarch64-linux-gnu-gcc

macOS

macOS is built on top of a BSD system and the bash or zsh commandline can be accessed with the Terminal application in the /Applications/Utility directory.

Xcode

The clang compiler and associated tools are provided by Apple. If you are running macOS 10.9+, you do not need to install the full Xcode application and can install the Commandline Tools Package only by running the following:

xcode-select --install

If you are running macOS 10.6 - 10.8, you will need to install Xcode from the Mac App Store or downloaded from http://developer.apple.com

Fat Libs

By building with the FAT_LIB=true Makefile option, libpd will be compiled with support for multiple architectures depending on the detected system version:

• macOS <= 10.13: i386 (32 bit Intel) & x86_64 (64 bit Intel)
• macOS >= 11.0: arm64 (64 bit Arm) & x86_64 (64 bit Intel)

To override autodetection, specify the -arch flags directly using the FAT_ARCHS Makefile option:

make FAT_LIB=true FAT_ARCHS="-arch i386 -arch x86_64"

Windows

libpd on Windows can be built with MinGW which provides the core build requirements: a compiler chain & shell environment. It is recommended to use the Msys2 distribution which provides both a Unix command shell and MinGW. Download the Msys2 64 bit installer for x86_64 or amd64 from:

http://www.msys2.org/

For 32 bit the latest version can be downloaded from https://repo.msys2.org/distrib/i686/, because it has been deprecated by the developers.

Then install to the default location (C:\msys32 or C:\msys64) and follow the setup/update info on the Msys2 webpage.

Msys2 provides both MinGW and command shells which are used to compile. Due to how MinGW is designed, you can only build a dll for the current installed environment.

Note: Msys2 development seems to change frequently, so some of the package names below may have changed after this document was written.

Open an Msys2 shell and install the compiler chain & make via:

# 32 bit
pacman -S mingw-w64-i686-toolchain mingw-w64-i686-clang make

# 64 bit
pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-clang make

You can also search for packages in Msys2 with pacman -S -s <searchterm>.

Once the packages are installed, you should now be ready to build libpd.

Note: For 64 bit Windows, build Pd with the following additional C flags to ensure long integers are the correct length:

make ADDITIONAL_CFLAGS='-DPD_LONGINTTYPE="long long"'

If you run into strange errors such as /bin/sh: cc: command not found, try closing and reopening your shell window before building again.

Double-Precision Support

By default, libpd computes numbers and samples internally as single-precision 32-bit floats. This is fast and good enough for most general usage. If you are working with small numbers beyond 6 decimal points, however, you will need a higher degree of precision.

To enable double-precision 64-bit floating point support, build libpd with -DPD_FLOATSIZE=64 in the CFLAGS. The libpd makefile provides the DOUBLE makefile variable for this:

make DOUBLE=true

Now utilize the libpd API which use the double type, such as the libpd double hook, libpd_add_double(), and libpd_process_double().

To double-check your build, the following will print a 1 if double-precision support is enabled:

printf("double-precision %d\n", (int)(sizeof(t_float)/8));

Loading Externals

Libpd can load pre-compiled dynamic libraries of external objects in the same manner as desktop Pd if it is compiled with the -ldl LDFLAG. This is done by default in the Makefile. The main difference is that libpd does not inherit the same search paths by default, so paths outside of those specified by the loading patch with [declare] objects need to be added via libpd's "add to search path" function.

Multi-Instance Compatibility

If libpd is compiled with multi-instance support via make MULIT=true and `-DPDINSTANC