Switch to a different documentation area.

Xamarin - Documentation

iOS

change platform

  1. Xamarin
  2. iOS
  3. Advanced Topics
  4. Deep Dive
  5. mtouch

mtouch

iPhone applications are shipped as application bundles. These are directories with the extension .app that contain your code, data, configuration files and a manifest that the iPhone uses to learn about your application.

The process of turning a .NET executable into an application is mostly driven by the mtouch command, a tool that integrates many of the steps required to turn the application into a bundle. This tool is also used to launch your application in the simulator and to deploy the software to an actual iPhone or iPod Touch device.

Building

The mtouch command can compile your code in three different ways:

  • Compile for simulator testing.
  • Compile for device deployment.
  • Deploy your executable to the device.
  • Compile to source code, for integration with X-Code.

Building for the Simulator

When you get started, the most common used scenario will be for you to try out the application in the Simulator, so you will be using the mtouch -sim to compile the code into a simulator package. This is done like this:

 $ mtouch -sim Hello.app hello.exe

Building for the Device

To build software for the device you will build your application using the mtouch -dev option, additionally you need to provide the name of the certificate used to sign your application. The following shows how the application is built for the device:

$ mtouch -dev -c "iPhone Developer: Miguel de Icaza" foo.exe

In this particular case, we are using the "iPhone Developer: Miguel de Icaza" certificate to sign the application. This step is very important, or the physical device will refuse to load the application.

Running your Application

Launching on the Simulator

Launching on the simulator is very simple once you have an application bundle:

 $ mtouch -launchsim Hello.app

You will see some output like this:

Launching application
Application launched
PID: 98460
Press enter to terminate the application

It is strongly recommended that you also keep a log of the standard output and standard error files to assist in your debugging. The output of Console.WriteLine goes to stdout, and the output from Console.Error.WriteLine and any other runtime error messages goes to stderr.

To do this, use the --stdout and --stderr flags:

../../tools/mtouch/mtouch --launchsim=Hello.app --stdout=output --stderr=error

If your application fails, you can see the fiels output and error to diagnose the problem.

Deploying to a Device

To deploy to your device you need to provision your device as described in Apple's Managing Devices  document.  Once your device has been properly provisioned, you can use the mtouch command to deploy a compiled ".app" into your device.   You do this using this command:

 

 $ mtouch -installdev=MyApp.app

 

These steps are typically performed by MonoDevelop.

Reference

--cxx

Use when you are compiling applications and linking with C++ code. This forces your executable to bring in the C++ runtime.

--gcc_flags=FLAGS

If you are linking third party static libraries, or need to provide custom options to gcc you can use this flag and mtouch will pass the options thru to the final gcc compilation stage.  You can learn more about linking third party static libraries here.

For example:

-gcc_flags "-L${ProjectDir} -lAdMobNoThumb -force_load ${ProjectDir}/libAdMobNoThumb.a"
--debug=VALUE

Flag used to enable debugging of the specified MonoTouch framework libraries.

If you pass `all' as the value, it will generate a debugging build for all assemblies, otherwise it will only generate a debug build of the specified assemblies.   This flag can be specified multiple times.

All user code is compiled as debuggable.   The flag is only used to enable source code debugging on device for the specified MonoTouch framework assembly.

--listdev

mtouch will print a list of all connected devices to stdout

--llvm

Will compile the code using the LLVM backend instead of Mono's default compilation engine.

--logdev

mtouch will connect to the syslog of the first enumerated connected device and pipe it to stdout

--mapinject

This is an experimental new feature that potentially improves startup time by injecting a static constructor into each type with the method map that the runtime requires to interop with Objective-C.  In the normal execution path we scan the type for the [Export] attribute to build this map.

--nodebugtrack 

The simulator builds currently turn on tracking of object resurrection / use of zombie objects when running in the debugger.  This behaviour can be disabled with this flag.

--nolinkaway

The linker by default will remove code that can not be used on devices and will replace the generated code with a 'throw NotSupportException ("Linked away")' statement. In some very rare cases you might want to disable this behavior and force the linker to keep the code as-is. Use this flag in those rare cases.

--noregistrar

mtouch by default uses a static library initializer to register all the Objective-C class definitions with the ObjC runtime.  This option can be disabled forcing the old managed implementation to run with this option.

There are various other options available to control mtouch, you can get a list of them by running mtouch --help from the Unix commandline.

--sgen

Configures the application to use the generational garbage collector instead of the Boehm GC.

--thumb

When used with LLVM produces thumb code instead of regular ARM code.