
  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:

        * A computer with either Linux or IRIX operating system. If you
          plan to use another system, be prepared to do some porting
          (little work on most UNIX-systems, a lot more for Windows or
          Mac).
        * *C++ compiler* (MIPSPRO CC or g++)
        * *X11 header files*
        * *The Qt2.2, 2.3 or 3 library and header files*
          (http://www.trolltech.com/).
        * *Audio file library* http://www.68k.org./~michael/audiofile/
        * *Linux kernel headers if you are running Linux.* Most Linux
          distributions ship them automatically. Have a look around
          ftp.kernel.org <ftp://ftp.kernel.org/> if they do not seem to
    be available.

    The following don't hurt, but are not required:

        * If you run Linux you probably want to use *libcap* (capability
          library) to handle the tricky task of dropping unnecessary
          privileges (See section on final Linux configuration.
          <#LINUX-LIBCAP>).
        * If your CPU is AMDs K6 or K7 you may want to also install *the
          Vector Mathematics Library (VML)*
          <http://www.tml.hut.fi/~tilmonen/vml/> before starting. This
    is not compulsory, but VML may give a minor performance boost.


    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"* <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
    <http://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 <http://www.tml.hut.fi/~tilmonen/givertcap/>
    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) <http://www.doxygen.org> is needed for
    this purpose

*

cd src
make doc-mj

*

------------------------------------------------------------------------

    Last update 6.2.2004

    Tommi.Ilmonen@hut.fi <mailto:Tommi.Ilmonen@hut.fi>

