A package is a jMax deployement unit: it is an archive containing a set of resoruces and the meta information needed to know what to do with them.

This description is so generic to make diffult to grasp exactly what a jMax package is, so let be more practical.

A jMax package fit the same role as am rpm or debian package on linux, or a dmg on macos, or an self extracting exe on windows: provide a user a set of cohrent functionalities in a format that simplify installation and assure that all the needed bit and pieces are delivered in the correct place.

Let's tell an history on how and why use packages. Mister Jaques L'Acousticiens decides to publish a set of impulse responses recorded in different French Cathedrals. He prepares a jMax package including the sound files, a pdf file documenting the recording conditions and some photos of the cathedrals.

He calls the package cathedrals, prepares it as a jar file (just a zip file with some meta data in the right place), and uploads it to the jMax official repository (http://www.jmax-phoenix.org/repository) to make it available to all the jMax Phoenix user.

Later, Jack The Hacker starts to write a set of objects and abstractions for jMax, providing, between others, a convolution reverb specialised in reproducing a cathedral acoustic environment, using the sound files and the photos from his french friend Jacques.

To do so, Jack packages his work as a jMax package, and declare a dependency on the cathedrals package, by putting the following xml tag:

 <require package="cathedrals"/>

in the package description file (that, as you may guess, is an XML file).

In this way, each time Jack loads his package, the cathedrals package is also loaded from the jmax official repository and made available to the Jack reverb package. Actually the package is downloaded just once, and cached locally in the Jack workstation in a jMax private directory. (Yes, you can disable network loading, and jMax will automatically disable a specific repository after a timeout).

The obvious question is: since the Jack package uses files from the cathedral package, and since Jack did not know, at the time he wrote his package, where these files will be downloaded, how can Jack use and refer these files ? The answer is that jMax has a special naming mechanism to address resources in packages, called the jMax URIs.

For example, Jack can use the impulse response of the Chartres cathedral by using the URI http://cathedrals/snd/chartres.wav as argument to his objects. This means: find the directory where the cathedrals package is, and look for snd/chartres.wav starting from that directory. The objects must use the appropriate jMax internal API to be able to understand the syntax, but the API in question is very simple (a couple of C functions, actually).

This syntax can be used within objects in patches, and in all the configuration files in the development environment.

At this point of the story, Giovanni Il Compositore wants to write a piece using the reverb package.

Initially, he just wants to hack around, and he don't bother to make a jMax Package. He just get the package from his friend Jack, and he just loads it manually using the File→Open menu item each time he start jMax. After a while, he gets bored and puts an explicit

   <require package="reverb"/>

in its personal configuration file ~/.jmax.xml, so the package is loaded at startup.

After a couple of month of work, the composition (called luminosa) is finished, and Giovanni want to get ready for a concert.

He reorganises his application as a jMax package; he wants it to be self contained, because he do not want to depends on an internet connection at the concert location.

He creates a packages directory in his package, and he manually downloads in it the cathedral package, and he also puts there the reverb package.

Then, he adds the following in the luminosa package definition:

 <require package="cathedrals"
          url="jmax://luminosa/packages/cathedrals.jpkg" />
 <require package="reverb"
          url="jmax://luminosa/packages/reverb.jpkg" />

This xml tags not only tells jMax to load the packages, but tells exactly where the package should be loaded from (in this case, from within the luminosa package). As you can see, a package can be a resource within an other package, making possible to build completely self contained applications in a single file.

The luminosa package is then stored in an USB key as a jar file (named luminosa.jpkg). Once in the concert location, Giovanni will just need to open the file luminosa.jpkg using the jMax File→Open menu item, and the whole composition (application) will be loaded with its full environment.

As you can see from this story, jMax packages give you a lot of flexibility, easy the distribution of your work to the other members of the community, and give you a way to bring along your applications giving you enough confidence on finding exactly the same environment each time.

Building a package is not very difficult: a package is just a standard directory structure with an xml file describing the content and the actions needed at load time.

As of today, there is no user interface to help you building a package, but there is a (quite primitive) user interface to browse the loaded packages. The declarative, xml based approach make things easier, and providing a interactive user interface to edit and build a package shouldn't be very expensive, even if it not currently in my short term priorities.

In this page you will find all the informations and details needed on how to write your own package. Take note of the fact that the package mechanism is extensible: new functionalities may be provided by third party packages and extend the syntax and the behaviour of the jMax package system.