PD-library-tutorial

From YoungMusic

Maybe this is not hard at all, but if you're, like me, a composer that only has a knowledge about programming by reading some basic books about it, this can save you some time. I know how to program, but making a library is not something that's in those books. Moreover, PD has some specific requirements when it wants to load a library. I've studied a few sources and experimented a bit. In the end I had something that worked. So I thought I'd write this down, mainly because I will forget about it otherwise. And maybe someone else can use this information too?

I use Dev-C++ to program. It's free and works very good. You can download it from Bloodshed software. The information about how to compile your project will refer to this software. The code itself should be useable by whatever compiler you want to use.

Compiler options

These are the same as normal externals. See my tutorial about them for more information. If, however, you want to make things a bit easier while working, I can recommend you save the dll you make directly in a the pd/extra directory. This way, you can keep your source where you want to, and fire up pd every time you want to check if everything works ok. (No, you cannot leave pd open, because you cannot overwrite your library while pd is running.)

To do this, open the project options panel. Choose the build options tab and point Dev-C++ to the output directory. Something like C:\pd\extra\yourlib for example. You should also override the output filename. Use 'yourlib.dll' if you see an .exe file there.

Library code

In your first file, say myLib.c for instance, you will have to write something like this:

#include "m_pd.h"

#include "name.c" // example external called 'name' 
 
// setup for the library 
static t_class *cMyLib;

typedef struct _MyLib {
  t_object object;
} typeMyLib;

static void *newMyLib(void) {
  typeMyLib *MyLib = (typeMyLib *)pd_new(cMyLib);  
  return (MyLib);
}

__declspec(dllexport) void MyLib_setup(void)
{
  cMyLib = class_new(gensym("MyLib"), newMyLib, 0,
    sizeof(t_object), CLASS_NOINLET, 0);
 
  // now call setup routines of every object
   
  Name_setup(); // setup function for your example external

  // You might want to change this :-)	
  post("MyLib library loaded! (c)left Yvan Vander Sanden 05.2007");
  
  // if you want to execute any functions when your library loads
  // you shoud add them here
}

It's as simple as that. Keep adding include files and setup functions for every external you want to add. Make sure though, and this is very important, that when you add new files for externals to your project, you don't have them compiled and linked seperately. You can, but then you need header files, and includes with every external. Anyway, if you get an error at the first line of your first included external: go to project options again, and on the Files tab, uncheck 'Include in compilation' and 'Include in linking'. That one kept me busy for at least some time.

Loading your library in PD

If you want your library to load when PD starts, do the following:

• File->Path: Add the path where your compiled external resides. Don't forget do click on 'save all settings' before you push the OK button.
• File->Startup: add '-lib MyLib' as a startup flag. I think the fields above should also work, but I have not figured out how. Here too, do not forget to save settings before you click OK.

Load PD again and see your library message on the first screen. If this is the first time you do this, I'm sure you feel very happy right now.

If everything does not work like it should be, please mail me. Same if you got some suggestions. I'm not sure if I can help you, as I'm not a very seasoned programmer, but I'll do my best.

Yvan Vander Sanden 00:09, 2 May 2007 (CEST)