INSTALLING MUSTAJUURI

Mustajuuri installation is straightforward business, but there are a few steps that must be taken.

The development environment is fairly involved because it handles simultaneous multi-platform compilations and largish amount of platform-in-dependency stuff. I use autoconf, but have not gotten around to automake, autoheader or autoxyz yet. Mustajuuri runs happily on Linux/x86 with kernel 2.2, 2.4 or greater and on SGI IRIX 6.5 systems. You may be able to compile and run it on other platforms with a bit of hacking (there are some FPU an endian issues that might need attention). The folowing instructions are for Linux, the IRIX installation is similar, but do note that you typically need to use LD_LIBRARYN32_PATH instead of LD_LIBRARY_PATH.

0. REQUIREMENTS

To install Mustajuuri you need the following libraries or tools: The following don't hurt, but are not required:

1. THE FAST WAY (INSTALLATION ONLY, NO DEVELOPMENT ENVIRONMENT)

This is your quickstart; If you run it as root Mustajuuri will try to install itself:

cd mustajuuri-[DATE]/src/

./scripts/fullbuild.sh

2. ENVIRONMENT VARIABLES

Set environment variables pointing to correct directories. It is a good idea to put these into your shell initialization file (.bashrc, .zshrc or similar). There is also a sample zshrc-file "zshrc-sample" that can be cut-pasted to your own shell initializations (do how-ever change the directory names).

For example:

export MUSTAJUURI_PATH=$HOME/mustajuuri

Set the QTDIR environment variable. This is needed for most Mustajuuri components. Without proper Qt settings you will be able to compile only the divabase, divaio and mjdsp libraries -- no real application or plugins. The location and version of Qt varies between Linux and IRIX distributions, so you must specify it yourself. Many Linux distributions place the Qt libraries under "/usr/lib", so trying to find something in there may give you the answer. Another possibility is "/usr/src", especially if you have a custom installation. So you can try something like this:

export QTDIR=/usr/src/qt3

Determine operating system:

export OSTYPE=mustajuuri-[DATE]/src/scripts/mj_uname.sh

Path for plugins:

export MUSTAJUURI_PLUGIN_PATH=$MUSTAJUURI_PATH/plugins/$OSTYPE/

Path for Mustajuuri binary:

export PATH=$PATH:$MUSTAJUURI_PATH/bin/$OSTYPE/

And yet path for dynamic libraries:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MUSTAJUURI_PATH/lib/$OSTYPE/

If you have more sound cards than the default stereo I/O card then you need to tell Mustajuuri the audio configuration on your system.

The information is stored in an environment variable. On Linux with OSS drivers it looks more or less like this (two stereo cards and one ADAT card):

export MJ_AUDIO_CONF="Input=2=/dev/dsp21|Input=2=/dev/dsp19|Output=2=/dev/dsp21|Output=2=/dev/dsp0|Output=8=/dev/dsp1|Input=8=/dev/dsp11"
...and in case you are using Alsa 0.5.x drivers (one stereo card):
export MJ_AUDIO_CONF="Input=2=0|Output=2=0"

...and in case you are using Alsa 0.9 beta 1-3 drivers (stereo and ADAT cards, for example SoundBlaster + Delta66):

export MJ_AUDIO_CONF="Input=2=hw:0,0|Output=2=hw:0,0|Input=8=hw:1,0|Output=8=hw:1,0"

BTW: This is done to inform Mustajuuri of the audio devices and their names in the system. Helps multi-platform work a fair bit.

On IRIX you do not need to do this, Mustajuuri auto-detects your hardware.

BTW: The format of the environment variable: The string should contain n chunks that are separated with "|"-character. Each chunk has three fields: 1) Direction 2) number of channels 3) device name. Direction is always either "Input" or "Output", number of channels is a positive integer and the device name depends entirely on you system. The fields within a chunk are separated with "="-character.

3. CONFIGURING

Configure the compilation parameters
./configure

After this you may need to edit $PLATFORM/Makeconf to match your Qt version. Mustajuuri can be compiled against any reasonably up-to-date Qt version. By default Mustajuuri expects the theraded version of Qt (-lqt-mt), but you can also build it against single-threaded Qt version (-lqt). This can be changed by adjusting the value of the QT -variable in $PLATFORM/Makeconf.

4. BUILDING MUSTAJUURI

Create include links and then binaries:

make links
make -k all

By default you get a dynamically linked binary under src/mj/$OSTYPE/ (binary named dmain). It is popssible to create a statically linked binary, but they usually fail to work :-|

cd mj
make smain

5. GIVING MUSTAJUURI THE NECESSARY CAPABILITIES

Mustajuuri stresses your computer hard. Especially if you want to use Mustajuuri as a real-time signal processing app (as an effects processor) Mustajuuri must get all CPU and memory resources it needs. In UNIX this is a problem - all resources of the system are shared and there are no guarantees about getting things done with low latency.

To overcome these problems Mustajuuri uses capabilities to get the necessary resources. Capabilities give the binary certain powers, but not the full root powers. Therefore a malicious user should not be able to compromise the security on your system with Mustajuuri.

The steps to take depend on your operating system.

5.1. LINUX: GIVING MUSTAJUURI NECESSARY CAPABILITIES

Linux systems need special tuning to make it possible to run a low-latency application. Especially if you want to run it under normal user id, like we do. The key to avoiding root-provileges is to use capabilities.

There are two steps that must be taken to get the capabilities correct:

  1. Patch the Linux kernel and recompile it (sorry, but this is your only hope).
  2. Compile the utility application givertcap.
PATCHING THE KERNEL

The kernel is patched by changing two lines from header "linux/capability.h":

#define CAP_INIT_EFF_SET    ( ~0 )
#define CAP_INIT_INH_SET    ( ~0 )
I used to recemmend the following, but it seems that it won't work with some new compiler/kernel combinations:
#define CAP_INIT_EFF_SET    { ~0 }
#define CAP_INIT_INH_SET    { ~0 }
(For further information see chapter 10 of the capfaq-0.2 document ftp.kernel.org/pub/linux/libs/security/linux-privs/kernel-2.2/capfaq-0.2.txt)

COMPILING GIVERTCAP

First of all your should have the POSIX capability library libcap. It is available from the site ftp.kernel.org or its mirrors. The path to the library is: /pub/linux/libs/security/linux-privs/kernel-2.2/. There are also rpm- and deb packages available for most distributions with the libcap. The library must be installed *before* you start installing or compiling Mustajuuri. If libcap is not present Mustajuuri will be very dangerous to the security of your system - in such cases it should not be setuid root on systems with untrusted users.

Once you have compiled Mustajuuri you need to give it the necessary powers (unless you always run Mustajuuri as root - not recommended). This process is not automated to the Makefiles as setuid operations should always be handled with great care. The idea is that Mustajuuri calls the setuid app that gives the necessary capabilities to Mustajuuri.

# Create the launcher application "givertcap":
cd src/utils/givecap
make 

The make-process will print further installation instructions after the application has been compiled. Once this is done mustajuuri will call the givertcap upon startup and thus gain the necessary capabilities. Simple :-)

The givertcap home page has more information on what givertcap is and how it works.

6. RUNNING

Now run the newly created binary:

cd mustajuuri-[DATE]
./bin/$OSTYPE/mustajuuri
./bin/$OSTYPE/mustajuuri src/examples/simple.mj
./bin/$OSTYPE/mustajuuri src/examples/simple.mj --autostart

If you have trouble, you can get (too much) debugging information to the screen, not that it helps you tough :-)

./$OSTYPE/dmain --debug 
./$OSTYPE/dmain --debug what

7. CREATING LADSPA PLUGINS

Some Mustajuuri plugins can also be used as LADSPA plugins. To enable this you need to compile the "ladspaexort" library. The compilatiom routine create the export library, but does not automatically put the resulting libary to the LADSPA plugin location.

The following commands create the wrapper library and place it to the standard location of LADSPA plugins.

cd src/ladspaexport
make 
cp $OSTYPE/libmjladspaexport.so /usr/local/lib/ladspa/

8. GENERATING HTML API DOCUMENTATION

You may want to generate html API documentation as well.

Doxygen (www.doxygen.org) is needed for this purpose

cd src
make doc-mj


Last update 6.2.2004

Tommi.Ilmonen@hut.fi