jMax jMax documentation

Projects and packages


Disclaimer

The current version of jMax use TCL as its scripting language, and the feature described in this document is currently based on TCL; future version of jMax may use a different scripting language, so the features described here will change, will be implemented with a different language and/or syntax, or will simply vanish.


What is a Package?

A package is a way to package and distribute jMax component, i.e. any kind of library made up of patches, templates, Max 0.26 abstractions, soundfiles, object libraries, Java libraries, documentation, help files and so on; jMax are based on TCL packages, and are currently based on jacl , a Java implementation of the TCL scripting language.


Commands

This release do not (yet) document how to build up a package; for some examples, take a look to under the packages subdirectory in your jMax installations. The following command is used to load a package (note that is actually a standard TCL command).

package require name

The package named name is loaded if not already loaded. The package in general consists of a directory named name; this directory is searched in all the directory contained in the TCL variables jmaxPkgPath, that should be a TCL list; if the package is not found, is searched in the packages part of the distribution.


What is a Project?

jMax is, after all, a programming language; and while it's learning curve and its graphical roots make it a good choice for starting developping small MIDI or sounds oriented applications, it is often used to develop medium or large sized projects, projects in the order of hundred of thousands of objects, equivalent to program of hundred of thousands lines of code.

Projects of this size require, together with easy of use of the basic tools, some tool that help to manage the complexity of developements and delivery of applications and libraries. In this release jMax introduce two set of features, a simple and rougth support for projects to handle applications, and the support of the concept of package , to handle delivery of libraries.

A jMax project is usually made by of many kind of components: patches, templates, soundfiles, object libraries, Java libraries, documentation, help files and so on; managing a project means being able to load/install all these components, to browse and edit the project structure, to handle the dependencies between this components and other components external to the project and so on.

Currently jMax provide a simple mechanism to load/install all the components, by means of a script file, and, thru the packages , a way to handle depedencies; future release will introduce more functionalities.


The Project File

A jMax project is contained in a directory and all its subdirectory; this directory is called the project directory. The main patch, i.e. the patch that is loaded in order to load the project, should be in the project directory.

The project directory can contain an other file, called the project file, that is a script that load/install all the components needed by the project.

The project file is loaded before the patch, and is found thru a naming convention; if the file is called "foo.jmax" or "foo.pat", jMax look first for a file called "foo.env", and if this file does not exists, it look for a file called "project.env"; this naming convention allows to have multiple project file in the same directory (usefull for small projects) or to share a single project file between different patches (for example, different version of the same patch).

The project file is currently a TCL file; the TCL commands are evaluated in an environment where the dir variable is defined to have the value of the project directory, so it can be used to build filename relative to the project directory, so that no dependency on the absolute path need to be coded in the

The project file can contains a number of TCL commands that load or install the different kind of components in jMax; for this release, the commands needed to install user developed libraries (C or Java) are not documented; the project file can also, in special case, contains I/O configuration commands, when you want to be sure that a project run in a specific configuration.

The currently jMax is not able to properly undo all the action in a project file; we suggest, for the moment, to restart before changing project.

Note that in some sense you can consider your .jmaxrc file as a default project file; all the commands available in the project file can be put in the when start hook, and thus apply to all the patches loaded in all the session; this is usefull while developping small applications that do not require a project organization.


Commands

The following are the available commands; the command name is printed in this typeface, while the arguments are type in this typeface; since the project file is a TCL file, any TCL command can be included in the file; but, as we said , we don't guarantee that future version will still use TCL as scripting language; anyway, future scripting language will the following commands, possibly with a different syntax.

# anything

Anything after the # is considered a comment and ignored.

package require package

Load a package named package; packages are libraries of different kind of functionalities, including patch libraries and UI components; see the packages documentation for details.

templateDirectory directory

Add the directory directory to the list of directories where templates are searched; in a project file, usually directory is a subdirectory of the project directory where templates are stored.

template name filename

Declare a single template called name, and set its definition to be the patch stored in the file filename; the file must be a in the jMax format.

abstractionDirectory directory

Add the directory directory to the list of directories where Max 0.26 abstractions are searched; in a project file, usually directory is a subdirectory of the project directory where abstractions are stored.

abstraction name filename

Declare a single Max 0.26 abstraction called name, and set its definition to be the patch stored in the file filename; the file must be a in the Max 0.26 format.

dataDirectory directory

Add the directory directory to the list of directories where soundfiles and miscellaneous data files are searched. The project directory is always implicitly part of this list.

declareIcon name filename

Create a new icon, named name, taking its content from filename. filename must be a image file, of a format reconized by the Java VM; (currently, GIF and JPEG files). If the name start with a % character, then the icon can be used on comments; otherwise, the name is interpreted as the name of a class or template, and the icon will be used to represent instances of this class or template in the patcher editor.

If the name start with an underscore (_), the icon will not be used either for comments or for templates, but it is available to Java written modules thru a specific API.

patcherMenu cmd [submenu] label object message

Add an item to the patcher editor popup menu; cmd specify which kind of action the menu item will perform: currently, only add is supported, and correspond to adding a new object.
The optional submenu command tell to add the new menu item in a submenu, having as label the submenu argument; if the submenu argument start with a %, it is considered as the name of an icon to use for the submenu item; if the submenu do not exists it is automatically created.
The label argument is used as a label for the new menu item; if it argument start with a %, it is considered as the name of an icon to use for the item.
The object is a text describing the object to be added, including its argument; note that if you want to specify an iconic comment, the description should be "comment %iconName". The message argument will be shown, as it is, in the status line while adding the object.
This command is usefull to specify menu short-cuts usefull for a given project, like frequently used templates or objects.

puts arg

A TCL commands, print its argument (that can be a double quoted string) to the jMax console when the project file is loaded.


Project File Example

# This package require the Ircam spat library
package require spat

# Old Max 0.26 abstraction are in subdirectory abstractions
abstractionDirectory $dir/abstractions

# New templates are in subdirectory templates
templateDirectory $dir/templates

# Special templates for this project

template foo  $dir/special/foo.jmax
template bar  $dir/special/bar.jmax
template frob $dir/special/frob.jmax

# Use a special version of the Max0.26 abstraction linedrive

abstraction linedrive $dir/special/linedrive.abs

# Sound files are in the snd directory

dataDirectory $dir/snd

# pbank and other files are in the data directory

dataDirectory $dir/data

Copyright © 1995,1999 IRCAM.
All rights reserved.