[[PageOutline]]

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

== Dependencies ==

In order to install MUSCLE from source, you need

* a recent Java runtime (Java 6 or higher), either [[http://www.java.com/en/download/index.jsp|Oracle-Java]] or [[http://openjdk.java.net/|Open-JDK]];
* a [[http://www.ruby-lang.org/|Ruby]] interpreter (1.8.7, 1.9.x or 2.0.x);
* the [[http://www.cmake.org/|CMake]] build system.

CMake is not needed for executing MUSCLE, only for installation.
=== Installation of dependencies on a Debian flavored Linux ===

Run
{{{
sudo apt-get install build-essential cmake ruby default-jdk
}}}

to install the minimal set of dependencies.

To resolve all features, also run
{{{
sudo apt-get install unzip subversion python-dev gfortran openmpi-bin libopenmpi-dev cmake-curses-gui
}}}
=== 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 5]], the command-line tools are installed by opening Preferences -> Downloads and pressing Install for "Command-line tools". Install the [[http://www.oracle.com/technetwork/java/javase/downloads/index.html|Java Development Kit (JDK) from Oracle]]. Download CMake on [[http://www.cmake.org/cmake/resources/software.html|their website]] or use an installation manager like [[http://mxcl.github.com/homebrew/|HomeBrew]] or [[http://www.macports.org/|MacPorts]]. With HomeBrew, you can run
{{{
brew install cmake
}}}
=== Installation of dependencies on Scientific Linux 5.6 ===

To install all dependencies in a single command, run
{{{
sudo 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
}}}

== 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]], or from the command-line. Then unzip the folder, go to the build directory inside and run the {{{build.sh}}} command.
{{{
curl -#O http://apps.man.poznan.pl/trac/muscle/downloads/MUSCLE-2.1.0-sources.zip
unzip MUSCLE-2.1.0-sources.zip
cd MUSCLE-2.1.0-sources/build

sudo ./build.sh
}}}

This installs MUSCLE in /opt/muscle. For another location, add this as the first argument to {{{build.sh}}}. If the configuration or the libraries of the host have changed since you last built MUSCLE, run
{{{
rm CMakeCache.txt
}}}
before running the build script to forget all CMake settings.

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 at login.

Finally, see if MUSCLE is working correctly:
{{{
muscle2 --version
}}}
== Advanced building options ==

Although the {{{build.sh}}} script is sufficient in most cases, sometimes it can not
detect where certain libraries are located, especially the libraries of the MPI example.
The build settings can be modified by setting the following environment variables:

||= Variable ||= Setting ||= Example ||
|| {{{MPI_C_COMPILER}}} || Compiler used for the C MPI example || {{{/usr/bin/mpicc}}} ||
|| {{{MPI_C_FLAGS}}} || Flags to give the C MPI compiler || {{{-O3 -Wall}}} ||
|| {{{MPI_C_INCLUDE_PATH}}} || Location of include files for C MPI || {{{/usr/include}}} ||
|| {{{MPI_C_LIBRARIES}}} || All libraries needed to link with for C MPI (semicolon separated) || {{{/usr/lib/libmpi.so;/usr/lib/libm.so}}} ||

Possible build options can be evaluated by going to the build directory and running:
{{{
cmake -L ..
}}}

Even more detailed build options are found with:
{{{
cmake -LA ..
}}}

These options can be passed to cmake by setting the environment variable {{{MUSCLE_CMAKE_OPTIONS}}}:
{{{
export MUSCLE_CMAKE_OPTIONS="-DOPTION=VALUE -DOPTION2=VALUE2"
}}}
For example, to build the python extension:
{{{
export MUSCLE_CMAKE_OPTIONS="-DBUILD_PYTHON=ON"
sudo ./build.sh
}}}
And if the Python libraries or headers cannot be found:
{{{
export MUSCLE_CMAKE_OPTIONS="-DBUILD_PYTHON=ON -DPYTHON_INCLUDE_DIR=/usr/include/python2.7 -DPYTHON_LIBRARY=/usr/lib/libpython2.7.so"
sudo ./build.sh
}}}
== Further reading ==
For more information how to use MUSCLE see the [[Documentation]] and [[Tutorials]] sections.

----

The offered version of MUSCLE 2 in extends and improves the [[http://muscle.berlios.de/|package]] provided by Jan Hegewald, notably it has:
* improved the installation procedure (some dependencies are already included in the bundle),
* updated API
* increased performance
* decreased complexity
* implemented a port range traversing technique for cross-cluster execution.

For MUSCLE version 1.x installation, see [[MUSCLE1 Installation]]