====== How to create a Package ======

This page tells how to create a package.

===== The jMax Package Structure =====


A package is actually a directory that contains a package configuration file.

The file must have a ''.jpkd'' extension (from **j**Max **p**ac**k**age **d**escriptor), and it must have
the same name of the directory.

So, the package //luminosa// will be implemented by a directory called ''luminosa'' including
a file called ''cathedral.jpkd''.

The directory may contains any kind of files. jMax do not impose any structure on how a package content
should be organised; of course, it is better to keep things well sorted, so to understand what is going on.

For example, as example can be:
<code>
luminosa
luminosa/luminosa.jpkd - The package description file
luminosa/luminosa.jmax - The cathedral path
luminosa/abstractions   - a sub directory containing abstractions
luminosa/sounds         - a sub directory containing sound files   
luminosa/packages       - a sub directory containing packages needed by this package.
</code>

A package can contains other packages.

A directory of this form is a jMax package, and can be loaded either implicitly thru //require// directives,
or explictly by loading the ''.jpkd'' file from the// File -> Open// menu item.

A package can have another form: it can be stored in a single java archive file (jar files, that are zip files
with some meta information added), which extensions must  be ''.jpkg''.

jMax can handle archived packages as the non archived one; more, packages that are loaded thru a ''require'' directive
can be loaded directly from a network repository; this allows for easy sharing of packages between users. 
As of today, a first repository is in place  [[http://www.jmax-phoenix.org/repository|here]], for experimentation 
purposes, but of course anybody can put online his repository.

Network repositories can be specified in the xml configuration files (see the TODO page). Download from network
repositories can be prevented using the appropriate command line options (see the TODO page).

Archived packages are actually unzipped by jMax at load time, to allows realtime access to
the package content from the applications. 

Archives are unzipped to the directory:
<code>
~/.jmax/cache
</code>

You are free to delete the packages stored there, jMax will try to reload them by need.


===== The jMax Package Description File Syntax =====

The package.jpkd file is an xml file.
Its generic form is the following.

<code xml>
<?xml version="1.0"?>
<jmax>
  <package name="myPackage">
   ....
   <!-- package declarations -->
   ....
  </package>

   <!-- other declarations -->
</jmax>
</code>

The accepted package declaration tags are:
  * ''documentation''
  * ''require''
  * ''module''
  * ''document'' (aliased to ''patch'')
  * ''object''
  * ''helpSummary''

==== The ''documentation'' tag ====

<code xml>
  <documentation text="this package frob the frobber big time" 
                 author="Maurizio De Cecco" 
                 copyright="(c) myself 2009" 
                 license="Public domain"
                 url="http://www.myproject.org"/>
</code>

Declare some information about the package.
The ''text'' attribute describe the package content and intent.
The ''author'' attribute declare the author name.
The ''copyright'' attribute declare a general copyright for the package.
The  ''license'' attribute specify the license this package is distributed with.
The ''url'' attribute specify an URL where to find more information about the package.

This tag is optional, and all his attributes are optional.
If present, they may be used (actually, not yet) by the user interface to document the
package.

==== The ''require'' tag ====

<code xml>
  <require package="neededPackage"/>
</code>

Specify that this package depends on ''neededPackage'' and that the latter should be loaded before
loading this one.
This declaration is recursive, ''neededPackage'' may depends on other packages. Each package
will be anyway loaded only once.


==== The ''module'' tag ====

<code xml>
  <module jar="jmax://myPackage/modules/frobber.jar"
          class="org.myorg.FrobberModule"
          />
</code>

This tag tell jMax to load a Java module. The module can implement any functionality, for example
it may provide a graphic representation of an object, implements a data editor, or provide extension
to a number of jMax functionalities by plugging in the corresponding extension points. 

The ''jar'' attribute specify the jar to be loaded.
The ''class'' attribute specify a class in the jar that must implement the jmax.module.MaxModule
interface, providing a set of methods to integrate the module in the user interface environnement.
The jar is loaded in the main class loader.

At the moment, there is no documentation on how to write Java module and extensions, the only
way is to study the sources, and of course to ask for help in the developers mailing list.




==== The ''document'' or ''patch'' tag ====

<code xml>
  <document url="jmax://myPacakge/mypatch.jmax" container="workspace" [editor options]>
</code>

The ''document'' and ''patch'' tag are synonyms.

Tell jMax to load a patch, or an arbitrary document that jMax can load, from
the position specified by the ''url'' attribute, that must be a ''jmax:'' style url.

The optional ''container'' attribute specify in which UI container the patch is opened 
([[user:CustomUIConfiguration | see this page for details on containers]]). The default is the
"workspace" container, that is the place where the ''File->Open'' menu action open the files.

The other attributes are passed to the specific editor opened; for patches, the only
supported editor option is the optional ''toolbar'' attribute. If its value is
"no", the standard patch editor toolbar will not be present in the editor window in locked
mode.

This tag allow to package an application as a package; when the package will be loaded,
the patches specified with this tag will be automatically opened.

See the synth and the customide examples in the distribution for a working examples.

==== The ''object'' tag ====


The ''object'' tag declare a new jMax object, provide some information about it.
It is the tag used to build up a library package.

<code xml>
  <object name="myObject"
          type="jMax"
          url="jmax://myPackage/libs/myObject.so"
          image="jmax://myPackage/images/myObjectPatchImage.png"
          icon="jmax://myPackage/icons/myObject.png"
          uiJavaClass="org.myorg.MyObjectUI"
          helpPatch="jmax://myPackage/help/myObjectHelp.jmax"
          description="My Object">
     <inlet position="1" description="MyObject left input">
     <inlet description="An other MyObject inputs">
     <output position="1" description="MyObject output">
   </object>  
</code>

In jMax, all the information known to the user interface about an object is defined within a package, using
the ''object'' tag. The ''object'' tag apply to all kind of objects, including external C jMax objects, Max 0.26
abstraction or jMax abstractions, or LADSPA plugins.

The meaning of the attributes is the following:
  * ''name'': the name of the object: the object loaded will have this name in a jMax patch, regardless of the file name. This allows including in object name characters that are not allowed in file names on some platforms, like '<' on Windows. The autocompletion popup menu for objects use these declarations to find object names, so if an object is loaded but not described by an ''object'' tag, it will not appear on the menu. This attribute is mandatory.

  * ''type'': specify the type of the object to be loaded. Recognised types are ''jmaxv1'' for jmax external objects packaged on a module according the version 1 of the jMax API (the current one), ''ispw'' for Max 0.26 abstractions, ''abstraction'' for jMax abstractions, ''ladspa'' for LADSPA plugins. Other types may be added in the future.  This attribute is mandatory only in the case of ''ladspa'' and for version of the jMax API differents from the 1, in all other cases it can be safely omitted, because the type of the object will be deduced from the value of the ''url'' attribute.
  * ''url'': specify where to load the object from. The url must be of the ''jmax:'' type. The type of the object is recognised from the filename extensions: 
    *''.so'' or ''.dll'' or ''.dylib'' identify a dynamic library containing external objects (on Linux/Unix platforms, Windows platforms and Mac OS X platforms). The library can contains more than one object.
    * ''.abs'' identify a Max 0.26/ISPW abstraction.
    * ''.jmax'' identify a jMax abstraction.
    * If the default behaviour is not the one needed (for example to load a LADSPA plugin library), the ''type'' attribute should be used to explicitly define the object type.
  * ''image'' : if specified, the image is used in the patch editor to represent the object. The value must be a jmax URL.
  * ''icon'' (optional): specify the icon (as a jmax URL) to be used to present the object in the patch browser an other contexts.
  * ''uiJavaClass'' (optional) : specify the Java class implementing the object within the patch editor; a package can then extend the patch editor adding new graphical objects. The Java API to program new objects is not yet documented, check the source code and ask for help on the list if you want to write a new graphical editor.
  * ''helpPatch'' (optional): the help patch for the object; the patch used as help patch for this object. Note that you can associate an help patch to any kind of object, including abstractions and ladspa plugins.
  * ''description'' (optional): a short description text that will be shown in the status line while mousing over the object.

The ''inlet'' and ''outlet'' sub-elements are optionals and are used to specify some metadata for the inlets and outlets of the object;
multiple ''inlet'' and ''outlet'' may be present.

The attributes for the ''inlet'' elements have the following meaning:

  * ''position'' (optional) : the position of the inlet (1 based) this element describe. If missing, this description apply by default to all the inlets for which an other ''inlet'' element has been specified.
  * ''description'' : a short text that is shown on the status line when mousing over the inlet.

The attributes for the ''oulet'' elements have the following meaning:

  * ''position'' (optional) : the position of the outlet (1 based) this element describe. If missing, this description apply by default to all the outlets for which an other ''inlet'' element has been specified.
  * ''description'' : a short text that is shown on the status line when mousing over the outlet.

For an example of use of the ''image'' attribute, check the ''synth'' example in the ''docs/example'' directory.

==== The ''helpSummary'' tag ====
<code xml>
  <helpSummary name="My Objects" url="jmax://myPackage//help/myObjects.summary.jmax"/>
</code>

Specify a patch to be used as help summary for the package. More than one help summary
can be declared by a package. Help summaries patches are directly accessible from the Help menu.

Attribute meaning is the following.

  * ''name'' : the name of the summary. This name will be shown in the help menu.
  * ''url'' : the jMax URL of the help summary patch.

==== More fun with package description file ====


The package.jpkd file is an standard jMax configuration file; this means that all the rules
about configuration files [[user:XMLConfigurationBasic | defined here]] apply also to the package description
files. This means that a package, other than defining its own structure using the syntax described in this 
section, can also do all the actions that can be done with a configuration file, like for example adding
an io-configuration, user interface configuration, set some preferences, and others.

Be careful that some part of the configuration file (like user interface configuration) can only be taken
in account if the package is loaded at jMax startup time, either by adding it in your personal configuration file
''~/.jmax.xml'' or passing it in the command line.

===== jMax Package Versioning =====

jMax Phoenix **do not** offer a mechanism for versioning packages.
This is **intentional** : modern development practices show that mechanisms like
automatically updating to the latest version, **especially** for a system able to load
a package from the Internet, is a very dangerous and unwelcome behaviour.

Essentially, you can fall in a situation like discover a major incompatibility in a new version
of a package just five minutes before a public performance.

So, jMax Phoenix adopt the philosophy that every require should identify  unambiguously
a specific version of a specific package; the easiest way is to say that jMax Phoenix
do not handle versioning, and that the version of a package should be included in its name;
each version of a package need to have a unique name (and file name).

If you want your application to use a new version of the package, you have to know
its full file name, and change the configuration file of your application.