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.
• Note: Due to special permissions required in macOS, we don't recommend using ~/Documents (or any subdirectory thereof) for source code.

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 p7zip

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!

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

During the build you may see a provisioning error:

Could not find any available provisioning profiles for Xamarin.PreBuilt.iOS on iOS.

To find the cause of this error, run this following build variant:

    $ V=1 make -j8

In the build output, it will show all the provisioning profiles that it's trying and why it's rejecting them. If the build is rejecting them all, try the following:

• make a default iOS app in Xcode
• set the bundle identifier to com.xamarin.Xamarin-PreBuilt
• build and deploy the app

Now re-make and it should get past this part of the build.

Faster builds

• Install ccache to make rebuilding native code faster

    brew install ccache
  

• Enable automatic caching of downloaded files by setting the MACIOS_CACHE_DOWNLOADS variable:

    $ export MACIOS_CACHE_DOWNLOADS=1
    $ make all -j8 && make install -j8 
  

  This will save downloaded files to ~/Library/Caches/xamarin-macios, and use those copies instead of downloading them the next time they're needed. There is no automatic cache management, so you'll have to clean this directory out once in a while to avoid running out of disk space.

  The best way to ensure that files are always cached is to set the MACIOS_CACHE_DOWNLOADS variable in ~/.zshrc (if using zsh) or ~/.bashrc (if using bash).

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