Compiling libpd as a Processing library

Last week Peter Kirn of CreateDigitalMusic gave a presentation at Virginia Tech on using libpd--the PureData library--inside of Processing.  He showed a simple PD patch that could then be controlled through a visual interface set up in a Processing sketch.  Coupled with the piece that Peter performed at the Laptop Orchestra concert event, which used libpd inside of Processing, my interest was definitely peaked.  So I began searching the Internet to find this libpd and documentation on how to get it running inside of Processing.

It became readily apparent that, while libpd was simple enough to find (hosted here: http://gitorious.org/pdlib), documentation on building, installing, or getting it into Processing was somewhat lacking.  Considering libpd is still an alpha build according to the puredata.info community, I can let this slide.  Documentation will probably improve once an official stable release is out.  But until then, I've put together this tutorial to show how I got libpd built and working inside of the Processing environment on Linux using the Eclipse IDE.

* Please note: This tutorial is for those who want to compile this library themselves.  If you are running a Linux 32-bit operating system and do not wish to compile it yourself, I've included a link to a .zip file that has the library already compiled and ready for use at the bottom of this page *

First, you'll need to get the following source packages from Gitorious (http://gitorious.org/pdlib) where libpd is hosted: libpd, jacknativeclient, pdjack, and puredatap5.  To do this, click on the Source Tree button for each package and then click "Download master as tar.gz" located on the right side of the next page.

Second, libpd will need to be built.  This can be done by using the included Makefile. For it to work on my machine running Ubuntu 10.04, I had to modify the JAVA_HOME variable and replace the default statement with one specific to my setup. For me, this meant changing line 11 of the Makefile from this  JAVA_HOME ?= /usr/lib/jvm/default-java to this JAVA_HOME ?= /usr/java/jdk1.6.0_21/.  This may look different for you depending on how Java is installed on your system.  The important thing is just to point this variable to the directory where the Java bin/ and include/ folders are located.  Then, from a command line, simply cd to the directory with the Makefile and type make.  

Once the build is done, there should be two new files in the libs/ folder: libpd.so and libpdnative.so.  These will come into play later when we make the Processing library in Eclipse.  Which brings us to our next step, creating a project in Eclipse.  If you don't have Eclipse you can get it from here: http://www.eclipse.org/downloads/.  I'm using Eclipse Classic 3.6.2 on 32-bit Linux.  Inside of the pdlib-puredatap5/ folder created when you unzip the puredatap5 source package there is a readme file.  Follow the instructions listed in there to get a basic Processing library project building.

Now we're ready to build the PureDataP5 library for Processing.  In the src/ folder of you Eclipse project, you'll need to delete the default "Hello" file and package that are there and replace it with the source files from the packages downloaded earlier.  Start with the source files from pdlib-puredatap5.  Right-click the src/ folder of the Eclipse project, choose Import... -> File System and browse to the src/ subfolder of the pdlib-puredatap5/ folder.  Repeat this process for the src/ folders in pdlib-pdjack/ and pdlib-jacknativeclient/.  The last source files to be imported are inside pdlib-libpd/java/.  Once you've imported all of these, there should be no errors in the src/ directory of your Eclipse project (you can ignore the warnings that appear for the JackNativeClient.java file).

Lastly, you need to import three .so libraries into the lib/ directory of the Eclipse project so they are included in the library/ folder of your Processing library.  This is done by the same Right-click -> Import... -> File System process as for the source files above.  The libpd.so and libpdnative.so libraries are inside pdlib-libpd/libs/.  The libjacknative.so library is in pdlib-jacknativeclient/lib/(OS)/ where (OS) corresponds to the operating system you're running.  For me this is linux32.  Once you've imported these libraries to your project, clicking the Run button in the Ant window of Eclipse--as described in the readme page for setting up a Processing project--will build your new Processing library.

Navigating to your Processing sketchbook folder, inside the libraries/ directory you should see a folder for your newly created library.  Inside of this, there is a folder called library/, and inside that should be the following four files: (yourLibrary).jar, libpd.so, libpdnative.so, libjacknativeclient.so.  If any files are missing, check your imports and build again.  If the .so files are not there, you can manually copy those into this folder and the library will still work.  Now you can import this library into a Processing sketch using the Sketch -> Import Library... -> yourLibrary menu option and begin using PureData patches for audio inside your Processing sketches.

* Note: building this library will also create a .zip file in the distribution/yourLibrary-version/download/ folder inside of your Eclipse project directory.  This .zip file can be extracted, and, following the installation instructions in this folder to get the library into your Processing sketchbook libraries/ directory, the library should work.  I've included a link to this .zip file for those of you who do not wish to go through the process of compiling this library yourself here *