= MUSCLE 2 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). We maintain a [[Clusters|list of clusters]] where MUSCLE is already deployed.

The offered version of MUSCLE 2 in extends and improves 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,
* updated API
* 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, either [[http://www.java.com/en/download/index.jsp|Oracle-Java] or [[http://openjdk.java.net/|Open-JDK]]. Java third-party dependencies are already provided in the bundle and do not need to be independently installed. 

For the command-line interface [[http://www.ruby-lang.org/|Ruby]] is needed.

To compile and install MUSCLE, use the [[http://www.cmake.org/|CMake]] package. For the MUSCLE Transport Overlay, to communicate between different clusters,[[http://www.boost.org/|Boost]] is needed.

=== Installation of dependencies on a Debian flavored Linux ===

Run
{{{
sudo apt-get install build-essentials cmake ruby libboost-dev
}}}

to install all dependencies at once.

=== Installation of dependencies on Scientific Linux 5.6 ===

'''Note:''' Some part of the presented installation procedure requires to be invoked by root.

{{{
yum install ruby gcc-c++ cmake jdk curl
}}}

 '''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:
{{{
 [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
}}}

=== Installation of dependencies on Mac OS X ===

Most dependencies are installed when installing Xcode. In [[http://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12|Xcode 4.4]], the command-line tools are installed by opening Preferences -> Downloads and pressing Install at the item "Command-line tools". For Boost and CMake, download the packages on their website or use an installation manager like [[http://mxcl.github.com/homebrew/|HomeBrew]] or [[http://www.macports.org/|MacPorts]].

=== Remainder of the installation ===

If your ruby version is 1.8.x:
{{{
ruby --version
}}}
then it is necessary to install json with the following command
{{{
sudo gem install json
}}}

When the dependencies are in place, you are ready to build and install MUSCLE.  Download the muscle bundle from [[http://apps.man.poznan.pl/trac/muscle/downloads|Downloads section]], e.g.
{{{
curl -#O http://apps.man.poznan.pl/trac/muscle/downloads/muscle-2.0-RC1.zip
}}}

Extract the download, e.g.
{{{
$ unzip muscle-2.0-RC1.zip
}}}
Change your working directory to the the MUSCLE directory:
{{{
$ cd muscle-2.0-RC1/build
}}}
Invoke MUSCLE build script with installation; this installs MUSCLE in /opt/muscle. For another location, add this as the first argument.
{{{
./build.sh
}}}
See if MUSCLE is working correctly:
{{{
source /opt/muscle/etc/muscle.profile
muscle2 --version
}}}
The command 
{{{
source /opt/muscle/etc/muscle.profile
}}}
should always be run before executing MUSCLE. It can help to put this command in {{{~/.bashrc}}} so that it runs on login.

== 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 ====
 In {{{src/java/examples/simplejava/Sender.java}}} we provide a minimalist kernel written in Java, which sends data (an array of double).

==== Receiver ====
In {{{src/java/examples/simplejava/ConsoleWriter.java}}} 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 {{{examples.simplejava.Sender}}} and {{{examples.simplejava.ConsoleWriter}}} kernels.

==== Execution ====
To run the simulation defined in src/cxa/SimpleExample.cxa.rb use the following command:
{{{
muscle2 --cxa src/cxa/SimpleExample.cxa.rb --main --allkernels
}}}
or in shorthand notation
{{{
muscle2 -c src/cxa/SimpleExample.cxa.rb -am
}}}
It will first start the Simulation Manager, of which one per simulation is necessary, and then the local manager, which manages the kernels that are started with one {{{muscle2}}} invocation.

== Further reading ==
For more information how to use MUSCLE see the pages in [Documentation] and [Tutorials] section.

= MUSCLE 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). We maintain a [[Clusters|list of clusters]] where MUSCLE is already deployed.

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

For the command-line interface [[http://www.ruby-lang.org/|Ruby]] is needed.

To compile and install MUSCLE, the [[http://www.cmake.org/|CMake]] package. For the C++ library, [[http://www.boost.org/|Boost]] is needed.

=== Installation of dependencies on a Debian flavored Linux ===

Run
{{{
sudo apt-get install build-essentials cmake ruby ruby-dev libboost-dev libgemplugin-ruby
}}}

to install all dependencies at once.

=== Installation of dependencies on 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
}}}
}}}

=== Installation of dependencies on Mac OS X ===

Most dependencies are installed when installing Xcode. In [[http://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12|Xcode 4.3]], the command-line tools are installed by opening Preferences -> Downloads and pressing Install at the item "Command-line tools". For Boost and CMake, download the packages on their website or use an installation manager like [[http://mxcl.github.com/homebrew/|HomeBrew]] or [[http://www.macports.org/|MacPorts]].

=== Remainder of the installation ===

If your ruby version is 1.8.x, then it is necessary to install json with the following command
{{{
sudo gem install json
}}}

When the dependencies are in place, you are ready to build and install MUSCLE.  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.1.1.zip
}}}
}}}

Extract the download, e.g.
{{{
#!div style="font-size: 90%"
{{{#!sh
$ unzip muscle-1.1.1.zip
}}}
}}}
Change your working directory to the the MUSCLE directory:
{{{
#!div style="font-size: 90%"
{{{#!sh
$ cd muscle-1.1.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 install --prefix=/opt/muscle
}}}
}}}
See if MUSCLE is working correctly:
{{{
#!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 simulation 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.