====== Installation Instructions ======

These instruction are adapted to the current format of the 
snapshot distribution. This format will evolve, and hopefully
jMax will be packages in standard debian or rpm format in the future.

 ==== What you need ==== 

A jMax snapshot, to be downloaded from the project sourceforge site.
Please note that distributions are OS and architecture specific.
jMax Phoenix packaging do not support multi architecture distributions.

The name of the release file is composed by the OS name,
the architecture jMax was compiled for and the revision number of
the snapshot; for example: jmax.Linux.x86_64.r107.tgz.

You need a Java virtual machine installed, version 1.6 or later. 
The Sun virtual machine work well, the openJDK 1.6 works well, but early
versions have some bug here and there, so be sure to have the latest version,
and report the JVM you are using in case of troubles.

For the time being, you need to be sure to have the portaudio and portmidi library .so installed;
you may install the version coming with your distribution, or the latest that you can find in the port audio
web site. If you are using Ubuntu Studio, these libraries are already installed.

An other package you need is the gnu run time for objective C; now jMax use a bit of Objective C in the 
FTS computational kernel, and it will use more and more of it.

=== Ubuntu ===

On an Ubuntu Studio distribution, the following command is what you need to install the missing pieces:

<code>
sudo apt-get  install openjdk-6-jre libobjc2
</code>

On a Ubuntu desk distribution, you'll need to:

<code>
sudo apt-get  install libportmidi0 openjdk-6-jre libobjc2
</code>

=== Debian ===

On a Debian distribution, you'll need to:

<code>
sudo apt-get  install libportaudio2 libportmidi0 openjdk-6-jre libobjc2
</code>

Due to a problem of the portaudio package for debian, the default configuration will not works on 
Debian; in order to use jMax you need to write a configuration file; putting the following content
in a file called ''.jmax.xml'' under you home directory should give you a stereo output.

<code lang="xml">
<?xml version="1.0"?>

<!-- jMax Phoenix -->

<!-- This configurqtion file explicitly set the number of the portaudio output 
     device to zero. This seems to be needed in Debian 5, because for some unknown reason
     the default portaudio device do not works.
 -->

<jmax>

  <io-configuration name="debian">
    <device name="portAudioStereoOut"
	    type="portaudio_dac"
	    deviceName="portaudio_default"
	    out_device="3"
	    out_channels="2"/>
    <map>
      <logical-device type="out~" name="main"/>
      <device name="portAudioStereoOut" />
    </map>
  </io-configuration>

  <preferences>
    <io-configuration name="debian"/>
  </preferences>
</jmax>
</code>


=== Fedora ===

On a Fedora distribution, go in the Add/Remove Software Panel, and install portaudio-19-9.fc2, the audio file library,
the latest OpenJDK Runtime Environment, and the latest Objective-C runtime; you also need the portmidi library, but be carefull:
by default the add/remove software panel offer to install the 200 version that apparently do not works (it does not contains the
linbporttime library); i installed the rpm for the version 184 and it worked.

=== Mandriva ===
On the Mandriva and the objective C runtime (libobjc2),
using the rpmdrake application; portaudio and java are already installed.





 ==== Installing the jMax distribution ==== 

jMax is distributed as a tar gzip'ed file. After downloading the jMax 
distribution file (for instance jmax.free.linuxpc.2.3.12.tar.gz),
you will need to execute the following:

  * Untar the package in the directory where you want to install jMax,  typically ''/usr/local'':

   * For example: ''tar xvzf jmax.Linux.x86_64.r107.tgz''. This will create the ''jmax'' directory; you are free to rename it if you want to track version numbers.
  
  * Current snapshot releases are for evaluation only, so it is not worth to set the permission to be able to run at real time priorities. Instructions to do so will be given in the future once worth doing.

 ==== The jMax distribution directory structure ==== 

The create jmax directory contains the following directories and files:

  * **jmax**: the jmax executable script. Run this script to start jmax.
  * **config**: contains the configuration files for this installation.
  * **docs**: contains (will contains) some documentation, readme file and so on
  * **examples**: contains some examples, patches or configuration examples.
  * **images**: contains the images used by jMax
  * **bin**:  contains the core jMax executable
  * **tcl**: contains the core jMax tcl code
  * **packages**: contains all the packages distributed with the core jMax

 ==== Running jMax ====

Run the jmax script from the distribution.
For the various command line options, see [[CommandLineOptions | this page ]].