In this document, we'll port an existing app to MutekH. We'll choose a standard publicly available application: `bc`.

bc is a command-line arbitrary precision calculator well known in the unix world. It uses standard APIs, makes reasonable use of I/O, and has a quite verifiable result.

= Getting the source tree =

Let's begin getting the source, and unpack it:
{{{
$ wget http://ftp.gnu.org/pub/gnu/bc/bc-1.06.tar.gz
$ tar xzvf bc-1.06.tar.gz
}}}

= Creating our source tree =

Now create another directory, and extract the meaningful sources
{{{
$ mkdir mutekh_port
$ cd mutekh_port
$ mkdir src lib h
$ cp ../bc-1.06/bc/*.[ch] bc/
$ cp ../bc-1.06/lib/*.[ch] lib/
$ cp ../bc-1.06/h/*.h h/
}}}

Let's create the Makefiles:

 * `bc/Makefile`
   {{{
objs = bc.o execute.o global.o load.o main.o scan.o storage.o util.o

DIR_CFLAGS=-I$(srcdir)/../lib -I$(srcdir)/../h -I$(srcdir)/.. -U__MUTEK__
scan.o_CFLAGS=-DEINTR=-1024
}}}
 * `lib/Makefile`
   {{{
objs = getopt.o getopt1.o number.o glue.o

DIR_CFLAGS=-I$(srcdir)/../lib -I$(srcdir)/../h -I$(srcdir)/.. -U__MUTEK__ -DHAVE_CONFIG_H
}}}
 * `Makefile`
   {{{
subdirs = bc lib
}}}

= Providing glue code =

Now let's create some glue code:
 * As this is userland-specific, MutekH does not define
  * `getenv()`
  * `signal()`
  * `sys/types.h`
 * As it is unix and user-specific, MutekH starts with `app_start()`, not `main()`. We need a wrapper that calls `main()`.

 We will have to provide them.

Add a `lib/glue.c` file:
{{{
#include <hexo/types.h>

char *getenv(const char *env)
{
	return NULL;
}

int main(int, char**);

void app_start()
{
	char *argv[] = {"bc"};
	main(1, argv);
}
}}}

Add a `signal.h` file:
{{{
#define SIGINT 0

static inline int signal(int sig, void *handler)
{
	return -1;
}
}}}

Create a `sys` directory, and a `sys/types.h` file containing:
{{{
#define isatty(x) 1
#define fileno(x) 0
#define fopen(x,y) NULL

#include <hexo/types.h>
}}}

= Creating the config.h =

As many autoconf-based programs, bc relies on a `config.h` file generated by the build system.

For MutekH, we will create this config.h from the config.h.in file.

Let's create a `config.h` file
{{{
#define HAVE_VPRINTF
#define STDC_HEADERS
#define DC_VERSION "1.06"
#define DC_COPYRIGHT "GNU"
#define BC_COPYRIGHT "GNU"
#define HAVE_LIMITS_H
#define HAVE_STDARG_H
#define HAVE_STDLIB_H
#define HAVE_STRING_H
#define HAVE_UNISTD_H
#define PACKAGE "bc for MutekH"
#define VERSION "1.06"
}}}

= The MutekH configuration file =

FInally, let's create a configuration file. For instance, with the mutekh_tutorial soclib platform, we may use the following config:
{{{
# Application license
CONFIG_LICENSE_APP_GPL

# Platform types
CONFIG_ARCH_SOCLIB

# Processor types
CONFIG_CPU_ARM
CONFIG_CPU_ARM_SOCLIB

# Mutek features
CONFIG_PTHREAD
CONFIG_MUTEK_CONSOLE

CONFIG_LIBC_STREAM
CONFIG_LIBC_STREAM_STD

CONFIG_HEXO_INTTYPES_DEPRECATED undefined

# Device drivers
CONFIG_DRIVER_CHAR_SOCLIBTTY
CONFIG_DRIVER_ICU_SOCLIB

# Code compilation options
CONFIG_COMPILE_DEBUG
CONFIG_COMPILE_OPTIMIZE 2

# New source code module to be compiled
CONFIG_MODULES bc:%CONFIGPATH
}}}

That's all, we finished porting our app !

= Compiling and running =

{{{
user@host ... caba-vgmn-mutekh_tutorial $ make CONFIG=config_soclib_arm APP=/path/to/mutek_port/src MUTEKH_DIR=path/to/mutekh
...
    LD o    .../caba-vgmn-mutekh_tutorial/mutekh/kernel-soclib-arm.o
    LD out  .../caba-vgmn-mutekh_tutorial/mutekh/kernel-soclib-arm.out
soclib-cc -P -p .../caba-vgmn-mutekh_tutorial/platform_desc  -o system.x
[-------------------------------------------------------------------------=] 0 left 
user@host … caba-vgmn-mutekh_tutorial $ ./simulation.x
}}}