Build & Run

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 [email protected]:xamarin/xamarin-macios.git

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.

Prerequisites

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

$ ./system-dependencies.sh --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 https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ 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/Xcode7.app. The recommended procedure is to download the corresponding Xcode dmg from Apple's Developer Center, extract Xcode.app to your system, and rename it before launching it the first time. Renaming Xcode.app 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.

Configure

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!

• 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

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.

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!