Personal tools
You are here: Home documentation developer LibraryTemplate
Views


If you are starting a library or want to port your existing library to multiple platforms, then the Library Template should make things much easier for you. Libraries in this format are very easy to install and they integrate tightly with Pd, providing things like namespace support, meta data for the search function, a listing in the Help Browser, etc. It handles building on all supported platforms (currently GNU/Linux, GNU/Hurd, GNU/kFreeBSD, Mac OS X/Universal, Windows/MinGW, Windows/Cygwin, Android, Apple iOS). Using this template makes it trivially easy to package your library for Debian, Ubuntu, Fedora, Gentoo, etc.

Getting Started

Here's how to get started using the library template for your project:

  1. download the whole template folder either a release or directly using SVN:

    svn co https://pure-data.svn.sourceforge.net/svnroot/pure-data/trunk/externals/template
    

  2. rename the template folder to the name of your library (e.g. mylibrary)

  3. edit the Makefile and put the library name in the first variable (e.g. LIBRARY_NAME=mylibrary)

  4. rename template-meta.pd replacing 'template' with the name you just used for the folder (e.g. mylibrary-meta.pd)

Now you can set library meta data in the meta file, things like version, authors, etc. Open the meta file (e.g. mylibrary-meta.pd) in Pd or a good text editor.

Ways of Building

Special Features

Tcl file per Object for GUI objects

If you have written a GUI object, you can put all of your Tcl code for the GUI object into a .tcl file with the same name as your object (e.g. myobject.c and myobject.tcl). This file will be automatically handled by the build system, but you will need to load it in your setup() function and include the m_imp.h header from Pd.

You can see this in action in the [cursor] object's cursor.c and cursor.tcl. Here's an excerpt:

#include "m_imp.h"
...

void cursor_setup(void)
{
...
    sys_vgui("eval [read [open {%s/%s.tcl}]]\n",
        cursor_class->c_externdir->s_name,
        cursor_class->c_name->s_name);
    sys_vgui("::hcs::cursor::setup %s\n", cursor_receive_symbol->s_name);
}

Making a Shared Library for the library

It is recently possible to have a shared binary library, a shared header, and a shared Tcl library. If your objects share C or Tcl code, then you can put the shared code in the shared libraries. As long as you follow the file naming scheme, the rest of it will be handled automatically. For the C file, it can be any code you want, as long as the file is named lib$(LIBRARY_NAME).c and the header is called $(LIBRARY_NAME).h. For example, if your library is called foo, you will set the LIBRARY_NAME variable at the top of the Makefile to foo, and then create your C header as foo.h, your shared C code as libfoo.c, and your shared Tcl code as libfoo.tcl.

Building all objects into a single library file

Some people want to build all of the objects into a single .pd_linux library file. In order to do that, you just need to include a C file with the name of your library. That $(LIBRARY_NAME).c file should only include the various setup functions needed. For example, here's template.c for the library template:

/* glue code for compiling "template" as a library
 * this calls the setup function of each object
 */
void mycobject_setup(void);

void template_setup(void) {
  mycobject_setup();
}

Note: if you'd like to do this without having created a shared library make sure you create dummy files for lib$(LIBRARY_NAME).c and $(LIBRARY_NAME).h, in case you don't want to edit the Makefile at that point. For example, here's libtemplate.c for the library template:

/* This is just a dummy file, you don't have to put something inside here */

Now run make $(LIBRARY_NAME) instead of just make and your compiler will output $(LIBRARY_NAME).pd_linux (or .pd_darwin or .dll et cetera ..).

Another note: do not include these files in SOURCES, but make sure you include them in EXTRA_DIST, the same for $(LIBRARY_NAME).c.

License of the Library Template

All of the files in the library template are released into the public domain so that people creating libraries can easily choose the license that works best for them (GPL-3, GPL-2, BSD, etc.). We hope, of course, that you choose a Free Software license.

Libraries that use this template

unmodified

arduino arraysize bassemu~ beatpipe comport cxc chaos earplug~ ekext ext13 framesync freeverb~ hcs iemnet import issiconvert jmmmp libdir list-abs mapping markex maxlib mjlib moonlib motex pan pddp pdogg pmpd purepd sigpack smlib windowing syslog

customized

apple bsaylor iemguts plugin~

TODO

  • RPM packaging

  • Eclipse template

  • Xcode template




Powered by IEM Powered by Plone Section 508 WCAG Valid XHTML Valid CSS Usable in any browser