libdir - A Common Format for Pd Libraries
Since more and more people are building collections of objects written in Pd, it makes sense to have a common library format. This library format should be easy to create, install, and use. It should work when installed into the global path (i.e. pd/extra) or when copied locally into a project folder. It should work with objects written in any supported language (i.e. binaries, .pd, and the various loaders like pdlua and pdtcl).
Libdirs can be used in the "dirlib" approach without any modification. This approach uses [declare] to add each library's folder to the path of the given patch instead of loading the libdir like a library.
Including in the Help Browser
Having a standard library format means that the Help Browser tree can be dynamically built based on the libraries that are installed. In order for this to work well, there needs to be a standard, otherwise the code will be far too complicated. This then opens the door for using more meta data in the help browser.
Here is the basic structure of a libdir:
mylibrary-\ |\_mylibrary.pd_linux (shared binary lib) | |\_mylibrary-meta.pd | |\_my_pd_object.pd | |\_my_pd_object-help.pd | |\_my_c_object.pd_linux | |\_my_c_object-help.pd | |\_README.txt | |\_LICENSE.txt | |\_manual--\ | |\_index.html | | | |\_etc... | \_examples |\_awesomeexample.pd | |\_evenbetter.pd | |\_etc...
mylibrary-meta.pd tags this folder as a library. It is a Pd patch that contains meta data about the library. The most basic meta data is *author*, *description*, *license*, etc. The meta patch also includes a reference to the loader if the objects are something other than a Pd patch or compiled DLL (.pd_darwin, .pd_linux, .dll, etc). i.e., it would have the object [loader/python] in the patch.
What works now
Ultimately, the meta file will be read for meta data, specifically for the auto-generated Help system, the loaders, and maybe for other things too. Right now, it has some human readable information and is used as a marker that a directory is meant to be a library. Plus its much easier to implement it this way, I can use open_via_path() instead of writing a new function. The grand plan is to have one directory hold the objects, help files, manuals, etc. making it a self-contained library.
Currently two paths are added to the helppath. The first supports having the help files in a complete library directory format, where everything is in one folder. The help meta system needs to be implemented for this to work with the new Help menu/browser system. Ultimately, /path/to/extra will have to be added to sys_helppath in order for this to work properly.
META Data --bbogart, Thu, 23 Mar 2006 21:13:51 +0100
I think if the meta-data applies to the whole directory (libdir) and its only containing META data, and not also acting as a breakout point for documentation, then it should be plaintext. Being able to edit the metafile for me is not enough reason to warrent the inefficiency of parsing a PD file for text-only information.
meta file as .pd --hans, Thu, 23 Mar 2006 21:49:44 +0100
the advantage with .pd format is that it makes loading language-specific loaders quite simple. Basically, when Pd opens a libdir, it first opens the meta file. In the meta file, the loader is included as an object. So Pd opening the meta patch loads the loader.Just as if you type [Gem]? in an object box loads the Gem lib. This could change in the future, but this smooths the implementation along the way.
Re: doc vs extra --hans, Thu, 23 Mar 2006 21:50:14 +0100
Ultimately yes. Not implemented yet.
simpler meta file --hans, Wed, 06 Jan 2010 22:07:18 +0100
I was thinking that the file could be called just 'meta.pd' to make it really simple... then the name of the library comes from the directory name alone.