-
Notifications
You must be signed in to change notification settings - Fork 507
Build & 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.
- 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 git@github.com: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.
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.
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.
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.
-
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).
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.
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
toxamarin-macios/_ios-build/Library/Frameworks/Xamarin.iOS.framework/Versions/git/bin
. - Copy
/Library/Frameworks/Xamarin.iOS.framework/Versions/Current/lib/mlaunch
toxamarin-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 executedmake install-system
from above,/Library/Frameworks/Xamarin.iOS.framework/Versions/Current
will point into thexamarin-macios/_ios-build
directory, and you won't find themlaunch
tool there. In that case, executels -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!
If you want to compile a custom Mono instead of using the prebuilt Mono binaries you need to do the following:
- Run
./configure --disable-packaged-mono
- Run
make world
to download+compile Mono from a custom submodule - Edit the local Mono in external/mono with your changes and build normally
- README
- xcode13.0 Binding Status
- xcode13.1 Binding Status
- xcode13.2 Binding Status
- xcode13.3 Binding Status
- xcode13.4 Binding Status
- xcode14.0 Binding Status
- xcode14.1 Binding Status
- xcode14.2 Binding Status
- xcode14.3 Binding Status
- xcode15.0 Binding Status
- xcode15.1 Binding Status
- xcode15.3 Binding Status
- xcode15.4 Binding Status
- xcode16.0 Binding Status