View source for Building and running embedded Linux .NET applications from first principles

== Overview ==

This walk-through has the aim of taking you from a clean system through to including Mono in a build image using the meta-mono layer, then building and packaging an example .NET project for inclusion in that image.

You may already have Yocto installed and just be looking to work with Mono for the first time, in which case you can jump forward to the section you find most relevant, <br/>
such as [[#Build an example project on the host for testing (optional)|building an example package on the host to test]] or [[#Adding the meta-mono layer to the Yocto build system|adding the meta-mono layer to the Yocto build system]].

The following assumptions are made. You are:

* familiar with basic Linux admin tasks
* aware of the Yocto Project Reference Manual [http://www.yoctoproject.org/docs/current/ref-manual/ref-manual.html here].
* using Ubuntu 12.04 LTS as your host build system
* working with Yocto 1.6 (daisy) release

== Obtain the required packages for your host system to support Yocto ==

First we will install the required host packages for Ubuntu as detailed in the quickstart, i.e.

  $ sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential chrpath libsdl1.2-dev xterm nano

Full details of system requirements and installation can be found in the Yocto Quickstart [http://www.yoctoproject.org/docs/1.6/yocto-project-qs/yocto-project-qs.html here]

=== Install Mono ===

Also install Mono on your host system as we'll use it to build and run some examples for test later

  $ sudo apt-get install mono-complete
  $ mono --version

With Ubuntu 12.04 LTS this will install Mono version 2.10 which is now quite old (December 2011).

If you wish to install a newer build of Mono to your host system you can follow the instructions [http://stackoverflow.com/questions/13365158/installing-mono-3-x-3-0-x-and-or-3-2-x here].

  $ sudo add-apt-repository ppa:directhex/monoxide
  $ sudo apt-get update
  $ sudo apt-get install mono-complete
  $ mono --version

This will install Mono 3.2.1 (August 2013)

If you wish to use the absolute latest Mono then there are instructions you can follow to build a release tarball [http://www.mono-project.com/Compiling_Mono_From_Tarball here] and from git [http://mono-project.com/Compiling_Mono_From_GIT here]. Be aware this may not be straightforward and that there can be issues, such as with missing files, if you follow this process. 

== Download and extract the Yocto 1.6 release ==

At the time of writing, the current release of Yocto (1.6) can be found [https://www.yoctoproject.org/download/yocto-project-16 here]
 
  $ cd ~
  $ mkdir yocto
  $ wget http://downloads.yoctoproject.org/releases/yocto/yocto-1.6/poky-daisy-11.0.0.tar.bz2
  $ tar xjvf poky-daisy-11.0.0.tar.bz2

This will get you the Yocto 1.6 base meta-data and the bitbake tool. You can also add in extra layers, usually of the form "meta-foo" to provide machine support and additional functionality.

== Configure the build environment to build an emulator image ==

  $ cd ~/yocto/poky-daisy-11.0.0
  $ source oe-init-build-env build_qemux86

This will create a build tree in "build_qemux86" although you could use a different name if you so wish with no adverse effects. 

It is entirely possible to have many build trees in parallel in different folders and to switch between them using <code>oe-init-build-env</code>.

<code>oe-init-build-env</code> will create a default configuration file in <code>conf/local/conf</code> which will build an emulator image suitable for execution with <code>qemu</code>

== Build a baseline image ==

After configuring the environment you will be left in the build_qemux86 folder.

You should then build a baseline image, which will take some time (numbers of hours)

  $ bitbake core-image-minimal

== Build an example project on the host for testing (optional) ==

=== Building with autotools ===

The most straightforward way to compile non-.NET projects for different targets within Yocto is to make use of [http://www.gnu.org/savannah-checkouts/gnu/automake/manual/html_node/index.html autotools]

Projects which support <code>autotools</code> provide a set of template files which are then used by the <code>autotools</code> to generate <code>Makefiles</code> and associated configuration files which are appropriate to build for the target environment.

Similarly it is possible to compile Mono/.NET projects using <code>autotools</code>

A very basic example 'Hello World' style project called <code>mono-helloworld</code> has been committed to GitHub [https://github.com/DynamicDevices/mono-helloworld here]

If you take a look at the two source files [https://github.com/DynamicDevices/mono-helloworld/blob/master/src/helloworld.cs helloworld.cs] and [https://github.com/DynamicDevices/mono-helloworld/blob/master/src/helloworldform.cs  helloworldform.cs] you can see the first outputs a 'Hello World' message to the console, and the second creates a Windows Form titled 'Hello World'.

Discussion of <code>autotools</code> template configuration for Mono is outside the scope of this guide, but the <code>mono-helloworld</code> project is based on the <code>mono-skel</code> example which can be found in the Autotools section of the Mono Application Deployment guidelines [http://mono-project.com/Guidelines:Application_Deployment here]

The project itself builds two .NET executables, <code>helloworld</code> and <code>helloworldform</code> respectively, the first of which is a console application and the second of which is a simple Windows Forms application.

To build the project on the host independently of Yocto first clone the example repository 

  $ mkdir ~/host
  $ cd ~/host
  $ git clone https://github.com/DynamicDevices/mono-helloworld

Then run the autotools, configure the build, and make the project

  $ cd mono-helloworld
  $ ./autogen.sh
  $ ./configure
  $ make

Following a successful compilation you will have a number of new files in the root of the build folder. 

There are two new .NET executables <code>src/helloworld.exe</code> and <code>src/helloworldform.exe</code>.

You can run the first with

  $ mono src/helloworld.exe

It will output 

HelloWorld

You can run the second with

  $ mono src/helloworldform.exe

Depending on your host environment (e.g. using SSH) you may need to explicitly set the <code>DISPLAY</code> variable for this to work, with

  $ export DISPLAY=:0
  $ mono src/helloworldform.exe

This will give you a basic Windows Forms window title

[[File:Monohelloworld.png|800px]]

So you have now shown that you can successfully fetch configure and build the project on the host. 

Next we will look at how Yocto automates the this process of fetching, configuring and building, then also installs and packages the output files.

=== Building with xbuild ===

Many individuals develop with Visual Studio, Mono Develop, Xamarin Studio or other similar integrated development environments (IDEs).

Mono provides <code>xbuild</code> which is the Mono implementation of Microsoft's <code>msbuild</code>, discussed [http://mono-project.com/Microsoft.Build here].

In essence this enables a developer to create a solution of projects within their IDE of choice, then use xbuild to build within the Mono environment.

A useful workflow to follow may be to develop locally with an IDE of choice, commit to a git repository upon release, then use a Yocto recipe to build and package that release into an existing image, or for provision to a package feed for update to existing targets in the field.

The <code>mono-helloworld</code> project discussed [[#Building with autotools|above]] also provides a solution and project files to support build with <code>xbuild</code>, or indeed with an IDE such as Visual Studio.

If you have already built the examples using <code>autotools</code> remove the folder and start again.

  $ cd ~/host
  $ rm -Rf mono-helloworld

Check out the mono-helloworld project again

  $ git clone https://github.com/DynamicDevices/mono-helloworld

Run xbuild. (As you might guess from the name of the .sln file you could clone this example project to a Windows host and open it up with Visual Studio, and in fact that is how it was created)

  $ xbuild /p:Configuration=Debug mono-helloworld_vs2010.sln

This results in a number of new files, including two new Mono/.NET executables in <code>bin/Debug</code> <code>helloworld.exe</code> and <code>helloworldform.exe</code>

You can run the first with

  $ mono bin/Debug/helloworld.exe

It will output 

HelloWorld

You can run the second with

  $ mono bin/Debug/helloworldform.exe

Depending on your host environment (e.g. using SSH) you may need to explicitly set the <code>DISPLAY</code> variable for this to work, with

  $ export DISPLAY=:0
  $ mono bin/Debug/helloworldform.exe

This will give you a basic Windows Forms window title

[[File:Monohelloworld.png|800px]]

So you have now shown that you can successfully fetch configure and build the project on the host. 

Next we will look at how Yocto automates the this process of fetching, configuring and building, then also installs and packages the output files.

== Adding the <code>meta-mono</code> layer to the Yocto build system ==

A preferred method for adding recipes to the build environment, and the method shown with this guide, is to place them within a new layer. 

Layers isolate particular sets of build meta-data based on machine, functionality or similar, and help to keep the environment clean.

The <code>meta-mono</code> layer contains Mono specific recipes to support execution of .NET applications on target boards. The layer can be found [http://git.yoctoproject.org/cgit/cgit.cgi/meta-mono here].

To use a new layer such as this you first clone the layer from its git repository and then add the layer to your <code>bitbake</code> configuration by editing <code>conf/bblayers.conf</code>

  $ cd ~/yocto/poky-daisy-11.0.0
  $ git clone git://git.yoctoproject.org/meta-mono
  $ cd ~/yocto/poky-daisy-11.0.0/build_qemux86
  $ nano conf/bblayers.conf

Your <code>bblayers.conf</code> should look similar to this

  # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
  # changes incompatibly
  LCONF_VERSION = "6"
  
  BBPATH = "${TOPDIR}"
  BBFILES ?= ""
  
  BBLAYERS ?= " \
    /home/user/yocto/poky-daisy-11.0.0/meta \
    /home/user/yocto/poky-daisy-11.0.0/meta-yocto \
    /home/user/yocto/poky-daisy-11.0.0/meta-yocto-bsp \
    "
  BBLAYERS_NON_REMOVABLE ?= " \
    /home/user/yocto/poky-daisy-11.0.0/meta \
    /home/user/yocto/poky-daisy-11.0.0/meta-yocto \
    "

Make the new layer visible to <code>bitbake</code> by adding a line to <code>BBLAYERS</code>

  BBLAYERS ?= " \
    /home/user/yocto/poky-daisy-11.0.0/meta \
    /home/user/yocto/poky-daisy-11.0.0/meta-yocto \
    /home/user/yocto/poky-daisy-11.0.0/meta-yocto-bsp \
    /home/user/yocto/poky-daisy-11.0.0/meta-mono \
    "

Now <code>bitbake</code> can see the recipes in the new layer.

You will also see when <code>bitbake</code> runs and shows the Build Configuration that the repository branch and hash of your layer is shown which is useful to know, particularly when comparing notes with others as to why a build fails, e.g.

  Build Configuration:
  BB_VERSION        = "1.22.0"
  BUILD_SYS         = "i686-linux"
  NATIVELSBSTRING   = "Ubuntu-12.04"
  TARGET_SYS        = "i586-poky-linux"
  MACHINE           = "qemux86"
  DISTRO            = "poky"
  DISTRO_VERSION    = "1.6"
  TUNE_FEATURES     = "m32 i586"
  TARGET_FPU        = ""
  meta
  meta-yocto
  meta-yocto-bsp    = "<unknown>:<unknown>"
  meta-mono         = "master:cb4998b3fbb7912468df8fc06d692fa872a21947"

== Build an image including Mono/.NET support ==

The <code>meta-mono</code> layer includes a recipe to build an image <code>core-image-mono</code> based on the Yocto standard image <code>core-image-sato</code>

To build this image

  $ bitbake core-image-mono

This may take a while, even if you have already built <code>core-image-minimal</code> as additional GUI support packages need to be built.

The <code>core-image-mono</code> recipe can be found [http://git.yoctoproject.org/cgit/cgit.cgi/meta-mono/tree/recipes-mono/images/core-image-mono.bb here] and pulls in an include file from [http://git.yoctoproject.org/cgit/cgit.cgi/meta-mono/tree/recipes-mono/images/core-image-mono.inc here].

You can see in the include file that extra packages are added to the standard <code>core-image-sato</code> image.

  IMAGE_INSTALL += "libgdiplus mono mono-helloworld"
  
This is how you would add Mono support to your image within a recipe, or within a .bbappend file. In fact it should only be necessary to add the <code>mono</code> package as this has a dependency on <code>libgdiplus</code> and it is not necessary to have the examples unless you wish to for testing purposes.

The <code>mono-helloworld</code> recipe included here shows how to build the example project using <code>autotools</code>. For details see the recipe itself [http://git.yoctoproject.org/cgit/cgit.cgi/meta-mono/tree/recipes-mono/mono-helloworld/mono-helloworld_1.1.bb here], and more importantly the include file it pulls in [http://git.yoctoproject.org/cgit/cgit.cgi/meta-mono/tree/recipes-mono/mono-helloworld/mono-helloworld.inc here].

You could choose to replace <code>mono-helloworld</code> with <code>mono-helloworld-xbuild</code> which as the name suggests shows how to build the eaxmple project with <code>xbuild</code>.

== Testing the .NET executable on an emulated target==

Having built <code>core-image-mono</code> you can then run it up under <code>qemu</code>

To run up the image, simply use
 $ runqemu qemux86

This will boot the emulator, load up the image, you'll see a kernel loading and then a basic user interface.

If you find that your keymap is incorrect you might wish to set this explicitly, for example

 $ runqemu qemux86 qemuparams='-k en-gb'

or

 $ runqemu qemux86 qemuparams='-k en-us'

Open up a terminal window using the appropriate icon, Log into the emulator as 'root', no password and run the examples.

You can run the first with

  $ mono helloworld.exe

Or alternatively the recipe installs a script to wrap use of Mono, so you can use the form

  $ helloworld

This will output 

HelloWorld

[[File:Monoemulatedhelloworld.png|800px]]

You can run the second with

  $ mono /usr/lib/helloworldform.exe

or

  $ helloworldform

Depending on your host environment (e.g. using SSH) you may need to explicitly set the <code>DISPLAY</code> variable for this to work, with

  $ export DISPLAY=:0
  $ mono /usr/lib/helloworld/helloworldform.exe

This will show a test Windows Forms form titled 'Hello World'

[[File:Monoemulatedhelloworldform.png|800px]]

== Breakdown of an autotools recipe ==

This is the contents of the mono-helloworld_1.1.bb recipe [http://git.yoctoproject.org/cgit/cgit.cgi/meta-mono/tree/recipes-mono/mono-helloworld/mono-helloworld_1.1.bb here]

 require mono-helloworld.inc
 SRC_URI[md5sum] = "79b0ba0044689789a54e3d55ec400fc0"
 SRC_URI[sha256sum] = "56388435f29ce94007155acc39593c900b6d3248a7f281e83ed2101a6da455f0"

It can be seen that we provide a couple of checksums which relate to the release tarball that will be downloaded

Similarly the is the included mono-helloworld.inc file can be found [http://git.yoctoproject.org/cgit/cgit.cgi/meta-mono/tree/recipes-mono/mono-helloworld/mono-helloworld.inc here]

  SUMMARY = "Mono Hello World"
  DESCRIPTION = "Test applications for Mono console and windows forms"
  AUTHOR = "Alex J Lennon <ajlennon@dynamicdevices.co.uk>"
  HOMEPAGE = "http://www.dynamicdevices.co.uk"
  SECTION = "mono/applications"
  PRIORITY = "optional"
  LICENSE = "GPLv3"
  LIC_FILES_CHKSUM = "file://LICENSE;md5=783b7e40cdfb4a1344d15b1f7081af66"
  DEPENDS = "mono"
  SRC_URI = "https://github.com/DynamicDevices/mono-helloworld/archive/v${PV}.tar.gz"
  inherit autotools
  FILES_${PN} = "${libdir}/helloworld/helloworld.exe \
  		${bindir}/helloworld \
         	${libdir}/helloworld/helloworldform.exe \
                ${bindir}/helloworldform \
  "

For more details on check-sums, licenses and so forth, see [https://wiki.yoctoproject.org/wiki/Building_your_own_recipes_from_first_principles#Build_an_example_package_based_on_a_remote_source_archive Building your own recipes from first principles] and the [https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide Recipe & Style Patch Guide].

We have a dependency on the <code>mono</code> package, and again we inherit the <code>autotools</code> class to make use of the <code>bitbake</code> <code>autotools</code> functionality.

Lastly we override <code>FILES_${PN}</code> which controls the installed files which are added to the main output package. <code>${libdir}</code> <code>${bindir}</code> are standard GNU variable naming conventions for installation paths. For details see [http://www.gnu.org/prep/standards/html_node/Directory-Variables.html here] and [https://www.sourceware.org/autobook/autobook/autobook_106.html here].

In this case we have made sure that the <code>helloworld</code> executable goes to <code>/usr/lib/helloworld/helloworld.exe</code> as does the <code>helloworldform.exe</code>.

It might seem quite strange to be installing the executable assemblies to the <code>/usr/lib</code> location, but this is in line with Mono application deployment recommendations [http://mono-project.com/Guidelines:Application_Deployment here].

We then install wrapper scripts to <code>/usr/bin</code> which can be called directly to run the respective examples. These scripts take the form

  #!/bin/sh
  exec @MONO@ @prefix@/lib/helloworld/@APP@.exe $MONO_EXTRA_ARGS "$@"

== Breakdown of an xbuild recipe ==

The <code>xbuild</code> recipe is similar to the <code>autotools</code> recipe above, excepting that we override a couple of methods to ensure <code>xbuild</code> runs as we wish it too

This recipe can be found [http://git.yoctoproject.org/cgit/cgit.cgi/meta-mono/tree/recipes-mono/mono-helloworld/mono-helloworld-xbuild_1.1.bb here].

First we include the definitions in the include file, and set the version specific checksums for the archive to be retrieved

 require mono-helloworld.inc
 SRC_URI[md5sum] = "79b0ba0044689789a54e3d55ec400fc0"
 SRC_URI[sha256sum] = "56388435f29ce94007155acc39593c900b6d3248a7f281e83ed2101a6da455f0"

Then we set our source directory which must be correct for <code>bitbake</code> to find extracted files from the retrieved archive

 REALPN = "mono-helloworld"
 S = "${WORKDIR}/${REALPN}-${PV}"

Now we override the compilation method to call <code>xbuild</code> to build a particular .NET configuration against the a .SLN file in the archive

 CONFIGURATION = "Debug"
 do_compile() {
         xbuild /p:Configuration=${CONFIGURATION} ${REALPN}_vs2010.sln
 }

Next we modify the installation method to make sure that the correct output files are installed and the executable scripts are modified to run the output assemblies

 do_install() {
         mkdir -p ${D}${bindir}
         mkdir -p ${D}${libdir}/helloworld
         mkdir -p ${D}${libdir}/helloworld/.debug  
         install -m 0755 ${S}/bin/${CONFIGURATION}/*.mdb ${D}${libdir}/helloworld/.debug
         install -m 0755 ${S}/bin/${CONFIGURATION}/*.exe ${D}${libdir}/helloworld
         install -m 0755 ${S}/script.in ${D}${bindir}/helloworld
         sed -i "s|@MONO@|mono|g" ${D}${bindir}/helloworld
         sed -i "s|@prefix@|/usr|g" ${D}${bindir}/helloworld
         sed -i "s|@APP@|helloworld|g" ${D}${bindir}/helloworld
         install -m 0755 ${S}/script.in ${D}${bindir}/helloworldform
         sed -i "s|@MONO@|mono|g" ${D}${bindir}/helloworldform
         sed -i "s|@prefix@|/usr|g" ${D}${bindir}/helloworldform
         sed -i "s|@APP@|helloworld|g" ${D}${bindir}/helloworldform
 }

Lastly we make sure that the .MDB debug files which are output are packaged correctly in the <code>-dbg</code> package. The other assemblies in <code>${libdir}</code> and <code>${bindir}</code> will be packaged correctly in the main output package by default

  FILES_${PN}-dbg += "${libdir}/helloworld/.debug/*"

For more details on check-sums, licenses and so forth, see [https://wiki.yoctoproject.org/wiki/Building_your_own_recipes_from_first_principles#Build_an_example_package_based_on_a_remote_source_archive Building your own recipes from first principles] and the [https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide Recipe & Style Patch Guide].

== Feedback ==

This is a living document. Please feel free to send comments, questions, corrections to Alex Lennon [mailto://ajlennon@dynamicdevices.co.uk here]