Basic Layout

At the root of each main section of the CVS (abstractions, doc, extensions, externals, packages), there is a Makefile. Each Makefile does the overarching build for that section, while packages/Makefile.buildlayout specifies all of the locations, common variables, etc. It is possible to override Makefile.buildlayout by setting the BUILDLAYOUT_DIR variable when running make

packages/Makefile works by calling all of the other Makefiles in the other CVS sections

For a given package type, Mac OS X Pd.app for example, there is a separate subdirectory packages/darwin_app with its own Makefile and files distinct to that platform and package.

Exceptions

For various reasons, there are some exceptions to the above rules: flext, gem, and pd. These can all be included using targets in packages/Makefile

How to add your library

The best way to start is to copy the template section, called template. Then do a case-preserving search-and-replace, replacing "template" with the name of your library. Editors such as emacs will make the replacements will preversing the case of the text it is replacing. For example, replacing "template" with "mylibrary" will make these changes:

      TEMPLATE_NAME = template
      template:
    

to this:

      MYLIBRARY_NAME = mylibrary
      mylibrary:
    

If your editor does not do this, you will need to do two separate search-and-replace actions, one for all lowercase, and another for all uppercase.

Once you have your section setup after the search-and-replace, you need to edit the paths of the files that you want to include. The paths will be the only text written out. All of the installation paths will be Makefile variables. Check the below example:

	
      install -d $(helpdir)/$(TEMPLATE_NAME)
      install -p $(abstractions_src)/template/help/*-help.pd \
             $(helpdir)/$(TEMPLATE_NAME)
    

becomes:

      install -d $(helpdir)/$(MYLIBRARY_NAME)
      install -p $(abstractions_src)/mylibrary/help/*-help.pd \
             $(helpdir)/$(MYLIBRARY_NAME)
    

Also, since it is common to store the help patches in the same directory as the object patchs, you can use this pattern to exclude the help patches from being copied to $(objectsdir):

	install -p $(shell ls -1 $(abstractions_src)/mylibrary/*.pd | \
		grep -v '\-help.pd')  $(objectsdir)/$(MYLIBRARY_NAME)
    

Makefile targets

To add your objects to this build system, first make your own targets and add it to the all: and install: targets. For example: for the RRADical objects, there is a target called rradical_install: which does everything needed to install the RRADical objects. This includes installing help patches and any other documentation. rradical_install: calls rradical: to build anything that needs to be built before being installed. There is also a clean target for each library, e.g. rradical_clean.

mylibrary:

All steps necessary to build your library go in this target. Once this target is complete, everything should be ready to install

mylibrary_install:

The installation of all files happens in this target.

mylibrary_clean:

This target should remove every single file installed by mylibrary_install, and any build products, like .o files, etc.

Explanations of Terms

MYLIBRARY_NAME = mylibrary

At the top of each library's section in the Makefile, you will see a variable MYLIBRARY_NAME. This variable is the name used to install the abstractions. This should be all lowercase since its used in the loading of objects within Pd (e.g. [mylibrary/myobject]).

$(objectsdir)

If your project consists of objects that are meant to be reused in other patches rather than used as a application, then they should go into this directory. They should be in a directory with a distinct name. This will be the name of your library of objects, which can be added to the path, or called directly (e.g. [mylibrary/myobject]).

The subdirectory name (e.g. mylibrary) should always be all lowercase.

$(helpdir)

All help patches should go into this directory in a subdirectory with the same nameas the subdirectory for your objects. For example, for [mylibrary/myobject] above, the helpfile would be mylibrary/myobject-help.pd. The subdirectory name (e.g. mylibrary) should always be all lowercase.

$(manualsdir)

If you have any other kinds of documentation, like a text or HTML manual, or a Pd-based tutorial, then it should go into this directory, again in a subdirectory with the same name as the library or application. Using the previous example again, the mylibrary manual would be mylibrary/mylibrary.html.

The subdirectory name (e.g. mylibrary) should always be all lowercase.

$(examplesdir)

If your project has a examples patches or applications that are meant to be run directly, then it should go into this directory within its own subdirectory. This directory is a browsable collection of applications. If your application has a lot of files associated with it, put a main patch and have the extra files in a subdirectory. rradical/usecases/showcase is a good example of this.

$(manualsdir)

If your project as a manual, then it should be installed into the $(manualsdir) in a folder using the name set in $(MYLIBRARY_NAME).

Applying patches to Pd core

Using the targets patch_pd and unpatch_pd, you can automatically apply and remove patches from the Pd core source (i.e. diff patches, not Pd patches). For patches that work on any platform, put them in packages/patches. For platform-specific patches, put them in packages/patches/darwin, packages/patches/linux, packages/patches/win, etc.

If you are going to commit your patch to CVS, make sure it applies without problem with the rest of the patches that are currently in CVS. If a patch is no longer valid, remove it from CVS.

patch_pd and unpatch_pd are currently only triggered manually.

Adding files not maintained in CVS

Sometimes, you can't compile something, but you have a binary you want to throw in. The target noncvs_install will install the files that are placed in the noncvs tree. There are only platform-specific directories in the this section since binaries will always be platform-specific. The noncvs tree mimics the standard Pd layout. For example, on Mac OS X, you currently have packages/noncvs/darwin/bin, packages/noncvs/darwin/extra, and packages/noncvs/darwin/doc/5.reference as possible locations to add your files.

noncvs_install is automatically used when you do a make install in packages.