Build & Run

Build and Run

If you want to understand how our SDKs work, 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 https://github.com/dotnet/macios

You may want to run a branch that aligns with a specific release version. Each release version has a tag, the name of this tag can be found in the release notes.

Prerequisites

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

$ ./system-dependencies.sh --provision-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 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 SDKs 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 xip 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.

Configure

There is a configure script that can optionally be used to configure the build. By default, everything required for all platforms will be built. Run ./configure --help to see the various options.

Build & Install

Follow these steps to build the SDKs:

• Change directories to the root of the repository folders:

  $ cd macios

• Fetch dependencies and build everything:

  $ make all -j8 && make install -j8

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.

If you run into a problem you can't figure out, you can get a verbose build by executing this, and then ask in our Discord channel:

```shell
$ V=1 make -j8
```

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.