A guide for using libraries in Pd vanilla for Pd-extended expats

Pd-extended to Pd Migration Tutorial

Intro

So Pd-extended is dead and you're looking for an up-to-date way to use Pd. Here are your options:

Pd-l2ork - Virginia Tech's answer to Pd-extended. Linux only.

- Virginia Tech's answer to Pd-extended. Linux only. Purr Data - In-development version of Pd-l2ork built with web technology . It's actually "Pd-l2ork 2.0" and cross platform, a first release is already available, but it still needs to port a few more GUI objects to the new web format.

- In-development version of Pd-l2ork built with . It's actually "Pd-l2ork 2.0" and cross platform, a first release is already available, but it still needs to port a few more GUI objects to the new web format. Pd - vanilla version of Pd that's been the main version from day 1. A little different than Pd-extended, but aside from cosmetic differences, can do everything Pd-extended can do.

My suggestion (and the topic of this page)? Use Pd. It doesn't automatically come with all the libraries Pd-extended came bundled with, but that can be easily remedied. You can use the new built-in library manager that's very easy to use and gets you all the libraries that Pd-extended had (and more!).

Downloading Pd libraries

Fire up Pd and in the menu bar, go to Help > Find externals. Type in the library you want (or certain keywords assocaited with the library) and click on the proper versino for your operating system. Pd downloads the compressed library to a location on your computer Pd looks at, unzips the library into a self-titled folder, and that's it! Where do the libraries actually go to? The Pure Data page has that info here. All distributions of Pd automatically look for libraries and plugins in these folders so if you choose to install a library outside of using the library manager, the best places for these libraries to go are those folders listed. Note that for Mac users the proper files are labelled Darwin.

If you can't find the right menu entry, you may need to download a newer version of Pd or alternatively visit the deken repository.

Using Pd libraries

Here's the major difference between Pd and Pd-extended. Since Pd-ext came with all the libraries already, it automatically loaded all of them and put each library folder in Pure Data's path list. Pd vanilla can do this as well but I'd like to break down your options and go through them one by one. Here are your options:

Use a "slash" declaration

Load singly-compiled libraries at startup and add search paths

Use the [declare] object

"Slash" declaration

This is my recommended solution. Note that this only works for libraries that are compiled separately. Meaning say for something like Cyclone, you see a bunch of .pd_linux files for each object (.pd_darwin for Mac, .dll for Windows). As stated earlier, the library manager downloads the library to a specific folder (in my case, ~/pd-externals but look here for your platform) and in there, you end up with a folder with the library name (~/pd-externals/cyclone/ for Cyclone) with everything. Now say you want to use Cyclone's [cycle~], how do you instatiate it (i.e. make it)? Since Pd only knows to look in ~/pd-externals, just like file paths you have to type in the folder it's in first. Since you downloaded the Cyclone library and now have a ~/pd-externals/cyclone/ folder, you now have a ~/pd-externals/cyclone/cycle~.pd_linux file. So you type in [cyclone/cycle~] and hey, there it is! (Note that an object's associated symbol can be different from their compiled file names and you're actually typing an object's symbol to get it, but these are technical matters you usually don't have to worry about so don't worry if you absolutely didn't understand any of this parenthesized stuff). If you're on Windows, you might have to type in [cyclone\cycle~] instead since Windows does the folder slash backwards but I haven't used Pd on a Windows machine so this is conjecture.

Loading/Search Paths

This is the way Pd-extended it so you don't have to type in the folder names. Basically, for libraries that are compiled as a single file, you can load it on startup in Pd's menu bar via Edit > Preferences > Startup... . What does this mean one file? That means a bunch of objects are compiled in one file which usually has the library's name instead of separate files for each. For example if you download Gem, there's a Gem.pd_linux. There's also a cyclone.pd_linux, which has the library's signal binary operators ([>~], [==~], etc) in addition to the separate files for the other objects (like cycle~.pd_linux). Pd knows to look for files that are titled the same name as the enclosing folder so you don't have to add those paths. So say if you downloaded Gem from the library manager, you have a ~/pd-externals/Gem/ folder with a Gem.pd_linux inside. Since Gem.pd_linux has the same name as ~/pd-externals/Gem/ and Pd looks for stuff in ~/pd-externals/, you don't need to add Gem's path (well, you kinda do but for different reasons...). After you've loaded the library, you can just type the object's name without any sort of slash declaration. For example, since the code for Cyclone's [>~] is nestled in cyclone.pd_linux, after you've loaded cyclone (note the lowercase), you can just type in [>~].

Say you have a library with multiple files, one for each object (like in Cyclone's example: cycle~.pd_linux, peek~.pd_linux, etc.). Then you want to add the library's folder into your search paths using Pd's menu via Edit > Preferences > Path.... Since Gem and Cyclone have separate binary files for each object (as well as self-titled library binaries like Gem.pd_linux and cyclone.pd_linux with many objects inside), you'll want to add their folders to your path. EVEN THOUGH, you have ~/pd-externals/ in your path, you don't have ~/pd-externals/Gem/ or ~/pd-externals/cyclone/ in your path so Pd can't find Cyclone's cycle~ object unless you type (as earlier) [cyclone/cycle~] or add ~/pd-externals/cyclone/ specifically into your path. After that, you can just type [cycle~] for Cyclone's cycle~ just like Pd-extended! Note that after you've used the slash declaration for an object ([cyclone/cycle~]), the path gets added to Pd so the second time, you only have to type in [cycle~].

The [declare] Object

Instead of using the Pd menus to load libraries and add paths, you can use the [declare] object in your patches, which does exactly the same things. For loading libraries, you can use the -stdlib flag, which loads a library specified relative to Pd and its search paths. So for Cyclone, you would make the object [declare] this way: [declare -stdlib cyclone]. This has the same exact effect as "Edit > Preferences > Startup...".

For adding paths to Pd, you can use the -stdpath flag, which adds search paths to Pd relative to it and its already-existing search paths. So for Cyclone, since it already looks in ~/pd-externals/ and you have ~/pd-externals/cyclone/, you would instantiate [declare] like so: [declare -stdpath cyclone/]. You can also use full paths with [declare], so since the full path for a Linux user would be /home/user/pd-externals/cyclone/, you can use that instead of plane cyclone/. This method of using [declare] does the exact same thing as "Edit > Preferences > Path...".

For [declare], you can use the -path and -lib flags instead of -stdpath and -stdlib if you want to use paths relative to the patch itself rather than Pd. If you're confused as to how to exactly use [declare], you can look at its help file for more info.

Wrapping Up

This about wraps up how to get started with Pd if you're familiar with Pd-extended and in particular, how to deal with library wrangling. The other options mentioned such as Pd-l2ork and Purr Data operate much more like Pd-extended in that all the libaries are included and all this business with search paths and library loading are already dealt with. Those software solutions are worthwhile Pd-extended alternatives, but I suggest giving Pd vanilla a serious chance as it is nearly-if-not-exactly identical to Pd-extended in functionality and knowing this stuff will only make you a more informed Pd user.

Perhaps a beginning or casual user doesn't need to know that "cycle~" or "z~" comes from Cyclone or Zexy respectively and don't come with vanilla distribution of Pd, but a more advanced user should be aware of this if not for the fact that these libraries are maintained separately from the core of Pd and thus may not be updated at the same time as Pd vanilla. Think of Pd vanilla as a small, stable core akin to C or perhaps even Processing (although that piece of software comes with a bit more built-in bells and whistles). You can live almost solely in the core of these languages without needed to load up any external libraries (perhaps this is less of a case in C) and if you need to, install something like Gem if you want to do sophisticated visuals, Zexy if you want signal binary operators or message repeaters, and so on. If you don't need these libraries, you can leave them uninstalled. I do agree that moving from Pd-extended to Pd vanilla involves a not-so-insignificant paradigm shift but it brings the user experience more in line with other creative coding tools such as the aforementioned Processing where "import" statements are required to even work with sound and separate downloading and installation procedures in Processing's own library manager are required to make use of Arduino, OSC, etc. Getting used to Pd vanilla's way of doing things may seem daunting at first but with the change, external libraries have never been easier to install. Unlike Pd-extended, Purr Data, and Pd-l2ork with their everything-and-the-kitchen sink approach, Pd vanilla and its new library manager provides a modular experience where Pd can serve as an easily-expanadable general visual programming platform.

Derek Kwan, 2/04/2017 (rev. 2/14/2017)