How to create a Package

This page tells how to create a package.

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

The file must have a .jpkd extension (from jMax package descriptor), 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:

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.

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 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:

~/.jmax/cache

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

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

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

The accepted package declaration tags are:

• documentation
• require
• module
• document (aliased to patch)
• object
• helpSummary

  <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"/>

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.

  <require package="neededPackage"/>

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.

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

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.

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

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 ( 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 declare a new jMax object, provide some information about it. It is the tag used to build up a library package.

  <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>

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.

  <helpSummary name="My Objects" url="jmax://myPackage//help/myObjects.summary.jmax"/>

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.

The package.jpkd file is an standard jMax configuration file; this means that all the rules about configuration files 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 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.