libpd

Pure Data 作为可嵌入的音频合成库

文档

请访问我们的网站和书籍，网址为 http://libpd.cc

有关 libpd 的文档，请参阅 wiki： https://github.com/libpd/libpd/wiki

如果您使用 Processing、iOS 或 Android，请参阅我们的配套仓库

获取 libpd

下载 libpd 的首选方法是通过 git。

请不要从 GitHub 下载 libpd 的 zip 或 tar.gz 文件。

"下载 zip" 按钮看起来可能是个好主意，但当前 GitHub 在编译 zip 文件时不包含子模块文件。这意味着 zip 文件缺少主要的 pd 源文件，您将无法构建 libpd，并且可能会遇到例如： "没有规则来生成目标 pure-data/src/d_arithmetic.o" 或 "没有此类文件或目录： pure-data/extra/bonk~/bonk~.c" 的错误。

要下载 libpd 并检出 pure-data 子模块，请执行以下操作

git clone https://github.com/libpd/libpd.git
cd libpd
git submodule init
git submodule update

现在您应该有一个 libpd 目录，且 libpd/pure-data 应该包含 pd 源文件。如果不是这样，请确保您在 libpd 目录中运行了 git 子模块命令。

对于大多数用途，建议检查最新稳定发布版本，使用 git 标签。例如，在克隆后切换到 libpd 版本 0.8.3：

git checkout 0.8.3

主分支包含最新的 libpd 开发版本，可以被认为是通常稳定的。但是，我们不做任何保证。 :)

仓库布局

纯数据

Pd Vanilla及其标准扩展的源代码目录。这是Miller Puckette的官方Pd git仓库的子模块。

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

libpd_wrapper

该目录包含构成libpd核心的源代码文件。

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

支持各种平台的构建。您可以自由地按需改进构建系统。

cpp, csharp, java, jni, objc, python

用于C++, C#, Java, Objective-C和Python使用libpd的粘合剂。您可以自由改进或添加对其他语言如Lua的支持。

样本

各种支持语言的小示例程序和测试。

libs

支持的各种语言的构建结果位置和所需的软件库。

构建libpd

核心构建要求

Unix命令行shell：bash，dash等
C编译链：gcc/clang & make

注意：各种语言包装器可能还有额外的需求。

当前主要的Makefile在Windows（MinGW）、Linux和MacOS X上构建动态lib，有以下目标

libpd：构建libpd C核心，默认如果没有指定目标
csharplib：构建libpdcsharp
javalib：构建libpdnative和jni包装器
javadoc：生成Java HTML文档
javasrc：创建Java源jar
clean：删除对象文件
clobber：删除链接库文件
install：安装libpd C库和C/C++*头文件，设置位置使用prefix=（默认：/usr/local）
uninstall：删除libpd C库和C/C++头文件，设置位置使用prefix=（默认：/usr/local）

* C++头文件仅在同时构建C实用层时安装（即UTIL=true），见下文。

Makefile选项允许条件编译libpd实用和pd附加外部源码到libpd以及其他选项

UTIL=true：编译位于libpd_wrapper/util的实用程序（默认）
EXTRA=true：编译位于pure-data/extra的外部程序，然后在libpd_init()中初始化（默认）
MULTI=true：编译支持多个实例
DEBUG=true：编译带有调试符号且没有优化的程序
LOCALE=false：不要将LC_NUMERIC数字格式设置为默认的"C"区域设置*（默认）
PORTAUDIO=true：编译带有Portaudio支持（目前仅限JAVA jni）
JAVA_HOME=/path/to/jdk：指定Java开发工具包的路径

要使用默认选项构建libpd C核心

make

要构建不包含util库和附加外部程序的libpd

make UTIL=false EXTRA=false

注意：C++包装器需要UTIL=true，因为使用了环形缓冲区。

* 参见已知问题部分以获取更多信息。

如果您需要将自定义搜索路径添加到CFLAGS或LDFLAGS，您可以在构建时通过ADDITIONAL_*变量指定它们

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

一旦成功构建libpd，编译好的库将位于libs目录中。

Linux & BSD

使用您的发行版的包管理器安装核心构建需求。对于Debian，您可以使用以下命令安装编译链、autotools和gettext：

sudo apt-get install build-essentials

macOS

macOS 建立在 BSD 系统之上，您可以通过“/Applications/Utility”目录中的 Terminal 应用程序访问 bash 命令行。

clang 编译器和相关工具由苹果公司提供。如果您正在运行 macOS 10.9 或更高版本，您无需安装完整的 Xcode 应用程序，只需运行以下命令即可安装 Commandline ToolsPACKAGE：

xcode-select --install

如果您正在运行 macOS 10.6-10.8，您需要从 Mac App Store 安装 Xcode 或从 http://developer.apple.com 下载。

Windows

Windows上的libpd可以使用MinGW或Cygwin构建，后者提供核心构建要求：编译器链和外壳环境。

建议使用Msys2发行版，它提供了Unix命令外壳和MinGW。从以下网址下载Msys2“x86_64”64位安装程序（或如果您使用32位Windows，则使用“i686”）：

http://www.msys2.org/

然后将其安装到默认位置（C:\msys32或C:\msys64），并按照Msys2网页上的设置/更新信息进行操作。

Msys2提供32位和64位MinGW和命令外壳，分别用于编译32位和64位。由于MinGW的设计方式，您无法使用32位MinGW构建64位libpd，反之亦然。

注意：Msys2开发似乎经常变化，因此以下某些包名可能在编写本文件后已更改。

打开Msys2外壳，并使用以下命令安装编译器链、autotools和gettext：

# 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

您还可以使用pacman -S -s <searchterm>在Msys2中搜索包。

安装这些包后，您现在应该可以构建libpd了。

C++

C++包装程序灵感来源于Java包装程序，它提供了一个PdBase类以及监听器、列表和消息类型类。这是一个仅包含头文件的库，因此您只需将项目中的“cpp”目录包含在内。另外，您可能还需要将libpd_wrapper/util添加到您的包含路径中。

示例程序在samples/cpp中。

C#

从 NuGet 安装

libpd 的 C# 库作为 NuGet 包可用

https://nuget.net.cn/packages/LibPdBinding

如果您的平台的原生 libpdcsharp.(so/dll) 不包含在内，您必须自行编译并复制生成的文件到输出目录。包含了用于 Windows 上 MinGW 编译的批处理脚本。

自行编译

C# 库期望在它的目录中有一个文件 libpdcsharp.(so/dll)。在使用项目之前，您需要编译它

make csharplib

将 csharp/LibPdBinding.csproj 包含在您的解决方案中，并在您的应用程序中引用该项目。有关详细信息，请参阅 csharp/README.txt。

Windows

此包装可以与 MinGW 一起构建。有关设置基于 Msys2 的 MinGW 构建环境，请参阅上一节“Windows”中的说明。

使用与您使用的 MinGW 匹配的 .bat DOS 批处理文件包装器构建 libpdcsharp

# 32 bit
./mingw32_build_csharp.bat

# 64 bit
./mingw64_build_csharp.bat

通常您想要 32 位版本，因为它也会在 64 位 Windows 上工作。但是，某些 C# 环境（如 Unity 5）需要 64 位版本。

编译完成之后，应在 libs 目录中找到一个 libpdcsharp.(so/dll) 库

您可能还需要与 libpdcsharp 一起使用 libwinpthread 库。这包含在 libpd 中的 libs 目录内，要么在 libs/mingw32，要么在 libs/mingw64 中。对于当前版本的 libwinpthread-1.dll，在您的 Msys2 安装 bin 目录中搜索。

注意：如果您将 Msys2 安装到了非默认位置，您需要更改 .bat 文件中的 %MSYS2% 变量。

Linux

若要在Linux下使用Mono库，您需要对LibPdBinding项目进行以下更改：

使用 make csharplib 编译 .so 文件。
从LibPdBinding项目中移除 libpdcsharp.dll 和 libwinpthread-1.dll。
将 libpdcsharp.so 添加到LibPdBinding项目中。
将 libpdcsharp.so 的“复制到输出目录”设置为“始终复制”

Java

预编译的二进制文件

可能已过时

在libpd-java-build仓库中可找到Java的现成二进制文件

https://github.com/wivlaro/libpd-java-build

自己编译

您需要Java开发工具包（JDK）来编译libpd Java库。请确保JDK的/bin路径已添加到您的$PATH环境变量中，并且可选地，JAVA_HOME变量指向JDK位置。

使用以下命令编译libpd Java库：

make javalib

这应在 libs 目录中生成一个libpd.jar和pdnative.(so/dll)。

可选地，您可以使用Eclipse使用.classpath & .project工作空间文件编译libpd。

您还可以构建libpd源jar和Java HTML文档

make javasrc
make javadoc

这应在libs/libpd-sources.jar和javadoc目录中生成。

Linux & BSD

通过您的发行版的软件包管理器安装JDK。

macOS

可以通过下载安装包或使用 macOS 的开源软件包管理器来安装 JDK。

homebrew: https://brew.sh.cn (推荐)
macports: https://www.macports.org

Windows

此包装可以与 MinGW 一起构建。有关设置基于 Msys2 的 MinGW 构建环境，请参阅上一节“Windows”中的说明。

通过下载安装包安装 JDK，然后将其 bin 路径添加到 $PATH 环境变量，并将 JDK 路径添加到 $JAVA_HOME（可选）。如果 JDK 安装在 C:\Program Files\Java\jdk1.8.0_152，请将以下内容添加到 ~/.bash_profile：

# add JDK bin path
export PATH=$PATH:'C:\Program Files\Java\jdk1.8.0_152\bin'

# JDK path (optional)
export JAVA_HOME=C:/Program\ Files/Java/jdk1.8.0_152

如果 shell 打开着，请重新启动 shell。

使用以下命令构建 libpd javalib：

make javalib

您还可以在运行 make 时通过以下方式设置 JAVA_HOME 路径：

make javalib JAVA_HOME=C:/Program\ Files/Java/jdk1.8.0_152

完成构建后，您应在 libs 目录下找到 libpd.jar 和 pdnative.(so/dll)。

Objective-C

Objective-C 封装适宜用于 iOS 和 macOS，包括用于声音输入/输出的一个（目前为 iOS 独占）音频单元和音频管理器。

Xcode 项目

libpd.xcodeproj 提供了构建 libpd + Obj-C 封装的静态库的 Xcode 项目，适用于 iOS 和 macOS。将 libpd 项目拖拽到现有的 Xcode 项目中，然后在项目目标的一般标签页中将 libpd-ios（或 libpd-osx）添加到链接的框架和库中。

该 Xcode 项目构建以下目标

libpd-ios：iOS 的 libpd 和 Obj-C 封装
libpd-osx：macOS 的 libpd 和 Obj-C 封装
libpd-ios-multi：支持多个实例的 iOS libpd
libpd-osx-multi：支持多个实例的 macOS libpd

有关详细说明，请参阅在 Xcode 中使用 libpd。

如果您不熟悉静态库的工作原理或如何在 Xcode 中使用它们，请参阅此有用的教程创建 iOS 静态库。

注意：libpd 与 Xcode 的版本进行了测试。建议您避免使用测试版或开发者预览版。

CocoaPods

如果您使用 Xcode 构建 iOS 应用，可以使用 CocoaPods 将 libpd 添加到您的项目中。

在您的 CocoaPods podfile 中使用以下内容

pod 'libpd', :git => 'https://github.com/libpd/libpd', :submodules => true

Python

Python 包装器提供了一個 "pylibpd" 模組，反映 libpd C 內置 API。使用以下命令构建包装器：

cd python
make

请参阅 samples/python 中的示例程序。注意，某些示例需要 "pyaudio" Portaudio 库。

使用 CMake 构建

可以使用 CMake 构建 libpd C 库。

CMake 是一个跨平台的开源构建系统。CMake 通过使用简单的平台和编译器无关的配置文件来控制软件编译过程，并生成可以在您选择的编译器环境中使用的本地 makefiles 和工作区。

依赖项

CMake：您可以在此处下载适用于您平台上的 CMake 下载地址。最低版本为 2.8.11。
pthreads：在 Windows 上，您需要提供一个 pthreads 库。

如果您正在使用 MinGW，您可以从此存储库中的 libs/mingw* 目录中使用的 libwinpthread-1.dll。或者，您也可以从此处下载它或从中编译它。这通常会生成 pthreadGC2.(dll/lib)。

如果您正在使用 Visual Studio，则需要提供为 Visual Studio 编译的 pthreads 库，无论是通过下载还是本地编译。请参阅此处。务必下载 / 编译与您的设置相符的正确版本。这通常是 pthreadVC2.(dll/lib)。

配置构建过程

配置CMake的一种方法是使用CMake GUI。GUI将列出可以提供给配置构建的变量。变量也可以在命令行界面中指定（例如以下示例）

在此步骤中，您可以选择要包含的特性和上述所描述的PD_EXTRA、PD_LOCALE、PD_MULTI和PD_UTILS。您还可以通过使用PD_BUILD_C_EXAMPLES启用构建C样例程序。

当使用Microsoft Visual Studio（MSVC）时，您将被要求提供pthread库及其头文件的路径，使用变量CMAKE_THREAD_LIBS_INIT和PTHREADS_INCLUDE_DIR。

在macOS上，您可以使用变量CMAKE_OSX_DEPLOYMENT_TARGET和CMAKE_OSX_ARCHITECTURES定义与当前系统不同的部署目标和架构。

您可以使用变量CMAKE_C_FLAGS指定额外的编译标志。

CMake现在可以生成Makefiles、MSVC解决方案或XCode项目。

构建

生成后，根据您的平台，您可以导航到CMake生成的构建文件所在的目录，然后

Linux：运行make
Windows：打开MSVC解决方案并构建它
macOS：打开XCode项目并构建它

当然，您也可以使用CMake本身通过在命令行运行以下命令来构建libpd：

cd <path/to/build/files/generated/by/CMake>
cmake --build .

命令行示例

以下是如何使用CMake在命令行上下载、配置和构建最新libpd的示例。

Linux

git clone https://github.com/libpd/libpd
cd libpd
git submodule init
git submodule update
mkdir build && cd build
cmake .. -DPD_MULTI:BOOL=ON -DPD_BUILD_C_EXAMPLES:BOOL=ON
cmake --build .

Windows / MSVC

git clone https://github.com/libpd/libpd
cd libpd
git submodule init
git submodule update
mkdir build && cd build
cmake .. -DCMAKE_THREAD_LIBS_INIT:PATH=</path/to/pthreadsVC2.lib> -DPTHREADS_INCLUDE_DIR:PATH=</path/to/pthread/header/files>
cmake --build .

限制

目前CMake脚本无法构建C#或Java绑定。请使用makefile来构建。

已知问题

如何在Visual Studio中使用libpd?

历史上，Pd被设计为使用开源gcc和make构建，并未直接支持在Windows上的Visual Studio构建，主要原因是C编译器版本之间的差异。

最近，代码已进行适配，并开发了一个CMake构建脚本，该脚本应允许你生成MSVC解决方案。你必须小心注意的唯一事情是提供一个为Visual Studio编译的pthreads库。请参阅有关使用CMake构建的部分。

另一种可能的方法是在Windows上的msys中使用MinGW和gcc、make构建libpd C库。你可以使用生成的.dll、.def和.lib文件，并与Visual Studio一起使用，提供的cpp包装器是一个全部头部库，因此它可以直接在VS中工作。

在msys中构建libpd后，你可以将其“安装”到一个临时目录，以获取所需的库和头文件。

make install prefix=libpd-build

加载补丁或DSP输出中的数字问题总是一致为0

Pd期望数字以英文格式表示，即“0.3”。如果你在系统上使用非英文语言或区域设置，它可能对数字进行不同的编码，例如“0,3”。这可能导致加载补丁中的奇怪错误，数字看起来不正确或最终截断为0。

默认情况下，libpd是以LC_NUMERIC区域设置为“C”的默认值构建的，所以这不应该是一个问题。如果你在需要特定区域设置的项目中使用libpd，你需要确保libpd的LC_NUMERIC不更改，或者在处理不同的数字设置时，至少将其重置为“C”。如果设置了非英文的LC_NUMERIC，你将遇到上面提到的数字解析问题。

如果你需要手动控制LC_NUMERIC，可以使用没有libpd_init中的setlocale()调用的libpd进行构建，使用SETLOCALE=false的makefile选项或在设置LIBPD_NO_NUMERIC定义时。

有关更多信息，请参阅https://github.com/libpd/libpd/issues/130。

libpd-ios 0.11.0

libpd-ios 0.11.0

libpd-ios 0.11.0

libpd

文档

获取 libpd

仓库布局

纯数据

libpd_wrapper

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

cpp, csharp, java, jni, objc, python

样本

libs

构建libpd

Linux & BSD

macOS

Windows

C++

C#

从 NuGet 安装

自行编译

Windows

Linux

Java

预编译的二进制文件

自己编译

Linux & BSD

macOS

Windows

Objective-C

Xcode 项目

CocoaPods

Python

使用 CMake 构建

依赖项

配置构建过程

构建

命令行示例

限制

已知问题

如何在Visual Studio中使用libpd?

加载补丁或DSP输出中的数字问题总是一致为0