= Installation =

The recent bundle of MUSCLE can be downloaded from the [[http://apps.man.poznan.pl/trac/muscle/downloads|Downloads section]]. The bundled package contains the source code, documentation and precompiled Java archives (jar).

The offered version of MUSCLE in several places extends and improve the [[http://muscle.berlios.de/|package]] provided by Jan Hegewald. We can list here the following elements:
* improved installation procedure (some dependencies are already included in the bundle),
* added support for generation of OTF trace logs,
* implemented Port Range traversing technique for cross-cluster execution.
== Dependencies ==
The core functionality of the MUSCLE is written in Java. To be able to integrate native code with the MUSCLE, there is also a native part which is written in C++. Bootstrapping and platform independent configuration is done with a flexible setup mechanism written in Ruby. 

In order to use the MUSCLE, you need a recent Java runtime. You can obtain it at either http://www.java.com/en/download/index.jsp (Oracle-Java) or http://openjdk.java.net/ (Open-JDK). Main Java third-party dependencies are already provided in the bundle and do not need to be independently installed. 

A Ruby installation can be downloaded from: [[http://www.ruby-lang.org/en/downloads/] (MUSCLE does currently not work with Ruby 1.9.1 or newer).
== General Instructions ==
If the dependencies are in place, you are ready to build and install MUSCLE. 
Extract the download, e.g.
{{{
#!div style="font-size: 90%"
{{{#!sh
$ unzip muscle-1.0.1.zip
}}}
}}}
Change your working directory to the the MUSCLE directory:
{{{
#!div style="font-size: 90%"
{{{#!sh
$ cd muscle-1.0.1
}}}
}}}
Invoke MUSCLE build script with  installation (we are installing muscle to the /opt/muscle directory which is default, type ./build.rb for more options):
{{{
#!div style="font-size: 90%"
{{{#!sh
$ ./build.rb --target=install
}}}
}}}
See if MUSCLE is working correctly:
{{{
#!div style="font-size: 90%"
{{{#!sh
$ /opt/muscle/bin/muscle --version
}}}
}}}

In case you plan to use MUSCLE with native code, you will have to compile the native library part of MUSCLE using a C++ compiler (such as g++). The build script belonging to MUSCLE also has a target to build the native libraries. This requires a C++ compiler and CMake (http://www.cmake.org/) to be available.

== Installation example - Scientific Linux 5.6 ==
'''Note:''' Some part of the presented installation procedure requires to be invoked by root.

1. Check if a proper version of ruby is already installed in the system, otherwise install it:
{{{
#!div style="font-size: 90%"
{{{#!sh
ruby --version
-bash: ruby: command not found

yum install ruby
...
ruby --version
ruby 1.8.5 (2006-08-25) [x86_64-linux]
}}}
}}}

2. Ensure if you have a c++ compiler available on your system. If you have not, install this:
{{{
#!div style="font-size: 90%"
{{{#!sh
yum install gcc-c++
}}}
}}}

3. Check if cmake is available, otherwise install cmake:
{{{
#!div style="font-size: 90%"
{{{#!sh
yum install cmake
}}}
}}}
 '''Note:''' you may need to add the reference to the repository with extra packages. To do this create the file 'epel.repo' in the /etc/yum.repos.d directory. The content of the file may look as follows:
 {{{
 #!div style="font-size: 90%"
 {{{#!sh
 [epel]
 name=Extra Packages for Enterprise Linux 5 - $basearch 
 
 #baseurl=http://download.fedoraproject.org/pub/epel/5/$basearch
 mirrorlist=http://mirrors.fedoraproject.org/mirrorlist?repo=epel-5&arch=$basearch
 failovermethod=priority
 enabled=1
 gpgcheck=0
 }}}
 }}}

4. Check if recent Java SE Runtime Environment (JRE) or Java SE Development Kit (JDK) are present in your system. As the precompiled MUSCLE package is already included at build/muscle.jar you may not need to compile the Java sources and JRE should be sufficient. Hovewer, if you want to recompile the Java part of the MUSCLE (recommended), a recent Java compiler is also required.  
{{{
#!div style="font-size: 90%"
{{{#!sh
yum install jdk
}}}
}}}

5. Download the muscle bundle from [[http://apps.man.poznan.pl/trac/muscle/downloads|Downloads section]], e.g.
{{{
#!div style="font-size: 90%"
{{{#!sh
wget http://apps.man.poznan.pl/trac/muscle/downloads/muscle-1.0.1.zip
}}}
}}}

6. Extract the package:
{{{
#!div style="font-size: 90%"
{{{#!sh
unzip muscle-1.0.1.zip
}}}
}}}

7. Compile MUSCLE (--target=default recompiles java and c++ stuff):
{{{
#!div style="font-size: 90%"
{{{#!sh
cd muscle-1.0.1
./build.rb --target=default --prefix=/opt/muscle
}}}
}}}

8. See if the MUSCLE is working:
{{{
#!div style="font-size: 90%"
{{{#!sh
/opt/muscle/bin/muscle --version
}}}
}}}

== Sample execution ==
There are some examples provided within the MUSCLE bundle. Example code for kernels can be found in the directories src/java/examples and src/cpp/examples. There are also prepared configurations for coupled examples CxA (MUSCLE simulations), which can be found in the src/cxa directory.

=== Hello World ===

==== Sender ====
 At src/java/examples/simplejava/Sender we provide a minimalist kernel written in Java, which sends data (an array of double).

==== Receiver ====
 At src/java/examples/simplejava/ConsoleWriter we provide a simple kernel written in Java. It receives data (an array of double) and prints its content to the standard output.

==== CxA (coupling schema) ====
 The configuration src/cxa/SimpleExample.cxa.rb configures a minimal CxA which couples the src/java/examples/simplejava/Sender and src/java/examples/simplejava/ConsoleWriter kernels.

==== Execution ====
To run the simmulation defined in src/cxa/SimpleExample.cxa.rb use the following command:
{{{
#!div style="font-size: 90%"
{{{#!sh
/opt/muscle/bin/muscle --cxa_file src/cxa/SimpleExample.cxa.rb --main plumber w r --autoquit
}}}
}}}

== Further reading ==
For more information how to use MUSCLE see doc/muscle_developers_guide.pdf included in the MUSCLE bundle.