Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/agraef/pd-lua

Lua bindings for Pd, updated for Lua 5.3+
https://github.com/agraef/pd-lua

computer-music lua multimedia pure-data purr-data

Last synced: 8 days ago
JSON representation

Lua bindings for Pd, updated for Lua 5.3+

Awesome Lists containing this project

README 

        
pdlua -- a Lua embedding for Pd

Copyright (C) 2007,2008,2009,2013 Claude Heiland-Allen 

Copyright (C) 2012 Martin Peach [email protected]



This program is free software; you can redistribute it and/or

modify it under the terms of the GNU General Public License

as published by the Free Software Foundation; either version 2

of the License, or (at your option) any later version.



This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

GNU General Public License for more details.



You should have received a copy of the GNU General Public License

along with this program; if not, write to the Free Software

Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.



Current maintainer: Albert Gräf 

This source is available on GitHub: https://github.com/agraef/pd-lua



pdlua works with all Pd flavors out there and makes Pd external programming

incredibly easy (please check the included examples and the tutorial in the

corresponding subdirectories). Originally written by Claude Heiland-Allen,

pdlua has gone through the hands of a few people over the years, including

mrpeach (maintainer since 2011), zmoelnig a.k.a. umlaeute (loader update,

Debian package), and myself (Arch package, Lua 5.3+ support, Purr Data and

plugdata support, pdx.lua live-coding extension, tutorial). Please also check

my brief account on the history of pd-lua below.



Lua 5.4 is highly recommended with the latest version, Lua 5.3 works as

well. Reportedly, Lua 5.2 and even 5.1 still work (at least to some extent),

but I haven't tested these myself for quite a while, so you may run into

problems with these old versions - use at your own risk.



If you haven't used pdlua before, please make sure to check the included

tutorial first. See:



https://agraef.github.io/pd-lua/tutorial/pd-lua-intro.html



This contains a fairly gentle introduction to pdlua, walks you through the

creation of a basic example, and then goes on to cover most major features of

pdlua, including the special facilities for tables, clocks, receivers, signal

processing, graphics, and live-coding, in quite some detail. This will be

helpful when embarking on your own projects, or trying to make sense of the

included examples.



History and Credits:



pdlua was originally written by Claude Heiland-Allen, with contributions by

Frank Barknecht and Martin Peach, according to the original source.

Please check Claude's website at https://mathr.co.uk/, and

https://mathr.co.uk/blog/lua.html for Lua-related content on his blog

(including pdlua's original announcement).



Martin Peach took over maintenance of pdlua in 2011, you can find that part of

the history in Pd's old svn repository at SourceForge, including IOhannes

Zmölnig's loader update for Pd 0.47. See

https://sourceforge.net/p/pure-data/svn/HEAD/tree/trunk/externals/loaders/pdlua/



The present source is a fork of umlaeute's 0.7.3 version in the Debian package

repository at https://anonscm.debian.org/git/pkg-multimedia/pd-lua.git, which

in turn was based on the 0.7.3 version of pdlua in Pd's svn repository.



The current version (0.8 and later) is actively maintained by Albert Gräf,

with contributions by many people: Claude Heiland-Allen (Lua 5.4 update,

bugfixes), Alexandre Porres (documentation updates), sebshader (relative path

loading), Timothy Schoen (plugdata compatibility, signal and graphics

support), and Ben Wesch (multi-channel signal support, Deken tests and uploads

on GitHub). This is also the version included in Purr Data

(https://github.com/agraef/purr-data) and Timothy Schoen's plugdata

(https://github.com/plugdata-team/plugdata).



Please file bugs and requests at https://github.com/agraef/pd-lua. I maintain

a lot of packages and thus it may take a while at times, but I look at all the

bug reports and pull requests, and try to respond to them eventually. :)



Ready-Made Packages:



The latest vanilla binaries for Ubuntu, Mac, and Windows can always be found

on https://github.com/agraef/pd-lua (but see below for the Deken package).

Also, both Purr Data and plugdata ship with pdlua, and have it enabled by

default, so no 3rd party package is needed in those environments.



For vanilla Pd, we recommend installing the Deken package (named `pdlua`),

readily available using Pd's `Find externals` menu option. This package was

originally uploaded by Alexandre Porres, but Ben Wesch recently added Deken

tests and uploads to our GitHub workflow, so that the Deken releases are now

automatized and always in sync with the GitHub releases. Thanks, Ben!



pd-lua is also in the Arch repositories (maintained by dvzrv, thanks David!),

and in the Debian repositories (maintained by IOhannes Zmölnig, thanks

umlaeute!). (During busy times, these may trail our releases for a little bit,

but most of the time they will the latest version.)



Mac users please note that the packages I distribute aren't notarized, so on

recent macOS versions you'll have to jump through the usual hoops to make them

usable. Running `xattr -rd com.apple.quarantine` on pdlua.pd_darwin should

usually do the trick, but check the internet for up-to-date information on

Gatekeeper for details.



Enabling pdlua:



Again, this step is only necessary with vanilla Pd; both Purr Data and

plugdata have the pdlua loader enabled by default, so it should be ready to go

immediately.



With vanilla Pd, after installing pdlua, the pdlua loader also needs to be

added to your startup libraries, before Pd will recognize any Lua object in

your patches. This only needs to be done once. (Alternatively, you can also

use the `-lib pdlua` option on the Pd command line, or a `declare -lib pdlua`

object in a patch with Lua objects.) To make any of this work, you may also

have to add the parent directory of the `pdlua` folder to Pd's search path if

pdlua was installed in an unusual location.



Compilation Instructions:



You can also compile pdlua yourself from source, which isn't hard to do.



The source should compile out of the box on (at least) Linux, macOS and

Windows, just make sure that you have Lua and Pd installed and run

`make`. pdlua uses pd-lib-builder by Katja Vetter as its build system, please

check https://github.com/pure-data/pd-lib-builder and the included

Makefile.pdlibbuilder for details.



pdlua works with any reasonably modern Pd flavour, but pd-lib-builder will

look for vanilla Pd (http://msp.ucsd.edu/software.html). So you'll need to

have that installed, or be prepared to adjust the Makefile accordingly.



If you compile from git sources and use the included lua submodule (see

Compilation from Git Sources below), then only Pd will be needed. Otherwise

you'll also have to install Lua (https://www.lua.org).



The following build environments on various platforms are known to work and

are supported.



Linux: Uses gcc and GNU make. Pd and Lua should be available in your package

repositories. If not then it's easy to install them from source.



Mac: Uses Xcode. The build requires that you have the Pd header files

somewhere under /Applications/Pd-*/Contents/Resources/src (which should be the

case if you're running a recent Pd distribution by MSP); otherwise you can set

the `PDINCLUDEDIR` make variable accordingly. Lua is available, e.g., in

Homebrew (https://brew.sh/).



Windows: Uses msys2/mingw (https://www.msys2.org/), which is the Windows

incarnation of gcc and GNU make. The build assumes that you have a recent Pd

installation as distributed by MSP, so that the header files and pd.dll are

found during compilation and linkage, respectively. Lua is available in msys2.



Compilation from Git Sources:



The repository source includes a lua submodule which can be used to compile

Lua alongside pdlua, so no Lua installation is needed to compile the

external. (You'll still need to have Pd installed.) Just make sure to check

out the submodule with the repository (`git clone --recurse-submodules`).

If you already checked out the repository, you can also do `git submodule

update --init` instead. This should get you a fairly recent revision of the

upstream Lua source.



Once the lua submodule is checked out, you can just run `make` as usual, it

will use the submodule to compile Lua alongside the pdlua module. The

resulting binary will be statically linked with the Lua interpreter.



Also note that on the Mac you can build a universal (a.k.a. arm64+x86_64)

binary this way, using `arch="arm64 x86_64"` when running `make`. This will

work best if Lua is compiled alongside pdlua, since installed Lua libraries

may not be universal binaries (in Homebrew at least they aren't).



Otherwise, if the lua submodule isn't checked out, `make` will try

`pkg-config` to locate an existing Lua installation on your system and link

against that.



Installation:



After a successful compile, you can go about installing the external with the

usual `make install` which copies the external to its own directory named

pdlua. This should generally do something sensible on each of the supported

platforms. Note that the installation may require root privileges.



Linux: By default, installation goes into /usr/local/lib/pd-externals, which

should be one of the directories on Pd's built-in search path.



Mac: Installation goes into ~/Library/Pd by default. Move the pdlua folder to

/Library/Pd for a system-wide installation.



Windows/mingw: Installation goes into the Pd subdirectory of your %APPDATA%

folder by default. Move the pdlua folder to the extra folder of Pd in your

ProgramFiles directory for a system-wide installation.



In any case, it's possible to override the default installation directory

using the PDLIBDIR variable. E.g., on Linux you can install into Pd's

/usr/lib/pd/extra folder as follows:



    make install PDLIBDIR=/usr/lib/pd/extra



It's generally advisable to do a staged install using `DESTDIR` first so that

you can review the installation directory layout beforehand and adjust it if

needed. To these ends, run `make install`, e.g., as follows:



    make install DESTDIR=./build



It is possible to use DESTDIR along with PDLIBDIR.



Another possibility is to run `make install objectsdir=./build` which creates

the `pdlua` folder directly in the `build` directory from where you can move

it to any location on Pd's library search path that you see fit. (This option

is considered deprecated, but it's still the most convenient for a quick

manual installation.)