CNMAT externals follow a few conventions:

  • The comment at the top of the C code should contain a block of text along these lines giving the object's name, description, authors, copyright years (which will initially be just the year in which you start writing it), and a brief description of each version of the object (which will initially be something like "VERSION 0.0: initial pre-alpha version"):
    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
    NAME: foo
    DESCRIPTION: Convert 12-tone music to D major
    AUTHORS: Matt Wright
    COPYRIGHT_YEARS: 2005
    PUBLICATION: ICMC99 paper | http://www.cnmat.berkeley.edu/...
    DRUPAL_NODE: /patch/4019
    SVN_REVISION: $LastChangedRevision: 999 $ 
    VERSION 0.0: First working version, monophonic only
    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
  • The code should #include "version.h". This file is list of #define statements generated automatically (by a Perl script that's called from the Makefile) from the above comment.
  • After your code #includes "ext.h", make it #include "version.c", which defines CNMAT's standard version-info-printing procedure. (Since it uses post() to print, it has to come after the declaration of post() in "ext.h".)
  • Put the following two lines in main(). The first prints version and copyright info when the object loads; the second allows users to send a "version" message to your object.
    version(0)
    
addmess((method) version, "version", 0);
  • You might also want to follow our convention of implementing a "tellmeeverything" method that prints all of the object's internal state.
  • Make sure to implement the assist method so that the user can get on-the-fly descriptions of what all the inlets and outlets do.
  • If your object prints a lot of messages to the Max window, give it a "verbose" method (argument 1 or 0) that can turn this verbosity on or off.
  • Use the error() procedure (not post() or ouchstring()) for error messages.
  • The CodeWarrior project should include a "Rez" file with a .r extension, so that the proper version info will appear when somebody says "Get Info" on the object in the Finder. These are all the same (except for old objects that are compiled separately for 68k, which we no longer support), so just copy one from another external, rename it to match the name of your external, and add it to the project.
  • Do not copy files from other parts of the subversion directory structure into the directory for an external! Instead, refer to them (in your Makefile and in your Xcode/Codewarrior project files) with relative paths. This is essential to avoid version skew.