==== What is a jMax Package ? ====


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:

<code lang=xml>
 <require package="cathedrals"/> 
</code>

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

<code lang="xml">
   <require package="reverb"/>
</code>

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:

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

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 [[PackagingReference | 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.