Skip to content

Build & Run

Alexander Köplinger edited this page Sep 24, 2019 · 7 revisions

Build and Run

If you want to understand how Xamarin.iOS or Xamarin.Mac works, or want to debug an issue, you'll want to get the source, build it, and run them locally.

Get the Source

Note: Building on Windows is not supported.

Clone the repository and its submodules:

$ git clone --recursive

You may want to run a specific branch that aligns with the current release versions of Xamarin.iOS. Each release version has a specific branch. A list of release branches are available on the Wiki.


Some of the dependencies can be provisioned with an included script:

$ ./ --provision-[xamarin-studio|mono|all]

Autoconf, automake, and libtool Use brew to install these tools. To install brew and all the tool dependencies:

$ ruby -e "$(curl -fsSL"
$ brew update
$ brew install libtool autoconf automake bison flex

CMake To install using brew:

$ brew install cmake

Xcode To build the Xamarin.iOS and Xamarin.Mac SDKs you need a certain version of Xcode. The build will tell you exactly which version you need. You can download the Xcode version you need from Apple's Developer Center (requires an Apple Developer account).

To ease development with different versions of the SDK that require different versions of Xcode, we require Xcode to be in a non-standard location (based on the Xcode version). For example, Xcode 7.0 must be installed in /Applications/ The recommended procedure is to download the corresponding Xcode dmg from Apple's Developer Center, extract to your system, and rename it before launching it the first time. Renaming after having launched it once may confuse Xcode, and strange errors start occurring.

Mono MDK You can download from the Mono Releases page. Also, the build will tell you if you need to update, and where to get it.

Visual Studio for Mac You can download from the Visual Studio for Mac homepage. Also, the build will tell you if you need to update, and where to get it.


There is a configure script that can optionally be used to configure the build. By default, everything required for both Xamarin.iOS and Xamarin.Mac will be built. If you prefer to use the defaults, skip this section and go right to Build & Install.

--disable-mac: Disable Mac-related parts. --disable-ios: Disable iOS-related parts. In both cases, the resulting build will contain both iOS and Mac bits because:

  • Parts of the iOS build depends on Mac parts (in particular mtouch uses Xamarin.Mac).
  • The class libraries build cannot be disabled because a very common error is to end up with code that only works/builds in either iOS or Mac.

--enable-ccache: Enables cached builds with ccache (default if ccache is found in the path). --disable-ccache: Disables cached builds with ccache, even if it is present. --disable-strip: If executables should be stripped or not. This makes it easier to debug native executables using lldb. --help: Show the help.

Build & Install

Follow these steps to build and install Xamarin.iOS and Xamarin.Mac:

  • Change directories to the root of the repository folders:

      $ cd xamarin-macios
  • Fetch dependencies and build everything:

      $ make world

This step can take a long time. Be patient!

If you run into problems and you've built the repo before, try make git-clean-all to ensure a clean state.

  • Make sure permissions are OK to install into system directories (this will ask for your password):

      $ make fix-install-permissions
  • Install on your machine:

      $ make install-system
  • Build again after any local changes

Don't use make world again to rebuild, because it resets dependencies and causes unnecessary rebuilds. Instead use the standard make all install (our Makefiles are parallel safe, which greatly speeds up the build):

    $ make all -j8 && make install -j8

Running Tests

Open the tests website by running:

    $ cd tests
    $ make runner

You'll see a listing of available tests split up by platforms, click "Run" next to one of the entries to run the tests.

Debugging Applications from Source

To install and launch applications to a simulator or device, a proprietary tool called mlaunch is required.

If you already have Xamarin.iOS installed, mlaunch can be copied from the install path. You will need to copy a file and directory.

  • Copy /Library/Frameworks/Xamarin.iOS.framework/Versions/Current/bin/mlaunch to xamarin-macios/_ios-build/Library/Frameworks/Xamarin.iOS.framework/Versions/git/bin.
  • Copy /Library/Frameworks/Xamarin.iOS.framework/Versions/Current/lib/mlaunch to xamarin-macios/_ios-build/Library/Frameworks/Xamarin.iOS.framework/Versions/git/lib.

Note: If working from an Xcode beta branch, there may be required changes to mlaunch. In this case, download and install the latest Xamarin.iOS package from Jenkins and follow the same steps to copy from that installation.
Note 2: If you already executed make install-system from above, /Library/Frameworks/Xamarin.iOS.framework/Versions/Current will point into the xamarin-macios/_ios-build directory, and you won't find the mlaunch tool there. In that case, execute ls -la /Library/Frameworks/Xamarin.iOS.framework/Versions and pick the exact version of Xamarin.iOS from there instead.

If you would like to debug source code on a device instead of a simulator, add -debug:all to your Project > Options > iOS Build > Additional mtouch arguments textbox for a device build configuration.

You can now step into the framework code using your local build while running Xamarin.iOS or Xamarin.Mac applications in Visual Studio for Mac!

Using a custom Mono built from source

If you want to compile a custom Mono instead of using the prebuilt Mono binaries you need to do the following:

  1. Run ./configure --disable-packaged-mono
  2. Run make world to download+compile Mono from a custom submodule
  3. Edit the local Mono in external/mono with your changes and build normally
Clone this wiki locally
You can’t perform that action at this time.