Mtouch

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.

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.

Debugging on the Simulator

Debugging on the simulator is currently limited to debugging at the GDB level. This debugging is described in Debugging with GDB. This means that it is mostly useful if you are debugging low-level operations or if you are familiar with Mono internals, it is not a complete managed debugger.

 $ mtouch -debugsim Hello.app

You will see some output like:

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

Open another terminal and launch gdb and type:

(gdb) attach 29558 <-- PID from above
Attaching to process 29558.
Reading symbols for shared libraries . done
0x8fe01010 in __dyld__dyld_start ()
(gdb) continue

Debugging on the Device

Debugging on the device is currently provided with the MonoDevelop's iPhone soft-debugger.   The soft debugger will help you debug managed code, but if you have unmanaged code, you might want to use XCode to debug your unmanaged libraries.

The mtouch commadn can help here, you can use mtouch to generate an XCode project file that you can load into XCode and debug from XCode using GDB.  This debugging is described in Debugging with GDB. This means that it is mostly useful if you are debugging low-level operations or if you are familiar with Mono internals, it is not a complete managed debugger.

 $ mtouch -xcode Hello -res MainWindow.xib -res Icon.png hello.exe

This command will generate a xcodeproject in the folder "Hello" containing the resources Icon.png and MainWindow.xib from your hello.exe, and open the project in xcode, you can then debug on the device via Xcode.

Additionally, if you run the code directly from MonoDevelop, you can switch to XCode's Organizer and select the device, and all of the output of Console.WriteLine and debugging information will be sent to that window.

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.

Extra options.

• --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.
• --gcc_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.
• --logdev: mtouch will connect to the syslog of the first enumerated connected device and pipe it to stdout
• --listdev: mtouch will print a list of all connected devices to stdout
• --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.