= Summary =

Building and running MutekH requires some development tools.
Most should be available from your operating system packages.
A script to easily get other specific tools installed is provided.

= Required tools =

== Repository access ==

The MutekH source code is available from its mercurial repository.
You will need [http://mercurial.selenic.com/ mercurial] (>=1.5) to fetch the source:

{{{
hg clone http://www.mutekh.org/hg/mutekh
}}}

MutekH rely on the [http://mercurial.selenic.com/wiki/Subrepository Subrepository]
feature of mercurial. Some external projects subrepositories require [http://subversion.tigris.org/ subversion]
installed so they are fetched automatically.
The [source:hg/.hgsub] file contains the external repositories list.
If some source files are missing, ensure your mercurial version is not outdated
or just perform additional checkouts by hand.

== Toolchain ==

Building MutekH requires the following standard software packages:

 - The [http://gcc.gnu.org/ GNU Compiler Collection] (gcc) (>=4.4.2).
 - [http://www.gnu.org/software/make/ GNU make] (>=3.81).
 - A [http://www.perl.org/ perl] script interpreter (>=5.8).

Some builds may require the following additional tools, depending on the target architecture and build configuration:

 - The [FlattenedDeviceTree flattened device tree] compiler (dtc): This tool comes with toolchains.
 - The heterogeneous linker found in [source:hg/tools/hlink], for heterogeneous platforms only.

== Target simulation tools ==

You may need real hardware or a simulator to run MutekH (Arch/Emu target doesn't need one though):

 - [http://www.qemu.org/ Qemu] to run MutekH, available in most GNU/Linux distributions.
 - [http://bochs.sourceforge.net/ Bochs] an other x86 emulator, available in most GNU/Linux distributions.
 - [https://www.soclib.fr/ SoCLib] to experiment with various multiprocessor platforms (Mips, !PowerPc, Arm, ...). A precompiled SoCLib platform is available [https://www.mutekh.org/www/tools/ here] for test purpose. We suggest building your own platforms by installing SoCLib (see soclib:InstallationNotes).

All this simulators can be used with the [http://www.gnu.org/software/gdb/ GNU debugger].

You may need extra tools to prepare bootable kernel images for some targets:

 - GNU mtools or mkisofs to create a x86 bootable disk images, available in most GNU/Linux distributions.
 - GNU grub or etherboot to boot compiled kernel images, included in boot image in [source:hg/tools/] directory.

The [source:hg/tools/x86_cdrom.sh] and [source:hg/tools/x86_floppy.sh] scripts are available to easily create boot disk images.

= Getting the tools =

Some tools are readily available in most GNU/Linux distributions.

Other tools require being build with a specific set of options and customized for a particular target.
MutekH comes with a script to build and install these tools on your particular platform.

== Precompiled tools ==

Some precompiled toolchains are avaialble [https://www.mutekh.org/www/tools/ here] for convenience and quick start purpose.
These binaries are available for GNU/Linux i386 and x86_64 distributions. It was configured for installation in {{{/opt/mutekh}}}.

== Building tools from source ==

The [source:hg/tools/crossgen.mk tools/crossgen.mk] script
is able to download, patch, build and install required specific tools for you.

The following commands display help and default configuration:
{{{
 $ cd .../mutekh
 $ tools/crossgen.mk
[display some help]
 $ tools/crossgen.mk config
[display default configuration]
}}}

The following example shows how to get a little endian Mips cross-compiler installed under `~/mutekh`:
{{{
 $ tools/crossgen.mk TARGET=mipsel PREFIX=$HOME/mutekh toolchain
}}}

This script can install the following tools for you:
 - GNU Compiler Collection ({{{gcc}}}),
 - GNU Binutils,
 - GNU Debugger ({{{gdb}}}),
 - Device Tree Compiler ({{{dtc}}}),
 - Bochs x86 emulator,
 - Qemu processor emulator,
 - Modified GNU coreutils timeout command (`testwrap`), used by [[Testsuite]].

= Running the tools =

When working with MutekH, be sure to add the `bin` and `lib` paths to your environment in order to use the tools:

{{{
export PATH=/opt/mutekh/bin:$PATH
export LD_LIBRARY_PATH=/opt/mutekh/lib:$LD_LIBRARY_PATH
}}}
if installed in `/opt/mutekh`, or:
{{{
export PATH=$HOME/mutekh/bin:$PATH
export LD_LIBRARY_PATH=$HOME/mutekh/lib:$LD_LIBRARY_PATH
}}}
if installed in `~/mutekh`.