diff --git a/.gitignore b/.gitignore index 38eb68b12469..2903fcc30983 100644 --- a/.gitignore +++ b/.gitignore @@ -17,5 +17,4 @@ packages .DS_Store jenkins-results .vs - *.raw diff --git a/CODEOWNERS b/CODEOWNERS index 645f597cd585..33e33c03880c 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -28,12 +28,15 @@ /src/audiotoolbox.cs @dalexsoto /src/AudioUnit @dalexsoto /src/audiounit.cs @dalexsoto +/src/authenticationservices.cs @spouliot /src/AVFoundation @mandel-macaque @dalexsoto /src/avfoundation.cs @mandel-macaque @dalexsoto /src/AVKit @spouliot @dalexsoto /src/avkit.cs @spouliot @dalexsoto /src/CallKit @dalexsoto /src/callkit.cs @dalexsoto +/src/CarPlay @dalexsoto +/src/carplay.cs @dalexsoto /src/CFNetwork @spouliot /src/cfnetwork.cs @spouliot /src/CloudKit @mandel-macaque @@ -92,6 +95,10 @@ /src/homekit.cs @VincentDondain /src/iad.cs @spouliot /src/iAd.framework @spouliot +/src/identitylookup.cs @dalexsoto +/src/identitylookupui.cs @dalexsoto +/src/ituneslibrary.cs @mandel-macaque +/src/iTunesLibrary @mandel-macaque /src/ImageIO @spouliot @chamons /src/imageio.cs @spouliot @chamons /src/ImageKit @chamons @@ -124,6 +131,9 @@ /src/modelio.cs @VincentDondain /src/MultipeerConnectivity @spouliot /src/multipeerconnectivity.cs @spouliot +/src/naturallanguage.cs @mandel-macaque +/src/NaturalLanguage @mandel-macaque +/src/Network @migueldeicaza /src/NetworkExtension @spouliot /src/networkextension.cs @spouliot /src/NotificationCenter @spouliot diff --git a/Make.config b/Make.config index 002bc3b03b13..b469d38d3d9f 100644 --- a/Make.config +++ b/Make.config @@ -17,29 +17,17 @@ PACKAGE_HEAD_REV=$(shell git rev-parse HEAD) # # A release branch requires updating: # -# PACKAGE_HEAD_BRANCH (set to the release branch name, this shows up in the IDE's version information, as well as mtouch/mmp --version) # IOS_PACKAGE_VERSION (major/minor #) # MAC_PACKAGE_VERSION (major/minor #) # PACKAGE_VERSION_REV (set to 0 and increment for service releases or previews) # (and updating the same on master as well, to next version) # -# -# PACKAGE_HEAD_BRANCH determines the branch name (for wrench builds) that shows up in the -# IDE's version information, as well as mtouch/mmp --version and the AssemblyInformationalVersion -# for product assemblies. -# -# For developer builds, we check with git which branch is the current one (we can't do that -# on wrench, because wrench technically builds hashes, not branches) -# -# -PACKAGE_HEAD_BRANCH?=d15-9 -ifeq ($(CURRENT_BRANCH),) -ifeq ($(BUILD_REVISION),) +ifeq ($(BRANCH_NAME),) +# BRANCH_NAME is set in Jenkins, so this is for local builds. CURRENT_BRANCH:=$(shell git rev-parse --abbrev-ref HEAD) else -CURRENT_BRANCH:=$(PACKAGE_HEAD_BRANCH) -endif +CURRENT_BRANCH:=$(BRANCH_NAME) endif # TODO: reset to 0 after major/minor version bump (SRO) and increment for service releases and previews @@ -50,16 +38,20 @@ IOS_PRODUCT=Xamarin.iOS IOS_PACKAGE_NAME=Xamarin.iOS IOS_PACKAGE_NAME_LOWER=$(shell echo $(IOS_PACKAGE_NAME) | tr "[:upper:]" "[:lower:]") # NEVER customize IOS_PACKAGE_VERSION itself, other parts (mtouch, web updater) are using the IOS_PACKAGE_VERSION_* variables -IOS_PACKAGE_VERSION=11.16.$(PACKAGE_VERSION_REV).$(IOS_COMMIT_DISTANCE) +IOS_PACKAGE_VERSION=12.2.$(PACKAGE_VERSION_REV).$(IOS_COMMIT_DISTANCE) IOS_PACKAGE_VERSION_MAJOR=$(word 1, $(subst ., ,$(IOS_PACKAGE_VERSION))) IOS_PACKAGE_VERSION_MINOR=$(word 2, $(subst ., ,$(IOS_PACKAGE_VERSION))) -IOS_PACKAGE_VERSION_REV=$(PACKAGE_VERSION_REV) IOS_PACKAGE_VERSION_BUILD=$(IOS_COMMIT_DISTANCE) -IOS_PACKAGE_UPDATE_ID=$(shell printf "2%02d%02d%02d%03d" $(IOS_PACKAGE_VERSION_MAJOR) $(IOS_PACKAGE_VERSION_MINOR) $(IOS_PACKAGE_VERSION_REV) $(IOS_PACKAGE_VERSION_BUILD)) +IOS_PACKAGE_UPDATE_ID=$(shell printf "2%02d%02d%02d%03d" $(IOS_PACKAGE_VERSION_MAJOR) $(IOS_PACKAGE_VERSION_MINOR) $(PACKAGE_VERSION_REV) $(IOS_PACKAGE_VERSION_BUILD)) + +# Xcode version should have both a major and a minor version (even if the minor version is 0) +XCODE_VERSION=10.0 +XCODE_URL=http://xamarin-storage/bot-provisioning/xcodes/Xcode_10_GM_seed.xip +XCODE_DEVELOPER_ROOT=/Applications/Xcode10GM.app/Contents/Developer -XCODE_VERSION=9.4 -XCODE_URL=http://xamarin-storage/bot-provisioning/xcodes/Xcode_9.4.xip -XCODE_DEVELOPER_ROOT=/Applications/Xcode94.app/Contents/Developer +XCODE94_VERSION=9.4 +XCODE94_URL=http://xamarin-storage/bot-provisioning/xcodes/Xcode_9.4.xip +XCODE94_DEVELOPER_ROOT=/Applications/Xcode94.app/Contents/Developer # Minimum Mono version MIN_MONO_VERSION=5.14.0.136 @@ -69,7 +61,7 @@ MIN_MONO_URL=https://xamjenkinsartifact.azureedge.net/build-package-osx-mono/201 # Minimum Visual Studio version MIN_VISUAL_STUDIO_URL=https://download.visualstudio.microsoft.com/download/pr/11550896/783d2219a348f93b6988fb415951788a/VisualStudioForMac-Preview-7.4.0.985.dmg MIN_VISUAL_STUDIO_VERSION=7.4.0.985 -MAX_VISUAL_STUDIO_VERSION=7.5.99 +MAX_VISUAL_STUDIO_VERSION=7.7.99 # Minimum CMake version MIN_CMAKE_URL=https://cmake.org/files/v3.6/cmake-3.6.2-Darwin-x86_64.dmg @@ -85,11 +77,11 @@ MIN_OSX_BUILD_VERSION=10.13 MIN_OSX_VERSION_FOR_IOS=10.11 MIN_OSX_VERSION_FOR_MAC=10.11 -IOS_SDK_VERSION=11.4 +IOS_SDK_VERSION=12.0 # When bumping OSX_SDK_VERSION also update the macOS version where we execute on bots in jenkins/Jenkinsfile (in the 'node' element) -OSX_SDK_VERSION=10.13 -WATCH_SDK_VERSION=4.3 -TVOS_SDK_VERSION=11.4 +OSX_SDK_VERSION=10.14 +WATCH_SDK_VERSION=5.0 +TVOS_SDK_VERSION=12.0 MIN_IOS_SDK_VERSION=6.0 MIN_OSX_SDK_VERSION=10.7 @@ -118,10 +110,14 @@ else APPLETLS_DEFINES = -d:XAMARIN_APPLETLS endif -XCODE_MAC_SDKROOT=$(XCODE_DEVELOPER_ROOT)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX$(OSX_SDK_VERSION).sdk +XCODE_MAC_SDKROOT=$(XCODE_DEVELOPER_ROOT)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk +XCODE94_MAC_SDKROOT=$(XCODE94_DEVELOPER_ROOT)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk + +MAC_CC=$(CCACHE)$(XCODE_DEVELOPER_ROOT)/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang -isysroot $(XCODE_MAC_SDKROOT) -mmacosx-version-min=$(MIN_OSX_VERSION_FOR_MAC) -stdlib=libc++ +MAC_CXX=$(CCACHE)$(XCODE_DEVELOPER_ROOT)/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang++ -isysroot $(XCODE_MAC_SDKROOT) -mmacosx-version-min=$(MIN_OSX_VERSION_FOR_MAC) -stdlib=libc++ -MAC_CC=$(CCACHE)$(XCODE_DEVELOPER_ROOT)/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang -isysroot $(XCODE_MAC_SDKROOT) -mmacosx-version-min=$(MIN_OSX_VERSION_FOR_MAC) -MAC_CXX=$(CCACHE)$(XCODE_DEVELOPER_ROOT)/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang++ -isysroot $(XCODE_MAC_SDKROOT) -mmacosx-version-min=$(MIN_OSX_VERSION_FOR_MAC) +MAC32_CC=$(CCACHE)$(XCODE94_DEVELOPER_ROOT)/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang -isysroot $(XCODE94_MAC_SDKROOT) -mmacosx-version-min=$(MIN_OSX_VERSION_FOR_MAC) -stdlib=libc++ +MAC32_CXX=$(CCACHE)$(XCODE94_DEVELOPER_ROOT)/Toolchains/XcodeDefault.xctoolchain/usr/bin/clang++ -isysroot $(XCODE94_MAC_SDKROOT) -mmacosx-version-min=$(MIN_OSX_VERSION_FOR_MAC) -stdlib=libc++ # This is the temporary directory where the various builds are installed BUILD_DESTDIR=$(abspath $(TOP)/builds/install) @@ -171,7 +167,7 @@ endif SIMULATOR_SDK=$(XCODE_DEVELOPER_ROOT)/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator$(IOS_SDK_VERSION).sdk -OBJC_CFLAGS=-ObjC++ -std=c++0x -fno-exceptions +OBJC_CFLAGS=-ObjC++ -std=c++0x -fno-exceptions -stdlib=libc++ COMMON_SIMULATOR_CFLAGS=-mios-simulator-version-min=$(MIN_IOS_SDK_VERSION) -isysroot $(SIMULATOR_SDK) $(CFLAGS) -g $(IOS_COMMON_DEFINES) SIMULATOR86_CFLAGS=$(COMMON_SIMULATOR_CFLAGS) -arch i386 @@ -264,7 +260,7 @@ MAC_PRODUCT=Xamarin.Mac MAC_PACKAGE_NAME=xamarin.mac MAC_PACKAGE_NAME_LOWER=$(shell echo $(MAC_PACKAGE_NAME) | tr "[:upper:]" "[:lower:]") -MAC_PACKAGE_VERSION=4.8.$(PACKAGE_VERSION_REV).$(MAC_COMMIT_DISTANCE) +MAC_PACKAGE_VERSION=5.0.$(PACKAGE_VERSION_REV).$(MAC_COMMIT_DISTANCE) MAC_PACKAGE_VERSION_MAJOR=$(word 1, $(subst ., ,$(MAC_PACKAGE_VERSION))) MAC_PACKAGE_VERSION_MINOR=$(word 2, $(subst ., ,$(MAC_PACKAGE_VERSION))) MAC_PACKAGE_VERSION_REV=$(PACKAGE_VERSION_REV) diff --git a/Versions-ios.plist.in b/Versions-ios.plist.in index 9c402277d2b9..8223bfb8e333 100644 --- a/Versions-ios.plist.in +++ b/Versions-ios.plist.in @@ -30,6 +30,7 @@ 11.2 11.3 11.4 + 12.0 tvOS @@ -44,6 +45,7 @@ 11.2 11.3 11.4 + 12.0 watchOS @@ -58,6 +60,7 @@ 4.1 4.2 4.3 + 5.0 RecommendedXcodeVersion diff --git a/Versions-mac.plist.in b/Versions-mac.plist.in index 9b4181cbd4b2..7f533d3a0da0 100644 --- a/Versions-mac.plist.in +++ b/Versions-mac.plist.in @@ -15,6 +15,7 @@ 10.11 10.12 10.13 + 10.14 RecommendedXcodeVersion diff --git a/builds/Makefile b/builds/Makefile index bf872c192f17..a070e85791d2 100644 --- a/builds/Makefile +++ b/builds/Makefile @@ -208,9 +208,10 @@ MAC_TARGETS = \ $(MAC_DESTDIR)/Library/Frameworks/Xamarin.Mac.framework/Versions/Current \ $(MAC_DIRECTORIES) \ +# $(3): specific xcode path define MacBuildTemplate $(2)_CPPFLAGS = \ - -isysroot $(XCODE_MAC_SDKROOT) \ + -isysroot $(5) \ -mmacosx-version-min=$(MIN_OSX_SDK_VERSION) $(2)_CFLAGS = -O2 -arch $(1) $(2)_CXXFLAGS = -O2 -arch $(1) @@ -237,9 +238,9 @@ $(2)_CONFIGURE_ENVIRONMENT = \ CFLAGS="$$($(2)_CFLAGS)" \ CXXFLAGS="$$($(2)_CXXFLAGS)" \ LDFLAGS="$$($(2)_LDFLAGS)" \ - CC="$(MAC_CC)" \ - CXX="$(MAC_CXX)" \ - DEVELOPER_DIR="$(XCODE_DEVELOPER_ROOT)" \ + CC="$(MAC$(4)_CC)" \ + CXX="$(MAC$(4)_CXX)" \ + DEVELOPER_DIR="$(3)" \ setup:: setup-$(2) @@ -261,8 +262,8 @@ $(BUILD_DESTDIR)/mono-$(2): mono-wrapper.in .stamp-configure-$(2) | $(BUILD_DEST build-$(2): .stamp-build-$(2) endef -$(eval $(call MacBuildTemplate,i386,mac32)) -$(eval $(call MacBuildTemplate,x86_64,mac64)) +$(eval $(call MacBuildTemplate,i386,mac32,$(XCODE94_DEVELOPER_ROOT),32,$(XCODE94_MAC_SDKROOT))) +$(eval $(call MacBuildTemplate,x86_64,mac64,$(XCODE_DEVELOPER_ROOT),,$(XCODE_MAC_SDKROOT))) $(MONO_PATH)/mcs/class/lib/%: .stamp-build-tools64; @true @@ -1548,6 +1549,7 @@ offsets-tool: $(MONO_PATH)/tools/offsets-tool/MonoAotOffsetsDumper.exe # $(2): llvm (llvm32 or llvm64) # $(3): cross compiler executable (arm-darwin-mono-sgen) # $(4): cross compiler executable generated by mono sdk +# $(5): specific xcode path ## define iOSCrossTemplate @@ -1564,7 +1566,7 @@ endif endif .stamp-build-$(1): .stamp-build-llvm $(MONO_PATH)/configure $(MONO_PATH)/tools/offsets-tool/MonoAotOffsetsDumper.exe $(MONO_DEPENDENCIES) $(SDK_CONFIG) - $(MAKE) -C $(SDK_BUILDDIR) package-ios-$(1) $(SDK_ARGS) + $(MAKE) -C $(SDK_BUILDDIR) package-ios-$(1) $(SDK_ARGS) $(if $(5), XCODE_DIR=$(5)) $(Q) touch $$@ build-$(1): .stamp-build-$(1) @@ -1585,6 +1587,6 @@ clean-$(1): $(SDK_CONFIG) endef -$(eval $(call iOSCrossTemplate,cross32,llvm32,arm-darwin-mono-sgen,arm-darwin-mono-sgen)) +$(eval $(call iOSCrossTemplate,cross32,llvm32,arm-darwin-mono-sgen,arm-darwin-mono-sgen,$(XCODE94_DEVELOPER_ROOT))) $(eval $(call iOSCrossTemplate,cross64,llvm64,arm64-darwin-mono-sgen,aarch64-darwin-mono-sgen)) -$(eval $(call iOSCrossTemplate,crosswatch,llvm32,armv7k-unknown-darwin-mono-sgen,armv7k-unknown-darwin-mono-sgen)) +$(eval $(call iOSCrossTemplate,crosswatch,llvm32,armv7k-unknown-darwin-mono-sgen,armv7k-unknown-darwin-mono-sgen,$(XCODE94_DEVELOPER_ROOT))) diff --git a/docs/website/Makefile b/docs/website/Makefile index dc8a04388b56..2e3fc19662aa 100644 --- a/docs/website/Makefile +++ b/docs/website/Makefile @@ -1,21 +1,23 @@ TOP=../../.. -WEBSITE_DOCS ?= $(TOP)/documentation +WEBSITE_DOCS ?= $(TOP)/xamarin-docs-pr XAMARIN_ANALYSIS ?=$(TOP)/xamarin-analysis/shared/Xamarin.Analysis XAMARIN_ANALYSIS_DOC = xamarin-analysis-doc-tool/bin/Debug all: xamarin-analysis-doc - cp mtouch-errors.md $(WEBSITE_DOCS)/guides/ios/troubleshooting/mtouch-errors/index.md - cp binding_objc_libs.md $(WEBSITE_DOCS)/guides/cross-platform/macios/binding/objective-c-libraries/index.md - cp binding_types_reference_guide.md $(WEBSITE_DOCS)/guides/cross-platform/macios/binding/binding-types-reference/index.md - cp xamarin-ios-analysis.md $(WEBSITE_DOCS)/guides/ios/troubleshooting/xamarin-ios-analysis/index.md - cp optimizations.md $(WEBSITE_DOCS)/guides/cross-platform/macios/build-optimizations/index.md + cp mtouch-errors.md $(WEBSITE_DOCS)/docs/ios/troubleshooting/mtouch-errors.md + cp mmp-errors.md $(WEBSITE_DOCS)/docs/mac/troubleshooting/mmp-errors.md + cp binding_objc_libs.md $(WEBSITE_DOCS)/docs/cross-platform/macios/binding/objective-c-libraries.md + cp binding_types_reference_guide.md $(WEBSITE_DOCS)/docs/cross-platform/macios/binding/binding-types-reference.md + cp xamarin-ios-analysis.md $(WEBSITE_DOCS)/ios/troubleshooting/xamarin-ios-analysis.md + cp optimizations.md $(WEBSITE_DOCS)/docs/cross-platform/macios/optimizations.md diff: - -diff -u $(WEBSITE_DOCS)/guides/ios/troubleshooting/mtouch-errors/index.md mtouch-errors.md - -diff -u $(WEBSITE_DOCS)/guides/cross-platform/macios/binding/objective-c-libraries/index.md binding_objc_libs.md - -diff -u $(WEBSITE_DOCS)/guides/cross-platform/macios/binding/binding-types-reference/index.md binding_types_reference_guide.md - -diff -u $(WEBSITE_DOCS)/guides/ios/troubleshooting/xamarin-ios-analysis/index.md xamarin-ios-analysis.md - -diff -u $(WEBSITE_DOCS)/guides/cross-platform/macios/build-optimizations/index.md optimizations.md + -diff -u $(WEBSITE_DOCS)/docs/ios/troubleshooting/mtouch-errors.md mtouch-errors.md + -diff -u $(WEBSITE_DOCS)/docs/mac/troubleshooting/mmp-errors.md mmp-errors.md + -diff -u $(WEBSITE_DOCS)/docs/cross-platform/macios/binding/objective-c-libraries.md binding_objc_libs.md + -diff -u $(WEBSITE_DOCS)/docs/cross-platform/macios/binding/binding-types-reference.md binding_types_reference_guide.md + -diff -u $(WEBSITE_DOCS)/docs/ios/troubleshooting/xamarin-ios-analysis.md xamarin-ios-analysis.md + -diff -u $(WEBSITE_DOCS)/docs/cross-platform/macios/optimizations.md optimizations.md xamarin-analysis-doc: msbuild xamarin-analysis-doc-tool/xamarin-analysis-doc.sln diff --git a/docs/website/binding_objc_libs.md b/docs/website/binding_objc_libs.md index 40e190b5e9d2..9f8c7974a99e 100644 --- a/docs/website/binding_objc_libs.md +++ b/docs/website/binding_objc_libs.md @@ -1,15 +1,14 @@ --- -id: 8A832A76-A770-1A7C-24BA-B3E6F57617A0 -title: Binding Objective-C Libraries -samplecode: - - title: "Binding Sample" - url: /samples/BindingSample/ -dateupdated: 2017-06-26 +title: "Binding Objective-C libraries" +ms.prod: xamarin +ms.assetid: 8A832A76-A770-1A7C-24BA-B3E6F57617A0 +ms.technology: xamarin-cross-platform +author: bradumbaugh +ms.author: brumbaug +ms.date: 03/06/2018 --- -[//]: # (The original file resides under https://github.com/xamarin/xamarin-macios/tree/master/docs/website/) -[//]: # (This allows all contributors (including external) to submit, using a PR, updates to the documentation that match the tools changes) -[//]: # (Modifications outside of xamarin-macios/master will be lost on future updates) +# Binding Objective-C libraries When working with Xamarin.iOS or Xamarin.Mac, you might encounter cases where you want to consume a third-party Objective-C library. In those situations, you @@ -19,16 +18,14 @@ use to bring the iOS and Mac APIs to C#. This document describes how to bind Objective-C APIs, if you are binding just C APIs, you should use the standard .NET mechanism for -this, [the P/Invoke framework](http://mono-project.com/Dllimport). +this, [the P/Invoke framework](http://www.mono-project.com/docs/advanced/pinvoke/). Details on how to statically link a C library are available on the -[Linking Native Libraries](/guides/ios/advanced_topics/native_interop) +[Linking Native Libraries](~/ios/platform/native-interop.md) page. -See our companion [Binding Types Reference -Guide](/guides/cross-platform/macios/binding/binding-types-reference/). +See our companion [Binding Types Reference Guide](~/cross-platform/macios/binding/binding-types-reference.md). Additionally, if you want to learn more about what happens under the hood, check our -[Binding Overview](/guides/cross-platform/macios/binding/overview/) -page. +[Binding Overview](~/cross-platform/macios/binding/overview.md) page. Bindings can be built for both iOS and Mac libraries. This page describes how to work on an iOS binding, however @@ -40,36 +37,31 @@ You can use the [iOS Binding Sample](https://github.com/xamarin/monotouch-samples/tree/master/BindingSample) project to experiment with bindings. -# Getting Started + -[[ide name="xs"]] +## Getting started +# [Visual Studio for Mac](#tab/vsmac) The easiest way to create a binding is to create a Xamarin.iOS Binding Project. -You can do this from Xamarin Studio on Mac by selecting the project type, +You can do this from Visual Studio for Mac by selecting the project type, **iOS > Library > Bindings Library**: +[![](objective-c-libraries-images/00-sml.png "Do this from Visual Studio for Mac by selecting the project type, iOS Library Bindings Library")](objective-c-libraries-images/00.png#lightbox) -[![](Images/00-sml.png "Do this from Xamarin Studio on Mac by selecting the project type, iOS Library Bindings Library")](Images/00.png) - - -[[/ide]] - -[[ide name="vs"]] - +# [Visual Studio](#tab/vswin) The easiest way to create a binding is to create a Xamarin.iOS Binding Project. You can do this from Visual Studio on Windows by selecting the project type, **Visual C# > iOS > Bindings Library (iOS)**: +[![](objective-c-libraries-images/00vs-sml.png "iOS Bindings Library iOS")](objective-c-libraries-images/00vs.png#lightbox) -[![](Images/00VS-sml.png "iOS Bindings Library iOS")](Images/00VS.png) - -> ⚠️ Note: Binding Projects for **Xamarin.Mac** are only supported in +> [!IMPORTANT] +> Note: Binding Projects for **Xamarin.Mac** are only supported in > Visual Studio for Mac. - -[[/ide]] +----- The generated project contains a small template that you can edit, it contains two files: `ApiDefinition.cs` and `StructsAndEnums.cs`. @@ -84,7 +76,8 @@ definitions that are required by the interfaces and delegates. This includes enumeration values and structures that your code might use. -# Binding an API + +## Binding an API To do a comprehensive binding, you will want to understand the Objective-C API definition and familiarize yourself with the .NET Framework Design @@ -98,7 +91,7 @@ contract between C# and Objective-C is. For example, this is a trivial api file for a library: -``` +```csharp using Foundation; namespace Cocos2D { @@ -130,7 +123,7 @@ three arguments. An in-depth discussion of the format of the API file and the attributes that you can use is covered in the [API definition -file](/guides/ios/advanced_topics/binding_objective-c/binding_objc_libs/#The_API_definition_file) +file](~/cross-platform/macios/binding/objective-c-libraries.md#The_API_definition_file) section below. To produce a complete binding, you will typically deal with four @@ -141,13 +134,12 @@ components: - Optional: extra sources that might expand the generated binding, or provide a more C# friendly API (any C# files that you add to the project). - The native library that you are binding. - This chart shows the relationship between the files: - [ ![](Images/Screen_Shot_2012-02-08_at_3.33.07_PM.png "This chart shows the relationship between the files")](Images/Screen_Shot_2012-02-08_at_3.33.07_PM.png) + [![](objective-c-libraries-images/screen-shot-2012-02-08-at-3.33.07-pm.png "This chart shows the relationship between the files")](objective-c-libraries-images/screen-shot-2012-02-08-at-3.33.07-pm.png#lightbox) -The API Definition file: will only contain namespaces and interface -definitions (with any members that an interface can contain) and +The API Definition file will only contain namespaces and interface +definitions (with any members that an interface can contain), and should not contain classes, enumerations, delegates or structs. The API definition file is merely the contract that will be used to generate the API. @@ -158,7 +150,7 @@ should be hosted on a separate file, in the example above the file and should be hosted in a separate file, for example `StructsAndEnums.cs`: -``` +```csharp public enum CameraMode { FlyOver, Back, Follow } @@ -179,7 +171,7 @@ file. Notice that you will be using partial classes as these augment the partial classes that are generated from the combination of the `ApiDefinition.cs` and the `StructsAndEnums.cs` core binding: -``` +```csharp public partial class Camera { // Provide a ToString method public override string ToString () @@ -197,24 +189,27 @@ project, either by dragging and dropping the native library from Finder onto the project in the solution explorer, or by right-clicking the project and choosing **Add** > **Add Files** to select the native library. Native libraries by convention start with the word "lib" and end with -the extension ".a". When you do this, Xamarin Studio will add two -files: the `.a` file and an automatically populated C# file that +the extension ".a". When you do this, Visual Studio for Mac will add two +files: the .a file and an automatically populated C# file that contains information about what the native library contains: - [ ![](Images/Screen_Shot_2012-02-08_at_3.45.06_PM.png "Native libraries by convention start with the word lib and end with the extension .a")](Images/Screen_Shot_2012-02-08_at_3.45.06_PM.png) + [![](objective-c-libraries-images/screen-shot-2012-02-08-at-3.45.06-pm.png "Native libraries by convention start with the word lib and end with the extension .a")](objective-c-libraries-images/screen-shot-2012-02-08-at-3.45.06-pm.png#lightbox) The contents of the `libMagicChord.linkwith.cs` file has information about how this library can be used and instructs your IDE to package this binary into the resulting DLL file: -``` +```csharp using System; using ObjCRuntime; [assembly: LinkWith ("libMagicChord.a", SmartLink = true, ForceLoad = true)] ``` -Full details about how to use the LinkWith attribute are documented in our [Binding Types Reference Guide](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide/). +Full details about how to use the +[`[LinkWith]`](~/cross-platform/macios/binding/binding-types-reference.md#LinkWithAttribute) +attribute are documented in the +[Binding Types Reference Guide](~/cross-platform/macios/binding/binding-types-reference.md). Now when you build the project you will end up with a `MagicChords.dll` file that contains both the binding and the native library. You can distribute this @@ -224,14 +219,13 @@ Sometimes you might find that you need a few enumeration values, delegate definitions or other types. Do not place those in the API definitions file, as this is merely a contract - - + -# The API definition file +## The API definition file The API definition file consists of a number of interfaces. The interfaces in the API definition will be turned into a class declaration and they must be -decorated with the [[BaseType]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#BaseTypeAttribute) attribute to specify the base class for the class. +decorated with the [`[BaseType]`](~/cross-platform/macios/binding/binding-types-reference.md#BaseTypeAttribute) attribute to specify the base class for the class. You might be wondering why we did not use classes instead of interfaces for the contract definition. We picked interfaces because @@ -244,18 +238,20 @@ we had to resort to decorating various parts of the contract with attributes to drive the binding. -## Binding Methods + +### Binding methods The simplest binding you can do is to bind a method. Just declare a method in the interface with the C# naming conventions and decorate the method with the -[[Export]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#ExportAttribute) -attribute. The [Export] attribute is what links your C# name with the -Objective-C name in the Xamarin.iOS runtime. The parameter of the -Export attribute is the name of the Objective-C selector, some -examples: - -``` +[`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) +attribute. The [`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) +attribute is what links your C# name with the Objective-C name in the +Xamarin.iOS runtime. The parameter of the +[`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) +attribute is the name of the Objective-C selector. Some examples: + +```csharp // A method, that takes no arguments [Export ("refresh")] void Refresh (); @@ -270,9 +266,10 @@ void Draw (string text, nint column, nint row); ``` The above samples show how you can bind instance methods. To bind static -methods, you must use the `[Static]` attribute, like this: +methods, you must use the [`[Static]`](~/cross-platform/macios/binding/binding-types-reference.md#StaticAttribute) +attribute, like this: -``` +```csharp // A static method, that takes no arguments [Static, Export ("refresh")] void Beep (); @@ -281,37 +278,38 @@ void Beep (); This is required because the contract is part of an interface, and interfaces have no notion of static vs instance declarations, so it is necessary once again to resort to attributes. If you want to hide a particular method from the -binding, you can decorate the method with the [[Internal]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#InternalAttribute) attribute. +binding, you can decorate the method with the [`[Internal]`](~/cross-platform/macios/binding/binding-types-reference.md#InternalAttribute) attribute. The `btouch-native` command will introduce checks for reference parameters to not be null. If you want to allow null values for a particular parameter, use the -[[NullAllowed]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#NullAllowedAttribute) +[`[NullAllowed]`](~/cross-platform/macios/binding/binding-types-reference.md#NullAllowedAttribute) attribute on the parameter, like this: -``` +```csharp [Export ("setText:")] string SetText ([NullAllowed] string text); ``` -When exporting a reference type, with the `[Export]` keyword you can also -specify the allocation semantics. This is necessary to ensure that no data is +When exporting a reference type, with the [`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) +keyword you can also specify the allocation semantics. This is necessary to ensure that no data is leaked. -## Binding Properties + +### Binding properties Just like methods, Objective-C properties are bound using the -[[Export]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide/#ExportAttribute) +[`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) attribute and map directly to C# properties. Just like methods, properties can be decorated with the -[[Static]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide/#StaticAttribute) +[`[Static]`](~/cross-platform/macios/binding/binding-types-reference.md#StaticAttribute) and the -[[Internal]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#InternalAttribute) +[`[Internal]`](~/cross-platform/macios/binding/binding-types-reference.md#InternalAttribute) attributes. -When you use the `[Export]` attribute on a property under the covers -btouch-native actually binds two methods: the getter and the setter. The name +When you use the [`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) +attribute on a property under the covers btouch-native actually binds two methods: the getter and the setter. The name that you provide to export is the **basename** and the the setter is computed by prepending the word "set", turning the first letter of the **basename** into upper case and making the selector take an @@ -321,16 +319,17 @@ actually binds the "label" and "setLabel:" Objective-C methods. Sometimes the Objective-C properties do not follow the pattern described above and the name is manually overwritten. In those cases you can control the way that the binding is generated by using the -`[Bind]` attribute on the getter or setter, for example: +[`[Bind]`](~/cross-platform/macios/binding/binding-types-reference.md#BindAttribute) +attribute on the getter or setter, for example: -``` +```csharp [Export ("menuVisible")] bool MenuVisible { [Bind ("isMenuVisible")] get; set; } ``` This then binds "isMenuVisible" and "setMenuVisible:". Optionally, a property can be bound using the following syntax: -``` +```csharp [Category, BaseType(typeof(UIView))] interface UIView_MyIn { @@ -344,40 +343,42 @@ interface UIView_MyIn Where the getter and setter are explicitly defined as in the `name` and `setName` bindings above. -In addition to support for static properties using `[Static]`, you can +In addition to support for static properties using +[`[Static]`](~/cross-platform/macios/binding/binding-types-reference.md#StaticAttribute), you can decorate thread-static properties with -[[IsThreadStatic]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#IsThreadStaticAttribute), +[`[IsThreadStatic]`](~/cross-platform/macios/binding/binding-types-reference.md#IsThreadStaticAttribute), for example: -``` +```csharp [Export ("currentRunLoop")][Static][IsThreadStatic] NSRunLoop Current { get; } ``` Just like methods allow some parameters to be flagged with -[[NullAllowed]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#NullAllowedAttribute), +[`[NullAllowed]`](~/cross-platform/macios/binding/binding-types-reference.md#NullAllowedAttribute), you can apply -[[NullAllowed]](//guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#NullAllowedAttribute) +[`[NullAllowed]`](~/cross-platform/macios/binding/binding-types-reference.md#NullAllowedAttribute) to a property to indicate that null is a valid value for the property, for example: -``` +```csharp [Export ("text"), NullAllowed] string Text { get; set; } ``` -The [[NullAllowed]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#NullAllowedAttribute) parameter can also be specified directly on the setter: +The [`[NullAllowed]`](~/cross-platform/macios/binding/binding-types-reference.md#NullAllowedAttribute) +parameter can also be specified directly on the setter: -``` +```csharp [Export ("text")] string Text { get; [NullAllowed] set; } ``` -### Caveats of Binding Custom Controls +#### Caveats of binding custom controls The following caveats should be considered when setting up the binding for a custom control: -1. **Binding properties must be static** - When defining the binding of properties, the `Static` attribute must be used. +1. **Binding properties must be static** - When defining the binding of properties, the [`[Static]`](~/cross-platform/macios/binding/binding-types-reference.md#StaticAttribute) attribute must be used. 2. **Property names must match exactly** - The name used to bind the property must match the name of the property in the custom control exactly. 3. **Property types must match exactly** - The variable type used to bind the property must match the type of the property in the custom control exactly. 4. **Breakpoints and the getter/setter** - Breakpoints placed in the getter or setter methods of the property will never be hit. @@ -385,32 +386,32 @@ The following caveats should be considered when setting up the binding for a cus Failure to observe any of the above listed caveats can result in the binding silently failing at runtime. - -### Objective-C Mutable Pattern and Properties + +#### Objective-C mutable pattern and properties -Objective-C frameworks use an idiom where some classes are -immutable with a mutable subclass. For example `NSString` is -the immutable version, while `NSMutableString` is the subclass -that allows mutation. +Objective-C frameworks use an idiom where some classes are immutable with +a mutable subclass. For example `NSString` is the immutable version, +while `NSMutableString` is the subclass that allows mutation. -In those classes it is common to see the immutable base -class contain properties with a getter, but no setter. And -for the mutable version to introduce the setter. Since this -is not really possible with C#, we had to map this idiom into -an idiom that would work with C#. +In those classes it is common to see the immutable base class contain +properties with a getter, but no setter. And for the mutable version to +introduce the setter. Since this is not really possible with C#, we had +to map this idiom into an idiom that would work with C#. -The way that this is mapped to C# is by adding both the -getter and the setter on the base class, but flagging the -setter with a `[NotImplemented]` attribute. +The way that this is mapped to C# is by adding both the getter and the +setter on the base class, but flagging the setter with a +[`[NotImplemented]`](~/cross-platform/macios/binding/binding-types-reference.md#NotImplementedAttribute) +attribute. -Then, on the mutable subclass, you use the `[Override]` attribute on the -property to ensure that the property is actually overriding the -parent's behavior. +Then, on the mutable subclass, you use the +[`[Override]`](~/cross-platform/macios/binding/binding-types-reference.md#OverrideAttribute) +attribute on the property to ensure that the property is actually overriding +the parent's behavior. Example: -``` +```csharp [BaseType (typeof (NSObject))] interface MyTree { string Name { get; [NotImplemented] set; } @@ -423,12 +424,11 @@ interface MyMutableTree { } ``` - + +### Binding constructors -## Binding Constructors - -The **btouch-native** tool will automatically generate fours +The `btouch-native` tool will automatically generate fours constructors in your class, for a given class `Foo`, it generates: - `Foo ()`: the default constructor (maps to Objective-C's "init" constructor) @@ -436,28 +436,26 @@ constructors in your class, for a given class `Foo`, it generates: - `Foo (IntPtr handle)`: the constructor for handle-based creation, this is invoked by the runtime when the runtime needs to expose a managed object from an unmanaged object. - `Foo (NSEmptyFlag)`: this is used by derived classes to prevent double initialization. - For constructors that you define, they need to be declared using the following signature inside the Interface definition: they must return an `IntPtr` value and the name of the method should be Constructor. For example to bind the `initWithFrame:` constructor, this is what you would use: -``` +```csharp [Export ("initWithFrame:")] IntPtr Constructor (CGRect frame); ``` - + - -## Binding Protocols +### Binding protocols As described in the API design document, in the section [discussing -Models and Protocols](/guides/ios/advanced_topics/api_design#Models), +Models and Protocols](~/ios/internals/api-design/index.md#Models), Xamarin.iOS maps the Objective-C protocols into classes that have been flagged with the -[[Model]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#Model_Definitions) +[`[Model]`](~/cross-platform/macios/binding/binding-types-reference.md#ModelAttribute) attribute. This is typically used when implementing Objective-C delegate classes. @@ -467,7 +465,7 @@ is that the delegate class might have one or more optional methods. For example consider the `UIKit` class `UIAccelerometerDelegate`, this is how it is bound in Xamarin.iOS: -``` +```csharp [BaseType (typeof (NSObject))] [Model][Protocol] interface UIAccelerometerDelegate { @@ -479,7 +477,7 @@ interface UIAccelerometerDelegate { Since this is an optional method on the definition for `UIAccelerometerDelegate` there is nothing else to do. But if there was a required method on the protocol, you should add the -[[Abstract]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#AbstractAttribute) +[`[Abstract]`](~/cross-platform/macios/binding/binding-types-reference.md#AbstractAttribute) attribute to the method. This will force the user of the implementation to actually provide a body for the method. @@ -489,18 +487,18 @@ messages. This is typically done in Objective-C by assigning to the methods in the protocol. The convention in Xamarin.iOS is to support both the Objective-C -loosely coupled style where any instance of an `NSObject` can be -assigned to the delegate, and to also expose a strongly typed version -of it. For this reason, we typically provide both a "Delegate" -property that is strongly typed and a "WeakDelegate" that is loosely -typed. We usually bind the loosely typed version with Export, and we -use the -[[Wrap]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#WrapAttribute) -attribute to provide the strongly typed version. +loosely-coupled style where any instance of an `NSObject` can be +assigned to the delegate, and to also expose a strongly-typed version +of it. For this reason, we typically provide both a `Delegate` +property that is strongly typed and a `WeakDelegate` that is +loosely typed. We usually bind the loosely-typed version with +[`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute), +and we use the [`[Wrap]`](~/cross-platform/macios/binding/binding-types-reference.md#WrapAttribute) +attribute to provide the strongly-typed version. This shows how we bound the `UIAccelerometer` class: -``` +```csharp [BaseType (typeof (NSObject))] interface UIAccelerometer { [Static] [Export ("sharedAccelerometer")] @@ -517,7 +515,7 @@ interface UIAccelerometer { } ``` - + **New in MonoTouch 7.0** @@ -534,12 +532,13 @@ Studio editor allows developers to implement protocol methods without having to use the separate subclasses of the previous abstract model classes. -Any definition that contains the `[Protocol]` attribute will actually +Any definition that contains the +[`[Protocol]`](~/cross-platform/macios/binding/binding-types-reference.md#ProtocolAttribute) attribute will actually generate three supporting classes that vastly improve the way that you consume protocols: -``` -// Full method implementation, contains all methods +```csharp + // Full method implementation, contains all methods class MyProtocol : IMyProtocol { public void Say (string msg); public void Listen (string msg); @@ -573,8 +572,9 @@ adopting the protocol. Notice that the interface only lists the required methods and does expose the optional methods. This means that classes that adopt the protocol will get full type checking for the required methods, but -will have to resort to weak typing (manually using Export attributes -and matching the signature) for the optional protocol methods. +will have to resort to weak typing (manually using +[`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) +attributes and matching the signature) for the optional protocol methods. To make it convenient to consume an API that uses protocols, the binding tool also will produce an extensions method class that exposes @@ -586,7 +586,7 @@ If you want to use the protocol definitions in your API, you will need to write skeleton empty interfaces in your API definition. If you want to use the MyProtocol in an API, you would need to do this: -``` +```csharp [BaseType (typeof (NSObject))] [Model, Protocol] interface MyProtocol { @@ -612,12 +612,12 @@ interface MyTool { The above is needed because at binding time the `IMyProtocol` would not exist, that is why you need to provide an empty interface. -### Adopting Protocol Generated Interfaces +#### Adopting protocol-generated interfaces Whenever you implement one of the interfaces generated for the protocols, like this: -``` +```csharp class MyDelegate : NSObject, IUITableViewDelegate { nint IUITableViewDelegate.GetRowHeight (nint row) { return 1; @@ -625,12 +625,10 @@ class MyDelegate : NSObject, IUITableViewDelegate { } ``` - - The implementation for the interface methods automatically gets exported with the proper name, so it is equivalent to this: -``` +```csharp class MyDelegate : NSObject, IUITableViewDelegate { [Export ("getRowHeight:")] nint IUITableViewDelegate.GetRowHeight (nint row) { @@ -644,37 +642,18 @@ implicitly or explicitly. - -## Binding Class Extensions - - +### Binding class extensions In Objective-C it is possible to extend classes with new methods, similar in spirit to C#'s extension methods. When one of these methods -is present, you can use the `BaseType` attribute to flag the method as being the receiver of the Objective-C -message. +is present, you can use the +[`[BaseType]`](~/cross-platform/macios/binding/binding-types-reference.md#BaseTypeAttribute) +attribute to flag the method as being the receiver of the Objective-C message. For example, in Xamarin.iOS we bound the extension methods that are defined on `NSString` when `UIKit` is imported as methods in the `NSStringDrawingExtensions`, like this: -``` +```csharp [Category, BaseType (typeof (NSString))] interface NSStringDrawingExtensions { [Export ("drawAtPoint:withFont:")] @@ -682,18 +661,13 @@ interface NSStringDrawingExtensions { } ``` - + +### Binding Objective-C argument lists -## Binding Objective-C Argument Lists +Objective-C supports variadic arguments. For example: -Objective-C supports variadic arguments, you can use the following -technique described by Zach Gris on [this -post](http://forums.monotouch.net/yaf_postst311_SOLVED-Binding-ObjectiveC-Argument-Lists.aspx). - -An Objective-C message looks like this: - -``` +```objc - (void) appendWorkers:(XWorker *) firstWorker, ... NS_REQUIRES_NIL_TERMINATION ; ``` @@ -701,7 +675,7 @@ An Objective-C message looks like this: To invoke this method from C# you will want to create a signature like this: -``` +```csharp [Export ("appendWorkers"), Internal] void AppendWorkers (Worker firstWorker, IntPtr workersPtr) ``` @@ -709,7 +683,7 @@ void AppendWorkers (Worker firstWorker, IntPtr workersPtr) This declares the method as internal, hiding the above API from users, but exposing it to the library. Then you can write a method like this: -``` +```csharp public void AppendWorkers(params Worker[] workers) { if (workers == null) @@ -728,10 +702,9 @@ public void AppendWorkers(params Worker[] workers) } ``` - - + -## Binding Fields +### Binding fields Sometimes you will want to access public fields that were declared in a library. @@ -741,19 +714,20 @@ Usually these fields contain strings or integers values that must be notification and as keys in dictionaries. To bind a field, add a property to your interface definition file, and - decorate the property with the [[Field]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#FieldAttribute) attribute. This attribute takes one parameter: the C name of the + decorate the property with the [`[Field]`](~/cross-platform/macios/binding/binding-types-reference.md#FieldAttribute) attribute. This attribute takes one parameter: the C name of the symbol to lookup. For example: -``` +```csharp [Field ("NSSomeEventNotification")] NSString NSSomeEventNotification { get; } ``` If you want to wrap various fields in a static class that does not -derive from `NSObject`, you can use the `[Static]` attribute on -the class, like this: +derive from `NSObject`, you can use the +[`[Static]`](~/cross-platform/macios/binding/binding-types-reference.md#StaticAttribute_Class) +attribute on the class, like this: -``` +```csharp [Static] interface LonelyClass { [Field ("NSSomeEventNotification")] @@ -765,7 +739,8 @@ The above will generate a `LonelyClass` which does not derive from `NSObject` and will contain a binding to the `NSSomeEventNotification` `NSString` exposed as an `NSString`. -The `[Field]` attribute can be applied to the following data types: +The [`[Field]`](~/cross-platform/macios/binding/binding-types-reference.md#FieldAttribute) +attribute can be applied to the following data types: - `NSString` references (read-only properties only) - `NSArray` references (read-only properties only) @@ -776,11 +751,10 @@ The `[Field]` attribute can be applied to the following data types: - `System.Drawing.SizeF` - `CGSize` - In addition to the native field name, you can specify the library name where the field is located, by passing the library name: -``` +```csharp [Static] interface LonelyClass { [Field ("SomeSharedLibrarySymbol", "SomeSharedLibrary")] @@ -791,7 +765,7 @@ interface LonelyClass { If you are linking statically, there is no library to bind to, so you need to use the `__Internal` name: -``` +```csharp [Static] interface LonelyClass { [Field ("MyFieldFromALibrary", "__Internal")] @@ -799,10 +773,9 @@ interface LonelyClass { } ``` - + - -## Binding Enums +### Binding enums You can add `enum` directly in your binding files to makes it easier to use them inside API definitions - without using a different source @@ -811,7 +784,7 @@ project). Example: -``` +```csharp [Native] // needed for enums defined as NSInteger in ObjC enum MyEnum {} @@ -827,7 +800,7 @@ methods to convert enums values and NSString constants for you. Example: -``` +```csharp enum NSRunLoopMode { [DefaultEnumValue] @@ -851,27 +824,32 @@ interface MyType { ``` In the above example you could decide to decorate `void Perform (NSString mode);` -with an `[Internal]` attribute. This will **hide** the constant-based API -from your binding consumers. +with an [`[Internal]`](~/cross-platform/macios/binding/binding-types-reference.md#InternalAttribute) +attribute. This will **hide** the constant-based API from your binding consumers. However this would limit subclassing the type as the nicer API alternative -uses a `[Wrap]` attribute. Those generated methods are not `virtual`, i.e. +uses a [`[Wrap]`](~/cross-platform/macios/binding/binding-types-reference.md#WrapAttribute) +attribute. Those generated methods are not `virtual`, i.e. you won't be able to override them - which may, or not, be a good choice. An alternative is to mark the original, `NSString`-based, definition as `[Protected]`. This will allow subclassing to work, when required, and the wrap'ed version will still work and call the overriden method. +### Binding `NSValue`, `NSNumber`, and `NSString` to a better type -## Binding NSValue NSNumber and NSString to a better type - -The [[BindAs]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#BindAsAttribute) attribute allows binding `NSNumber`, `NSValue` and `NSString`(enums) into more accurate C# types. The attribute can be used to create better, more accurate, .NET API over the native API. +The [`[BindAs]`](~/cross-platform/macios/binding/binding-types-reference.md#BindAsAttribute) attribute allows binding `NSNumber`, `NSValue` and `NSString`(enums) into more accurate C# types. The attribute can be used to create better, more accurate, .NET API over the native API. -You can decorate methods (on return value), parameters and properties with [[BindAs]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#BindAsAttribute). The only restriction is that your member **must not** be inside a `[Protocol]` or `[Model]` interface. +You can decorate methods (on return value), parameters and properties with +[`[BindAs]`](~/cross-platform/macios/binding/binding-types-reference.md#BindAsAttribute). +The only restriction is that your member **must not** be inside a +[`[Protocol]`](~/cross-platform/macios/binding/binding-types-reference.md#ProtocolAttribute) +or [`[Model]`](~/cross-platform/macios/binding/binding-types-reference.md#ModelAttribute) +interface. For example: -``` +```csharp [return: BindAs (typeof (bool?))] [Export ("shouldDrawAt:")] NSNumber ShouldDraw ([BindAs (typeof (CGRect))] NSValue rect); @@ -879,18 +857,18 @@ NSNumber ShouldDraw ([BindAs (typeof (CGRect))] NSValue rect); Would output: -``` +```csharp [Export ("shouldDrawAt:")] bool? ShouldDraw (CGRect rect) { ... } ``` Internally we will do the `bool?` <-> `NSNumber` and `CGRect` <-> `NSValue` conversions. -[[BindAs]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#BindAsAttribute) also supports arrays of `NSNumber` `NSValue` and `NSString`(enums). +[`[BindAs]`](~/cross-platform/macios/binding/binding-types-reference.md#BindAsAttribute) also supports arrays of `NSNumber` `NSValue` and `NSString`(enums). For example: -``` +```csharp [BindAs (typeof (CAScroll []))] [Export ("supportedScrollModes")] NSString [] SupportedScrollModes { get; set; } @@ -898,29 +876,29 @@ NSString [] SupportedScrollModes { get; set; } Would output: -``` +```csharp [Export ("supportedScrollModes")] CAScroll [] SupportedScrollModes { get; set; } ``` `CAScroll` is a `NSString` backed enum, we will fetch the right `NSString` value and handle the type conversion. -Please see [[BindAs] documentation](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#BindAsAttribute) to see supported conversion types. - - +Please see the [`[BindAs]`](~/cross-platform/macios/binding/binding-types-reference.md#BindAsAttribute) +documentation to see supported conversion types. + -## Binding Notifications +### Binding notifications Notifications are messages that are posted to the `NSNotificationCenter.DefaultCenter` and are used as a mechanism to broadcast messages from one part of the application to another. Developers subscribe to notifications typically using the -[NSNotificationCenter](/api/type/Foundation.NSNotificationCenter/)'s -[AddObserver](/api/type/Foundation.NSNotificationCenter/M/AddObserver/) +[NSNotificationCenter](https://developer.xamarin.com/api/type/Foundation.NSNotificationCenter/)'s +[AddObserver](https://developer.xamarin.com/api/type/Foundation.NSNotificationCenter/M/AddObserver/) method. When an application posts a message to the notification center, it typically contains a payload stored in the -[NSNotification.UserInfo](/api/property/Foundation.NSNotification.UserInfo/) +[NSNotification.UserInfo](https://developer.xamarin.com/api/property/Foundation.NSNotification.UserInfo/) dictionary. This dictionary is weakly typed, and getting information out of it is error prone, as users typically need to read in the documentation which keys are available on the dictionary and the types @@ -929,9 +907,9 @@ keys sometimes is used as a boolean as well. The Xamarin.iOS binding generator provides support for developers to bind notifications. To do this, you set the -[[Notification]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#NotificationAttribute) +[`[Notification]`](~/cross-platform/macios/binding/binding-types-reference.md#NotificationAttribute) attribute on a property that has been also been tagged with a -[[Field]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#FieldAttribute) +[`[Field]`](~/cross-platform/macios/binding/binding-types-reference.md#FieldAttribute) property (it can be public or private). This attribute can be used without arguments for notifications that @@ -939,13 +917,13 @@ carry no payload, or you can specify a `System.Type` that references another interface in the API definition, typically with the name ending with "EventArgs". The generator will turn the interface into a class that subclasses `EventArgs` and will include all of the properties -listed there. The `[Export]` attribute should be used in the EventArgs -class to list the name of the key used to look up the Objective-C -dictionary to fetch the value. +listed there. The [`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) +attribute should be used in the EventArgs class to list the name of the key +used to look up the Objective-C dictionary to fetch the value. For example: -``` +```csharp interface MyClass { [Notification] [Field ("MyClassDidStartNotification")] @@ -956,7 +934,7 @@ interface MyClass { The above code will generate a nested class `MyClass.Notifications` with the following methods: -``` +```csharp public class MyClass { [..] public Notifications { @@ -967,10 +945,10 @@ public class MyClass { Users of your code can then easily subscribe to notifications posted to the -[NSDefaultCenter](/api/property/Foundation.NSNotificationCenter.DefaultCenter/) +[NSDefaultCenter](https://developer.xamarin.com/api/property/Foundation.NSNotificationCenter.DefaultCenter/) by using code like this: -``` +```csharp var token = MyClass.Notifications.ObserverDidStart ((notification) => { Console.WriteLine ("Observed the 'DidStart' event!"); }); @@ -979,17 +957,16 @@ var token = MyClass.Notifications.ObserverDidStart ((notification) => { The returned value from `ObserveDidStart` can be used to easily stop receiving notifications, like this: -``` +```csharp token.Dispose (); ``` - Or you can call -[NSNotification.DefaultCenter.RemoveObserver](/api/member/Foundation.NSNotificationCenter.RemoveObserver/p/Foundation.NSObject/) +[NSNotification.DefaultCenter.RemoveObserver](https://developer.xamarin.com/api/member/Foundation.NSNotificationCenter.RemoveObserver/p/Foundation.NSObject/) and pass the token. If your notification contains parameters, you should specify a helper `EventArgs` interface, like this: -``` +```csharp interface MyClass { [Notification (typeof (MyScreenChangedEventArgs)] [Field ("MyClassScreenChangedNotification")] @@ -1012,7 +989,7 @@ interface MyScreenChangedEventArgs { The above will generate a `MyScreenChangedEventArgs` class with the `ScreenX` and `ScreenY` properties that will fetch the data from the -[NSNotification.UserInfo](/api/property/Foundation.NSNotification.UserInfo/) +[NSNotification.UserInfo](https://developer.xamarin.com/api/property/Foundation.NSNotification.UserInfo/) dictionary using the keys "ScreenXKey" and "ScreenYKey" respectively and apply the proper conversions. The `[ProbePresence]` attribute is used for the generator to probe if the key is set in the `UserInfo`, @@ -1021,16 +998,15 @@ the presence of the key is the value (typically for boolean values). This allows you to write code like this: -``` +```csharp var token = MyClass.NotificationsObserveScreenChanged ((notification) => { Console.WriteLine ("The new screen dimensions are {0},{1}", notification.ScreenX, notification.ScreenY); }); ``` - + - -## Binding Categories +### Binding categories Categories are an Objective-C mechanism used to extend the set of methods and properties available in a class. In practice, they are @@ -1041,26 +1017,27 @@ linked in. In some other cases, they are used to organize features in a class by functionality. They are similar in spirit to C# extension methods.This is what a category would look like in Objective-C: -``` +```csharp @interface UIView (MyUIViewExtension) -(void) makeBackgroundRed; @end ``` - - The above example if found on a library would extend instances of `UIView` with the method `makeBackgroundRed`. -To bind those, you can use the `[Category]` attribute on an interface -definition. When using the Category attribute, the meaning of the -`[BaseType]` attribute changes from being used to specify the base -class to extend, to be the type to extend. +To bind those, you can use the [`[Category]`](~/cross-platform/macios/binding/binding-types-reference.md#CategoryAttribute) +attribute on an interface definition. When using the +[`[Category]`](~/cross-platform/macios/binding/binding-types-reference.md#CategoryAttribute) +attribute, the meaning of the +[`[BaseType]`](~/cross-platform/macios/binding/binding-types-reference.md#BaseTypeAttribute) +attribute changes from being used to specify the base class to extend, to +be the type to extend. The following shows how the `UIView` extensions are bound and turned into C# extension methods: -``` +```csharp [BaseType (typeof (UIView))] [Category] interface MyUIViewExtension { @@ -1069,8 +1046,6 @@ interface MyUIViewExtension { } ``` - - The above will create a `MyUIViewExtension` a class that contains the `MakeBackgroundRed` extension method. This means that you can now call "MakeBackgroundRed" on any `UIView` subclass, giving you the same @@ -1078,7 +1053,7 @@ functionality you would get on Objective-C. In some other cases, categories are used not to extend a system class, but to organize functionality, purely for decoration purposes. Like this: -``` +```csharp @interface SocialNetworking (Twitter) - (void) postToTwitter:(Message *) message; @end @@ -1089,13 +1064,13 @@ picture; @end ``` +Although you can use the +[`[Category]`](~/cross-platform/macios/binding/binding-types-reference.md#CategoryAttribute) +attribute also for this decoration style of declarations, you might as well +just add them all to the class definition. Both of these would achieve the +same: - -Although you can use the `Category` attribute also for this -decoration style of declarations, you might as well just add them -all to the class definition. Both of these would achieve the same: - -``` +```csharp [BaseType (typeof (NSObject))] interface SocialNetworking { } @@ -1117,7 +1092,7 @@ interface Facebook { It is just shorter in these cases to merge the categories: -``` +```csharp [BaseType (typeof (NSObject))] interface SocialNetworking { [Export ("postToTwitter:")] @@ -1128,32 +1103,31 @@ interface SocialNetworking { } ``` - - + -## Binding Blocks +### Binding blocks Blocks are a new construct introduced by Apple to bring the functional equivalent of C# anonymous methods to Objective-C. For example, the `NSSet` class now exposes this method: -``` +```csharp - (void) enumerateObjectsUsingBlock:(void (^)(id obj, BOOL *stop) block ``` The above description declares a method called -"*enumerateObjectsUsingBlock:*" that takes one argument named -*block*. This block is similar to a C# anonymous method in that it has +`enumerateObjectsUsingBlock:` that takes one argument named +`block`. This block is similar to a C# anonymous method in that it has support for capturing the current environment (the "this" pointer, access to local variables and parameters). The above method in `NSSet` -invokes the block with two parameters an `NSObject` (the "id obj" part) -and a pointer to a boolean (the "BOOL *stop") part. +invokes the block with two parameters an `NSObject` (the `id obj` part) +and a pointer to a boolean (the `BOOL *stop`) part. To bind this kind of API with btouch, you need to first declare the block type signature as a C# delegate and then reference it from an API entry point, like this: -``` +```csharp // This declares the callback signature for the block: delegate void NSSetEnumerator (NSObject obj, ref bool stop) @@ -1164,7 +1138,7 @@ void Enumerate (NSSetEnumerator enum) And now your code can call your function from C#: -``` +```csharp var myset = new NSMutableSet (); myset.Add (new NSString ("Foo")); @@ -1175,7 +1149,7 @@ s.Enumerate (delegate (NSObject obj, ref bool stop){ You can also use lambdas if you prefer: -``` +```csharp var myset = new NSMutableSet (); mySet.Add (new NSString ("Foo")); @@ -1184,15 +1158,16 @@ s.Enumerate ((obj, stop) => { }); ``` - - + -## Asynchronous Methods +### Asynchronous methods The binding generator can turn a certain class of methods into async-friendly methods (methods that return a Task or Task<T>). -You can use the `[Async]` attribute on methods that return +You can use the +[`[Async]`](~/cross-platform/macios/binding/binding-types-reference.md#AsyncAttribute) +attribute on methods that return void and whose last argument is a callback. When you apply this to a method, the binding generator will generate a version of that method with the suffix `Async`. If the callback @@ -1205,43 +1180,41 @@ properties. Example: -``` +```csharp [Export ("loadfile:completed:")] [Async] void LoadFile (string file, Action completed); ``` - - The above code will generate both the LoadFile method, as well as: -``` +```csharp [Export ("loadfile:completed:")] Task LoadFileAsync (string file); ``` - + -## Surfacing Strong Types for weak NSDictionary parameters +### Surfacing strong types for weak NSDictionary parameters -In many places in the Objective-C API, parameters are passed as weakly -typed `NSDictionary` APIs with specific keys and values, but these are +In many places in the Objective-C API, parameters are passed as +weakly-typed `NSDictionary` APIs with specific keys and values, but these are error prone (you can pass invalid keys, and get no warnings; you can pass invalid values, and get no warnings) and frustrating to use as they require multiple trips to the documentation to lookup the possible key names and values. -The solution is to provide a strongly typed version that provides the -strongly typed version of the API and behind the scenes maps the +The solution is to provide a strongly-typed version that provides the +strongly-typed version of the API and behind the scenes maps the various underlying keys and values. So for example, if the Objective-C API accepted an `NSDictionary` and it -is documented as taking the key "XyzVolumeKey" which takes an -`NSNumber` with a volume value from 0.0 to 1.0 and a "XyzCaptionKey" that +is documented as taking the key `XyzVolumeKey` which takes an +`NSNumber` with a volume value from 0.0 to 1.0 and a `XyzCaptionKey` that takes a string, you would want your users to have a nice API that looks like this: -``` +```csharp public class XyzOptions { public nfloat? Volume { get; set; } public string Caption { get; set; } @@ -1254,11 +1227,11 @@ there are scenarios where the value might not be set. To do this, you need to do a few things: -* Create a strongly typed class, that subclasses - [DictionaryContainer](/api/type/Foundation.DictionaryContainer/) and provides the various getters and setters for each property. -* Declare overloads for the methods taking `NSDictionary` to take the new strongly typed version. +* Create a strongly-typed class, that subclasses + [DictionaryContainer](https://developer.xamarin.com/api/type/Foundation.DictionaryContainer/) and provides the various getters and setters for each property. +* Declare overloads for the methods taking `NSDictionary` to take the new strongly-typed version. -You can create the strongly typed class either manually, or use the +You can create the strongly-typed class either manually, or use the generator to do the work for you. We first explore how to do this manually so you understand what is going on, and then the automatic approach. @@ -1267,10 +1240,9 @@ You need to create a supporting file for this, it does not go into your contract API. This is what you would have to write to create your XyzOptions class: - -``` +```csharp public class XyzOptions : DictionaryContainer { -#if !COREBUILD +# if !COREBUILD public XyzOptions () : base (new NSMutableDictionary ()) {} public XyzOptions (NSDictionary dictionary) : base (dictionary){} @@ -1282,14 +1254,14 @@ public class XyzOptions : DictionaryContainer { get { return GetStringValue (XyzOptionsKeys.CaptionKey); } set { SetStringValue (XyzOptionsKeys.CaptionKey, value); } } -#endif +# endif } ``` You then should provide a wrapper method that surfaces the high-level API, on top of the low-level API. -``` +```csharp [BaseType (typeof (NSObject))] interface XyzPanel { [Export ("playback:withOptions:")] @@ -1302,18 +1274,20 @@ interface XyzPanel { If your API does not need to be overwritten, you can safely hide the NSDictionary-based API by using the -[Internal](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#InternalAttribute) +[`[Internal]`](~/cross-platform/macios/binding/binding-types-reference.md#InternalAttribute) attribute. -As you can see, we use the `[Wrap]` attribute to surface a new API entry -point, and we surface it using our strongly typed XyzOptions class. -The wrapper method also allows for null to be passed. +As you can see, we use the +[`[Wrap]`](~/cross-platform/macios/binding/binding-types-reference.md#WrapAttribute) +attribute to surface a new API entry point, and we surface it using our +strongly-typed `XyzOptions` class. The wrapper method also allows for null +to be passed. Now, one thing that we did not mention is where the `XyzOptionsKeys` values came from. You would typically group the keys that an API -surfaces in a static class like XyzOptionsKeys, like this: +surfaces in a static class like `XyzOptionsKeys`, like this: -``` +```csharp [Static] class XyzOptionKeys { [Field ("kXyzVolumeKey")] @@ -1324,31 +1298,32 @@ class XyzOptionKeys { } ``` -Let us look at the automatic support for creating these strongly typed +Let us look at the automatic support for creating these strongly-typed dictionaries. This avoids plenty of the boilerplate, and you can define the dictionary directly in your API contract, instead of using an external file. -To create a strongly typed dictionary, introduce an interface in your +To create a strongly-typed dictionary, introduce an interface in your API and decorate it with the -[StrongDictionary](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#StrongDictionary) +[StrongDictionary](~/cross-platform/macios/binding/binding-types-reference.md#StrongDictionary) attribute. This tells the generator that it should create a class with the same name as your interface that will derive from `DictionaryContainer` and will provide strong typed accessors for it. -The `StrongDictionary` attribute takes one parameter, which is the name +The [`[StrongDictionary]`](~/cross-platform/macios/binding/binding-types-reference.md#StrongDictionary) +attribute takes one parameter, which is the name of the static class that contains your dictionary keys. Then each -property of the interface will become a strongly typed accessor. By +property of the interface will become a strongly-typed accessor. By default, the code will use the name of the property with the suffix "Key" in the static class to create the accessor. -This means that creating your strongly typed accessor no longer +This means that creating your strongly-typed accessor no longer requires an external file, nor having to manually create getters and setters for every property, nor having to lookup the keys manually yourself. This is what your entire binding would look like: -``` +```csharp [Static] class XyzOptionKeys { [Field ("kXyzVolumeKey")] @@ -1375,236 +1350,58 @@ interface XyzPanel { In case you need to reference in your `XyzOption` members a different field (that is not the name of the property with the suffix `Key`), -you can decorate the property with an `Export` attribute with the name -that you want to use. - - +you can decorate the property with an +[`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) +attribute with the name that you want to use. -# Type mappings + +## Type mappings This section covers how Objective-C types are mapped to C# types. - -## Simple Types +### Simple types The following table shows how you should map types from the Objective-C and CocoaTouch world to the Xamarin.iOS world: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Type mappings -
- Objective-C type name - - Xamarin.iOS Unified API type -
- BOOL, GLboolean - - bool -
- NSInteger - - nint -
- NSUInteger - - nuint -
- CFTimeInterval / NSTimeInterval - - double -
- NSString (more on binding - NSString) - - string -
- char * - - - [PlainString] string -
- CGRect - - CGRect -
- CGPoint - - CGPoint -
- CGSize - - CGSize -
- CGFloat, GLfloat - - nfloat -
- CoreFoundation types (CF*) - - CoreFoundation.CF* -
- GLint - - nint -
- GLfloat - - nfloat -
- Foundation types (NS*) - - Foundation.NS* -
- id - - Foundation.NSObject -
- NSGlyph - - nint -
- NSSize - - CGSize -
- NSTextAlignment - - UITextAlignment -
- SEL - - ObjCRuntime.Selector -
- dispatch_queue_t - - CoreFoundation.DispatchQueue -
- CFTimeInterval - - double -
- CFIndex - - nint -
- NSGlyph - - nuint -
- - - - -## Arrays +|Objective-C type name|Xamarin.iOS Unified API type| +|---|---| +|`BOOL`, `GLboolean`|`bool`| +|`NSInteger`|`nint`| +|`NSUInteger`|`nuint`| +|`CFTimeInterval` / `NSTimeInterval`|`double`| +|`NSString` ([more on binding NSString](~/ios/internals/api-design/nsstring.md))|`string`| +|`char *`|`string` (see also: [`[PlainString]`](~/cross-platform/macios/binding/binding-types-reference.md#plainstring))| +|`CGRect`|`CGRect`| +|`CGPoint`|`CGPoint`| +|`CGSize`|`CGSize`| +|`CGFloat`, `GLfloat`|`nfloat`| +|CoreFoundation types (`CF*`)|`CoreFoundation.CF*`| +|`GLint`|`nint`| +|`GLfloat`|`nfloat`| +|Foundation types (`NS*`)|`Foundation.NS*`| +|`id`|`Foundation`.`NSObject`| +|`NSGlyph`|`nint`| +|`NSSize`|`CGSize`| +|`NSTextAlignment`|`UITextAlignment`| +|`SEL`|`ObjCRuntime.Selector`| +|`dispatch_queue_t`|`CoreFoundation.DispatchQueue`| +|`CFTimeInterval`|`double`| +|`CFIndex`|`nint`| +|`NSGlyph`|`nuint`| + + + +### Arrays The Xamarin.iOS runtime automatically takes care of converting C# arrays to `NSArrays` and doing the conversion back, so for example the imaginary Objective-C method that returns an `NSArray` of `UIViews`: -``` +```csharp // Get the peer views - untyped - (NSArray *)getPeerViews (); @@ -1614,7 +1411,7 @@ imaginary Objective-C method that returns an `NSArray` of `UIViews`: Is bound like this: -``` +```csharp [Export ("getPeerViews")] UIView [] GetPeerViews (); @@ -1622,7 +1419,7 @@ UIView [] GetPeerViews (); void SetViews (UIView [] views); ``` -The idea is to use a strongly typed C# array as this will allow the +The idea is to use a strongly-typed C# array as this will allow the IDE to provide proper code completion with the actual type without forcing the user to guess, or look up the documentation to find out the actual type of the objects contained in the array. @@ -1630,13 +1427,12 @@ the actual type of the objects contained in the array. In cases where you can not track down the actual most derived type contained in the array, you can use `NSObject []` as the return value. - - + -## Selectors +### Selectors Selectors appear on the Objective-C API as the special type -"SEL". When binding a selector, you would map the type to +`SEL`. When binding a selector, you would map the type to `ObjCRuntime.Selector`. Typically selectors are exposed in an API with both an object, the target object, and a selector to invoke in the target object. Providing both of these basically corresponds to @@ -1645,7 +1441,7 @@ as well as the object to invoke the method in. This is what the binding looks like: -``` +```csharp interface Button { [Export ("setTarget:selector:")] void SetTarget (NSObject target, Selector sel); @@ -1654,7 +1450,7 @@ interface Button { And this is how the method would typically be used in an application: -``` +```csharp class DialogPrint : UIViewController { void HookPrintButton (Button b) { @@ -1672,11 +1468,11 @@ class DialogPrint : UIViewController { To make the binding nicer to C# developers, you typically will provide a method that takes an `NSAction` parameter, which allows C# delegates and lambdas to be used instead of the `Target+Selector`. To do this you -would typically hide the "SetTarget" method by flagging it with an -"Internal" attribute and then you would expose a new helper method, -like this: +would typically hide the `SetTarget` method by flagging it with an +[`[Internal]`](~/cross-platform/macios/binding/binding-types-reference.md#InternalAttribute) +attribute and then you would expose a new helper method, like this: -``` +```csharp // API.cs interface Button { [Export ("setTarget:selector:"), Internal] @@ -1694,7 +1490,7 @@ public partial class Button { So now your user code can be written like this: -``` +```csharp class DialogPrint : UIViewController { void HookPrintButton (Button b) { @@ -1712,10 +1508,9 @@ class DialogPrint : UIViewController { } ``` - - + -## Strings +### Strings When you are binding a method that takes an `NSString`, you can replace that with a C# string type, both on return types and parameters. @@ -1723,24 +1518,23 @@ that with a C# string type, both on return types and parameters. The only case when you might want to use an `NSString` directly is when the string is used as a token. For more information about strings and `NSString`, read the [API Design on -NSString](/guides/ios/advanced_topics/api_design/nsstring) document. +NSString](~/ios/internals/api-design/nsstring.md) document. In some rare cases, an API might expose a C-like string (`char *`) instead of an Objective-C string (`NSString *`). In those cases, you can annotate the parameter with the -[[PlainString]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#PlainString) +[`[PlainString]`](~/cross-platform/macios/binding/binding-types-reference.md#plainstring) attribute. - + - -## out/ref parameters +### out/ref parameters Some APIs return values in their parameters, or pass parameters by reference. -Typically the signature looks like this:: +Typically the signature looks like this: -``` +```csharp - (void) someting:(int) foo withError:(NSError **) retError - (void) someString:(NSObject **)byref ``` @@ -1753,46 +1547,43 @@ by reference, rather than a pure output value. Your binding would look like this: -``` +```csharp [Export ("something:withError:")] void Something (nint foo, out NSError error); [Export ("someString:")] void SomeString (ref NSObject byref); ``` - - + -## Memory management attributes +### Memory management attributes -When you use the `[Export]` attribute and you are passing data that will -be retained by the called method, you can specify the argument -semantics by passing it as a second parameter, for example: +When you use the [`[Export]`](~/cross-platform/macios/binding/binding-types-reference.md#ExportAttribute) +attribute and you are passing data that will be retained by the called method, +you can specify the argument semantics by passing it as a second parameter, +for example: -``` +```csharp [Export ("method", ArgumentSemantic.Retain)] ``` The above would flag the value as having the "Retain" semantics. The semantics available are: -- Assign: -- Copy: -- Retain: - +- Assign +- Copy +- Retain - + +### Style guidelines -## Style Guidelines + - - - -### Using [Internal] +#### Using [Internal] You can use the -[[Internal]](/guides/ios/advanced_topics/binding_objective-c/binding_types_reference_guide#InternalAttribute) +[`[Internal]`](~/cross-platform/macios/binding/binding-types-reference.md#InternalAttribute) attribute to hide a method from the public API. You might want to do this in cases where the exposed API is too low-level and you want to provide a high-level implementation in a separate file based on this @@ -1803,10 +1594,9 @@ generator, for example some advanced scenarios might expose types that are not bound and you want to bind in your own way, and you want to wrap those types yourself in your own way. - + - -# Event Handlers and Callbacks +## Event handlers and callbacks Objective-C classes typically broadcast notifications or request information by sending a message on a delegate class (Objective-C @@ -1817,7 +1607,7 @@ sometimes be cumbersome. Xamarin.iOS exposes the C# event pattern and a method-callback system on the class that can be used in these situations. This allows code like this to run: -``` +```csharp button.Clicked += delegate { Console.WriteLine ("I was clicked"); }; @@ -1836,7 +1626,7 @@ will is the one that currently emits events and sends those into the Considering the following setup: -``` +```csharp [BaseType (typeof (NSObject))] interface MyClass { [Export ("delegate", ArgumentSemantic.Assign)][NullAllowed] @@ -1855,9 +1645,14 @@ interface MyClassDelegate { To wrap the class you must: -- In your host class, add to your `[BaseType]` declaration the type that is acting as its delegate and the C# name that you exposed. In our example above those are "typeof (MyClassDelegate)" and "WeakDelegate" respectively. -- In your delegate class, on each method that has more than two parameters, you need to specify the type that you want to use for the automatically generated EventArgs class. - +- In your host class, add to your + [`[BaseType]`](~/cross-platform/macios/binding/binding-types-reference.md#BaseTypeAttribute) + declaration the type that is acting as its delegate and the C# name that + you exposed. In our example above those are `typeof (MyClassDelegate)` + and `WeakDelegate` respectively. +- In your delegate class, on each method that has more than two parameters, + you need to specify the type that you want to use for the automatically + generated EventArgs class. The binding generator is not limited to wrapping only a single event destination, it is possible that some Objective-C classes to emit @@ -1867,7 +1662,7 @@ is ready to support those cases. The resulting code will be: -``` +```csharp [BaseType (typeof (NSObject), Delegates=new string [] {"WeakDelegate"}, Events=new Type [] { typeof (MyClassDelegate) })] @@ -1888,12 +1683,12 @@ interface MyClassDelegate { The `EventArgs` is used to specify the name of the `EventArgs` class to be generated. You should use one per signature (in this example, the `EventArgs` will -contain a "With" property of type nint). +contain a `With` property of type nint). With the definitions above, the generator will produce the following event in the generated MyClass: -``` +```csharp public MyClassLoadedEventArgs : EventArgs { public MyClassLoadedEventArgs (nint bytes); public nint Bytes { get; set; } @@ -1906,7 +1701,7 @@ public event EventHandler Loaded { So you can now use the code like this: -``` +```csharp MyClass c = new MyClass (); c.Loaded += delegate (sender, args){ Console.WriteLine ("Loaded event with {0} bytes", args.Bytes); @@ -1915,28 +1710,30 @@ c.Loaded += delegate (sender, args){ Callbacks are just like event invocations, the difference is that instead of having multiple potential subscribers (for example, -multiple methods can hook into a "Clicked" event or a "Download -Finished" event) callbacks can only have a single subscriber. +multiple methods can hook into a `Clicked` event or a `DownloadFinished` event) +callbacks can only have a single subscriber. The process is identical, the only difference is that instead of -exposing the name of the EventArgs class that will be generated, the +exposing the name of the `EventArgs` class that will be generated, the EventArgs actually is used to name the resulting C# delegate name. If the method in the delegate class returns a value, the binding generator will map this into a delegate method in the parent class instead of an event. In these cases you need to provide the default value that should be returned by the method if the user does not hook -up to the delegate. You do this using the `[DefaultValue]` or -`[DefaultValueFromArgument]` attributes. - -DefaultValue will hardcode a return value, while -`[DefaultValueFromArgument]` is used to specify which input argument -will be returned. +up to the delegate. You do this using the +[`[DefaultValue]`](~/cross-platform/macios/binding/binding-types-reference.md#DefaultValueAttribute) +or [`[DefaultValueFromArgument]`](~/cross-platform/macios/binding/binding-types-reference.md#DefaultValueFromArgumentAttribute) +attributes. - +[`[DefaultValue]`](~/cross-platform/macios/binding/binding-types-reference.md#DefaultValueAttribute) +will hardcode a return value, while +[`[DefaultValueFromArgument]`](~/cross-platform/macios/binding/binding-types-reference.md#DefaultValueFromArgumentAttribute) +is used to specify which input argument will be returned. + -# Enumerations and Base Types +## Enumerations and base types You can also reference enumerations or base types that are not directly supported by the btouch interface definition system. To do @@ -1944,36 +1741,36 @@ this, put your enumerations and core types into a separate file and include this as part of one of the extra files that you provide to btouch. - + - -# Linking the Dependencies +## Linking the dependencies If you are binding APIs that are not part of your application, you need to make sure that your executable is linked against these libraries. You need to inform Xamarin.iOS how to link your libraries, this can be done -either by altering your build configuration to invoke the mtouch command with +either by altering your build configuration to invoke the `mtouch` command with some extra build arguments that specify how to link with the new libraries using the "-gcc_flags" option, followed by a quoted string that contains all the extra libraries that are required for your program, like this: -``` +```bash -gcc_flags "-L${ProjectDir} -lMylibrary -force_load -lSystemLibrary -framework CFNetwork -ObjC" ``` The above example will link `libMyLibrary.a`, `libSystemLibrary.dylib` and the `CFNetwork` framework library into your final executable. -Or you can take advantage of the assembly-level `LinkWithAttribute`, -that you can embed in your contract files (such as -`AssemblyInfo.cs`). When you use the `LinkWithAttribute`, you will need to -have your native library available at the time you make your binding, -as this will embed the native library with your application. For -example: +Or you can take advantage of the assembly-level +[`[LinkWithAttribute]`](~/cross-platform/macios/binding/binding-types-reference.md#LinkWithAttribute), +that you can embed in your contract files (such as `AssemblyInfo.cs`). +When you use the [`[LinkWithAttribute]`](~/cross-platform/macios/binding/binding-types-reference.md#LinkWithAttribute), +you will need to have your native library available at the time you +make your binding, as this will embed the native library with your +application. For example: -``` +```csharp // Specify only the library name as a constructor argument and specify everything else with properties: [assembly: LinkWith ("libMyLibrary.a", LinkTarget = LinkTarget.ArmV6 | LinkTarget.ArmV7 | LinkTarget.Simulator, ForceLoad = true, IsCxx = true)] @@ -1981,26 +1778,25 @@ example: [assembly: LinkWith ("libMyLibrary.a", LinkTarget.ArmV6 | LinkTarget.ArmV7 | LinkTarget.Simulator, ForceLoad = true, IsCxx = true)] ``` -You might be wondering, why do you need "force_load" command, and the +You might be wondering, why do you need `-force_load` command, and the reason is that the -ObjC flag although it compiles the code in, it does not preserve the metadata required to support categories (the linker/compiler dead code elimination strips it) which you need at runtime for Xamarin.iOS. - - + -# Assisted References +## Assisted references Some transient objects like action sheets and alert boxes are cumbersome to keep track of for developers and the binding generator can help a little bit here. For example if you had a class that showed a message and then -generated a "Done" event, the traditional way of handling this would +generated a `Done` event, the traditional way of handling this would be: -``` +```csharp class Demo { MessageBox box; @@ -2018,7 +1814,7 @@ on his own. While binding code, the generator supports keeping track of the reference for you and clear it when a special method is invoked, the above code would then become: -``` +```csharp class Demo { void ShowError (string msg) { @@ -2033,11 +1829,11 @@ instance, that it works with a local variable and that it is not necessary to clear the reference when the object dies. To take advantage of this, your class should have a Events property -set in the `[BaseType]` declaration and also the `KeepUntilRef` variable -set to the name of the method that is invoked when the object has -completed its work, like this: +set in the [`[BaseType]`](~/cross-platform/macios/binding/binding-types-reference.md#BaseTypeAttribute) +declaration and also the `KeepUntilRef` variable set to the name of the +method that is invoked when the object has completed its work, like this: -``` +```csharp [BaseType (typeof (NSObject), KeepUntilRef="Dismiss"), Delegates=new string [] { "WeakDelegate" }, Events=new Type [] { typeof (SomeDelegate) }) ] class Demo { [Export ("show")] @@ -2045,18 +1841,21 @@ class Demo { } ``` - - + -# Inheriting Protocols +## Inheriting protocols As of Xamarin.iOS v3.2, we support inheriting from protocols that have -been marked with the `[Model]` property. This is useful in certain API -patterns, such as in `MapKit` where the `MKOverlay` protocol, inherits -from the `MKAnnotation` protocol, and is adopted by a number of classes -which inherit from `NSObject`. +been marked with the [`[Model]`](~/cross-platform/macios/binding/binding-types-reference.md#ModelAttribute) +property. This is useful in certain API patterns, such as in `MapKit` where +the `MKOverlay` protocol, inherits from the `MKAnnotation` protocol, and is +adopted by a number of classes which inherit from `NSObject`. Historically we required copying the protocol to every implementation, but in these cases now we can have the `MKShape` class inherit from the `MKOverlay` protocol and it will generate all the required methods automatically. + +## Related links + +- [Binding Sample](https://developer.xamarin.com/samples/BindingSample/) diff --git a/docs/website/binding_types_reference_guide.md b/docs/website/binding_types_reference_guide.md index cb1a4077288d..c84291dd7130 100644 --- a/docs/website/binding_types_reference_guide.md +++ b/docs/website/binding_types_reference_guide.md @@ -1,12 +1,14 @@ --- -id: C6618E9D-07FA-4C84-D014-10DAC989E48D -title: Binding Types Reference Guide -dateupdated: 2017-06-26 +title: "Binding types reference guide" +ms.prod: xamarin +ms.assetid: C6618E9D-07FA-4C84-D014-10DAC989E48D +ms.technology: xamarin-cross-platform +author: bradumbaugh +ms.author: brumbaug +ms.date: 03/06/2018 --- -[//]: # (The original file resides under https://github.com/xamarin/xamarin-macios/tree/master/docs/website/) -[//]: # (This allows all contributors (including external) to submit, using a PR, updates to the documentation that match the tools changes) -[//]: # (Modifications outside of xamarin-macios/master will be lost on future updates) +# Binding types reference guide This document describes the list of attributes that you can use to annotate your API contract files to drive the binding and the code generated @@ -15,24 +17,23 @@ Xamarin.iOS and Xamarin.Mac API contracts are written in C# mostly as interface definitions that define the way that Objective-C code is surfaced to C#. The process involves a mix of interface declarations plus some basic type definitions that the API contract might require. For an introduction to binding -types, see our companion guide [Binding Objective-C Libraries](/guides/cross-platform/macios/binding/objective-c-libraries/). +types, see our companion guide [Binding Objective-C Libraries](~/cross-platform/macios/binding/objective-c-libraries.md). - -# Type Definitions +## Type definitions Syntax: -``` +```csharp [BaseType (typeof (BTYPE)) interface MyType [: Protocol1, Protocol2] { IntPtr Constructor (string foo); } ``` -Every interface in your contract definition that has the `[BaseType]` attribute -that declares the base type for the generated object. In the above declaration a -`MyType` class C# type will be generated that binds to an Objective-C type called -**MyType**. +Every interface in your contract definition that has the +[`[BaseType]`](#BaseTypeAttribute) attribute that declares the base type for +the generated object. In the above declaration a `MyType` class C# type will +be generated that binds to an Objective-C type called `MyType`. If you specify any types after the typename (in the sample above `Protocol1` and `Protocol2`) using the interface inheritance syntax the contents of those @@ -44,7 +45,7 @@ itself. The following shows how the Objective-C declaration for `UITextField` would be defined in a Xamarin.iOS contract: -``` +```objc @interface UITextField : UIControl { } @@ -52,30 +53,29 @@ defined in a Xamarin.iOS contract: Would be written like this as a C# API contract: -``` +```csharp [BaseType (typeof (UIControl))] interface UITextField : UITextInput { } ``` You can control many other aspects of the code generation by applying other -attributes to the interface as well as configuring the BaseType attribute. - - +attributes to the interface as well as configuring the [`[BaseType]`](#BaseTypeAttribute) +attribute. -## Generating Events +### Generating events One feature of the Xamarin.iOS and Xamarin.Mac API design is that we map Objective-C delegate classes as C# events and callbacks. Users can choose in a per-instance basis whether they want to adopt the Objective-C programming -pattern, by assigning to properties like **Delegate** an instance of a class that +pattern, by assigning to properties like `Delegate` an instance of a class that implements the various methods that the Objective-C runtime would call, or by choosing the C#-style events and properties. Let us see one example of how to use the Objective-C model: -``` +```csharp bool MakeDecision () { return true; @@ -104,7 +104,7 @@ class MyScrollViewDelegate : UIScrollViewDelegate { In the above example, you can see that we have chosen to overwrite two methods, one a notification that a scrolling event has taken place, and the second that is a callback that should return a boolean value instructing the -scrollView whether it should scroll to the top or not. +`scrollView` whether it should scroll to the top or not. The C# model allows the user of your library to listen to notifications using the C# event syntax or the property syntax to hook up callbacks that are @@ -112,7 +112,7 @@ expected to return values. This is how the C# code for the same feature looks like using lambdas: -``` +```csharp void Setup () { var scrollview = new UIScrollView (myRect); @@ -129,27 +129,27 @@ connect multiple copies. The `ShouldScrollToTop` is not an event, it is instead property with the type `UIScrollViewCondition` which has this signature: -``` +```csharp public delegate bool UIScrollViewCondition (UIScrollView scrollView); ``` -It returns a bool value, in this case the lambda syntax allows us to just +It returns a `bool` value, in this case the lambda syntax allows us to just return the value from the `MakeDecision` function. The binding generator supports generating events and properties that link a class like `UIScrollView` with its `UIScrollViewDelegate` (well call these the Model -class), this is done by annotating your `BaseType` definition with the `Events` and -`Delegates` parameters (described below). In addition to annotating the `BaseType` -with those parameters it is necessary to inform the generator of a few more -components. +class), this is done by annotating your [`[BaseType]`](#BaseTypeAttribute) +definition with the `Events` and `Delegates` parameters (described below). +In addition to annotating the [`[BaseType]`](#BaseTypeAttribute) with those +parameters it is necessary to inform the generator of a few more components. For events that take more than one parameter (in Objective-C the convention is that the first parameter in a delegate class is the instance of the sender object) you must provide the name that you would like for the generated -EventArgs class to be. This is done with the `EventArgs` attribute on the method -declaration in your Model class. For example: +`EventArgs` class to be. This is done with the [`[EventArgs]`](#EventArgsAttribute) +attribute on the method declaration in your Model class. For example: -``` +```csharp [BaseType (typeof (UINavigationControllerDelegate))] [Model][Protocol] public interface UIImagePickerControllerDelegate { @@ -161,7 +161,7 @@ public interface UIImagePickerControllerDelegate { The above declaration will generate a `UIImagePickerImagePickedEventArgs` class that derives from `EventArgs` and packs both parameters, the `UIImage` and the `NSDictionary`. The generator produces this: -``` +```csharp public partial class UIImagePickerImagePickedEventArgs : EventArgs { public UIImagePickerImagePickedEventArgs (UIImage image, NSDictionary editingInfo); public UIImage Image { get; set; } @@ -169,9 +169,9 @@ public partial class UIImagePickerImagePickedEventArgs : EventArgs { } ``` -It then exposes the following in the UIImagePickerController class: +It then exposes the following in the `UIImagePickerController` class: -``` +```csharp public event EventHandler FinishedPickingImage { add; remove; } ``` @@ -180,7 +180,7 @@ name for the generated C# delegate (the signature for the method) and also a default value to return in case the user does not provide an implementation himself. For example, the `ShouldScrollToTop` definition is this: -``` +```csharp [BaseType (typeof (NSObject))] [Model][Protocol] public interface UIScrollViewDelegate { @@ -193,20 +193,19 @@ The above will create a `UIScrollViewCondition` delegate with the signature that was shown above, and if the user does not provide an implementation, the return value will be true. -In addition to the `DefaultValue` attribute, you can also use -the `DefaultValueFromArgument` that -directs the generator to return the value of the specified -parameter in the call or the `NoDefaultValue` parameter that -instructs the generator that there is no default value. +In addition to the [`[DefaultValue]`](#DefaultValueAttribute) attribute, +you can also use the [`[DefaultValueFromArgument]`](#DefaultValueFromArgumentAttribute) +attribute that directs the generator to return the value of the specified +parameter in the call or the [`[NoDefaultValue]`](#NoDefaultValueAttribute) +parameter that instructs the generator that there is no default value. - + - -## BaseTypeAttribute +### BaseTypeAttribute Syntax: -``` +```csharp public class BaseTypeAttribute : Attribute { public BaseTypeAttribute (Type t); @@ -219,7 +218,7 @@ public class BaseTypeAttribute : Attribute { } ``` -### BaseType.Name +#### BaseType.Name You use the `Name` property to control the name that this type will bind to in the Objective-C world. This is typically used to give the C# type a name that is @@ -230,36 +229,36 @@ Example, in the following case we map the Objective-C `NSURLConnection` type to `NSUrlConnection`, as the .NET Framework Design Guidelines use "Url" instead of "URL": -``` +```csharp [BaseType (typeof (NSObject), Name="NSURLConnection")] interface NSUrlConnection { } ``` -The specified name is specified is used as the value for the generated +The specified name is used as the value for the generated `[Register]` attribute in the binding. If `Name` is not specified, the type's short -name is used as the value for the `Register` attribute in the generated +name is used as the value for the `[Register]` attribute in the generated output. +#### BaseType.Events and BaseType.Delegates -### BaseType.Events and BaseType.Delegates - -These properties are used to drive the generation of C#-style Events in the +These properties are used to drive the generation of C#-style events in the generated classes. They are used to link a given class with its Objective-C delegate class. You will encounter many cases where a class uses a delegate class to send notifications and events. For example a `BarcodeScanner` would have a companion `BardodeScannerDelegate` class. The `BarcodeScanner` class would -typically have a "delegate" property that you would assign an instance of +typically have a `Delegate` property that you would assign an instance of `BarcodeScannerDelegate` to, while this works, you might want to expose to your users a C#-like style event interface, and in those cases you would use the -`Events` and `Delegates` properties of the `BaseType` attribute. +`Events` and `Delegates` properties of the [`[BaseType]`](#BaseTypeAttribute) +attribute. These properties are always set together and must have the same number of elements and be kept in sync. The `Delegates` array contains one string for each -weakly-typed delegate that you want to wrap, and the Events array contains one +weakly-typed delegate that you want to wrap, and the `Events` array contains one type for each type that you want to associate with it. -``` +```csharp [BaseType (typeof (NSObject), Delegates=new string [] { "WeakDelegate" }, Events=new Type [] {typeof(UIAccelerometerDelegate)})] @@ -272,23 +271,21 @@ public interface UIAccelerometerDelegate { } ``` - - -### BaseType.KeepRefUntil +#### BaseType.KeepRefUntil If you apply this attribute when new instances of this class are created, the instance of that object will be kept around until the method referenced by the `KeepRefUntil` has been invoked. This is useful to improve the usability of your APIs, when you do not want your user to keep a reference to an object around to use your code. The value of this property is the name of a method in the -`Delegate` class, so you must use this in combination with the Events and +`Delegate` class, so you must use this in combination with the `Events` and `Delegates` properties as well. The following example show how this is used by `UIActionSheet` in Xamarin.iOS: -``` +```csharp [BaseType (typeof (NSObject), KeepRefUntil="Dismissed")] [BaseType (typeof (UIView), KeepRefUntil="Dismissed", @@ -305,18 +302,17 @@ public interface UIActionSheetDelegate { } ``` - + -## DesignatedDefaultCtorAttribute +### DesignatedDefaultCtorAttribute When this attribute is applied to the interface definition it will generate -a `[DesignatedInitializer]` attribute on the default (generated) constructor +a `[DesignatedInitializer]` attribute on the default (generated) constructor, which maps to the `init` selector. + - - -## DisableDefaultCtorAttribute +### DisableDefaultCtorAttribute When this attribute is applied to the interface definition it will prevent the generator from producing the default constructor. @@ -324,10 +320,9 @@ the generator from producing the default constructor. Use this attribute when you need the object to be initialized with one of the other constructors in the class. - - + -## PrivateDefaultCtorAttribute +### PrivateDefaultCtorAttribute When this attribute is applied to the interface definition it will flag the default constructor as private. This means that you can still instantiate object @@ -335,7 +330,8 @@ of this class internally from your extension file, but it just wont be accessible to users of your class. -## CategoryAttribute + +### CategoryAttribute Use this attribute on a type definition to bind Objective-C categories and to expose those as C# extension methods to mirror the @@ -352,24 +348,24 @@ extension methods. This is what a category would look like in Objective-C: -``` +```objc @interface UIView (MyUIViewExtension) -(void) makeBackgroundRed; @end ``` -The above example if found on a library would extend instances of +The above example is found on a library that would extend instances of `UIView` with the method `makeBackgroundRed`. -To bind those, you can use the `[Category]` attribute on -an interface definition. When using the `Category` attribute, the -meaning of the `[BaseType]` attribute changes from being -used to specify the base class to extend, to be the type to extend. +To bind those, you can use the [`[Category]`](#CategoryAttribute) attribute on +an interface definition. When using the [`[Category]`](#CategoryAttribute) attribute, the +meaning of the [`[BaseType]`](#BaseTypeAttribute) attribute changes from being +used to specify the base class to extend, to being the type to extend. The following shows how the `UIView` extensions are bound and turned into C# extension methods: -``` +```csharp [BaseType (typeof (UIView))] [Category] interface MyUIViewExtension { @@ -380,7 +376,7 @@ interface MyUIViewExtension { The above will create a `MyUIViewExtension` a class that contains the `MakeBackgroundRed` extension method. This means -that you can now call "MakeBackgroundRed" on any `UIView` subclass, +that you can now call `MakeBackgroundRed` on any `UIView` subclass, giving you the same functionality you would get on Objective-C. In some cases you will find **static** members inside categories like in the following example: @@ -405,7 +401,7 @@ interface FooObject_Extensions { } ``` -This is incorrect because in order to use the `BoolMethod` extension you need an instance of `FooObject` but you are binding an ObjC **static** extension, this is a side effect due to the fact of how C# extension methods are implemented. +This is incorrect because to use the `BoolMethod` extension you need an instance of `FooObject` but you are binding an ObjC **static** extension, this is a side effect due to the fact of how C# extension methods are implemented. The only way to use the above definitions is by the following ugly code: @@ -425,19 +421,20 @@ interface FooObject { } ``` -We will issue a warning (BI1117) whenever we find a `[Static]` member inside a `[Category]` definition. If you really want to have `[Static]` members inside your `[Category]` definitions you can silence the warning by using `[Category (allowStaticMembers: true)]` or by decorating either your member or `[Category]` interface definition with `[Internal]`. +We will issue a warning (BI1117) whenever we find a [`[Static]`](#StaticAttribute) member inside a [`[Category]`](#CategoryAttribute) definition. If you really want to have [`[Static]`](#StaticAttribute) members inside your [`[Category]`](#CategoryAttribute) definitions you can silence the warning by using `[Category (allowStaticMembers: true)]` or by decorating either your member or [`[Category]`](#CategoryAttribute) interface definition with [`[Internal]`](#InternalAttribute). - -## StaticAttribute + + +### StaticAttribute When this attribute is applied to a class it will just generate a static -class, one that does not derive from `NSObject` so the `[BaseType]` attribute is -ignored. Static classes are used to host C public variables that you want to -expose. +class, one that does not derive from `NSObject`, so the +[`[BaseType]`](#BaseTypeAttribute) attribute is ignored. Static classes are +used to host C public variables that you want to expose. For example: -``` +```csharp [Static] interface CBAdvertisement { [Field ("CBAdvertisementDataServiceUUIDsKey")] @@ -446,20 +443,17 @@ interface CBAdvertisement { Will generate a C# class with the following API: -``` +```csharp public partial class CBAdvertisement { public static NSString DataServiceUUIDsKey { get; } } ``` - -# Model Definitions - -###Protocol definitions/Model +## Protocol/Model definitions Models are typically used by protocol implementation. They differ in that the runtime will only register with -Objective-C the methods that actually have been overwritten. +Objective-C the methods that actually have been overwritten. Otherwise, the method will not be registered. This in general means that when you subclass a class that @@ -469,22 +463,23 @@ exception, you are supposed to implement the entire behavior on your subclass for any methods you override. -## AbstractAttribute + +### AbstractAttribute By default, members that are part of a protocol are not mandatory. This allows users to create a subclass of the `Model` object by merely deriving from the class in C# and overriding only the methods they care about. Sometimes the Objective-C contract requires that the user provides an implementation for this -method (those are flagged with the @required directive in Objective-C). In those -cases, you should flag those methods with the `Abstract` attribute. +method (those are flagged with the `@required` directive in Objective-C). In those +cases, you should flag those methods with the `[Abstract]` attribute. -The `Abstract` attribute can be applied to either methods or properties and -causes the generator to flag the generated member as "abstract" and the class to +The `[Abstract]` attribute can be applied to either methods or properties and +causes the generator to flag the generated member as abstract and the class to be an abstract class. The following is taken from Xamarin.iOS: -``` +```csharp [BaseType (typeof (NSObject))] [Model][Protocol] public interface UITableViewDataSource { @@ -494,17 +489,16 @@ public interface UITableViewDataSource { } ``` - - + -## DefaultValueAttribute +### DefaultValueAttribute Specifies the default value to be returned by a model method if the user does not provide a method for this particular method in the Model object Syntax: -``` +```csharp public class DefaultValueAttribute : Attribute { public DefaultValueAttribute (object o); public object Default { get; set; } @@ -518,7 +512,7 @@ value to a lambda that can respond true or false, the default value return in this case would be false, the value that we specified in the `DefaultValue` attribute: -``` +```csharp [BaseType (typeof (NSObject))] [Model][Protocol] interface CameraDelegate { @@ -530,22 +524,20 @@ interface CameraDelegate { If the user sets a handler in the imaginary class, then this value would be ignored: -``` +```csharp var camera = new Camera (); camera.ShouldUploadToServer = (camera, action) => return SomeDecision (); ``` +See also: [`[NoDefaultValue]`](#NoDefaultValueAttribute), [`[DefaultValueFromArgument]`](#DefaultValueFromArgumentAttribute). + -See -also: [NoDefaultValueAttribute](#NoDefaultValueAttribute), [DefaultValueFromArgumentAttribute](#DefaultValueFromArgumentAttribute). - - -## DefaultValueFromArgumentAttribute +### DefaultValueFromArgumentAttribute Syntax: -``` +```csharp public class DefaultValueFromArgumentAttribute : Attribute { public DefaultValueFromArgumentAttribute (string argument); public string Argument { get; } @@ -558,7 +550,7 @@ if the user did not provide his own method or lambda. Example: -``` +```csharp [BaseType (typeof (NSObject))] [Model][Protocol] public interface NSAnimationDelegate { @@ -572,17 +564,15 @@ the C# events/properties, and did not set `NSAnimation.ComputeAnimationCurve` to method or lambda, the return value would be the value passed in the progress parameter. +See also: [`[NoDefaultValue]`](#NoDefaultValueAttribute), [`[DefaultValue]`](#DefaultValueAttribute) - -See also: [NoDefaultValueAttribute](#NoDefaultValueAttribute), [DefaultValueAttribute](#DefaultValueAttribute) - -## IgnoredInDelegateAttribute +### IgnoredInDelegateAttribute Sometimes it makes sense not to expose an event or delegate property from a Model class into the host class so adding this attribute will instruct the generator to avoid the generation of any method decorated with it. -``` +```csharp [BaseType (typeof (UINavigationControllerDelegate))] [Model][Protocol] public interface UIImagePickerControllerDelegate { @@ -594,15 +584,14 @@ public interface UIImagePickerControllerDelegate { } ``` - -## DelegateNameAttribute +### DelegateNameAttribute This attribute is used in Model methods that return values to set the name of the delegate signature to use. Example: -``` +```csharp [BaseType (typeof (NSObject))] [Model][Protocol] public interface NSAnimationDelegate { @@ -614,11 +603,11 @@ public interface NSAnimationDelegate { With the above definition, the generator will produce the following public declaration: -``` +```csharp public delegate float NSAnimationProgress (MonoMac.AppKit.NSAnimation animation, float progress); ``` -## DelegateApiNameAttribute +### DelegateApiNameAttribute This attribute is used to allow the generator to change the name of the property generated in the host class. Sometimes it is useful when the name of the FooDelegate class method @@ -630,7 +619,7 @@ class with a better given name. Example: -``` +```csharp [BaseType (typeof (NSObject))] [Model][Protocol] public interface NSAnimationDelegate { @@ -642,22 +631,23 @@ public interface NSAnimationDelegate { With the above definition, the generator will produce the following public declaration in the host class: -``` +```csharp public Func ComputeAnimationCurve { get; set; } ``` + -## EventArgsAttribute +### EventArgsAttribute For events that take more than one parameter (in Objective-C the convention is that the first parameter in a delegate class is the instance of the sender object) you must provide the name that you would like for the generated -EventArgs class to be. This is done with the `EventArgs` attribute on the method +EventArgs class to be. This is done with the `[EventArgs]` attribute on the method declaration in your `Model` class. For example: -``` +```csharp [BaseType (typeof (UINavigationControllerDelegate))] [Model][Protocol] public interface UIImagePickerControllerDelegate { @@ -669,7 +659,7 @@ public interface UIImagePickerControllerDelegate { The above declaration will generate a `UIImagePickerImagePickedEventArgs` class that derives from EventArgs and packs both parameters, the `UIImage` and the `NSDictionary`. The generator produces this: -``` +```csharp public partial class UIImagePickerImagePickedEventArgs : EventArgs { public UIImagePickerImagePickedEventArgs (UIImage image, NSDictionary editingInfo); public UIImage Image { get; set; } @@ -677,24 +667,24 @@ public partial class UIImagePickerImagePickedEventArgs : EventArgs { } ``` -It then exposes the following in the UIImagePickerController class: +It then exposes the following in the `UIImagePickerController` class: -``` +```csharp public event EventHandler FinishedPickingImage { add; remove; } ``` - -## EventNameAttribute + +### EventNameAttribute This attribute is used to allow the generator to change the name of an event or property generated in the class. Sometimes it is useful when the name of the -`Model` class method makes sense for the model class, but would look odd in the +Model class method makes sense for the model class, but would look odd in the originating class as an event or property. For example, the `UIWebView` uses the following bit from the `UIWebViewDelegate`: -``` +```csharp [Export ("webViewDidFinishLoad:"), EventArgs ("UIWebView"), EventName ("LoadFinished")] void LoadingFinished (UIWebView webView); ``` @@ -702,17 +692,16 @@ void LoadingFinished (UIWebView webView); The above exposes `LoadingFinished` as the method in the `UIWebViewDelegate`, but `LoadFinished` as the event to hook up to in a `UIWebView`: -``` +```csharp var webView = new UIWebView (...); webView.LoadFinished += delegate { Console.WriteLine ("done!"); } ``` - - + -## ModelAttribute +### ModelAttribute -When you apply the `Model` attribute to a type definition in your contract API, +When you apply the `[Model]` attribute to a type definition in your contract API, the runtime will generate special code that will only surface invocations to methods in the class if the user has overwritten a method in the class. This attribute is typically applied to all APIs that wrap an Objective-C delegate @@ -741,21 +730,18 @@ It's possible to customize the name of the Objective-C class in two ways: It's recommended to use `AutoGeneratedName = true` (this may become the default in the future). - - - -## NoDefaultValueAttribute - + +### NoDefaultValueAttribute Specifies that the method on the model does not provide a default return value. This works with the Objective-C runtime by responding -"false" to the Objective-C runtime request to determine if the +`false` to the Objective-C runtime request to determine if the specified selector is implemented in this class. -``` +```csharp [BaseType (typeof (NSObject))] [Model][Protocol] interface CameraDelegate { @@ -764,11 +750,11 @@ interface CameraDelegate { } ``` -See also: [DefaultValueAttribute](#DefaultValueAttribute) and -[DefaultValueAttribute](#DefaultValueAttribute). +See also: [`[DefaultValue]`](#DefaultValueAttribute), [`[DefaultValueFromArgument]`](#DefaultValueFromArgumentAttribute) + -# Protocols +## Protocols The Objective-C protocol concept does not really exist in C#. Protocols are similar to C# interfaces but they differ in that not all of the methods and @@ -776,9 +762,9 @@ properties declared in a protocol must be implemented by the class that adopts it. Instead some of the methods and properties are optional. Some protocols are generally used as Model classes, those should be bound -using the Model attribute. +using the [`[Model]`](#ModelAttribute) attribute. -``` +```csharp [BaseType (typeof (NSObject))] [Model, Protocol] interface MyProtocol { @@ -793,13 +779,13 @@ interface MyProtocol { } ``` -Starting with MonoTouch 7.0 a new and improved protocol +Starting with Xamarin.iOS 7.0 a new and improved protocol binding functionality has been incorporated. Any definition that contains the `[Protocol]` attribute will actually generate three supporting classes that vastly improve the way that you consume protocols: -``` +```csharp // Full method implementation, contains all methods class MyProtocol : IMyProtocol { public void Say (string msg); @@ -841,7 +827,7 @@ you will need to write skeleton empty interfaces in your API definition. If you want to use the MyProtocol in an API, you would need to do this: -``` +```csharp [BaseType (typeof (NSObject))] [Model, Protocol] interface MyProtocol { @@ -868,12 +854,12 @@ The above is needed because at binding time the `IMyProtocol` would not exist, that is why you need to provide an empty interface. -## Adopting Protocol Generated Interfaces +### Adopting protocol-generated interfaces Whenever you implement one of the interfaces generated for the protocols, like this: -``` +```csharp class MyDelegate : NSObject, IUITableViewDelegate { nint IUITableViewDelegate.GetRowHeight (nint row) { return 1; @@ -884,7 +870,7 @@ class MyDelegate : NSObject, IUITableViewDelegate { The implementation for the interface methods automatically gets exported with the proper name, so it is equivalent to this: -``` +```csharp class MyDelegate : NSObject, IUITableViewDelegate { [Export ("getRowHeight:")] nint IUITableViewDelegate.GetRowHeight (nint row) { @@ -896,16 +882,16 @@ class MyDelegate : NSObject, IUITableViewDelegate { It does not matter if the interface is implemented implicitly or explicitly. -## Protocol Inlining +### Protocol inlining While you bind existing Objective-C types that have been declared as adopting a protocol, you will want to inline the protocol directly. To do this, merely -declare your protocol as an interface without any `[BaseType]` attribute and list -the protocol in the list of base interfaces for your interface. +declare your protocol as an interface without any [`[BaseType]`](#BaseTypeAttribute) +attribute and list the protocol in the list of base interfaces for your interface. Example: -``` +```csharp interface SpeakProtocol { [Export ("say:")] void Say (string msg); @@ -918,18 +904,14 @@ interface Robot : SpeakProtocol { } ``` - - -# Member Definitions +## Member definitions The attributes in this section are applied to individual members of a type: properties and method declarations. - - -## AlignAttribute +### AlignAttribute Used to specify the alignment value for property return types. Certain properties take pointers to addresses that must be aligned at certain boundaries @@ -940,22 +922,20 @@ use the alignment value. This is typically used with the `OpenTK.Vector4` and Example: -``` +```csharp public interface GLKBaseEffect { [Export ("constantColor")] Vector4 ConstantColor { [Align (16)] get; set; } } ``` - - -## AppearanceAttribute +### AppearanceAttribute -The `Appearance` attribute is limited to iOS5 where the Appearance manager was +The `[Appearance]` attribute is limited to iOS 5, where the Appearance manager was introduced. -The `Appearance` attribute can be applied to any method or property that +The `[Appearance]` attribute can be applied to any method or property that participate in the `UIAppearance` framework. When this attribute is applied to a method or property in a class, it will direct the binding generator to create a strongly-typed appearance class that is used to style all the instances of this @@ -963,7 +943,7 @@ class, or the instances that match certain criteria. Example: -``` +```csharp public interface UIToolbar { [Since (5,0)] [Export ("setBackgroundImage:forToolbarPosition:barMetrics:")] @@ -979,7 +959,7 @@ public interface UIToolbar { The above would generate the following code in UIToolbar: -``` +```csharp public partial class UIToolbar { public partial class UIToolbarAppearance : UIView.UIViewAppearance { public virtual void SetBackgroundImage (UIImage backgroundImage, UIToolbarPosition position, UIBarMetrics barMetrics); @@ -990,10 +970,9 @@ public partial class UIToolbar { } ``` +### AutoReleaseAttribute (Xamarin.iOS 5.4) -## AutoReleaseAttribute (Xamarin.iOS 5.4) - -Use the `AutoReleaseAttribute` on methods and properties to wrap the method +Use the `[AutoReleaseAttribute]` on methods and properties to wrap the method invocation to the method in an `NSAutoReleasePool`. In Objective-C there are some methods that return values that are added to @@ -1010,10 +989,9 @@ as your thread did not return control to the main loop. Uf your thread was some sort of background downloader that is always alive and waiting for work, the images would never be released. +### ForcedTypeAttribute -## ForcedTypeAttribute - -The `ForcedTypeAttribute` is used to enforce the creation of a managed type even +The `[ForcedTypeAttribute]` is used to enforce the creation of a managed type even if the returned unmanaged object does not match the type described in the binding definition. @@ -1027,10 +1005,10 @@ It clearly states that it will return an `NSURLSessionDownloadTask` instance, bu `NSURLSessionDownloadTask`. Since we are in a type-safe context an `InvalidCastException` will happen. -In order to comply with the header description and avoid the `InvalidCastException`, the -`ForcedTypeAttribute` is used. +To comply with the header description and avoid the `InvalidCastException`, the +`[ForcedTypeAttribute]` is used. -``` +```csharp [BaseType (typeof (NSObject), Name="NSURLSession")] interface NSUrlSession { @@ -1040,24 +1018,25 @@ interface NSUrlSession { } ``` -The `ForcedTypeAttribute` also accepts a boolean value named `Owns` that is `false` +The `[ForcedTypeAttribute]` also accepts a boolean value named `Owns` that is `false` by default `[ForcedType (owns: true)]`. The owns parameter is used to follow the [Ownership Policy](https://developer.apple.com/library/content/documentation/CoreFoundation/Conceptual/CFMemoryMgmt/Concepts/Ownership.html) for **Core Foundation** objects. -The `ForcedTypeAttribute` is only valid on `parameters`, `properties` and `return value`. - +The `[ForcedTypeAttribute]` is only valid on parameters, properties, +and return value. + -## BindAsAttribute +### BindAsAttribute -The `BindAsAttribute` allows binding `NSNumber`, `NSValue` and `NSString`(enums) into more accurate C# types. The attribute can be used to create better, more accurate, .NET API over the native API. +The `[BindAsAttribute]` allows binding `NSNumber`, `NSValue` and `NSString`(enums) into more accurate C# types. The attribute can be used to create better, more accurate, .NET API over the native API. -You can decorate methods (on return value), parameters and properties with `BindAs`. The only restriction is that your member **must not** be inside a `[Protocol]` or `[Model]` interface. +You can decorate methods (on return value), parameters and properties with `BindAs`. The only restriction is that your member **must not** be inside a `[Protocol]` or [`[Model]`](#ModelAttribute) interface. For example: -``` +```csharp [return: BindAs (typeof (bool?))] [Export ("shouldDrawAt:")] NSNumber ShouldDraw ([BindAs (typeof (CGRect))] NSValue rect); @@ -1065,7 +1044,7 @@ NSNumber ShouldDraw ([BindAs (typeof (CGRect))] NSValue rect); Would output: -``` +```csharp [Export ("shouldDrawAt:")] bool? ShouldDraw (CGRect rect) { ... } ``` @@ -1078,7 +1057,7 @@ The current supported encapsulation types are: * `NSNumber` * `NSString` -### NSValue +#### NSValue The following C# data types are supported to be encapsulated from/into `NSValue`: @@ -1100,7 +1079,7 @@ The following C# data types are supported to be encapsulated from/into `NSValue` * CMTimeMapping * CATransform3D -### NSNumber +#### NSNumber The following C# data types are supported to be encapsulated from/into `NSNumber`: @@ -1120,11 +1099,11 @@ The following C# data types are supported to be encapsulated from/into `NSNumber * nuint * Enums -### NSString +#### NSString -`[BindAs]` works in conjuntion with [enums backed by a NSString constant](#enum-attributes) so you can create better .NET API, for example: +[`[BindAs]`](#BindAsAttribute) works in conjuntion with [enums backed by a NSString constant](#enum-attributes) so you can create better .NET API, for example: -``` +```csharp [BindAs (typeof (CAScroll))] [Export ("supportedScrollMode")] NSString SupportedScrollMode { get; set; } @@ -1132,18 +1111,18 @@ NSString SupportedScrollMode { get; set; } Would output: -``` +```csharp [Export ("supportedScrollMode")] CAScroll SupportedScrollMode { get; set; } ``` -We will handle the `enum` <-> `NSString` conversion only if the provided enum type to `[BindAs]` is [backed by a NSString constant](#enum-attributes). +We will handle the `enum` <-> `NSString` conversion only if the provided enum type to [`[BindAs]`](#BindAsAttribute) is [backed by a NSString constant](#enum-attributes). -### Arrays +#### Arrays -`[BindAs]` also supports arrays of any of the supported types, you can have the following API definition as an example: +[`[BindAs]`](#BindAsAttribute) also supports arrays of any of the supported types, you can have the following API definition as an example: -``` +```csharp [return: BindAs (typeof (CAScroll []))] [Export ("getScrollModesAt:")] NSString [] GetScrollModes ([BindAs (typeof (CGRect []))] NSValue [] rects); @@ -1151,47 +1130,48 @@ NSString [] GetScrollModes ([BindAs (typeof (CGRect []))] NSValue [] rects); Would output: -``` +```csharp [Export ("getScrollModesAt:")] CAScroll? [] GetScrollModes (CGRect [] rects) { ... } ``` The `rects` parameter will be encapsulated into a `NSArray` that contains an `NSValue` for each `CGRect` and in return you will get an array of `CAScroll?` which has been created using the values of the returned `NSArray` containing `NSStrings`. + -## BindAttribute +### BindAttribute -The `Bind` attribute has two uses one when applied to a method or property +The `[Bind]` attribute has two uses one when applied to a method or property declaration, and another one when applied to the individual getter or setter in a property. -When used for a method or property, the effect of the Bind attribute is to +When used for a method or property, the effect of the `[Bind]` attribute is to generate a method that invokes the specified selector. But the resulting -generated method is not decorated with the `[Export]` attribute, which means that +generated method is not decorated with the [`[Export]`](#ExportAttribute) attribute, which means that it can not participate in method overriding. This is typically used in -combination with the `Target` attribute for implementing Objective-C extension +combination with the `[Target]` attribute for implementing Objective-C extension methods. For example: -``` +```csharp public interface UIView { [Bind ("drawAtPoint:withFont:")] SizeF DrawString ([Target] string str, CGPoint point, UIFont font); } ``` -When used in a getter or setter, the `Bind` attribute is used to alter the +When used in a getter or setter, the `[Bind]` attribute is used to alter the defaults inferred by the code generator when generating the getter and setter Objective-C selector names for a property. By default when you flag a property -with the name "fooBar", the generator would generate a "fooBar" export for the -getter and "setFooBar:" for the setter. In a few cases, Objective-C does not -follow this convention, usually they change the getter name to be "isFooBar". +with the name `fooBar`, the generator would generate a `fooBar` export for the +getter and `setFooBar:` for the setter. In a few cases, Objective-C does not +follow this convention, usually they change the getter name to be `isFooBar`. You would use this attribute to inform the generator of this. For example: -``` +```csharp // Default behavior [Export ("active")] bool Active { get; set; } @@ -1201,10 +1181,9 @@ bool Active { get; set; } bool Visible { [Bind ("isVisible")] get; set; } ``` - + - -## AsyncAttribute +### AsyncAttribute Only available on Xamarin.iOS 6.3 and newer. @@ -1217,9 +1196,9 @@ this to a method, the binding generator will generate a version of that method with the suffix `Async`. If the callback takes no parameters, the return value will be a `Task`, if the callback takes a parameter, the result will be a -Task<T>. +`Task`. -``` +```csharp [Export ("upload:complete:")] [Async] void LoadFile (string file, NSAction complete) @@ -1227,7 +1206,7 @@ void LoadFile (string file, NSAction complete) The following will generate this async method: -``` +```csharp Task LoadFileAsync (string file); ``` @@ -1236,7 +1215,7 @@ should set the `ResultType` or `ResultTypeName` to specify the desired name of the generated type which will hold all the properties. -``` +```csharp delegate void OnComplete (string [] files, nint byteCount); [Export ("upload:complete:")] @@ -1245,10 +1224,10 @@ void LoadFiles (string file, OnComplete complete) ``` The following will generate this async method, where -`FileLoading` contains properties to access both "files" and -"byteCount": +`FileLoading` contains properties to access both `files` and +`byteCount`: -``` +```csharp Task LoadFile (string file); ``` @@ -1257,7 +1236,7 @@ the generated `Async` method will check if the value is not null, and if that is the case, the generated async method will set the task exception. -``` +```csharp [Export ("upload:onComplete:")] [Async] void Upload (string file, Action onComplete); @@ -1265,40 +1244,35 @@ void Upload (string file, Action onComplete); The above generates the following async method: -``` +```csharp Task UploadAsync (string file); ``` And on error, the resulting Task will have the exception set to an `NSErrorException` that wraps the resulting `NSError`. -### AsyncAttribute.ResultType - - +#### AsyncAttribute.ResultType Use this property to specify the value for the returning `Task` object. This parameter takes an existing type, thus it needs to be defined in one of your core api definitions. - -### AsyncAttribute.ResultTypeName +#### AsyncAttribute.ResultTypeName Use this property to specify the value for the returning `Task` object. This parameter takes the name of your desired type name, the generator will produce a series of properties, one for each parameter that the callback takes. - -### AsyncAttribute.MethodName - - +#### AsyncAttribute.MethodName Use this property to customize the name of the generated async methods. The default is to use the name of the method and append the text "Async", you can use this to change this default. + -## DesignatedInitializerAttribute +### DesignatedInitializerAttribute When this attribute is applied to a constructor it will generate the same `[DesignatedInitializer]` in the final platform assembly. This is to help @@ -1306,8 +1280,9 @@ the IDE indicate which constructor should be used in subclasses. This should map to ObjC/clang use of `__attribute__((objc_designated_initializer))`. + -## DisableZeroCopyAttribute +### DisableZeroCopyAttribute This attribute is applied to string parameters or string properties and instructs the code generator to not use the zero-copy string marshaling for @@ -1317,9 +1292,9 @@ zero-copy string marshaling using either the `--zero-copy` command line option or setting the assembly-level attribute `ZeroCopyStringsAttribute`. This is necessary in cases where the property is declared in Objective-C to -be a "retain" or "assign" property instead of a "copy" property. These typically +be a `retain` or `assign` property instead of a `copy` property. These typically happen in third-party libraries that have been wrongly "optimized" by -developers. In general, "retain" or "assign" `NSString` properties are incorrect +developers. In general, `retain` or `assign` `NSString` properties are incorrect since `NSMutableString` or user-derived classes of `NSString` might alter the contents of the strings without the knowledge of the library code, subtly breaking the application. Typically this happens due to premature @@ -1327,47 +1302,45 @@ optimization. The following shows two such properties in Objective-C: -``` +```csharp @property(nonatomic,retain) NSString *name; @property(nonatomic,assign) NSString *name2; ``` - - + -## DisposeAttribute +### DisposeAttribute -When you apply the `DisposeAttribute` to a class, you provide a code snippet +When you apply the `[DisposeAttribute]` to a class, you provide a code snippet that will be added to the `Dispose()` method implementation of the class. Since the `Dispose` method is automatically generated by the `bmac-native` and `btouch-native` -tools, you need to use the `Dispose` attribute to inject some code in the +tools, you need to use the `[Dispose]` attribute to inject some code in the generated `Dispose` method implementation. For example: -``` +```csharp [BaseType (typeof (NSObject))] [Dispose ("if (OpenConnections > 0) CloseAllConnections ();")] interface DatabaseConnection { } ``` - - + -## ExportAttribute +### ExportAttribute -The `Export` attribute is used to flag a method or property to be exposed to +The `[Export]` attribute is used to flag a method or property to be exposed to the Objective-C runtime. This attribute is shared between the binding tool and the actual Xamarin.iOS and Xamarin.Mac runtimes. For methods, the parameter is passed verbatim to the generated code, for properties, a getter and setter Exports are -generated based on the base declaration (see the section on the `BindAttribute` +generated based on the base declaration (see the section on the [`[BindAttribute]`](#BindAttribute) for information on how to alter the behavior of the binding tool). Syntax: -``` +```csharp public enum ArgumentSemantic { None, Assign, Copy, Retain. } @@ -1382,18 +1355,15 @@ public class ExportAttribute : Attribute { } ``` -The [selector](http://developer.apple.com/library/ios/#documentation/cocoa/conceptual/objectivec/Chapters/ocSelectors.html) and it represents the underlying Objective-C name -of the method or property that is being bound. +The [selector](https://developer.apple.com/library/content/documentation/General/Conceptual/DevPedia-CocoaCore/Selector.html) +represents the name of the underlying Objective-C method or property that is +being bound. - +#### ExportAttribute.ArgumentSemantic + -### ExportAttribute.ArgumentSemantic - - - - -## FieldAttribute +### FieldAttribute This attribute is used to expose a C global variable as a field that is loaded on demand and exposed to C# code. Usually this is required to get the @@ -1403,7 +1373,7 @@ as-is by user code. Syntax: -``` +```csharp public class FieldAttribute : Attribute { public FieldAttribute (string symbolName); public FieldAttribute (string symbolName, string libraryName); @@ -1416,7 +1386,7 @@ The `symbolName` is the C symbol to link with. By default this will be loaded from a library whose name is inferred from the namespace where the type is defined. If this is not the library where the symbol is looked up, you should pass the `libraryName` parameter. If you're linking a -static library, use "__Internal" as the `libraryName` parameter. +static library, use `__Internal` as the `libraryName` parameter. The generated properties are always static. @@ -1432,11 +1402,12 @@ Properties flagged with the Field attribute can be of the following types: * `System.IntPtr` * Enums -Setters are not supported for [enums backed by NSString constants](#enum-attributes), but they can be manually bound if needed. +Setters are not supported for [enums backed by NSString constants](#enum-attributes), +but they can be manually bound if needed. Example: -``` +```csharp [Static] interface CameraEffects { [Field ("kCameraEffectsZoomFactorKey", "CameraLibrary")] @@ -1444,13 +1415,12 @@ interface CameraEffects { } ``` + +### InternalAttribute - -## InternalAttribute - -The `Internal` attribute can be applied to methods or properties and it has the -effect of flagging the generated code with the "internal" C# keyword making the +The `[Internal]` attribute can be applied to methods or properties and it has the +effect of flagging the generated code with the `internal` C# keyword making the code only accessible to code in the generated assembly. This is typically used to hide APIs that are too low-level or provide a suboptimal public API that you want to improve upon or for APIs that are not supported by the generator and @@ -1458,14 +1428,14 @@ require some hand-coding. When you design the binding, you would typically hide the method or property using this attribute and provide a different name for the method or property, -and then on your C# complementary support file, you would add a strongly typed +and then on your C# complementary support file, you would add a strongly-typed wrapper that exposes the underlying functionality. For example: -``` +```csharp [Internal] -[Export ("setValue:forKey:"); +[Export ("setValue:forKey:")] void _SetValueForKey (NSObject value, NSObject key); [Internal] @@ -1475,7 +1445,7 @@ NSObject _GetValueForKey (NSObject key); Then, in your supporting file, you could have some code like this: -``` +```csharp public NSObject this [NSObject idx] { get { return _GetValueForKey (idx); @@ -1486,19 +1456,17 @@ public NSObject this [NSObject idx] { } ``` + -## IsThreadStaticAttribute +### IsThreadStaticAttribute This attribute flags the backing field for a property to be annotated with the .NET `[ThreadStatic]` attribute. This is useful if the field is a thread static variable. - +### MarshalNativeExceptions (Xamarin.iOS 6.0.6) - -## MarshalNativeExceptions (Xamarin.iOS 6.0.6) - -This attribute will make a method support native (ObjectiveC) exceptions. +This attribute will make a method support native (Objective-C) exceptions. Instead of calling `objc_msgSend` directly, the invocation will go through a custom trampoline which catches ObjectiveC exceptions and marshals them into managed exceptions. @@ -1508,36 +1476,33 @@ if a signature isn't supported when native linking of an app that uses the binding fails with a missing monotouch_*_objc_msgSend* symbol), but more can be added at request. - - -## NewAttribute +### NewAttribute This attribute is applied to methods and properties to have the generator -generate the "new" keyword in front of the declaration. +generate the `new` keyword in front of the declaration. It is used to avoid compiler warnings when the same method or property name is introduced in a subclass that already existed in a base class. - + - -## NotificationAttribute +### NotificationAttribute You can apply this attribute to fields to have the generator produce a -strongly typed helper Notifications class. +strongly-typed helper Notifications class. This attribute can be used without arguments for notifications that carry no payload, or you can specify a `System.Type` that references another interface in the API definition, typically with the name ending with "EventArgs". The generator will turn the interface into a class that subclasses `EventArgs` and -will include all of the properties listed there. The `[Export]` attribute should +will include all of the properties listed there. The [`[Export]`](#ExportAttribute) attribute should be used in the `EventArgs` class to list the name of the key used to look up the Objective-C dictionary to fetch the value. For example: -``` +```csharp interface MyClass { [Notification] [Field ("MyClassDidStartNotification")] @@ -1548,7 +1513,7 @@ interface MyClass { The above code will generate a nested class `MyClass.Notifications` with the following methods: -``` +```csharp public class MyClass { [..] public Notifications { @@ -1560,10 +1525,10 @@ public class MyClass { Users of your code can then easily subscribe to notifications posted to the -[NSDefaultCenter](/api/property/Foundation.NSNotificationCenter.DefaultCenter/) +[NSDefaultCenter](https://developer.xamarin.com/api/property/Foundation.NSNotificationCenter.DefaultCenter/) by using code like this: -``` +```csharp var token = MyClass.Notifications.ObserverDidStart ((notification) => { Console.WriteLine ("Observed the 'DidStart' event!"); }); @@ -1571,7 +1536,7 @@ var token = MyClass.Notifications.ObserverDidStart ((notification) => { Or to set a specific object to observe. If you pass `null` to `objectToObserve` this method will behave just like its other peer. -``` +```csharp var token = MyClass.Notifications.ObserverDidStart (objectToObserve, (notification) => { Console.WriteLine ("Observed the 'DidStart' event on objectToObserve!"); }); @@ -1580,16 +1545,15 @@ var token = MyClass.Notifications.ObserverDidStart (objectToObserve, (notificati The returned value from `ObserveDidStart` can be used to easily stop receiving notifications, like this: -``` +```csharp token.Dispose (); ``` - -Or you can call [NSNotification.DefaultCenter.RemoveObserver](/api/member/Foundation.NSNotificationCenter.RemoveObserver/p/Foundation.NSObject//) +Or you can call [NSNotification.DefaultCenter.RemoveObserver](https://developer.xamarin.com/api/member/Foundation.NSNotificationCenter.RemoveObserver/p/Foundation.NSObject//) and pass the token. If your notification contains parameters, you should specify a helper `EventArgs` interface, like this: -``` +```csharp interface MyClass { [Notification (typeof (MyScreenChangedEventArgs)] [Field ("MyClassScreenChangedNotification")] @@ -1612,8 +1576,8 @@ interface MyScreenChangedEventArgs { The above will generate a `MyScreenChangedEventArgs` class with the `ScreenX` and `ScreenY` properties that will fetch the data from the -[NSNotification.UserInfo](/api/property/Foundation.NSNotification.UserInfo/) -dictionary using the keys **ScreenXKey** and **ScreenYKey** +[NSNotification.UserInfo](https://developer.xamarin.com/api/property/Foundation.NSNotification.UserInfo/) +dictionary using the keys `ScreenXKey` and `ScreenYKey` respectively and apply the proper conversions. The `[ProbePresence]` attribute is used for the generator to probe if the key is set in the `UserInfo`, instead of trying to extract the value. This is used for @@ -1622,7 +1586,7 @@ boolean values). This allows you to write code like this: -``` +```csharp var token = MyClass.NotificationsObserveScreenChanged ((notification) => { Console.WriteLine ("The new screen dimensions are {0},{1}", notification.ScreenX, notification.ScreenY); }); @@ -1630,7 +1594,7 @@ var token = MyClass.NotificationsObserveScreenChanged ((notification) => { In some cases, there is no constant associated with the value passed on the dictionary. Apple sometimes uses public symbol constants and -sometimes uses string constants. By default the `[Export]` attribute +sometimes uses string constants. By default the [`[Export]`](#ExportAttribute) attribute in your provided `EventArgs` class will use the specified name as a public symbol to be looked up at runtime. If this is not the case, and instead it is supposed to be looked up as a string constant then @@ -1639,14 +1603,14 @@ pass the `ArgumentSemantic.Assign` value to the Export attribute. **New in Xamarin.iOS 8.4** Sometimes, notifications will begin life without any arguments, so the -use of `[Notification]` without arguments is acceptable. But +use of [`[Notification]`](#NotificationAttribute) without arguments is acceptable. But sometimes, parameters to the notification will be introduced. To support this scenario, the attribute can be applied more than once. If you are developing a binding, and you want to avoid breaking existing user code, you would turn an existing notification from: -``` +```csharp interface MyClass { [Notification] [Field ("MyClassScreenChangedNotification")] @@ -1656,7 +1620,7 @@ interface MyClass { Into a version that lists the notification attribute twice, like this: -``` +```csharp interface MyClass { [Notification] [Notification (typeof (MyScreenChangedEventArgs)] @@ -1665,24 +1629,25 @@ interface MyClass { } ``` + -## NullAllowedAttribute +### NullAllowedAttribute When this is applied to a property it flags the property as allowing the -value null to be assigned to it. This is only valid for reference types. +value `null` to be assigned to it. This is only valid for reference types. When this is applied to a parameter in a method signature it indicates that the specified parameter can be null and that no check should be performed for -passing null values. +passing `null` values. If the reference type does not have this attribute, the binding tool will generate a check for the value being assigned before passing it to Objective-C and will generate a check that will throw an `ArgumentNullException` if the value -assigned is null. +assigned is `null`. For example: -``` +```csharp // In properties [NullAllowed] @@ -1692,47 +1657,40 @@ UIImage IconFile { get; set; } void SetImage ([NullAllowed] UIImage image, State forState); ``` -## OverrideAttribute + -Use this attribute to instruct the binding generator that the binding for -this particular method should be flagged with an "override" keyword. - - +### OverrideAttribute +Use this attribute to instruct the binding generator that the binding for +this particular method should be flagged with an `override` keyword. -## PreSnippetAttribute +### PreSnippetAttribute You can use this attribute to inject some code to be inserted after the input -parameters have been validated, but before the code calls into Objective-C +parameters have been validated, but before the code calls into Objective-C. Example: -``` +```csharp [Export ("demo")] [PreSnippet ("var old = ViewController;")] void Demo (); ``` - - - -## PrologueSnippetAttribute +### PrologueSnippetAttribute You can use this attribute to inject some code to be inserted before any of the parameters are validated in the generated method. Example: -``` +```csharp [Export ("demo")] [Prologue ("Trace.Entry ();")] void Demo (); ``` - - - -## PostGetAttribute +### PostGetAttribute Instructs the binding generator to invoke the specified property from this class to fetch a value from it. @@ -1747,7 +1705,7 @@ a given binding. Example: -``` +```csharp [BaseType (typeof (NSObject))] [Since (4,0)] public interface NSOperation { @@ -1767,26 +1725,20 @@ adding or removing dependencies from the `NSOperation` object, ensuring that we have a graph that represents the actual loaded objects, preventing both memory leaks as well as memory corruption. - - - -## PostSnippetAttribute +### PostSnippetAttribute You can use this attribute to inject some C# source code to be inserted after the code has invoked the underlying Objective-C method Example: -``` +```csharp [Export ("demo")] [PostSnippet ("if (old != null) old.DemoComplete ();")] void Demo (); ``` - - - -## ProxyAttribute +### ProxyAttribute This attribute is applied to return values to flag them as being proxy objects. Some Objective-C APIs return proxy objects that can not be @@ -1794,10 +1746,7 @@ differentiated from user bindings. The effect of this attribute is to flag the object as being a `DirectBinding` object. For a scenario in Xamarin.Mac, you can see the [discussion on this bug](https://bugzilla.novell.com/show_bug.cgi?id=670844). - - - -## RetainListAttribute +### RetainListAttribute Instructs the generator to keep a managed reference to the parameter or remove an internal reference to the parameter. This is used to keep objects @@ -1805,23 +1754,20 @@ referenced. Syntax: -``` +```csharp public class RetainListAttribute: Attribute { public RetainListAttribute (bool doAdd, string listName); } ``` -If the value of "doAdd" is true, then the parameter is added to the +If the value of `doAdd` is true, then the parameter is added to the `__mt_{0}_var List;`. Where `{0}` is replaced with the given `listName`. You must declare this backing field in your complementary partial class to the API. For an example see [foundation.cs](https://github.com/mono/maccore/blob/master/src/foundation.cs) and [NSNotificationCenter.cs](https://github.com/mono/maccore/blob/master/src/Foundation/NSNotificationCenter.cs) - - - -## ReleaseAttribute (Xamarin.iOS 6.0) +### ReleaseAttribute (Xamarin.iOS 6.0) This can be applied to return types to indicate that the generator should call `Release` on the object before returning it. This is only needed when a @@ -1830,7 +1776,7 @@ is the most common scenario) Example: -``` +```csharp [Export ("getAndRetainObject")] [return: Release ()] NSObject GetAndRetainObject (); @@ -1840,59 +1786,53 @@ Additionally this attribute is propagated to the generated code, so that the Xamarin.iOS runtime knows it must retain the object upon returning to Objective-C from such a function. - - -## SealedAttribute +### SealedAttribute Instructs the generator to flag the generated method as sealed. If this attribute is not specified, the default is to generate a virtual method (either a virtual method, an abstract method or an override depending on how other attributes are used). - - + -## StaticAttribute +### StaticAttribute -When the `Static` attribute is applied to a method or property this generates a +When the `[Static]` attribute is applied to a method or property, this generates a static method or property. If this attribute is not specified, then the generator produces an instance method or property. - - -## TransientAttribute +### TransientAttribute Use this attribute to flag properties whose values are transient, that is, -objects that are created temporarily by iOS but are not long lived. When this +objects that are created temporarily by iOS but are not long-lived. When this attribute is applied to a property, the generator does not create a backing field for this property, which means that the managed class does not keep a reference to the object. - - + -## WrapAttribute +### WrapAttribute -In the design of the Xamarin.iOS/Xamarin.Mac bindings, the `Wrap` attribute is used -to wrap a weakly typed object with a strongly typed object. This comes into play -mostly with Objective-C "delegate" objects which are typically declared as being +In the design of the Xamarin.iOS/Xamarin.Mac bindings, the `[Wrap]` attribute is used +to wrap a weakly-typed object with a strongly-typed object. This comes into play +mostly with Objective-C delegate objects which are typically declared as being of type `id` or `NSObject`. The convention used by Xamarin.iOS and Xamarin.Mac is to expose those delegates or data sources as being of type `NSObject` and are named using the convention "Weak" + the name being -exposed. An "id delegate" property from Objective-C would be exposed as an +exposed. An `id delegate` property from Objective-C would be exposed as an `NSObject WeakDelegate { get; set; }` property in the API contract file. But typically the value that is assigned to this delegate is of a strong -type, so we surface the strong type and apply the `Wrap` attribute, this means +type, so we surface the strong type and apply the `[Wrap]` attribute, this means that users can choose to use weak types if they need some fine-control or if -they need to resort to low-level tricks, or they can use the strongly typed +they need to resort to low-level tricks, or they can use the strongly-typed property for most of their work. Example: -``` +```csharp [BaseType (typeof (NSObject))] interface Demo { [Export ("delegate"), NullAllowed] @@ -1912,7 +1852,7 @@ interface DemoDelegate { This is how the user would use the weakly-typed version of the Delegate: -``` +```csharp // The weak case, user has to roll his own class SomeObject : NSObject { [Export ("doDemo")] @@ -1924,26 +1864,25 @@ var demo = new Demo (); demo.WeakDelegate = new SomeObject (); ``` -And this is how the user would use the strongly typed version, notice that +And this is how the user would use the strongly-typed version, notice that the user takes advantage of C#'s type system and is using the override keyword to declare his intent and that he does not have to manually decorate the method -with `Export`, since we did that work in the binding for the user: +with `[Export]`, since we did that work in the binding for the user: -``` +```csharp // This is the strong case, class MyDelegate : DemoDelegate { override void Demo DoDemo () {} } - var strongDemo = new Demo (); demo.Delegate = new MyDelegate (); ``` -Another use of the `Wrap` attribute is to support strongly typed version -of methods. For example: +Another use of the `[Wrap]` attribute is to support strongly-typed version +of methods. For example: -``` +```csharp [BaseType (typeof (NSObject))] interface XyzPanel { [Export ("playback:withOptions:")] @@ -1954,17 +1893,18 @@ interface XyzPanel { } ``` -When the `WrapAttribute` is used inside a `Category` you need to include `This` as -the first argument inside the `Wrap` signature, for example: +When the `[Wrap]` attribute is applied on a method inside a type decorated +with a `[Category]` attribute you need to include `This` as +the first argument since an extension method is being generated. For example: -``` +```csharp [Wrap ("Write (This, image, options?.Dictionary, out error)")] bool Write (CIImage image, CIImageRepresentationOptions options, out NSError error); ``` The members generated by `[Wrap]` are not `virtual` by default, if you need a `virtual` member you can set to `true` the optional `isVirtual` parameter. -``` +```csharp [BaseType (typeof (NSObject))] interface FooExplorer { [Export ("fooWithContentsOfURL:")] @@ -1995,32 +1935,29 @@ enum PersonRelationship { Interface definition: -``` +```csharp // Property definition. - [Export ("presenceType")] - NSString _PresenceType { get; set; } +[Export ("presenceType")] +NSString _PresenceType { get; set; } - PersonRelationship PresenceType { - [Wrap ("PersonRelationshipExtensions.GetValue (_PresenceType)")] - get; - [Wrap ("_PresenceType = value.GetConstant ()")] - set; - } +PersonRelationship PresenceType { + [Wrap ("PersonRelationshipExtensions.GetValue (_PresenceType)")] + get; + [Wrap ("_PresenceType = value.GetConstant ()")] + set; +} ``` - - -# Parameter Attributes +## Parameter attributes This section describes the attributes that you can apply to the parameters in -a method definition as well as the `NullAttribute` that applies to a property as a +a method definition as well as the `[NullAttribute]` that applies to a property as a whole. + -## BlockCallback - - +### BlockCallback This attribute is applied to parameter types in C# delegate declarations to notify the binder that the parameter @@ -2030,16 +1967,15 @@ convention and should marshal it in this way. This is typically used for callbacks that are defined like this in Objective-C: -``` +```csharp typedef returnType (^SomeTypeDefinition) (int parameter1, NSString *parameter2); ``` See also: [CCallback](#CCallback). + -## CCallback - - +### CCallback This attribute is applied to parameter types in C# delegate declarations to notify the binder that the parameter @@ -2049,14 +1985,13 @@ convention and should marshal it in this way. This is typically used for callbacks that are defined like this in Objective-C: - typedef returnType (*SomeTypeDefinition) (int parameter1, NSString *parameter2); +```objc +typedef returnType (*SomeTypeDefinition) (int parameter1, NSString *parameter2); +``` See also: [BlockCallback](#BlockCallback). - -## Params - - +### Params You can use the `[Params]` attribute on the last array parameter of a method definition to have the generator inject a "params" in @@ -2065,19 +2000,24 @@ optional parameters. For example, the following definition: - [Export ("loadFiles:")] - void LoadFiles ([Params]NSUrl [] files); +```csharp +[Export ("loadFiles:")] +void LoadFiles ([Params]NSUrl [] files); +``` Allows the following code to be written: - foo.LoadFiles (new NSUrl (url)); - foo.LoadFiles (new NSUrl (url1), new NSUrl (url2), new NSUrl (url3)); +```csharp +foo.LoadFiles (new NSUrl (url)); +foo.LoadFiles (new NSUrl (url1), new NSUrl (url2), new NSUrl (url3)); +``` This has the added advantage that it does not require users to create an array purely for passing elements. + -## PlainString +### PlainString You can use the `[PlainString]` attribute in front of string parameters to instruct the binding generator to pass the string as a C string, instead of @@ -2089,14 +2029,14 @@ Use `[PlainString]` in those cases. For example, the following Objective-C declarations: -``` +```csharp - (void) setText: (NSString *) theText; - (void) logMessage: (char *) message; ``` Should be bound like this: -``` +```csharp [Export ("setText:")] void SetText (string theText); @@ -2104,10 +2044,7 @@ void SetText (string theText); void LogMessage ([PlainString] string theText); ``` - - - -## RetainAttribute +### RetainAttribute Instructs the generator to keep a reference to the specified parameter. The generator will provide the backing store for this field or you can specify a @@ -2117,11 +2054,11 @@ that Objective-C will only keep this copy of the object. For instance, an API like `SetDisplay (SomeObject)` would use this attribute as it is likely that the SetDisplay could only display one object at a time. If you need to keep track of more than one object (for example, for a Stack-like API) you would use the -`RetainList` attribute. +`[RetainList]` attribute. Syntax: -``` +```csharp public class RetainAttribute { public RetainAttribute (); public RetainAttribute (string wrapName); @@ -2129,10 +2066,8 @@ public class RetainAttribute { } ``` - - -## RetainListAttribute +### RetainListAttribute Instructs the generator to keep a managed reference to the parameter or remove an internal reference to the parameter. This is used to keep objects @@ -2140,29 +2075,25 @@ referenced. Syntax: -``` +```csharp public class RetainListAttribute: Attribute { public RetainListAttribute (bool doAdd, string listName); } ``` -If the value of "doAdd" is true, then the parameter is added to the +If the value of `doAdd` is true, then the parameter is added to the `__mt_{0}_var List`. Where `{0}` is replaced with the given `listName`. You must declare this backing field in your complementary partial class to the API. For an example see [foundation.cs](https://github.com/mono/maccore/blob/master/src/foundation.cs) and [NSNotificationCenter.cs](https://github.com/mono/maccore/blob/master/src/Foundation/NSNotificationCenter.cs) - - - -## TransientAttribute - +### TransientAttribute This attribute is applied to parameters and is only used when transitioning from Objective-C to C#. During those -transitions the various Objective-C NSObjects parameters are +transitions the various Objective-C `NSObject` parameters are wrapped into a managed representation of the object. The runtime will take a reference to the native object and @@ -2190,11 +2121,14 @@ methods on it will throw an exception). If the object passed was not created, or if there was already an outstanding managed representation of the object, -the forced dispose does not take place. +the forced dispose does not take place. + -# Property Attributes +## Property attributes -## NotImplementedAttribute + + +### NotImplementedAttribute This attribute is used to support an Objective-C idiom where a property with a getter is introduced in a base class, and a mutable @@ -2209,7 +2143,7 @@ support the mutable idiom in Objective-C. Example: -``` +```csharp [BaseType (typeof (NSObject))] interface MyString { [Export ("initWithValue:")] @@ -2232,7 +2166,9 @@ interface MyMutableString { } ``` -# Enum Attributes + + +## Enum attributes Mapping `NSString` constants to enum values is a easy way to create better .NET API. It: @@ -2243,7 +2179,7 @@ Mapping `NSString` constants to enum values is a easy way to create better Example: -``` +```csharp enum NSRunLoopMode { [DefaultEnumValue] @@ -2265,33 +2201,33 @@ available to developers even if they are not part of the API. Examples: -``` +```csharp // using the NSString constant in a different API / framework / 3rd party code CallApiRequiringAnNSString (NSRunLoopMode.Default.GetConstant ()); ``` -``` +```csharp // converting the constants from a different API / framework / 3rd party code var constant = CallApiReturningAnNSString (); // back into an enum value CallApiWithEnum (NSRunLoopModeExtensions.GetValue (constant)); ``` -## DefaultEnumValueAttribute +### DefaultEnumValueAttribute You can decorate **one** enum value with this attribute. This will become the constant being returned if the enum value is not known. From the example above: -``` +```csharp var x = (NSRunLoopMode) 99; Call (x.GetConstant ()); // NSDefaultRunLoopMode will be used ``` If no enum value is decorated then a `NotSupportedException` will be thrown. -## ErrorDomainAttribute +### ErrorDomainAttribute Error codes are bound as an enum values. There's generally an error domain for them and it's not always easy to find which one applies (or if one even exists). @@ -2300,7 +2236,7 @@ You can use this attribute to associate the error domain with the enum itself. Example: -``` +```csharp [Native] [ErrorDomain ("AVKitErrorDomain")] public enum AVKitError : nint { @@ -2313,8 +2249,7 @@ Example: You can then call the extension method `GetDomain` to get the domain constant of any error. - -## FieldAttribute +### FieldAttribute This is the same `[Field]` attribute used for constants inside type. It can also be used inside enums to map a value with a specific constant. @@ -2324,23 +2259,23 @@ A `null` value can be used to specify which enum value should be returned if a From the example above: -``` +```csharp var constant = NSRunLoopMode.NewInWatchOS3; // will be null in watchOS 2.x Call (NSRunLoopModeExtensions.GetValue (constant)); // will return 1000 ``` If no `null` value is present then an `ArgumentNullException` will be thrown. -# Global Attributes +## Global attributes Global attributes are either applied using the `[assembly:]` attribute modifier -like the `LinkWithAttribute` or can be used anywhere, like the `Lion` and `Since` +like the [`[LinkWithAttribute]`](#LinkWithAttribute) or can be used anywhere, +like the [`[Lion]`](#SinceAndLionAttributes) and [`[Since]`](#SinceAndLionAttributes) attributes. - - + -## LinkWithAttribute +### LinkWithAttribute This is an assembly-level attribute which allows developers to specify the linking flags required to reuse a bound library without forcing the consumer @@ -2349,7 +2284,7 @@ passed to a library. Syntax: -``` +```csharp // In properties [Flags] public enum LinkTarget { @@ -2380,11 +2315,11 @@ public class LinkWithAttribute : Attribute { This attribute is applied at the assembly level, for example, this is what the [CorePlot bindings](https://github.com/mono/monotouch-bindings/tree/master/CorePlot) use: -``` +```csharp [assembly: LinkWith ("libCorePlot-CocoaTouch.a", LinkTarget.ArmV7 | LinkTarget.ArmV7s | LinkTarget.Simulator, Frameworks = "CoreGraphics QuartzCore", ForceLoad = true)] ``` -When you use the `LinkWith` attribute, the specified `libraryName` is embedded +When you use the `[LinkWith]` attribute, the specified `libraryName` is embedded into the resulting assembly, allowing users to ship a single DLL that contains both the unmanaged dependencies as well as the command line flags necessary to properly consume the library from Xamarin.iOS. @@ -2392,24 +2327,21 @@ properly consume the library from Xamarin.iOS. It's also possible to not provide a `libraryName`, in which case the `LinkWith` attribute can be used to only specify additional linker flags: - ``` csharp +``` csharp [assembly: LinkWith (LinkerFlags = "-lsqlite3")] - ``` - - - +``` -### LinkWithAttribute Constructors +#### LinkWithAttribute constructors These constructors allow you to specify the library to link with and embed into your resulting assembly, the supported targets that the library supports and any optional library flags that are necessary to link with the library. -Note that the LinkTarget argument is inferred by Xamarin.iOS and does not need to be set. +Note that the `LinkTarget` argument is inferred by Xamarin.iOS and does not need to be set. Examples: -``` +```csharp // Specify additional linker: [assembly: LinkWith (LinkerFlags = "-sqlite3")] @@ -2423,19 +2355,13 @@ Examples: [assembly: LinkWith ("libDemo.a", LinkTarget.Thumb | LinkTarget.Simulator, SmartLink = true, ForceLoad = true, IsCxx = true); ``` - - - -### LinkWithAttribute.ForceLoad +#### LinkWithAttribute.ForceLoad The `ForceLoad` property is used to decide whether or not the `-force_load` link flag is used for linking the native library. For now, this should always be true. - - - -### LinkWithAttribute.Frameworks +#### LinkWithAttribute.Frameworks If the library being bound has a hard requirement on any frameworks (other than `Foundation` and `UIKit`), you should set the `Frameworks` property to a string @@ -2443,19 +2369,13 @@ containing a space-delimited list of the required platform frameworks. For example, if you are binding a library that requires `CoreGraphics` and `CoreText`, you would set the `Frameworks` property to `"CoreGraphics CoreText"`. - - - -### LinkWithAttribute.IsCxx +#### LinkWithAttribute.IsCxx Set this property to true if the resulting executable needs to be compiled using a C++ compiler instead of the default, which is a C compiler. Use this if the library that you are binding was written in C++. - - - -### LinkWithAttribute.LibraryName +#### LinkWithAttribute.LibraryName The name of the unmanaged library to bundle. This is a file with the extension ".a" and it can contain object code for multiple platforms (for @@ -2465,10 +2385,7 @@ Earlier versions of Xamarin.iOS checked the `LinkTarget` property to determine the platform your library supported, but this is now auto-detected, and the `LinkTarget` property is ignored. - - - -### LinkWithAttribute.LinkerFlags +#### LinkWithAttribute.LinkerFlags The `LinkerFlags` string provides a way for binding authors to specify any additional linker flags needed when linking the native library into the @@ -2477,34 +2394,23 @@ application. For example, if the native library requires libxml2 and zlib, you would set the `LinkerFlags` string to `"-lxml2 -lz"`. - - - -### LinkWithAttribute.LinkTarget +#### LinkWithAttribute.LinkTarget Earlier versions of Xamarin.iOS checked the `LinkTarget` property to determine the platform your library supported, but this is now auto-detected, and the `LinkTarget` property is ignored. - - -### LinkWithAttribute.NeedsGccExceptionHandling +#### LinkWithAttribute.NeedsGccExceptionHandling Set this property to true if the library that you are linking requires the GCC Exception Handling library (gcc_eh) - - - -### LinkWithAttribute.SmartLink +#### LinkWithAttribute.SmartLink The `SmartLink` property should be set to true to let Xamarin.iOS determine whether `ForceLoad` is required or not. - - - -### LinkWithAttribute.WeakFrameworks +#### LinkWithAttribute.WeakFrameworks The `WeakFrameworks` property works the same way as the `Frameworks` property, except that at link-time, the `-weak_framework` specifier is passed @@ -2520,19 +2426,18 @@ Good candidates for weak linking would be `Frameworks` like Accounts, `CoreBluetooth`, `CoreImage`, `GLKit`, `NewsstandKit` and `Twitter` since they are only available in iOS 5. - - + -## SinceAttribute (iOS) and LionAttribute (MacOS X) +### SinceAttribute (iOS) and LionAttribute (macOS) -You use the `Since` Attribute to flag APIs as having being introduced at a +You use the `[Since]` attribute to flag APIs as having being introduced at a certain point in time. The attribute should only be used to flag types and methods that could cause a runtime problem if the underlying class, method or property is not available. Syntax: -``` +```csharp public SinceAttribute : Attribute { public SinceAttribute (byte major, byte minor); public byte Major, Minor; @@ -2545,7 +2450,7 @@ device with an older version of the operating system. Example when applied to a type: -``` +```csharp // Type introduced with iOS 4.2 [Since (4,2)] [BaseType (typeof (UIPrintFormatter))] @@ -2557,7 +2462,7 @@ interface UIViewPrintFormatter { Example when applied to a new member: -``` +```csharp [BaseType (typeof (UIViewController))] public interface UITableViewController { [Export ("tableView", ArgumentSemantic.Retain)] @@ -2568,39 +2473,32 @@ public interface UITableViewController { bool ClearsSelectionOnViewWillAppear { get; set; } ``` -The `Lion` attribute is applied in the same way but for types introduced with -Lion. The reason to use `Lion` versus the more specific version number that is +The `[Lion]` attribute is applied in the same way but for types introduced with +Lion. The reason to use `[Lion]` versus the more specific version number that is used in iOS is that iOS is revised very often, while major OS X releases happen rarely and it is easier to remember the operating system by their codename than by their version number - - - -## AdviceAttribute +### AdviceAttribute Use this attribute to give developers a hint about other APIs that might be more convenient for them to use. For example, if you -provide a strongly typed version of an API, you could use this -attribute on the weakly typed attribute to direct the developer to the +provide a strongly-typed version of an API, you could use this +attribute on the weakly-typed attribute to direct the developer to the better API. The information from this attribute is shown in the documentation and tools can be developed to give user suggestions on how to improve -his code. +### RequiresSuperAttribute -## RequiresSuperAttribute - -This is a specialized subclass of the `[Advice]` attribute can be used -to hint the developer that overriding a method **requires** a call to +This is a specialized subclass of the `[Advice]` attribute that can be used +to hint to the developer that overriding a method **requires** a call to the base (overridden) method. This correspond to `clang` [` __attribute__((objc_requires_super))`](https://clang.llvm.org/docs/AttributeReference.html#objc-requires-super-clang-objc-requires-super) - - -## ZeroCopyStringsAttribute +### ZeroCopyStringsAttribute Only available in Xamarin.iOS 5.4 and newer. @@ -2614,13 +2512,13 @@ string as the string that Objective-C consumes without incurring the creation of a new `NSString` object and avoiding copying the data from the C# strings to the Objective-C string. The only drawback of using Zero Copy strings is that you must ensure that any string property that you wrap that happens to be flagged as -"retain" or "copy" has the `DisableZeroCopy` attribute set. This is +`retain` or `copy` has the `[DisableZeroCopy]` attribute set. This is require because the handle for zero-copy strings is allocated on the stack and is invalid upon the function return. Example: -``` +```csharp [ZeroCopyStrings] [BaseType (typeof (NSObject))] interface MyBinding { @@ -2640,27 +2538,29 @@ interface MyBinding { You can also apply the attribute at the assembly level, and it will apply to all the types of the assembly: - [assembly:ZeroCopyStrings] +```csharp +[assembly:ZeroCopyStrings] +``` -# Strongly Typed Dictionaries +## Strongly-typed dictionaries With Xamarin.iOS 8.0 we introduced support for easily creating -Strongly Typed classes that wrap `NSDictionaries`. +strongly-typed classes that wrap `NSDictionaries`. While it has always been possible to use the -[DictionaryContainer](/api/type/Foundation.DictionaryContainer/) +[DictionaryContainer](https://developer.xamarin.com/api/type/Foundation.DictionaryContainer/) data type together with a manual API, it is now a lot simpler to do this. For more information, see [Surfacing Strong -Types](/guides/cross-platform/macios/binding/objective-c-libraries/#Surfacing_Strong_Types_for_weak_NSDictionary_parameters). +Types](~/cross-platform/macios/binding/objective-c-libraries.md#Surfacing_Strong_Types). - + -## StrongDictionary +### StrongDictionary When this attribute is applied to an interface, the generator will produce a class with the same name as the interface that derives from -[DictionaryContainer](/api/type/Foundation.DictionaryContainer/) -and turns each property defined in the interface into a strongly typed +[DictionaryContainer](https://developer.xamarin.com/api/type/Foundation.DictionaryContainer/) +and turns each property defined in the interface into a strongly-typed getter and setter for the dictionary. This automatically generates a class that can be instantiated from an @@ -2673,7 +2573,7 @@ a member in the specified type for a name with the suffix "Key". For example: -``` +```csharp [StrongDictionary ("MyOptionKeys")] interface MyOption { string Name { get; set; } @@ -2702,7 +2602,7 @@ dictionary to retrieve a string. And will use the If you want to use a different key, you can use the export attribute on the property, for example: -``` +```csharp [StrongDictionary ("MyColoringKeys")] interface MyColoringOptions { [Export ("TheName")] // Override the default which would be NameKey @@ -2724,75 +2624,24 @@ interface MyColoringKeys { } ``` -### Strong Dictionary Types - -The following data types are supported in the `StrongDictionary` -definition: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +#### Strong dictionary types + +The following data types are supported in the `StrongDictionary` definition: + +|C# Interface Type|`NSDictionary` Storage Type| +|---|---| +|`bool`|`Boolean` stored in an `NSNumber`| +|Enumeration values|integer stored in an `NSNumber`| +|`int`|32-bit integer stored in an `NSNumber`| +|`uint`|32-bit unsigned integer stored in an `NSNumber`| +|`nint`|`NSInteger` stored in an `NSNumber`| +|`nuint`|`NSUInteger` stored in an `NSNumber`| +|`long`|64-bit integer stored in an `NSNumber`| +|`float`|32-bit integer stored as an `NSNumber`| +|`double`|64-bit integer stored as an `NSNumber`| +|`NSObject` and subclasses|`NSObject`| +|`NSDictionary`|`NSDictionary`| +|`string`|`NSString`| +|`NSString`|`NSString`| +|C# `Array` of `NSObject`|`NSArray`| +|C# `Array` of enumerations|`NSArray` containing `NSNumber` values| diff --git a/docs/website/mmp-errors.md b/docs/website/mmp-errors.md index bffa33c98250..d4fee27789cb 100644 --- a/docs/website/mmp-errors.md +++ b/docs/website/mmp-errors.md @@ -1,18 +1,24 @@ --- -id: 5B26339F-A202-4E41-9229-D0BC9E77868E -title: Xamarin.Mac errors -dateupdated: 2017-06-26 +title: "Xamarin.Mac error messages (mmp)" +description: "An errors reference guide for mmp." +ms.topic: troubleshooting +ms.prod: xamarin +ms.assetid: 5B26339F-A202-4E41-9229-D0BC9E77868E +ms.technology: xamarin-mac +author: bradumbaugh +ms.author: brumbaug +ms.date: 03/27/2018 --- -[//]: # (The original file resides under https://github.com/xamarin/xamarin-macios/tree/master/docs/website/) -[//]: # (This allows all contributors (including external) to submit, using a PR, updates to the documentation that match the tools changes) -[//]: # (Modifications outside of xamarin-macios/master will be lost on future updates) +# Xamarin.Mac error messages (mmp) -# MM0xxx: mmp error messages +## MM0xxx: mmp error messages E.g. parameters, environment, missing tools. -### MM0000: Unexpected error - Please file a bug report at http://bugzilla.xamarin.com + + +#### MM0000: Unexpected error - Please file a bug report at http://bugzilla.xamarin.com An unexpected error condition occurred. Please [file a bug report](https://bugzilla.xamarin.com/enter_bug.cgi?product=Xamarin.Mac) with as much information as possible, including: @@ -22,76 +28,128 @@ An unexpected error condition occurred. Please [file a bug report](https://bugzi The easiest way to get exact version information is to use the **Xamarin Studio** menu, **About Xamarin Studio** item, **Show Details** button and copy/paste the version informations (you can use the **Copy Information** button). -### MM0001: This version of Xamarin.Mac requires Mono {0} (the current Mono version is {1}). Please update the Mono.framework from http://mono-project.com/Downloads + + +#### MM0001: This version of Xamarin.Mac requires Mono {0} (the current Mono version is {1}). Please update the Mono.framework from http://mono-project.com/Downloads + + + +#### MM0003: Application name '{0}.exe' conflicts with an SDK or product assembly (.dll) name. -### MM0003: Application name '{0}.exe' conflicts with an SDK or product assembly (.dll) name. + -### MM0007: The root assembly '{0}' does not exist +#### MM0007: The root assembly '{0}' does not exist -### MM0008: You should provide one root assembly only, found {0} assemblies: '{1}' + -### MM0009: Error while loading assemblies: *. +#### MM0008: You should provide one root assembly only, found {0} assemblies: '{1}' + + + +#### MM0009: Error while loading assemblies: *. An error occurred while loading the assemblies from the root assembly references. More information may be provided in the build output. -### MM0010: Could not parse the command line arguments: {0} + + +#### MM0010: Could not parse the command line arguments: {0} -### MM0016: The option '{0}' has been deprecated. + + +#### MM0016: The option '{0}' has been deprecated. + + + +#### MM0017: You should provide a root assembly + + + +#### MM0018: Unknown command line argument: '{0}' + + -### MM0017: You should provide a root assembly +#### MM0020: The valid options for '{0}' are '{1}'. -### MM0018: Unknown command line argument: '{0}' + -### MM0020: The valid options for '{0}' are '{1}'. +#### MM0023: Application name '{0}.exe' conflicts with another user assembly. -### MM0023: Application name '{0}.exe' conflicts with another user assembly. + -### MM0026: Could not parse the command line argument '{0}': {1} +#### MM0026: Could not parse the command line argument '{0}': {1} -### MM0043: The Boehm garbage collector is not supported. The SGen garbage collector has been selected instead. + -### MM0050: You cannot provide a root assembly if --no-root-assembly is passed. +#### MM0043: The Boehm garbage collector is not supported. The SGen garbage collector has been selected instead. -### MM0051: An output directory (--output) is required if --no-root-assembly is passed. + -### MM0053: Cannot disable new refcount with the Unified API. +#### MM0050: You cannot provide a root assembly if --no-root-assembly is passed. -### MM0056: Cannot find Xcode in any of our default locations. Please install Xcode, or pass a custom path using --sdkroot= + -### MM0059: Could not find the currently selected Xcode on the system: {0}; +#### MM0051: An output directory (--output) is required if --no-root-assembly is passed. -### MM0060: Could not find the currently selected Xcode on the system. 'xcode-select --print-path' returned '{0}', but that directory does not exist. + -### MM0068: Invalid value for target framework: {0}. +#### MM0053: Cannot disable new refcount with the Unified API. -### MM0071: Unknown platform: *. This usually indicates a bug in Xamarin.Mac; please file a bug report at https://bugzilla.xamarin.com with a test case. + + +#### MM0056: Cannot find Xcode in any of our default locations. Please install Xcode, or pass a custom path using --sdkroot= + + + +#### MM0059: Could not find the currently selected Xcode on the system: {0}; + + + +#### MM0060: Could not find the currently selected Xcode on the system. 'xcode-select --print-path' returned '{0}', but that directory does not exist. + + + +#### MM0068: Invalid value for target framework: {0}. + + + +#### MM0071: Unknown platform: *. This usually indicates a bug in Xamarin.Mac; please file a bug report at https://bugzilla.xamarin.com with a test case. This usually indicates a bug in Xamarin.Mac; please file a bug report at [https://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=Xamarin.Mac) with a test case. -### MM0073: Xamarin.Mac * does not support a deployment target of * (the minimum is *). Please select a newer deployment target in your project's Info.plist. + + +#### MM0073: Xamarin.Mac * does not support a deployment target of * (the minimum is *). Please select a newer deployment target in your project's Info.plist. The minimum deployment target is the one specified in the error message; please select a newer deployment target in the project's Info.plist. If updating the deployment target is not possible, then please use an older version of Xamarin.Mac. -### MM0074: Xamarin.Mac * does not support a deployment target of * (the maximum is *). Please select an older deployment target in your project's Info.plist or upgrade to a newer version of Xamarin.Mac. + + +#### MM0074: Xamarin.Mac * does not support a deployment target of * (the maximum is *). Please select an older deployment target in your project's Info.plist or upgrade to a newer version of Xamarin.Mac. Xamarin.Mac does not support setting the minimum deployment target to a higher version than the version this particular version of Xamarin.Mac was built for. Please select an older minimum deployment target in the project's Info.plist, or upgrade to a newer version of Xamarin.Mac. -### MM0079: Internal Error - No executable was copied into the app bundle. Please contact 'support@xamarin.com' + + +#### MM0079: Internal Error - No executable was copied into the app bundle. Please contact 'support@xamarin.com' -### MM0080: Disabling NewRefCount, --new-refcount:false, is deprecated. + + +#### MM0080: Disabling NewRefCount, --new-refcount:false, is deprecated. -### MM0091: This version of Xamarin.Mac requires the * SDK (shipped with Xcode *). Either upgrade Xcode to get the required header files or use the dynamic registrar or set the managed linker behaviour to Link Platform or Link Framework SDKs Only (to try to avoid the new APIs). + + +#### MM0091: This version of Xamarin.Mac requires the * SDK (shipped with Xcode *). Either upgrade Xcode to get the required header files or use the dynamic registrar or set the managed linker behaviour to Link Platform or Link Framework SDKs Only (to try to avoid the new APIs). -Xamarin.Mac requires the header files, from the SDK version specified in the error message, to build your application with the static registrar.. The recommended way to fix this error is to upgrade Xcode to get the required SDK, this will include all the required header files. If you have multiple versions of Xcode installed, or want to use an Xcode in a non-default location, make sure to set the correct Xcode location in your IDE's preferences. +Xamarin.Mac requires the header files, from the SDK version specified in the error message, to build your application with the static registrar. The recommended way to fix this error is to upgrade Xcode to get the required SDK, this will include all the required header files. If you have multiple versions of Xcode installed, or want to use an Xcode in a non-default location, make sure to set the correct Xcode location in your IDE's preferences. One potential, alternative solution, is to enable the managed linker. This will remove unused API including, in most cases, the new API where the header files are missing (or incomplete). However this will not work if your project uses API that was introduced in a newer SDK than the one your Xcode provides. @@ -99,16 +157,25 @@ A second potential, alternative solution, is use the dynamic registrar instead. A last-straw solution would be to use an older version of Xamarin.Mac, one that supports the SDK your project requires. + + +#### MM0097: machine.config file '{0}' can not be found. + + -### MM0097: machine.config file '{0}' can not be found. +#### MM0098: AOT compilation is only available on Unified -### MM0098: AOT compilation is only available on Unified + -### MM0099: Internal error {0}. Please file a bug report with a test case (http://bugzilla.xamarin.com). +#### MM0099: Internal error {0}. Please file a bug report with a test case (http://bugzilla.xamarin.com). -### MM0114: Hybrid AOT compilation requires all assemblies to be AOT compiled. + -### MM0129: Debugging symbol file for '*' does not match the assembly and is ignored. +#### MM0114: Hybrid AOT compilation requires all assemblies to be AOT compiled. + + + +#### MM0129: Debugging symbol file for '*' does not match the assembly and is ignored. The debugging symbols, either a .pdb (portable pdb only) or a .mdb file, for the specified assembly could not be loaded. @@ -118,15 +185,21 @@ This warning won't affect the application being built, however you might not be Please report this issue to the publisher of the assembly package (e.g. nuget author) so this can be fixed in their future releases. -### MM0130: No root assemblies found. You should provide at least one root assembly. + + +#### MM0130: No root assemblies found. You should provide at least one root assembly. When running --runregistrar, at least one root assembly should be provided. -### MM0131: Product assembly '{0}' not found in assembly list: '{1}' + + +#### MM0131: Product assembly '{0}' not found in assembly list: '{1}' When running --runregistrar, the assembly list should include the product assembly, Xamarin.Mac, XamMac. -### + +#### MM0132: Unknown optimization: *. Valid values are: * The specified optimization was not recognized. @@ -134,9 +207,13 @@ The accepted format is `[+|-]optimization-name`, where `optimization-name` is on See [Build optimizations](https://developer.xamarin.com/guides/cross-platform/macios/build-optimizations) for a complete description of each optimization. -### MM0133: Found more than 1 assembly matching '{0}' choosing first: '{1}' + + +#### MM0133: Found more than 1 assembly matching '{0}' choosing first: '{1}' -### MM0134: 32-bit applications should be migrated to 64-bit. + + +#### MM0134: 32-bit applications should be migrated to 64-bit. Apple has announced that it will not allow macOS App Store submissions of 32-bit apps (starting January 2018). @@ -146,7 +223,9 @@ For more details: https://developer.apple.com/news/?id=06282017a Consider updating your application and any dependencies to 64-bit. -### MM0135: Did not link system framework '{0}' (referenced by assembly '{1}') because it was introduced in {2} {3}, and we're using the {2} {4} SDK. + + +#### MM0135: Did not link system framework '{0}' (referenced by assembly '{1}') because it was introduced in {2} {3}, and we're using the {2} {4} SDK. To build your application, Xamarin.Mac must link against system libraries, some of which depend upon the SDK version specified in the error message. Since you are using an older version of the SDK, invocations to those APIs may fail at runtime. @@ -170,95 +249,163 @@ Xcode 10 does not support building 32-bit applications. Change the architecture in the project's Mac Build options to 'x86_64' in order to build a 64-bit application. -# MM1xxx: file copy / symlinks (project related) +## MM1xxx: file copy / symlinks (project related) + + + +#### MM1034: Could not create symlink '{file}' -> '{target}': error {number} + +### MM14xx: Product assemblies + + + +#### MM1401: The required '{0}' assembly is missing from the references + + + +#### MM1402: The assembly '{0}' is not compatible with this tool + + + +#### MM1403: {0} '{1}' could not be found. Target framework '{0}' is unusable to package the application. + + + +#### MM1404: Target framework '{0}' is invalid. + + + +#### MM1405: useFullXamMacFramework must always target framework .NET 4.5, not '{0}' which is invalid -### MM1034: Could not create symlink '{file}' -> '{target}': error {number} + -## MM14xx: Product assemblies +#### MM1406: Target framework '{0}' is invalid when targetting Xamarin.Mac 4.5 .NET framwork. -### MM1401: The required '{0}' assembly is missing from the references + -### MM1402: The assembly '{0}' is not compatible with this tool +#### MM1407: Mismatch between Xamarin.Mac reference '{0}' and target framework selected '{1}'. -### MM1403: {0} '{1}' could not be found. Target framework '{0}' is unusable to package the application. +### MM15xx: Assembly gathering (not requiring linker) errors -### MM1404: Target framework '{0}' is invalid. + -### MM1405: useFullXamMacFramework must always target framework .NET 4.5, not '{0}' which is invalid +#### MM1501: Can not resolve reference: {0} -### MM1406: Target framework '{0}' is invalid when targetting Xamarin.Mac 4.5 .NET framwork. +### MachO.cs -### MM1407: Mismatch between Xamarin.Mac reference '{0}' and target framework selected '{1}'. + -## MM15xx: Assembly gathering (not requiring linker) errors +#### MM1600: Not a Mach-O dynamic library (unknown header '0x{0}'): {1}. -### MM1501: Can not resolve reference: {0} + -## MachO.cs +#### MM1601: Not a static library (unknown header '{0}'): {1}. -### MM1600: Not a Mach-O dynamic library (unknown header '0x{0}'): {1}. + -### MM1601: Not a static library (unknown header '{0}'): {1}. +#### MM1602: Not a Mach-O dynamic library (unknown header '0x{0}'): {1}. -### MM1602: Not a Mach-O dynamic library (unknown header '0x{0}'): {1}. + -### MM1603: Unknown format for fat entry at position {0} in {1}. +#### MM1603: Unknown format for fat entry at position {0} in {1}. -### MM1604: File of type {0} is not a MachO file ({1}). + -# MM2xxx: Linker +#### MM1604: File of type {0} is not a MachO file ({1}). -## MM20xx: Linker (general) errors +## MM2xxx: Linker -### MM2001: Could not link assemblies +### MM20xx: Linker (general) errors -### MM2002: Can not resolve reference: {0} + -### MM2003: Option '{0}' will be ignored since linking is disabled +#### MM2001: Could not link assemblies -### MM2004: Extra linker definitions file '{0}' could not be located. + -### MM2005: Definitions from '{0}' could not be parsed. +#### MM2002: Can not resolve reference: {0} -### MM2006: Native library '{0}' was referenced but could not be found. + -### MM2007: Xamarin.Mac Unified API against a full .NET profile does not support linking. Pass the -nolink flag. +#### MM2003: Option '{0}' will be ignored since linking is disabled -### MM2009: Referenced by {0}.{1} ** This message is related to MM2006 ** + -### MM2010: Unknown HttpMessageHandler `{0}`. Valid values are HttpClientHandler (default), CFNetworkHandler or NSUrlSessionHandler +#### MM2004: Extra linker definitions file '{0}' could not be located. -### MM2011: Unknown TLSProvider `{0}. Valid values are default or appletls + -### MM2012: Only first {0} of {1} "Referenced by" warnings shown. ** This message related to 2009 ** +#### MM2005: Definitions from '{0}' could not be parsed. -### MM2013: Failed to resolve the reference to "{0}", referenced in "{1}". The app will not include the referenced assembly, and may fail at runtime. + -### MM2014: Xamarin.Mac Extensions do not support linking. Request for linking will be ignored. ** This message is obsolete in XM 3.6+ ** +#### MM2006: Native library '{0}' was referenced but could not be found. + + + +#### MM2007: Xamarin.Mac Unified API against a full .NET profile does not support linking. Pass the -nolink flag. + + + +#### MM2009: Referenced by {0}.{1} ** This message is related to MM2006 ** + + + +#### MM2010: Unknown HttpMessageHandler `{0}`. Valid values are HttpClientHandler (default), CFNetworkHandler or NSUrlSessionHandler + + + +#### MM2011: Unknown TLSProvider `{0}. Valid values are default or appletls + + + +#### MM2012: Only first {0} of {1} "Referenced by" warnings shown. ** This message related to 2009 ** + + + +#### MM2013: Failed to resolve the reference to "{0}", referenced in "{1}". The app will not include the referenced assembly, and may fail at runtime. + + + +#### MM2014: Xamarin.Mac Extensions do not support linking. Request for linking will be ignored. ** This message is obsolete in XM 3.6+ ** -### MM2016: Invalid TlsProvider `{0}` option. The only valid value `{1}` will be used. + + +#### MM2016: Invalid TlsProvider `{0}` option. The only valid value `{1}` will be used. + + + +#### MM2017: Could not process XML description: {0} + + + +#### MM202x: Binding Optimizer failed processing `...`. -### MM2017: Could not process XML description: {0} + -### MM202x: Binding Optimizer failed processing `...`. +#### MM2100: Xamarin.Mac Classic API does not support Platform Linking. -### MM2103: Error processing assembly '\*': * + + +#### MM2103: Error processing assembly '\*': * An unexpected error occured when processing an assembly. The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](https://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -### MM2104: Unable to link assembly '{0}' as it is mixed-mode. + + +#### MM2104: Unable to link assembly '{0}' as it is mixed-mode. Mixed-mode assemblies can not be processed by the linker. See https://msdn.microsoft.com/en-us/library/x0w2664k.aspx for more information on mixed-mode assemblies. - + -### MM2106: Could not optimize the call to BlockLiteral.SetupBlock[Unsafe] in * at offset * because *. +#### MM2106: Could not optimize the call to BlockLiteral.SetupBlock[Unsafe] in * at offset * because *. The linker reports this warning when it can't optimize a call to BlockLiteral.SetupBlock or Block.SetupBlockUnsafe. @@ -269,7 +416,9 @@ Please file an [issue](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log so that we can investigate what went wrong and possibly enable more scenarios in the future. -### MM2107: It's not safe to remove the dynamic registrar because {reasons} + + +#### MM2107: It's not safe to remove the dynamic registrar because {reasons} The linker reports this warning when the developer requests removal of the dynamic registrar (by passing `--optimize:remove-dynamic-registrar` to @@ -281,7 +430,9 @@ To remove the warning either remove the optimization argument to mmp, or pass By default this option will be automatically enabled whenever it's possible and safe to do so. -### MM2108: '{0}' was stripped of architectures except '{1}' to comply with App Store restrictions. This could break exisiting codesigning signatures. Consider stripping the library with lipo or disabling with --optimize=-trim-architectures"); + + +#### MM2108: '{0}' was stripped of architectures except '{1}' to comply with App Store restrictions. This could break exisiting codesigning signatures. Consider stripping the library with lipo or disabling with --optimize=-trim-architectures"); The App Store now rejects applications which contain libraries and frameworks which contain 32-bit variants. The library was stripped of unused archtectures when copied into the final application bundle. @@ -289,14 +440,17 @@ This is in general safe, and will reduce application bundle size as an added ben Consider using `lipo` to remove the unnecessary archtectures permanently from the source library. If the application is not being published to the App Store, this removal can be disabled by passing --optimize=-trim-architectures as Additional MMP Arguments. -### MM2109: Xamarin.Mac Classic API does not support Platform Linking. + + +#### MM2109: Xamarin.Mac Classic API does not support Platform Linking. +## MM3xxx: AOT -# MM3xxx: AOT +### MM30xx: AOT (general) errors -## MM30xx: AOT (general) errors + -### MM3001: Could not AOT the assembly '{0}' +#### MM3001: Could not AOT the assembly '{0}' @@ -305,21 +459,32 @@ Consider using `lipo` to remove the unnecessary archtectures permanently from th -### MM3009: AOT of '{0}' was requested but was not found -### MM3010: Exclusion of AOT of '{0}' was requested but was not found + -# MM4xxx: code generation +#### MM3009: AOT of '{0}' was requested but was not found -## MM40xx: driver.m + -### MM4001: The main template could not be expanded to `{0}`. +#### MM3010: Exclusion of AOT of '{0}' was requested but was not found -## MM41xx: registrar +## MM4xxx: code generation -### MM4134: Your application is using the '{0}' framework, which isn't included in the MacOS SDK you're using to build your app (this framework was introduced in OSX {2}, while you're building with the MacOS {1} SDK.) This configuration is not supported with the static registrar (pass --registrar:dynamic as an additional mmp argument in your project's Mac Build option to select). Alternatively select a newer SDK in your app's Mac Build options. +### MM40xx: driver.m -### MM4173: The registrar can't compute the block signature for the delegate of type {delegate-type} in the method {method} because *. + + +#### MM4001: The main template could not be expanded to `{0}`. + +### MM41xx: registrar + + + +#### MM4134: Your application is using the '{0}' framework, which isn't included in the MacOS SDK you're using to build your app (this framework was introduced in OSX {2}, while you're building with the MacOS {1} SDK.) This configuration is not supported with the static registrar (pass --registrar:dynamic as an additional mmp argument in your project's Mac Build option to select). Alternatively select a newer SDK in your app's Mac Build options. + + + +#### MM4173: The registrar can't compute the block signature for the delegate of type {delegate-type} in the method {method} because *. This is a warning indicating that the registrar couldn't inject the block signature of the specified method into the generated registrar code, because @@ -340,11 +505,13 @@ There are currently two possible reasons for this warning: shouldn't happen, so please file an [issue](https://github.com/xamarin/xamarin-macios/issues/new) with a test project so that we can fix it. -### MM4174: Unable to locate the block to delegate conversion method for the method {method}'s parameter #{parameter}. + + +#### MM4174: Unable to locate the block to delegate conversion method for the method {method}'s parameter #{parameter}. This is a warning indicating that the static registrar couldn't find the method to create a delegate for an Objective-C block. An attempt will be made -at runtime to find the method, but it will likely fail as well (with an MM8009 +at runtime to find the method, but it will likely fail as well (with an MT8009 exception). One possible reason for this warning is when manually writing bindings for API @@ -352,7 +519,7 @@ that uses blocks. It's recommended to use a binding project to bind Objective-C code, in particular when it involves blocks, since it's quite complicated to get it right when doing it manually. -If this is not the case, please file a bug at [https://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=Xamarin.Mac) with a test case. +If this is not the case, please file an [issue](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. ### MM4175: The parameter '{parameter}' in the method '{method}' has an invalid BlockProxy attribute (the type passed to the attribute does not have a 'Create' method). @@ -390,31 +557,45 @@ will be shown. Reference: https://github.com/xamarin/xamarin-macios/issues/4072 -# MM5xxx: GCC and toolchain +## MM5xxx: GCC and toolchain -## MM51xx: compilation +### MM51xx: compilation -### MM5101: Missing '{0}' compiler. Please install Xcode 'Command-Line Tools' component. + + +#### MM5101: Missing '{0}' compiler. Please install Xcode 'Command-Line Tools' component. -### MM5103: Failed to compile. Error code - {0}. Please file a bug report at http://bugzilla.xamarin.com + + +#### MM5103: Failed to compile. Error code - {0}. Please file a bug report at http://bugzilla.xamarin.com -## MM52xx: linking +### MM52xx: linking + + + +#### MM5202: Mono.framework MDK is missing. Please install the MDK for your Mono.framework version from http://mono-project.com/Downloads + + + +#### MM5203: Can't find libxammac.a, likely because of a corrupted Xamarin.Mac installation. Please reinstall Xamarin.Mac. -### MM5202: Mono.framework MDK is missing. Please install the MDK for your Mono.framework version from http://mono-project.com/Downloads + -### MM5203: Can't find libxammac.a, likely because of a corrupted Xamarin.Mac installation. Please reinstall Xamarin.Mac. +#### MM5204: Invalid architecture. x86_64 is only supported on non-Classic profiles. -### MM5204: Invalid architecture. x86_64 is only supported on non-Classic profiles. + -### MM5205: Invalid architecture '{0}'. Valid architectures are i386 and x86_64 (when --profile=mobile). +#### MM5205: Invalid architecture '{0}'. Valid architectures are i386 and x86_64 (when --profile=mobile). -### MM5218: Can't ignore the dynamic symbol {symbol} (--ignore-dynamic-symbol={symbol}) because it was not detected as a dynamic symbol. + -See the [equivalent mtouch warning](mtouch-errors.md#MT5218). +#### MM5218: Can't ignore the dynamic symbol {symbol} (--ignore-dynamic-symbol={symbol}) because it was not detected as a dynamic symbol. + +See the [equivalent mtouch warning](~/ios/troubleshooting/mtouch-errors.md#MT5218). @@ -429,32 +610,48 @@ See the [equivalent mtouch warning](mtouch-errors.md#MT5218). -## MM53xx: other tools +### MM53xx: other tools + + -### MM5301: pkg-config could not be found. Please install the Mono.framework from http://mono-project.com/Downloads +#### MM5301: pkg-config could not be found. Please install the Mono.framework from http://mono-project.com/Downloads -### MM5305: Missing 'otool' tool. Please install Xcode 'Command-Line Tools' component + + +#### MM5305: Missing 'otool' tool. Please install Xcode 'Command-Line Tools' component + + + +#### MM5306: Missing dependencies. Please install Xcode 'Command-Line Tools' component + + -### MM5306: Missing dependencies. Please install Xcode 'Command-Line Tools' component +#### MM5308: Xcode license agreement may not have been accepted. Please launch Xcode. -### MM5308: Xcode license agreement may not have been accepted. Please launch Xcode. + -### MM5309: Native linking failed with error code 1. Check build log for details. +#### MM5309: Native linking failed with error code 1. Check build log for details. -### MM5310: install_name_tool failed with an error code '{0}'. Check build log for details. + + +#### MM5310: install_name_tool failed with an error code '{0}'. Check build log for details. + + + +#### MM5311: lipo failed with an error code '{0}'. Check build log for details. ### MM5311: lipo failed with an error code '{0}'. Check build log for details. -# MM8xxx: runtime +## MM8xxx: runtime -## MM800x: misc +### MM800x: misc @@ -474,9 +671,13 @@ See the [equivalent mtouch warning](mtouch-errors.md#MT5218). -### MM8017: The Boehm garbage collector is not supported. Please use SGen instead. + -### MM8025: Failed to compute the token reference for the type '{type.AssemblyQualifiedName}' because {reasons} +#### MM8017: The Boehm garbage collector is not supported. Please use SGen instead. + + + +#### MM8025: Failed to compute the token reference for the type '{type.AssemblyQualifiedName}' because {reasons} This indicates a bug in Xamarin.Mac. Please file a bug at [https://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=Xamarin.Mac). @@ -484,10 +685,12 @@ A potential workaround would be to disable the `register-protocols` optimization, by passing `--optimize:-register-protocols` as an additional mmp argument in the project's Mac Build options. -### MM8026: * is not supported when the dynamic registrar has been linked away. + +#### MM8026: * is not supported when the dynamic registrar has been linked away. + This usually indicates a bug in Xamarin.Mac, because the dynamic registrar should not be linked away if it's needed. Please file a bug at [https://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=Xamarin.Mac). - + It's possible to force the linker to keep the dynamic registrar by adding `--optimize=-remove-dynamic-registrar` to the additional mmp arguments in the project's Mac Build options. diff --git a/docs/website/mtouch-errors.md b/docs/website/mtouch-errors.md index fcc65a88587c..822199d859e4 100644 --- a/docs/website/mtouch-errors.md +++ b/docs/website/mtouch-errors.md @@ -1,14 +1,17 @@ --- -id: 9F76162B-D622-45DA-996B-2FBF8017E208 -title: Xamarin.iOS errors -dateupdated: 2017-06-26 +title: "Xamarin.iOS errors" +ms.topic: troubleshooting +ms.prod: xamarin +ms.assetid: 9F76162B-D622-45DA-996B-2FBF8017E208 +ms.technology: xamarin-ios +author: bradumbaugh +ms.author: brumbaug +ms.date: 03/06/2018 --- -[//]: # (The original file resides under https://github.com/xamarin/xamarin-macios/tree/master/docs/website/) -[//]: # (This allows all contributors (including external) to submit, using a PR, updates to the documentation that match the tools changes) -[//]: # (Modifications outside of xamarin-macios/master will be lost on future updates) +# Xamarin.iOS errors -# MT0xxx: mtouch error messages +## MT0xxx: mtouch error messages E.g. parameters, environment, missing tools. @@ -17,61 +20,85 @@ E.g. parameters, environment, missing tools. https://github.com/xamarin/xamarin-macios/blob/master/tools/mtouch/error.cs --> -### MT0000: Unexpected error - Please fill a bug report at http://bugzilla.xamarin.com + -An unexpected error condition occurred. Please [file a bug report](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with as much information as possible, including: +### MT0000: Unexpected error - Please fill a bug report at http://bugzilla.xamarin.com + +An unexpected error condition occurred. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with as much information as possible, including: * Full build logs, with maximum verbosity (e.g. `-v -v -v -v` in the **Additional mtouch arguments**); * A minimal test case that reproduce the error; and * All version informations -The easiest way to get exact version information is to use the **Xamarin Studio** menu, **About Xamarin Studio** item, **Show Details** button and copy/paste the version informations (you can use the **Copy Information** button). +The easiest way to get exact version information is to use the **Visual Studio for Mac** menu, **About Visual Studio for Mac** item, **Show Details** button and copy/paste the version informations (you can use the **Copy Information** button). + + -### MT0001: '-devname' was provided without any device-specific action +### MT0001: '-devname' was provided without any device-specific action This is a warning that is emitted if -devname is passed to mtouch when no device-specific action (-logdev/-installdev/-killdev/-launchdev/-listapps) was requested. -### MT0002: Could not parse the environment variable *. + + +### MT0002: Could not parse the environment variable *. This error happens if you try to set an invalid environment key=value variable pair. The correct format is: `mtouch --setenv=VARIABLE=VALUE` -### MT0003: Application name '*.exe' conflicts with an SDK or product assembly (.dll) name. + + +### MT0003: Application name '*.exe' conflicts with an SDK or product assembly (.dll) name. The executable assembly's name and the application's name can't match the name of any dll in the app. Please modify the name of your executable. -### MT0004: New refcounting logic requires SGen to be enabled too. + + +### MT0004: New refcounting logic requires SGen to be enabled too. If you enable the refcounting extension you must also enable the SGen garbage collector in the project's iOS Build options (Advanced tab). Starting with Xamarin.iOS 7.2.1 this requirement has been lifted, the new refcounting logic can be enabled with both Boehm and SGen Garbage Collectors. -### MT0005: The output directory * does not exist. + + +### MT0005: The output directory * does not exist. Please create the directory. This error is not generated anymore, mtouch will automatically create the directory if it doesn't exist. -### MT0006: There is no devel platform at *, use --platform=PLAT to specify the SDK. + + +### MT0006: There is no devel platform at *, use --platform=PLAT to specify the SDK. Xamarin.iOS cannot find the SDK directory at the location mentioned in the error message. Please verify that the path is correct. -### MT0007: The root assembly * does not exist. + + +### MT0007: The root assembly * does not exist. Xamarin.iOS cannot find the assembly at the location mentioned in the error message. Please verify that the path is correct. -### MT0008: You should provide one root assembly only, found # assemblies: *. + + +### MT0008: You should provide one root assembly only, found # assemblies: *. More than one root assembly was passed to mtouch, while there can be only one root assembly. -### MT0009: Error while loading assemblies: *. + + +### MT0009: Error while loading assemblies: *. An error occurred while loading the assemblies from the root assembly references. More information may be provided in the build output. -### MT0010: Could not parse the command line arguments: *. + + +### MT0010: Could not parse the command line arguments: *. An error occurred while parsing the command line arguments. Please verify that they are all correct. -### MT0011: * was built against a more recent runtime (*) than MonoTouch supports. + + +### MT0011: * was built against a more recent runtime (*) than MonoTouch supports. This warning is typically reported because the project has a reference to a class library that was not built using the Xamarin.iOS BCL. @@ -79,37 +106,50 @@ The same way an app using the .NET 4.0 SDK may not work on a system only support The general solution is to build the library as a Xamarin.iOS Class Library. This can be accomplished by creating a new Xamarin.iOS Class Library project and add all the source files to it. If you do not have the source code for the library, you should contact the vendor and request that they provide a Xamarin.iOS-compatible version of their library. -### MT0012: Incomplete data is provided to complete *. + + +### MT0012: Incomplete data is provided to complete *. This error is not reported anymore in the current version of Xamarin.iOS. -### MT0013: Profiling support requires sgen to be enabled too. + + +### MT0013: Profiling support requires sgen to be enabled too. SGen (--sgen) must be enabled if profiling (--profiling) is enabled. -### MT0014: The iOS * SDK does not support building applications targeting *. + + +### MT0014: The iOS * SDK does not support building applications targeting *. This can happen in the following circumstances: * ARMv6 is enabled and Xcode 4.5 or later is installed. * ARMv7s is enabled and Xcode 4.4 or earlier is installed. - Please verify that the installed version of Xcode supports the selected architectures. -### MT0015: Invalid ABI: *. Supported ABIs are: i386, x86_64, armv7, armv7+llvm, armv7+llvm+thumb2, armv7s, armv7s+llvm, armv7s+llvm+thumb2, arm64 and arm64+llvm. + + +### MT0015: Invalid ABI: *. Supported ABIs are: i386, x86_64, armv7, armv7+llvm, armv7+llvm+thumb2, armv7s, armv7s+llvm, armv7s+llvm+thumb2, arm64 and arm64+llvm. An invalid ABI was passed to mtouch. Please specify a valid ABI. -### MT0016: The option * has been deprecated. + + +### MT0016: The option * has been deprecated. The mentioned mtouch option has been deprecated and will be ignored. -### MT0017: You should provide a root assembly. + + +### MT0017: You should provide a root assembly. It is required to specify a root assembly (typically the main executable) when building an app. -### MT0018: Unknown command line argument: *. + + +### MT0018: Unknown command line argument: *. Mtouch does not recognize the command line argument mentioned in the error message. @@ -126,7 +166,9 @@ instead of this: `--foo something` -### MT0019: Only one --[log|install|kill|launch]dev or --[launch|debug]sim option can be used. + + +#### MT0019: Only one --[log|install|kill|launch]dev or --[launch|debug]sim option can be used. There are several options for mtouch that can't be used simultaneously: @@ -137,242 +179,363 @@ There are several options for mtouch that can't be used simultaneously: - --launchdebug - --launchsim + +### MT0020: The valid options for '\*' are '\*'. + -### MT0020 The valid options for '\*' are '\*'. +### MT0021: Cannot compile using gcc/g++ (--use-gcc) when using the static registrar (this is the default when compiling for device). Either remove the --use-gcc flag or use the dynamic registrar (--registrar:dynamic). + - -### MT0021 Cannot compile using gcc/g++ (--use-gcc) when using the static registrar (this is the default when compiling for device). Either remove the --use-gcc flag or use the dynamic registrar (--registrar:dynamic). - - - -### MT0022 The options '--unsupported--enable-generics-in-registrar' and '--registrar' are not compatible. +### MT0022: The options '--unsupported--enable-generics-in-registrar' and '--registrar' are not compatible. Remove both the options `--unsupported--enable-generics-in-registrar` and `--registrar`. Starting with Xamarin.iOS 7.2.1 the default registrar supports generics. This error is no longer shown (the command-line argument `--unsupported--enable-generics-in-registrar` has been removed from mtouch). -### MT0023 Application name '*.exe' conflicts with another user assembly. + + +### MT0023: Application name '*.exe' conflicts with another user assembly. The executable assembly's name and the application's name can't match the name of any dll in the app. Please modify the name of your executable. -### MT0024 Could not find required file '*'. + + +### MT0024: Could not find required file '*'. + +### MT0025: No SDK version was provided. Please add `--sdk=X.Y` to specify which iOS SDK should be used to build your application. -### MT0025 No SDK version was provided. Please add `--sdk=X.Y` to specify which iOS SDK should be used to build your application. + +### MT0026: Could not parse the command line argument '*': * + -### MT0026 Could not parse the command line argument '*': * +### MT0027: The options '\*' and '\*' are not compatible. + +### MT0028: Cannot enable PIE (-pie) when targeting iOS 4.1 or earlier. Please disable PIE (-pie:false) or set the deployment target to at least iOS 4.2 -### MT0027 The options '\*' and '\*' are not compatible. + +### MT0029: REPL (--enable-repl) is only supported in the simulator (--sim). +REPL is only supported if you're building for the simulator. This means that if you pass `--enable-repl` to mtouch, you must also pass `--sim`. -### MT0028 Cannot enable PIE (-pie) when targeting iOS 4.1 or earlier. Please disable PIE (-pie:false) or set the deployment target to at least iOS 4.2 + +### MT0030: The executable name (\*) and the app name (\*) are different, this may prevent crash logs from getting symbolicated properly. +When Xcode symbolicates (translates memory addresses to function names and file/line numbers) the process may fail if the executable and app have different names (without the extension). -### MT0029: REPL (--enable-repl) is only supported in the simulator (--sim). +To fix this either change 'Application Name' in the project's Build/iOS Application options, or change 'Assembly Name' in the project's Build/Output options. -REPL is only supported if you're building for the simulator. This means that if you pass `--enable-repl` to mtouch, you must also pass `--sim`. + -### MT0030: The executable name (\*) and the app name (\*) are different, this may prevent crash logs from getting symbolicated properly. +### MT0031: The command line arguments '--enable-background-fetch' and '--launch-for-background-fetch' require '--launchsim' too. -When Xcode symbolicates (translates memory addresses to function names and file/line numbers) the process may fail if the executable and app have different names (without the extension). + -To fix this either change 'Application Name' in the project's Build/iOS Application options, or change 'Assembly Name' in the project's Build/Output options. +### MT0032: The option '--debugtrack' is ignored unless '--debug' is also specified. -### MT0031: The command line arguments '--enable-background-fetch' and '--launch-for-background-fetch' require '--launchsim' too. + -### MT0032: The option '--debugtrack' is ignored unless '--debug' is also specified. +### MT0033: A Xamarin.iOS project must reference either monotouch.dll or Xamarin.iOS.dll -### MT0033 A Xamarin.iOS project must reference either monotouch.dll or Xamarin.iOS.dll + -### MT0034 Cannot include both 'monotouch.dll' and 'Xamarin.iOS.dll' in the same Xamarin.iOS project - '\*' is referenced explicitly, while '\*' is referenced by '*'. +### MT0034: Cannot include both 'monotouch.dll' and 'Xamarin.iOS.dll' in the same Xamarin.iOS project - '\*' is referenced explicitly, while '\*' is referenced by '*'. -### MT0036 Cannot launch a * simulator for a * app. Please enable the correct architecture(s) in your project's iOS Build options (Advanced page). + + +### MT0036: Cannot launch a * simulator for a * app. Please enable the correct architecture(s) in your project's iOS Build options (Advanced page). + + + +### MT0037: monotouch.dll is not 64-bit compatible. Either reference Xamarin.iOS.dll, or do not build for a 64-bit architecture (ARM64 and/or x86_64). + + + +### MT0038: The old registrars (--registrar:oldstatic|olddynamic) are not supported when referencing Xamarin.iOS.dll. + + + +### MT0039: Applications targeting ARMv6 cannot reference Xamarin.iOS.dll. + + -### MT0037 monotouch.dll is not 64-bit compatible. Either reference Xamarin.iOS.dll, or do not build for a 64-bit architecture (ARM64 and/or x86_64). +### MT0040: Could not find the assembly '\*', referenced by '\*'. -### MT0038 The old registrars (--registrar:oldstatic|olddynamic) are not supported when referencing Xamarin.iOS.dll. + -### MT0039 Applications targeting ARMv6 cannot reference Xamarin.iOS.dll. +### MT0041: Cannot reference both 'monotouch.dll' and 'Xamarin.iOS.dll'. -### MT0040 Could not find the assembly '\*', referenced by '\*'. + -### MT0041 Cannot reference both 'monotouch.dll' and 'Xamarin.iOS.dll'. +### MT0042: No reference to either monotouch.dll or Xamarin.iOS.dll was found. A reference to monotouch.dll will be added. -### MT0042 No reference to either monotouch.dll or Xamarin.iOS.dll was found. A reference to monotouch.dll will be added. + -### MT0043: The Boehm garbage collector is currently not supported when referencing 'Xamarin.iOS.dll'. The SGen garbage collector has been selected instead. +### MT0043: The Boehm garbage collector is currently not supported when referencing 'Xamarin.iOS.dll'. The SGen garbage collector has been selected instead. Only the SGen garbage collector is supported with Unified projects. Ensure there are no additional mtouch flags specifying Boehm as the garbage collector. -### MT0044: --listsim is only supported with Xcode 6.0 or later. + + +### MT0044: --listsim is only supported with Xcode 6.0 or later. Install a newer Xcode version. -### MT0045: --extension is only supported when using the iOS 8.0 (or later) SDK. + + +### MT0045: --extension is only supported when using the iOS 8.0 (or later) SDK. -### MT0047: The minimum deployment target for Unified applications is 5.1.1, the current deployment target is '*'. Please select a newer deployment target in your project's iOS Application options. + + +### MT0047: The minimum deployment target for Unified applications is 5.1.1, the current deployment target is '*'. Please select a newer deployment target in your project's iOS Application options. -### MT0049: *.framework is supported only if deployment target is 8.0 or later. * features might not work correctly. + + +### MT0049: *.framework is supported only if deployment target is 8.0 or later. * features might not work correctly. The specified framework is not supported in the iOS version the deployment target refers to. Either update the deployment target to a newer iOS version, or remove usage of the specified framework from the app. -### MT0051: Xamarin.iOS * requires Xcode 5.0 or later. The current Xcode version (found in *) is *. + + +### MT0051: Xamarin.iOS * requires Xcode 5.0 or later. The current Xcode version (found in *) is *. Install a newer Xcode. -### MT0052: No command specified. + + +### MT0052: No command specified. No action was specified for mtouch. -### MT0054: Unable to canonicalize the path '*': * + + +### MT0054: Unable to canonicalize the path '*': * -This is an internal error. If you see this error, please file a bug [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This is an internal error. If you see this error, please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT0055: The Xcode path '*' does not exist. + + +### MT0055: The Xcode path '*' does not exist. The Xcode path passed using `--sdkroot` does not exist. Please specify a valid path. -### MT0056: Cannot find Xcode in the default location (/Applications/Xcode.app). Please install Xcode, or pass a custom path using --sdkroot . -### MT0057: Cannot determine the path to Xcode.app from the sdk root '*'. Please specify the full path to the Xcode.app bundle. + + +### MT0056: Cannot find Xcode in the default location (/Applications/Xcode.app). Please install Xcode, or pass a custom path using --sdkroot . + + + +### MT0057: Cannot determine the path to Xcode.app from the sdk root '*'. Please specify the full path to the Xcode.app bundle. The path passed using `--sdkroot` does not specify a valid Xcode app. Please specify a path to an Xcode app. -### MT0058: The Xcode.app '\*' is invalid (the file '\*' does not exist). + + +### MT0058: The Xcode.app '\*' is invalid (the file '\*' does not exist). The path passed using `--sdkroot` does not specify a valid Xcode app. Please specify a path to an Xcode app. -### MT0059: Could not find the currently selected Xcode on the system: * + + +### MT0059: Could not find the currently selected Xcode on the system: * -### MT0060: Could not find the currently selected Xcode on the system. 'xcode-select --print-path' returned '*', but that directory does not exist. + -### MT0061: No Xcode.app specified (using --sdkroot), using the system Xcode as reported by 'xcode-select --print-path': * +### MT0060: Could not find the currently selected Xcode on the system. 'xcode-select --print-path' returned '*', but that directory does not exist. + + + +### MT0061: No Xcode.app specified (using --sdkroot), using the system Xcode as reported by 'xcode-select --print-path': * This is a informational warning, explaining which Xcode will be used, since none was specified. -### MT0062: No Xcode.app specified (using --sdkroot or 'xcode-select --print-path'), using the default Xcode instead: * + + +### MT0062: No Xcode.app specified (using --sdkroot or 'xcode-select --print-path'), using the default Xcode instead: * This is a informational warning, explaining which Xcode will be used, since none was specified. -### MT0063: Cannot find the executable in the extension * (no CFBundleExecutable entry in its Info.plist) + + +### MT0063: Cannot find the executable in the extension * (no CFBundleExecutable entry in its Info.plist) Every Info.plist must have an executable (using the CFBundleExecutable entry), however an entry should be generated automatically during the build. -This usually indicates a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. -### MT0064: Xamarin.iOS only supports embedded frameworks with Unified projects. + + +### MT0064: Xamarin.iOS only supports embedded frameworks with Unified projects. Xamarin.iOS only supports embedded frameworks when using the Unified API; please update your project to use the Unified API. -### MT0065: Xamarin.iOS only supports embedded frameworks when deployment target is at least 8.0 (current deployment target: * embedded frameworks: *) + + +### MT0065: Xamarin.iOS only supports embedded frameworks when deployment target is at least 8.0 (current deployment target: * embedded frameworks: *) Xamarin.iOS only supports embedded frameworks when the deployment target is at least 8.0 (because earlier versions of iOS does not support embedded frameworks). Please update the deployment target in the project's Info.plist to 8.0 or higher. -### MT0066: Invalid build registrar assembly: * + + +### MT0066: Invalid build registrar assembly: * -This usually indicates a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. -### MT0067: Invalid registrar: * + -This usually indicates a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. +### MT0067: Invalid registrar: * -### MT0068: Invalid value for target framework: *. +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. + + + +### MT0068: Invalid value for target framework: *. An invalid target framework was passed using the --target-framework argument. Please specify a valid target framework. - + + + + + -### MT0070: Invalid target framework: *. Valid target frameworks are: *. +### MT0070: Invalid target framework: *. Valid target frameworks are: *. An invalid target framework was passed using the --target-framework argument. Please specify a valid target framework. -### MT0071: Unknown platform: *. This usually indicates a bug in Xamarin.iOS; please file a bug report at http://bugzilla.xamarin.com with a test case. + + +### MT0071: Unknown platform: *. This usually indicates a bug in Xamarin.iOS; please file a bug report at http://bugzilla.xamarin.com with a test case. + +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. + + -This usually indicates a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. +### MT0072: Extensions are not supported for the platform '*'. -### MT0072: Extensions are not supported for the platform '*'. +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. -This usually indicates a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. + -### MT0073: Xamarin.iOS * does not support a deployment target of * (the minimum is *). Please select a newer deployment target in your project's Info.plist. +### MT0073: Xamarin.iOS * does not support a deployment target of * (the minimum is *). Please select a newer deployment target in your project's Info.plist. The minimum deployment target is the one specified in the error message; please select a newer deployment target in the project's Info.plist. If updating the deployment target is not possible, then please use an older version of Xamarin.iOS. -### MT0074: Xamarin.iOS * does not support a deployment target of * (the maximum is *). Please select an older deployment target in your project's Info.plist or upgrade to a newer version of Xamarin.iOS. + + +### MT0074: Xamarin.iOS * does not support a minimum deployment target of * (the maximum is *). Please select an older deployment target in your project's Info.plist or upgrade to a newer version of Xamarin.iOS. Xamarin.iOS does not support setting the minimum deployment target to a higher version than the version this particular version of Xamarin.iOS was built for. Please select an older minimum deployment target in the project's Info.plist, or upgrade to a newer version of Xamarin.iOS. -### MT0075: Invalid architecture '*' for * projects. Valid architectures are: * + + +### MT0075: Invalid architecture '*' for * projects. Valid architectures are: * An invalid architecture was specified. Please verify that architecture is valid. -### MT0075: No architecture specified (using the --abi argument). An architecture is required for * projects. + + +### MT0076: No architecture specified (using the --abi argument). An architecture is required for * projects. + +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. -This usually indicates a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. + -### MT0076: WatchOS projects must be extensions. +### MT0077: WatchOS projects must be extensions. -This usually indicates a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. -### MT0077: Incremental builds are enabled with a deployment target < 8.0 (currently *). This is not supported (the resulting application will not launch on iOS 9), so the deployment target will be set to 8.0. + + +### MT0078: Incremental builds are enabled with a deployment target < 8.0 (currently *). This is not supported (the resulting application will not launch on iOS 9), so the deployment target will be set to 8.0. This is a warning informing that the deployment target has been set to 8.0 for this build so that incremental builds work properly. Incremental builds are only supported when the deployment target is at least 8.0 (because the resulting application will not launch on iOS 9 otherwise). -### MT0078: The recommended Xcode version for Xamarin.iOS * is Xcode * or later. The current Xcode version (found in *) is *. + + +### MT0079: The recommended Xcode version for Xamarin.iOS * is Xcode * or later. The current Xcode version (found in *) is *. This is a warning informing that the current version of Xcode is not the recommended version of Xcode for this version of Xamarin.iOS. -Please upgrade Xcode in order to ensure optimal behavior. +Please upgrade Xcode to ensure optimal behavior. + + -### MT0080: Disabling NewRefCount, --new-refcount:false, is deprecated. +### MT0080: Disabling NewRefCount, --new-refcount:false, is deprecated. This is a warning informing that the request to disable the new refcount (--new-refcount:false) has been ignored. The new refcount feature is now mandatory for all projects, and it's thus not possible to disable anymore. -### MT0081: The command line argument --download-crash-report also requires --download-crash-report-to. -### MT0082: REPL (--enable-repl) is only supported when linking is not used (--nolink). -### MT0083: Asm-only bitcode is not supported on watchOS. Use either --bitcode:marker or --bitcode:full. -### MT0084: Bitcode is not supported in the simulator. Do not pass --bitcode when building for the simulator. -### MT0085: No reference to '*' was found. It will be added automatically. -### MT0086: A target framework (--target-framework) must be specified when building for TVOS or WatchOS. + + +### MT0081: The command line argument --download-crash-report also requires --download-crash-report-to. + + + +### MT0082: REPL (--enable-repl) is only supported when linking is not used (--nolink). + + + +### MT0083: Asm-only bitcode is not supported on watchOS. Use either --bitcode:marker or --bitcode:full. + + -This usually indicates a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. +### MT0084: Bitcode is not supported in the simulator. Do not pass --bitcode when building for the simulator. -### MT0087: Incremental builds (--fastdev) is not supported with the Boehm GC. Incremental builds will be disabled. + -### MT0088: The GC must be in cooperative mode for watchOS apps. Please remove the --coop:false argument to mtouch. +### MT0085: No reference to '*' was found. It will be added automatically. -### MT0089: The option '\*' cannot take the value '\*' when cooperative mode is enabled for the GC. + -### MT0091: This version of Xamarin.iOS requires the * SDK (shipped with Xcode *). Either upgrade Xcode to get the required header files or set the managed linker behaviour to Link Framework SDKs Only (to try to avoid the new APIs). +### MT0086: A target framework (--target-framework) must be specified when building for TVOS or WatchOS. + +This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). + + + +### MT0087: Incremental builds (--fastdev) is not supported with the Boehm GC. Incremental builds will be disabled. + + + +### MT0088: The GC must be in cooperative mode for watchOS apps. Please remove the --coop:false argument to mtouch. + + + +### MT0089: The option '\*' cannot take the value '\*' when cooperative mode is enabled for the GC. + + + +### MT0091: This version of Xamarin.iOS requires the * SDK (shipped with Xcode *). Either upgrade Xcode to get the required header files or set the managed linker behaviour to Link Framework SDKs Only (to try to avoid the new APIs). Xamarin.iOS requires the header files, from the SDK version specified in the error message, to build your application. The recommended way to fix this error is to upgrade Xcode to get the required SDK, this will include all the required header files. If you have multiple versions of Xcode installed, or want to use an Xcode in a non-default location, make sure to set the correct Xcode location in your IDE's preferences. @@ -382,34 +545,48 @@ A last-straw solution would be to use an older version of Xamarin.iOS, one that -### MT0093: Could not find 'mlaunch'. + + +### MT0093: Could not find 'mlaunch'. -### MT0095: Aot files could not be copied to the destination directory {dest}: {error} + -### MT0096: No reference to Xamarin.iOS.dll was found. +### MT0095: Aot files could not be copied to the destination directory {dest}: {error} + + + +### MT0096: No reference to Xamarin.iOS.dll was found. -### MT0099: Internal error *. Please file a bug report with a test case (http://bugzilla.xamarin.com). + + +### MT0099: Internal error *. Please file a bug report with a test case (http://bugzilla.xamarin.com). This error message is reported when an internal consistency check in Xamarin.iOS fails. -This indicates a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. -### MT0100: Invalid assembly build target: '*'. Please file a bug report with a test case (http://bugzilla.xamarin.com). + + +### MT0100: Invalid assembly build target: '*'. Please file a bug report with a test case (http://bugzilla.xamarin.com). This error message is reported when an internal consistency check in Xamarin.iOS fails. -This is always a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test case. +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. + + -### MT0101: The assembly '*' is specified multiple times in --assembly-build-target arguments. +### MT0101: The assembly '*' is specified multiple times in --assembly-build-target arguments. The assembly mentioned in the error message is specified multiple times in --assembly-build-target arguments. Please make sure each assembly is only mentioned once. -### MT0102: The assemblies '\*' and '\*' have the same target name ('\*'), but different targets ('\*' and '*'). + + +### MT0102: The assemblies '\*' and '\*' have the same target name ('\*'), but different targets ('\*' and '*'). The assemblies mentioned in the error message have conflicting build targets. @@ -419,7 +596,9 @@ For example: This example is trying to create both a dynamic library and a framework with the same make (`MyBinary`). -### MT0103: The static object '\*' contains more than one assembly ('\*'), but each static object must correspond with exactly one assembly. + + +### MT0103: The static object '\*' contains more than one assembly ('\*'), but each static object must correspond with exactly one assembly. The assemblies mentioned in the error message are all compiled to a single static object. This is not allowed, every assembly must be compiled to a different static object. @@ -429,7 +608,9 @@ For example: This example tries to build a static object (`MyBinary`) comprised of two assemblies (`Assembly1.dll` and `Assembly2.dll`), which is not allowed. -### MT0105: No assembly build target was specified for '*'. + + +### MT0105: No assembly build target was specified for '*'. When specifying the assembly build target using `--assembly-build-target`, every assembly in the app must have a build target assigned. @@ -437,7 +618,9 @@ This error is reported when the assembly mentioned in the error message does not See the documentation about `--assembly-build-target` for further information. -### MT0106: The assembly build target name '\*' is invalid: the character '\*' is not allowed. + + +### MT0106: The assembly build target name '\*' is invalid: the character '\*' is not allowed. The assembly build target name must be a valid filename. @@ -447,17 +630,25 @@ For example these values will trigger this error: because `my/path.o` is not a valid filename due to the directory separator character. -### MT0107: The assemblies '\*' have different custom LLVM optimizations (\*), which is not allowed when they are all compiled to a single binary. + + +### MT0107: The assemblies '\*' have different custom LLVM optimizations (\*), which is not allowed when they are all compiled to a single binary. -### MT0108: The assembly build target '*' did not match any assemblies. + -### MT0109: The assembly '{0}' was loaded from a different path than the provided path (provided path: {1}, actual path: {2}). +### MT0108: The assembly build target '*' did not match any assemblies. + + + +### MT0109: The assembly '{0}' was loaded from a different path than the provided path (provided path: {1}, actual path: {2}). This is a warning indicating that an assembly referenced by the application was loaded from a different location than requested. This might mean that the app is referencing multiple assemblies with the same name, but from different locations, which might lead to unexpected results (only the first assembly will be used). -### MT0110: Incremental builds have been disabled because this version of Xamarin.iOS does not support incremental builds in projects that include third-party binding libraries and that compiles to bitcode. + + +### MT0110: Incremental builds have been disabled because this version of Xamarin.iOS does not support incremental builds in projects that include third-party binding libraries and that compiles to bitcode. Incremental builds have been disabled because this version of Xamarin.iOS does not support incremental builds in projects that include third-party binding libraries and that compiles to bitcode (tvOS and watchOS projects). @@ -467,7 +658,9 @@ For further information see bug #[51710](https://bugzilla.xamarin.com/show_bug.c This warning is not reported anymore. -### MT0111: Bitcode has been enabled because this version of Xamarin.iOS does not support building watchOS projects using LLVM without enabling bitcode. + + +### MT0111: Bitcode has been enabled because this version of Xamarin.iOS does not support building watchOS projects using LLVM without enabling bitcode. Bitcode has been enabled automatically because this version of Xamarin.iOS does not support building watchOS projects using LLVM without enabling bitcode. @@ -475,7 +668,9 @@ No action is required on your part, this message is purely informational. For further information see bug #[51634](https://bugzilla.xamarin.com/show_bug.cgi?id=51634). -### MT0112: Native code sharing has been disabled because * + + +### MT0112: Native code sharing has been disabled because * There are multiple reasons code sharing can be disabled: @@ -491,8 +686,9 @@ Native code sharing is currently not supported if the container app includes I18 Native code sharing requires is not supported for projects that use custom xml definitions for the managed linker. + -### MT0113: Native code sharing has been disabled for the extension '*' because *. +### MT0113: Native code sharing has been disabled for the extension '*' because *. * because the bitcode options differ between the container app (\*) and the extension (\*). @@ -552,7 +748,9 @@ Native code sharing requires is not supported for projects that use custom xml d -### MT0115: It is recommended to reference dynamic symbols using code (--dynamic-symbol-mode=code) when bitcode is enabled. + + +### MT0115: It is recommended to reference dynamic symbols using code (--dynamic-symbol-mode=code) when bitcode is enabled. Xamarin.iOS projects will often reference native symbols dynamically, which means that the native linker might remove such native symbols during the @@ -573,7 +771,11 @@ linker. This will most likely result in native linker errors. The solution is to remove the `--dynamic-symbol-mode=linker` argument from the additional mtouch arguments in the project's Build options. -### MT0116: Invalid architecture: {arch}. 32-bit architectures are not supported when deployment target is 11 or later. Make sure the project does not build for a 32-bit architecture. + + + + +### MT0116: Invalid architecture: {arch}. 32-bit architectures are not supported when deployment target is 11 or later. Make sure the project does not build for a 32-bit architecture. iOS 11 does not contain support for 32-bit applications, so it's not supported to build for a 32-bit application when the deployment target is iOS 11 or @@ -583,13 +785,19 @@ Either change the target architecture in the project's iOS build options to arm64, or change the deployment target in the project's Info.plist to an earlier iOS version. -### MT0117: Can't launch a 32-bit app on a simulator that only supports 64-bit. + + +### MT0117: Can't launch a 32-bit app on a simulator that only supports 64-bit. + + -### MT0116: Aot files could not be found at the expected directory '{msymdir}'. +### MT0118: Aot files could not be found at the expected directory '{msymdir}'. -### MT0123: The executable assembly * does not reference *. + + +### MT0123: The executable assembly * does not reference *. No reference could be found to the platform assembly (Xamarin.iOS.dll / Xamarin.TVOS.dll / Xamarin.WatchOS.dll) in the executable assembly. @@ -614,21 +822,29 @@ class Program { } ``` -### MT0124: Could not set the current language to '{lang}' (according to LANG={LANG}): {exception} + + +### MT0124: Could not set the current language to '{lang}' (according to LANG={LANG}): {exception} This is a warning, indicating that the current language couldn't be set to the language in the error message. The current language will default to the system language. -### MT0125: The --assembly-build-target command-line argument is ignored in the simulator. + + +### MT0125: The --assembly-build-target command-line argument is ignored in the simulator. No action is required, this message is purely informational. -### MT0126: Incremental builds have been disabled because incremental builds are not supported in the simulator. + + +### MT0126: Incremental builds have been disabled because incremental builds are not supported in the simulator. No action is required, this message is purely informational. -### MT0127: Incremental builds have been disabled because this version of Xamarin.iOS does not support incremental builds in projects that include more than one third-party binding libraries. + + +### MT0127: Incremental builds have been disabled because this version of Xamarin.iOS does not support incremental builds in projects that include more than one third-party binding libraries. Incremental builds have been disabled automatically because this version of Xamarin.iOS does not always build projects with multiple third-party binding libraries correctly. @@ -636,13 +852,17 @@ No action is required, this message is purely informational. For further information see bug #[52727](https://bugzilla.xamarin.com/show_bug.cgi?id=52727). -### MT0128: Could not touch the file '*': * + + +### MT0128: Could not touch the file '*': * A failure occurred when touching a file (which is done to ensure partial builds are done correctly). -This warning can most likely be ignored; in case of any problems file a bug (https://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS)) and it will be investigated. +This warning can most likely be ignored; in case of any problems file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) and it will be investigated. + + -### MT0129: Debugging symbol file for '*' does not match the assembly and is ignored. +### MT0129: Debugging symbol file for '*' does not match the assembly and is ignored. The debugging symbols, either a .pdb (portable pdb only) or a .mdb file, for the specified assembly could not be loaded. @@ -652,14 +872,20 @@ This warning won't affect the application being built, however you might not be Please report this issue to the publisher of the assembly package (e.g. nuget author) so this can be fixed in their future releases. -### MT0130: No root assemblies found. You should provide at least one root assembly. + + +### MT0130: No root assemblies found. You should provide at least one root assembly. When running --runregistrar, at least one root assembly should be provided. -### MT0131: Product assembly '{0}' not found in assembly list: '{1}' + + +### MT0131: Product assembly '{0}' not found in assembly list: '{1}' When running --runregistrar, the assembly list should include the product assembly, Xamarin.iOS, Xamarin.WatchOS, Xamarin.TVOS. -### + +### MT0132: Unknown optimization: *. Valid values are: * The specified optimization was not recognized. @@ -667,13 +893,17 @@ The accepted format is `[+|-]optimization-name`, where `optimization-name` is on See [Build optimizations](https://developer.xamarin.com/guides/cross-platform/macios/build-optimization/) for a complete description of each optimization. -### MT0133: Found more than 1 assembly matching '{0}' choosing first: '{1}' + + +### MT0133: Found more than 1 assembly matching '{0}' choosing first: '{1}' When using --recursive-directories, only 1 assembly should match -### MT0135: Did not link system framework '{0}' (referenced by assembly '{1}') because it was introduced in {2} {3}, and we're using the {2} {4} SDK. + + +### MT0135: Did not link system framework '{0}' (referenced by assembly '{1}') because it was introduced in {2} {3}, and we're using the {2} {4} SDK. To build your application, Xamarin.iOS must link against system libraries, some of which depend upon the SDK version specified in the error message. Since you are using an older version of the SDK, invocations to those APIs may fail at runtime. @@ -710,37 +940,39 @@ means that if the build otherwise succeeds, this warning can be ignored. MT10xx installer.cs / mtouch.cs --> -### MT1001 Could not find an application at the specified directory - - - -### MT1002 Could not create symlinks, files were copied - - + -### MT1003 Could not kill the application '*'. You may have to kill the application manually. +### MT1001: Could not find an application at the specified directory + +### MT1002: Could not create symlinks, files were copied -### MT1004 Could not get the list of installed applications. + +### MT1003: Could not kill the application '*'. You may have to kill the application manually. + -### MT1005 Could not kill the application '\*' on the device '\*': *- You may have to kill the application manually. +### MT1004: Could not get the list of installed applications. +## MT1xxx: Project related error messages + -### MT1006 Could not install the application '\*' on the device '\*': *. +### MT1005: Could not kill the application '\*' on the device '\*': *- You may have to kill the application manually. + +### MT1006: Could not install the application '\*' on the device '\*': *. -### MT1007 Failed to launch the application '\*' on the device '\*': *. You can still launch the application manually by tapping on it. + +### MT1007: Failed to launch the application '\*' on the device '\*': *. You can still launch the application manually by tapping on it. + -### MT1008: Failed to launch the simulator - - +### MT1008: Failed to launch the simulator This error is reported if mtouch failed to launch the simulator. This can happen sometimes because there is @@ -749,54 +981,73 @@ This error is reported if mtouch failed to launch the The following command issued on the Unix command line can be used to kill stuck simulator processes: -``` +```bash $ launchctl list|grep UIKitApplication|awk '{print $3}'|xargs launchctl remove ``` -### MT1009 Could not copy the assembly '\*' to '\*': * + + +### MT1009: Could not copy the assembly '\*' to '\*': * This is a known issue in certain versions of Xamarin.iOS. If this occurs to you, try the following workaround: - sudo chmod 0644 /Library/Frameworks/Xamarin.iOS.framework/Versions/Current/lib/mono/*/*.mdb +```bash +sudo chmod 0644 /Library/Frameworks/Xamarin.iOS.framework/Versions/Current/lib/mono/*/*.mdb +``` However, since this issue has been resolved in the latest version of -Xamarin.iOS, please file a new bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) +Xamarin.iOS, please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with your full version information and build log output. -### MT1010 Could not load the assembly '*': * + +### MT1010: Could not load the assembly '*': * + -### MT1011 Could not add missing resource file: '*' +### MT1011: Could not add missing resource file: '*' + +### MT1012: Failed to list the apps on the device '*': * -### MT1012 Failed to list the apps on the device '*': * + +### MT1013: Dependency tracking error: no files to compare. Please file a bug report at http://bugzilla.xamarin.com with a test case. +This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case. -### MT1013 Dependency tracking error: no files to compare. Please file a bug report at http://bugzilla.xamarin.com with a test case. + -This indicates a bug in Xamarin.iOS. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a test caes. +### MT1014: Failed to re-use cached version of '*': *. -### MT1014 Failed to re-use cached version of '*': *. + +### MT1015: Failed to create the executable '*': * + -### MT1015 Failed to create the executable '*': * +### MT1015: Failed to create the executable '*': * -### MT1015 Failed to create the executable '*': * + -### MT1016: Failed to create the NOTICE file because a directory already exists with the same name. +### MT1016: Failed to create the NOTICE file because a directory already exists with the same name. Remove the directory `NOTICE` from the project. -### MT1017: Failed to create the NOTICE file: *. + + +### MT1017: Failed to create the NOTICE file: *. -### MT1018: Your application failed code-signing checks and could not be installed on the device '*'. Check your certificates, provisioning profiles, and bundle ids. Probably your device is not part of the selected provisioning profile (error: 0xe8008015). -### MT1019: Your application has entitlements not supported by your current provisioning profile and could not be installed on the device '*'. Please check the iOS Device Log for more detailed information (error: 0xe8008016). + + +### MT1018: Your application failed code-signing checks and could not be installed on the device '*'. Check your certificates, provisioning profiles, and bundle ids. Probably your device is not part of the selected provisioning profile (error: 0xe8008015). + + + +### MT1019: Your application has entitlements not supported by your current provisioning profile and could not be installed on the device '*'. Please check the iOS Device Log for more detailed information (error: 0xe8008016). This can happen if: @@ -809,20 +1060,27 @@ This can happen if: - Create a new app from a template in Xcode, select the same provisioning profile, and deploy to same device. Sometimes Xcode can automatically refresh provisioning profiles with new devices (in other cases Xcode will ask you what to do). -Go to the iOS Dev Center and update the provisioning profile with the new device, then download the updated provisioning profile to your machine. - In most cases more information about the failure will be printed to the iOS Device Log, which can help diagnosing the issue. -### MT1020: Failed to launch the application '\*' on the device '\*': * + -### MT1021: Could not copy the file '\*' to '\*': {2} +### MT1020: Failed to launch the application '\*' on the device '\*': * + + + +### MT1021: Could not copy the file '\*' to '\*': {2} A file could not be copied. The error message from the copy operation has more information about the error. -### MT1022: Could not copy the directory '\*' to '\*': {2} + + +### MT1022: Could not copy the directory '\*' to '\*': {2} A directory could not be copied. The error message from the copy operation has more information about the error. -### MT1023: Could not communicate with the device to find the application '*' : * + + +### MT1023: Could not communicate with the device to find the application '*' : * An error occurred when trying to lookup an application on device. @@ -833,13 +1091,17 @@ Things to try to solve this: * Reboot the device. * Reboot the Mac. -### MT1024: The application signature could not be verified on device '*'. Please make sure that the provisioning profile is installed and not expired (error: 0xe8008017). + + +### MT1024: The application signature could not be verified on device '*'. Please make sure that the provisioning profile is installed and not expired (error: 0xe8008017). The device rejected the application install because the signature could not be verified. Please make sure that the provisioning profile is installed and not expired. -### MT1025: Could not list the crash reports on the device *. + + +### MT1025: Could not list the crash reports on the device *. An error occurred when trying to list the crash reports on the device. @@ -851,7 +1113,9 @@ Things to try to solve this: * Reboot the Mac. * Synchronize the device with iTunes (this will remove any crash reports from the device). -### MT1026: Could not download the crash report * from the device *. + + +### MT1026: Could not download the crash report * from the device *. An error occurred when trying to download the crash reports from the device. @@ -863,35 +1127,51 @@ Things to try to solve this: * Reboot the Mac. * Synchronize the device with iTunes (this will remove any crash reports from the device). -### MT1027: Can't use Xcode 7+ to launch applications on devices with iOS * (Xcode 7 only supports iOS 6+). + + +### MT1027: Can't use Xcode 7+ to launch applications on devices with iOS * (Xcode 7 only supports iOS 6+). It is not possible to use Xcode 7+ to launch applications on devices with iOS version below 6.0. Please use an older version of Xcode, or tap on the app manually to launch it. -### MT1028: Invalid device specification: '*'. Expected 'ios', 'watchos' or 'all'. + + +### MT1028: Invalid device specification: '*'. Expected 'ios', 'watchos' or 'all'. The device specification passed using --device is invalid. Valid values are: 'ios', 'watchos' or 'all'. -### MT1029: Could not find an application at the specified directory: * + + +### MT1029: Could not find an application at the specified directory: * The application path passed to --launchdev does not exist. Please specify a valid app bundle. -### MT1030: Launching applications on device using a bundle identifier is deprecated. Please pass the full path to the bundle to launch. + + +### MT1030: Launching applications on device using a bundle identifier is deprecated. Please pass the full path to the bundle to launch. It's recommended to pass the path to the app to launch on device instead of just the bundle id. -### MT1031: Could not launch the app '\*' on the device '\*' because the device is locked. Please unlock the device and try again. + + +### MT1031: Could not launch the app '\*' on the device '\*' because the device is locked. Please unlock the device and try again. Please unlock the device and try again. -### MT1032: This application executable might be too large (* MB) to execute on device. If bitcode was enabled you might want to disable it for development, it is only required to submit applications to Apple. + + +### MT1032: This application executable might be too large (* MB) to execute on device. If bitcode was enabled you might want to disable it for development, it is only required to submit applications to Apple. + + -### MT1033: Could not uninstall the application '\*' from the device '\*': * +### MT1033: Could not uninstall the application '\*' from the device '\*': * -### MT1035: Cannot include different versions of the framework '{name}' + + +### MT1035: Cannot include different versions of the framework '{name}' It is not possible to link with different versions of the same framework. @@ -899,7 +1179,9 @@ This typically happens when an extension references a different version of a fra Following this error there will be multiple [MT1036](#MT1036) errors listing the paths for each different framework. -### MT1036: Framework '{name}' included from: {path} (Related to previous error) + + +### MT1036: Framework '{name}' included from: {path} (Related to previous error) This error is reported only together with [MT1036](#MT1036). Please see [MT1036](#MT1036) for more information. @@ -909,37 +1191,41 @@ This error is reported only together with [MT1036](#MT1036). Please see [MT1036] MT11xx DebugService.cs --> -### MT1101 Could not start app - + +### MT1101: Could not start app -### MT1102 Could not attach to the app (to kill it): * + +### MT1102: Could not attach to the app (to kill it): * + -### MT1103 Could not detach +### MT1103: Could not detach + +### MT1104: Failed to send packet: * -### MT1104 Failed to send packet: * + +### MT1105: Unexpected response type + -### MT1105 Unexpected response type +### MT1106: Could not get list of applications on the device: Request timed out. + - -### MT1106 Could not get list of applications on the device: Request timed out. - - - -### MT1107: Application failed to launch: * +### MT1107: Application failed to launch: * Please check if your device is locked. If you're deploying an enterprise app or using a free provisioning profile, you might have trust the developer (this is explained here). -### MT1108: Could not find developer tools for this XX (YY) device. + + +### MT1108: Could not find developer tools for this XX (YY) device. A few operations from mtouch require the DeveloperDiskImage.dmg file to be present. This file is part of Xcode and is usually located relative to the @@ -950,16 +1236,21 @@ This error can happen either because you do not have a DeveloperDiskImage.dmg that matches the device that you have connected. + -### MT1109: Application failed to launch because the device is locked. Please unlock the device and try again. +### MT1109: Application failed to launch because the device is locked. Please unlock the device and try again. Please check if your device is locked. -### MT1110: Application failed to launch because of iOS security restrictions. Please ensure the developer is trusted. + + +### MT1110: Application failed to launch because of iOS security restrictions. Please ensure the developer is trusted. If you're deploying an enterprise app or using a free provisioning profile, you might have trust the developer (this is explained here). -### MT1111: Application launched successfully, but it's not possible to wait for the app to exit as requested because it's not possible to detect app termination when launching using gdbserver. + + +### MT1111: Application launched successfully, but it's not possible to wait for the app to exit as requested because it's not possible to detect app termination when launching using gdbserver. ### MT12xx: Simulator @@ -967,26 +1258,85 @@ If you're deploying an enterprise app or using a free provisioning profile, you MT12xx simcontroller.cs --> -### MT1201: Could not load the simulator: * -### MT1202: Invalid simulator configuration: * -### MT1203: Invalid simulator specification: * -### MT1204: Invalid simulator specification '*': runtime not specified. -### MT1205: Invalid simulator specification '*': device type not specified. -### MT1206: Could not find the simulator runtime '*'. -### MT1207: Could not find the simulator device type '*'. -### MT1208: Could not find the simulator runtime '*'. -### MT1209: Could not find the simulator device type '*'. -### MT1210: Invalid simulator specification: \*, unknown key '\*' -### MT1211: The simulator version '\*' does not support the simulator type '\*' -### MT1212: Failed to create a simulator version where type = * and runtime = *. -### MT1213: Invalid simulator specification for Xcode 4: * -### MT1214: Invalid simulator specification for Xcode 5: * -### MT1215: Invalid SDK specified: * -### MT1216: Could not find the simulator UDID '*'. -### MT1217: Could not load the app bundle at '*'. -### MT1218: No bundle identifier found in the app at '*'. -### MT1219: Could not find the simulator for '*'. -### MT1220: Could not find the latest simulator runtime for device '*'. + + +### MT1201: Could not load the simulator: * + + + +### MT1202: Invalid simulator configuration: * + + + +### MT1203: Invalid simulator specification: * + + + +### MT1204: Invalid simulator specification '*': runtime not specified. + + + +### MT1205: Invalid simulator specification '*': device type not specified. + + + +### MT1206: Could not find the simulator runtime '*'. + + + +### MT1207: Could not find the simulator device type '*'. + + + +### MT1208: Could not find the simulator runtime '*'. + + + +### MT1209: Could not find the simulator device type '*'. + + + +### MT1210: Invalid simulator specification: \*, unknown key '\*' + + + +### MT1211: The simulator version '\*' does not support the simulator type '\*' + + + +### MT1212: Failed to create a simulator version where type = * and runtime = *. + + + +### MT1213: Invalid simulator specification for Xcode 4: * + + + +### MT1214: Invalid simulator specification for Xcode 5: * + + + +### MT1215: Invalid SDK specified: * + + + +### MT1216: Could not find the simulator UDID '*'. + + + +### MT1217: Could not load the app bundle at '*'. + + + +### MT1218: No bundle identifier found in the app at '*'. + + + +### MT1219: Could not find the simulator for '*'. + + + +### MT1220: Could not find the latest simulator runtime for device '*'. This usually indicates a problem with Xcode. @@ -996,7 +1346,9 @@ Things to try to fix this: * Pass an explicit SDK version using --sdk . * Reinstall Xcode. -### MT1221: Could not find the paired iPhone simulator for the WatchOS simulator '*'. + + +### MT1221: Could not find the paired iPhone simulator for the WatchOS simulator '*'. When launching a WatchOS app in a WatchOS simulator, there must be a paired iOS Simulator as well. @@ -1008,26 +1360,33 @@ Watch simulators can be paired with iOS Simulators using Xcode's Devices UI (men MT13xx [LinkWith] --> + -### MT1301 Native library `*` (\*) was ignored since it does not match the current build architecture(s) (\*) +### MT1301: Native library `*` (\*) was ignored since it does not match the current build architecture(s) (\*) + +### MT1302: Could not extract the native library '*' from '+'. Please ensure the native library was properly embedded in the managed assembly (if the assembly was built using a binding project, the native library must be included in the project, and its Build Action must be 'ObjcBindingNativeLibrary'). -### MT1302 Could not extract the native library '*' from '+'. Please ensure the native library was properly embedded in the managed assembly (if the assembly was built using a binding project, the native library must be included in the project, and its Build Action must be 'ObjcBindingNativeLibrary'). + -### MT1303: Could not decompress the native framework '\*' from '\*'. Please review the build log for more information from the native 'zip' command. +### MT1303: Could not decompress the native framework '\*' from '\*'. Please review the build log for more information from the native 'zip' command. Could not decompress the specified native framework from the binding library. Please review the bulid log for more information about this failure from the native 'zip' command. -### MT1304: The embedded framework '*' in * is invalid: it does not contain an Info.plist. + + +### MT1304: The embedded framework '*' in * is invalid: it does not contain an Info.plist. The specified embedded framework does not contain an Info.plist, and is therefore not a valid framework. Please make sure the framework is valid. -### MT1305: The binding library '\*' contains a user framework (\*), but embedded user frameworks require iOS 8.0 (the current deployment target is *). Please set the deployment target in the Info.plist file to at least 8.0. + + +### MT1305: The binding library '\*' contains a user framework (\*), but embedded user frameworks require iOS 8.0 (the current deployment target is *). Please set the deployment target in the Info.plist file to at least 8.0. The specified binding library contains an embedded framework, but Xamarin.iOS only supports embedded frameworks on iOS 8.0 or later. @@ -1039,7 +1398,9 @@ Please set the deployment target in the Info.plist file to at least 8.0 to solve MT14xx CrashReports.cs --> -### MT1400: Could not open crash report service: AFCConnectionOpen returned * + + +### MT1400: Could not open crash report service: AFCConnectionOpen returned * An error occurred when trying to access crash reports from the device. @@ -1051,7 +1412,9 @@ Things to try to solve this: * Reboot the Mac. * Synchronize the device with iTunes (this will remove any crash reports from the device). -### MT1401: Could not close crash report service: AFCConnectionClose returned * + + +### MT1401: Could not close crash report service: AFCConnectionClose returned * An error occurred when trying to access crash reports from the device. @@ -1063,7 +1426,9 @@ Things to try to solve this: * Reboot the Mac. * Synchronize the device with iTunes (this will remove any crash reports from the device). -### MT1402: Could not read file info for *: AFCFileInfoOpen returned * + + +### MT1402: Could not read file info for *: AFCFileInfoOpen returned * An error occurred when trying to access crash reports from the device. @@ -1075,7 +1440,9 @@ Things to try to solve this: * Reboot the Mac. * Synchronize the device with iTunes (this will remove any crash reports from the device). -### MT1403: Could not read crash report: AFCDirectoryOpen (*) returned: * + + +### MT1403: Could not read crash report: AFCDirectoryOpen (*) returned: * An error occurred when trying to access crash reports from the device. @@ -1087,7 +1454,9 @@ Things to try to solve this: * Reboot the Mac. * Synchronize the device with iTunes (this will remove any crash reports from the device). -### MT1404: Could not read crash report: AFCFileRefOpen (*) returned: * + + +### MT1404: Could not read crash report: AFCFileRefOpen (*) returned: * An error occurred when trying to access crash reports from the device. @@ -1099,7 +1468,9 @@ Things to try to solve this: * Reboot the Mac. * Synchronize the device with iTunes (this will remove any crash reports from the device). -### MT1405: Could not read crash report: AFCFileRefRead (*) returned: * + + +### MT1405: Could not read crash report: AFCFileRefRead (*) returned: * An error occurred when trying to access crash reports from the device. @@ -1111,7 +1482,9 @@ Things to try to solve this: * Reboot the Mac. * Synchronize the device with iTunes (this will remove any crash reports from the device). -### MT1406: Could not list crash reports: AFCDirectoryOpen (*) returned: * + + +### MT1406: Could not list crash reports: AFCDirectoryOpen (*) returned: * An error occurred when trying to access crash reports from the device. @@ -1131,7 +1504,9 @@ Things to try to solve this: MT16xx MachO.cs --> -### MT1600: Not a Mach-O dynamic library (unknown header '0x*'): *. + + +### MT1600: Not a Mach-O dynamic library (unknown header '0x*'): *. An error occurred while processing the dynamic library in question. @@ -1141,7 +1516,9 @@ The format of a library can be verified using the `file` command from a terminal file -arch all -l /path/to/library.dylib -### MT1601: Not a static library (unknown header '*'): *. + + +### MT1601: Not a static library (unknown header '*'): *. An error occurred while processing the static library in question. @@ -1151,7 +1528,9 @@ The format of a library can be verified using the `file` command from a terminal file -arch all -l /path/to/library.a -### MT1602: Not a Mach-O dynamic library (unknown header '0x*'): *. + + +### MT1602: Not a Mach-O dynamic library (unknown header '0x*'): *. An error occurred while processing the dynamic library in question. @@ -1161,7 +1540,9 @@ The format of a library can be verified using the `file` command from a terminal file -arch all -l /path/to/library.dylib -### MT1603: Unknown format for fat entry at position * in *. + + +### MT1603: Unknown format for fat entry at position * in *. An error occurred while processing the fat archive in question. @@ -1171,7 +1552,9 @@ The format of a fat archive can be verified using the `file` command from a term file -arch all -l /path/to/file -### MT1604: File of type * is not a MachO file (*). + + +### MT1604: File of type * is not a MachO file (*). An error occurred while processing the MachO file in question. @@ -1181,14 +1564,16 @@ The format of a file can be verified using the `file` command from a terminal: file -arch all -l /path/to/file -# MT2xxx: Linker error messages +## MT2xxx: Linker error messages -### MT2001 Could not link assemblies + + +### MT2001: Could not link assemblies This error means that the managed linker encountered an unexpected error, e.g. an exception, and could not complete or save the assembly being processed. More information about the exact error will be part of the build log, e.g. @@ -1202,33 +1587,38 @@ Parameter name: instruction It is important to file a bug report for such issues. In most case a workaround can be provided until a proper fix is published. The above information is critical (along with a test case and/or the assembly binairy) to resolve the issue. + -### MT2002 Can not resolve reference: * - - - -### MT2003 Option '*' will be ignored since linking is disabled - +### MT2002: Can not resolve reference: * + -### MT2004 Extra linker definitions file '*' could not be located. +### MT2003: Option '*' will be ignored since linking is disabled + +### MT2004: Extra linker definitions file '*' could not be located. -### MT2005 Definitions from '*' could not be parsed. + +### MT2005: Definitions from '*' could not be parsed. + -### MT2006: Can not load mscorlib.dll from: *. Please reinstall Xamarin.iOS. +### MT2006: Can not load mscorlib.dll from: *. Please reinstall Xamarin.iOS. This generally indicates that there is a problem with your Xamarin.iOS installation. Please try reinstalling Xamarin.iOS. -### MT2010: Unknown HttpMessageHandler `*`. Valid values are HttpClientHandler (default), CFNetworkHandler or NSUrlSessionHandler + -### MT2011: Unknown TlsProvider `*`. Valid values are default or appletls. +### MT2010: Unknown HttpMessageHandler `*`. Valid values are HttpClientHandler (default), CFNetworkHandler or NSUrlSessionHandler + + + +### MT2011: Unknown TlsProvider `*`. Valid values are default or appletls. The value given to `tls-provider=` is not a valid TLS (Transport Layer Security) provider. @@ -1238,7 +1628,9 @@ The `default` and `appletls` are the only valid values and both represent the sa -### MT2015: Invalid HttpMessageHandler `*` for watchOS. The only valid value is NSUrlSessionHandler. + + +### MT2015: Invalid HttpMessageHandler `*` for watchOS. The only valid value is NSUrlSessionHandler. This is a warning that occurs because the project file specifies an invalid HttpMessageHandler. @@ -1246,168 +1638,184 @@ Earlier versions of our preview tools generated by default an invalid value in t To fix this warning, open the project file in a text editor, and remove all HttpMessageHandler nodes from the XML. -### MT2016: Invalid TlsProvider `legacy` option. The only valid value `appletls` will be used. + + +### MT2016: Invalid TlsProvider `legacy` option. The only valid value `appletls` will be used. The `legacy` provider, which was a fully managed SSLv3 / TLSv1 only provider, is not shipped with Xamarin.iOS anymore. Projects that were using this old provider and now build with the newer `appletls` one. To fix this warning, open the project file in a text editor, and remove all `MtouchTlsProvider`` nodes from the XML. -### MT2017: Could not process XML description. + + +### MT2017: Could not process XML description. This means there is an error on the [custom XML linker configuration file](https://developer.xamarin.com/guides/cross-platform/advanced/custom_linking/) you provided, please review your file. -### MT2018: The assembly '\*' is referenced from two different locations: '\*' and '*'. + + +### MT2018: The assembly '\*' is referenced from two different locations: '\*' and '*'. The assembly mentioned in the error message is loaded from multiple locations. Make sure to always use the same version of an assembly. -### MT2019: Can not load the root assembly '*' + + +### MT2019: Can not load the root assembly '*' The root assembly could not be loaded. Please verify that the path in the error message refers to an existing file, and that it's a valid .NET assembly. -### MT202x: Binding Optimizer failed processing `...`. + -Something unexpected occured when trying to optimize generated binding code. The element causing the issue is named in the error message. In order to fix this issue the assembly named (or containing the type or method named) will need to be provided in a [bug report](http://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). +### MT202x: Binding Optimizer failed processing `...`. + +Something unexpected occured when trying to optimize generated binding code. The element causing the issue is named in the error message. To fix this issue the assembly named (or containing the type or method named) will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). The last digit `x` will be: * `0` for an assembly name; * `1` for a type name; * `3` for a method name; -### MT2030: Remove User Resources failed processing `...`. + + +### MT2030: Remove User Resources failed processing `...`. -Something unexpected occured when trying to remove user resources. The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](http://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). +Something unexpected occured when trying to remove user resources. The assembly causing the issue is named in the error message. To fix this issue the assembly will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). User resources are files included inside assemblies (as resources) that needs to be extracted, at build time, to create the application bundle. This includes: * `__monotouch_content_*` and `__monotouch_pages_*` resources; and * Native libraries embedded inside a binding assembly; -### MT2040: Default HttpMessageHandler setter failed processing `...`. + -Something unexpected occured when trying to set the default `HttpMessageHandler` for the application. Please file a [bug report](http://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). +### MT2040: Default HttpMessageHandler setter failed processing `...`. -### MT2050: Code Remover failed processing `...`. +Something unexpected occured when trying to set the default `HttpMessageHandler` for the application. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -Something unexpected occured when trying to remove code from BCL shipping with the application. Please file a [bug report](http://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). + -### MT2060: Sealer failed processing `...`. +### MT2050: Code Remover failed processing `...`. -Something unexpected occured when trying to seal types or methods (final) or when devirtualizing some methods. The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](http://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). +Something unexpected occured when trying to remove code from BCL shipping with the application. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -### MT2070: Metadata Reducer failed processing `...`. + -Something unexpected occured when trying to reduce the metadata from the application. The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](http://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). +### MT2060: Sealer failed processing `...`. -### MT2080: MarkNSObjects failed processing `...`. +Something unexpected occured when trying to seal types or methods (final) or when devirtualizing some methods. The assembly causing the issue is named in the error message. To fix this issue the assembly will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -Something unexpected occured when trying to mark `NSObject` subclasses from the application. The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](http://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). + -### MT2090: Inliner failed processing `...`. +### MT2070: Metadata Reducer failed processing `...`. -Something unexpected occured when trying to inline code from the application. The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](https://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). +Something unexpected occured when trying to reduce the metadata from the application. The assembly causing the issue is named in the error message. To fix this issue the assembly will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -### MT2100: Smart Enum Conversion Preserver failed processing `...`. + -Something unexpected occured when trying to mark the conversion methods for smart enums from the application. The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](https://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). +### MT2080: MarkNSObjects failed processing `...`. - +Something unexpected occured when trying to mark `NSObject` subclasses from the application. The assembly causing the issue is named in the error message. To fix this issue the assembly will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). - + -### MT2101: Can't resolve the reference '\*', referenced from the method '\*' in '*'. +### MT2090: Inliner failed processing `...`. -An invalid assembly reference was encountered when processing the method mentioned in the error message. - -The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](https://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). +Something unexpected occured when trying to inline code from the application. The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -### MT2102: Error processing the method '\*' in the assembly '\*': * + -Something unexpected occured when trying to mark the method mentioned in the error message. + -The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](https://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). + +### MT2100: Smart Enum Conversion Preserver failed processing `...`. -### MT2103: Error processing assembly '\*': * +Something unexpected occured when trying to mark the conversion methods for smart enums from the application. The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -An unexpected error occured when processing an assembly. + -The assembly causing the issue is named in the error message. In order to fix this issue the assembly will need to be provided in a [bug report](https://bugzilla.xamarin.com) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). +### MT2101: Can't resolve the reference '\*', referenced from the method '\*' in '*'. -### MT2104: Unable to link assembly '{0}' as it is mixed-mode. +An invalid assembly reference was encountered when processing the method mentioned in the error message. -Mixed-mode assemblies can not be processed by the linker. +The assembly causing the issue is named in the error message. To fix this issue the assembly will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -See https://msdn.microsoft.com/en-us/library/x0w2664k.aspx for more information on mixed-mode assemblies. + -### MT2105: The [BindingImpl] attribute on the member * is invalid: * +### MT2102: Error processing the method '\*' in the assembly '\*': * -The `[BindingImpl]` attribute on the mentioned member is invalid. The expected format is `[BindingImpl (BindingImplOptions.ValueA | BindingImplOptions.ValueB)]`. +Something unexpected occured when trying to mark the method mentioned in the error message. -### MT2106: Could not optimize the call to BlockLiteral.SetupBlock[Unsafe] in * at offset * because *. +The assembly causing the issue is named in the error message. To fix this issue the assembly will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -The linker reports this warning when it can't optimize a call to BlockLiteral.SetupBlock or Block.SetupBlockUnsafe. + -The message will point to the method that calls BlockLiteral.SetupBlock[Unsafe], and -it may also give clues as to why the call couldn't be optimized. +### MT2103: Error processing assembly '\*': * -Please file an [issue](https://github.com/xamarin/xamarin-macios/issues/new) -along with a complete build log so that we can investigate what went wrong and -possibly enable more scenarios in the future. +An unexpected error occured when processing an assembly. -### MT2107: It's not safe to remove the dynamic registrar because {reasons} +The assembly causing the issue is named in the error message. To fix this issue the assembly will need to be provided in a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) along with a complete build log with verbosity enabled (i.e. `-v -v -v -v` in the **Additional mtouch arguments**). -The linker reports this warning when the developer requests removal of the -dynamic registrar (by passing `--optimize:remove-dynamic-registrar` to -mtouch), but the linker determines that it's not safe to do so. + -To remove the warning either remove the optimization argument to mtouch, or pass -`--nowarn:2107` to ignore it. +### MM2104: Unable to link assembly '{0}' as it is mixed-mode. -By default this option will be automatically enabled whenever it's possible -and safe to do so. +Mixed-mode assemblies can not be processed by the linker. - +See https://msdn.microsoft.com/en-us/library/x0w2664k.aspx for more information on mixed-mode assemblies. -# MT3xxx: AOT error messages +## MT3xxx: AOT error messages -### MT3001 Could not AOT the assembly '*' + -This generally indicates a bug in the AOT compiler. Please file a bug [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS) with a project that can be used to reproduce the error. +### MT3001: Could not AOT the assembly '*' + +This generally indicates a bug in the AOT compiler. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a project that can be used to reproduce the error. Sometimes it's possible to work around this by disabling incremental builds in the project's iOS Build option (but it's still a bug, so please report it anyways). -### MT3002 AOT restriction: Method '*' must be static since it is decorated with [MonoPInvokeCallback]. See [https://developer.xamarin.com/guides/ios/advanced_topics/limitations/#Reverse_Callbacks](https://developer.xamarin.com/guides/ios/advanced_topics/limitations/#Reverse_Callbacks) + -This error message comes from the AOT compiler. +### MT3002: AOT restriction: Method '*' must be static since it is decorated with [MonoPInvokeCallback]. See [https://developer.xamarin.com/guides/ios/advanced_topics/limitations/#Reverse_Callbacks](https://developer.xamarin.com/guides/ios/advanced_topics/limitations/#Reverse_Callbacks) +This error message comes from the AOT compiler. + -### MT3003 Conflicting --debug and --llvm options. Soft-debugging is disabled. +### MT3003: Conflicting --debug and --llvm options. Soft-debugging is disabled. Debugging is not supported when LLVM is enabled. If you need to debug the app, disable LLVM first. -### MT3004 Could not AOT the assembly '*' because it doesn't exist. + +### MT3004: Could not AOT the assembly '*' because it doesn't exist. + -### MT3005 The dependency '\*' of the assembly '\*' was not found. Please review the project's references. +### MT3005: The dependency '\*' of the assembly '\*' was not found. Please review the project's references. This typically occurs when an assembly references another version of a platform assembly (usually the .NET 4 version of mscorlib.dll). This is not supported, and may not build or execute properly (the assembly may use API from the .NET 4 version of mscorlib.dll that the Xamarin.iOS version does not have). -### MT3006 Could not compute a complete dependency map for the project. This will result in slower build times because Xamarin.iOS can't properly detect what needs to be rebuilt (and what does not need to be rebuilt). Please review previous warnings for more details. + + +### MT3006: Could not compute a complete dependency map for the project. This will result in slower build times because Xamarin.iOS can't properly detect what needs to be rebuilt (and what does not need to be rebuilt). Please review previous warnings for more details. build or execute properly (the assembly may use API from the .NET 4 version of mscorlib.dll that the Xamarin.iOS version does not have). -### MT3007: Debug info files (*.mdb) will not be loaded when llvm is enabled. + + +### MT3007: Debug info files (*.mdb) will not be loaded when llvm is enabled. -### MT3008: Bitcode support requires the use of the LLVM AOT backend (--llvm) + + +### MT3008: Bitcode support requires the use of the LLVM AOT backend (--llvm) Bitcode support requires the use of the LLVM AOT backend (--llvm). @@ -1416,7 +1824,7 @@ Either disable Bitcode support or enable LLVM. -# MT4xxx: Code generation error messages +## MT4xxx: Code generation error messages ### MT40xx: Main @@ -1425,13 +1833,17 @@ Either disable Bitcode support or enable LLVM. MT40xx main.m --> -### MT4001 The main template could not be expanded to `*`. + + +### MT4001: The main template could not be expanded to `*`. -An error occurred when generating main.m. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +An error occurred when generating `main.m`. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT4002 Failed to compile the generated code for P/Invoke methods. Please file a bug report at http://bugzilla.xamarin.com + -Failed to compile the generated code for P/Invoke methods. Please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT4002: Failed to compile the generated code for P/Invoke methods. Please file a bug report at http://bugzilla.xamarin.com + +Failed to compile the generated code for P/Invoke methods. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). ### MT41xx: Registrar @@ -1439,153 +1851,201 @@ Failed to compile the generated code for P/Invoke methods. Please file a bug rep MT41xx registrar.m --> -### MT4101 The registrar cannot build a signature for type `*`. + + +### MT4101: The registrar cannot build a signature for type `*`. A type was found in exported API that the runtime doesn't know how to marshal to/from Objective-C. -If you believe Xamarin.iOS should support the type in question, please file an enhancement request at [http://bugzilla.xamarin.com](http://bugzilla.xamarin.com). +If you believe Xamarin.iOS should support the type in question, please file an enhancement request on [github](https://github.com/xamarin/xamarin-macios/issues/new). + + -### MT4102 The registrar found an invalid type `*` in signature for method `*`. Use `*` instead. +### MT4102: The registrar found an invalid type `*` in signature for method `*`. Use `*` instead. This currently only happens with one type: System.DateTime. Use the Objective-C equivalent (NSDate) instead. -### MT4103 The registrar found an invalid type `*` in signature for method `*`: The type implements INativeObject, but does not have a constructor that takes two (IntPtr, bool) arguments + + +### MT4103: The registrar found an invalid type `*` in signature for method `*`: The type implements INativeObject, but does not have a constructor that takes two (IntPtr, bool) arguments This occurs when the registrar encounter a type in a signature with the mentioned characteristics. The registrar might need to create new instances of the type, and in this case it requires a constructor with the (IntPtr, bool) signature - the first argument (IntPtr) specifies the managed handle, while the second if the caller hands over ownership of the native handle (if this value is false 'retain' will be called on the object). -### MT4104 The registrar cannot marshal the return value for type `*` in signature for method `*`. + + +### MT4104: The registrar cannot marshal the return value for type `*` in signature for method `*`. A type was found in exported API that the runtime doesn't know how to marshal to/from Objective-C. -If you believe Xamarin.iOS should support the type in question, please file an enhancement request at [http://bugzilla.xamarin.com](http://bugzilla.xamarin.com). +If you believe Xamarin.iOS should support the type in question, please file an enhancement request on [github](https://github.com/xamarin/xamarin-macios/issues/new). + + + +### MT4105: The registrar cannot marshal the parameter of type `*` in signature for method `*`. -### MT4105 The registrar cannot marshal the parameter of type `*` in signature for method `*`. +If you believe Xamarin.iOS should support the type in question, please file an enhancement request on [github](https://github.com/xamarin/xamarin-macios/issues/new). -If you believe Xamarin.iOS should support the type in question, please file an enhancement request at [http://bugzilla.xamarin.com](http://bugzilla.xamarin.com). + -### MT4106 The registrar cannot marshal the return value for structure `*` in signature for method `*`. +### MT4106: The registrar cannot marshal the return value for structure `*` in signature for method `*`. A type was found in exported API that the runtime doesn't know how to marshal to/from Objective-C. -If you believe Xamarin.iOS should support the type in question, please file an enhancement request at [http://bugzilla.xamarin.com](http://bugzilla.xamarin.com). +If you believe Xamarin.iOS should support the type in question, please file an enhancement request on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT4107 The registrar cannot marshal the parameter of type `*` in signature for method `+`. + + +### MT4107: The registrar cannot marshal the parameter of type `*` in signature for method `+`. A type was found in exported API that the runtime doesn't know how to marshal to/from Objective-C. -If you believe Xamarin.iOS should support the type in question, please file an enhancement request at [http://bugzilla.xamarin.com](http://bugzilla.xamarin.com). +If you believe Xamarin.iOS should support the type in question, please file an enhancement request on [github](https://github.com/xamarin/xamarin-macios/issues/new). + + -### MT4108 The registrar cannot get the ObjectiveC type for managed type `*`. +### MT4108: The registrar cannot get the ObjectiveC type for managed type `*`. A type was found in exported API that the runtime doesn't know how to marshal to/from Objective-C. -If you believe Xamarin.iOS should support the type in question, please file an enhancement request at [http://bugzilla.xamarin.com](http://bugzilla.xamarin.com). +If you believe Xamarin.iOS should support the type in question, please file an enhancement request on [github](https://github.com/xamarin/xamarin-macios/issues/new). + + -### MT4109 Failed to compile the generated registrar code. Please file a bug report at http://bugzilla.xamarin.com +### MT4109: Failed to compile the generated registrar code. Please file a bug report at http://bugzilla.xamarin.com Failed to compile the generated code for the registrar. The build log will contain the output from the native compiler, explaining why the code isn't compiling. -This is always a bug in Xamarin.iOS; please file a bug report at [http://bugzilla.xamarin.com](http://bugzilla.xamarin.com) with your project or a test case. +This is always a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new) with your project or a test case. -### MT4110 The registrar cannot marshal the out parameter of type `*` in signature for method `*`. + +### MT4110: The registrar cannot marshal the out parameter of type `*` in signature for method `*`. + -### MT4111 The registrar cannot build a signature for type `*` in method `*`. +### MT4111: The registrar cannot build a signature for type `*` in method `*`. + +### MT4112: The registrar found an invalid type `*`. Registering generic types with Objective-C is not supported, and may lead to random behavior and/or crashes (for backwards compatibility with older versions of Xamarin.iOS it is possible to ignore this error by passing `--unsupported--enable-generics-in-registrar` as an additional mtouch argument in the project's iOS Build options page. See [developer.xamarin.com/guides/ios/advanced_topics/registrar](https://developer.xamarin.com/guides/ios/advanced_topics/registrar) for more information). -### MT4112 The registrar found an invalid type `*`. Registering generic types with Objective-C is not supported, and may lead to random behavior and/or crashes (for backwards compatibility with older versions of Xamarin.iOS it is possible to ignore this error by passing `--unsupported--enable-generics-in-registrar` as an additional mtouch argument in the project's iOS Build options page. See [developer.xamarin.com/guides/ios/advanced_topics/registrar](https://developer.xamarin.com/guides/ios/advanced_topics/registrar) for more information). + +### MT4113: The registrar found a generic method: '\*.\*'. Exporting generic methods is not supported, and will lead to random behavior and/or crashes. + -### MT4113 The registrar found a generic method: '\*.\*'. Exporting generic methods is not supported, and will lead to random behavior and/or crashes. +### MT4114: Unexpected error in the registrar for the method '\*.\*' - Please file a bug report at http://bugzilla.xamarin.com + +### MT4116: Could not register the assembly '*': * -### MT4114 Unexpected error in the registrar for the method '\*.\*' - Please file a bug report at http://bugzilla.xamarin.com + +### MT4117: The registrar found a signature mismatch in the method '*.*' - the selector indicates the method takes * parameters, while the managed method has * parameters. + -### MT4116 Could not register the assembly '*': * +### MT4118: Cannot register two managed types ('\*' and '\*') with the same native name ('*'). + +### MT4119: Could not register the selector '\*' of the member '\*.*' because the selector is already registered on a different member. -### MT4117 The registrar found a signature mismatch in the method '*.*' - the selector indicates the method takes * parameters, while the managed method has * parameters. + +### MT4120: The registrar found an unknown field type '\*' in field '\*.*'. Please file a bug report at http://bugzilla.xamarin.com +This error indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT4118 Cannot register two managed types ('\*' and '\*') with the same native name ('*'). + +### MT4121: Cannot use GCC/G++ to compile the generated code from the static registrar when using the Accounts framework (the header files provided by Apple used during the compilation require Clang). Either use Clang (--compiler:clang) or the dynamic registrar (--registrar:dynamic). + -### MT4119 Could not register the selector '\*' of the member '\*.*' because the selector is already registered on a different member. +### MT4122: Cannot use the Clang compiler provided in the *.* SDK to compile the generated code from the static registrar when non-ASCII type names ('*') are present in the application. Either use GCC/G++ (--compiler:gcc|g++), the dynamic registrar (--registrar:dynamic) or a newer SDK. + +### MT4123: The type of the variadic parameter in the variadic function '*' must be System.IntPtr. -### MT4120 The registrar found an unknown field type '\*' in field '\*.*'. Please file a bug report at http://bugzilla.xamarin.com + -This error indicates a bug in Xamarin.iOS. Please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT4124: Invalid * found on '*'. Please file a bug report at http://bugzilla.xamarin.com -### MT4121 Cannot use GCC/G++ to compile the generated code from the static registrar when using the Accounts framework (the header files provided by Apple used during the compilation require Clang). Either use Clang (--compiler:clang) or the dynamic registrar (--registrar:dynamic). +This error indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). + +### MT4125: The registrar found an invalid type '\*' in signature for method '\*': The interface must have a Protocol attribute specifying its wrapper type. -### MT4122 Cannot use the Clang compiler provided in the *.* SDK to compile the generated code from the static registrar when non-ASCII type names ('*') are present in the application. Either use GCC/G++ (--compiler:gcc|g++), the dynamic registrar (--registrar:dynamic) or a newer SDK. + +### MT4126: Cannot register two managed protocols ('\*' and '\*') with the same native name ('*'). + -### MT4123 The type of the variadic parameter in the variadic function '*' must be System.IntPtr. +### MT4127: Cannot register more than one interface method for the method '\*' (which is implementing '\*'). + +### MT4128: The registrar found an invalid generic parameter type '\*' in the method '\*'. The generic parameter must have an 'NSObject' constraint. -### MT4124 Invalid * found on '*'. Please file a bug report at http://bugzilla.xamarin.com + -This error indicates a bug in Xamarin.iOS. Please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT4129: The registrar found an invalid generic return type '\*' in the method '\*'. The generic return type must have an 'NSObject' constraint. -### MT4125 The registrar found an invalid type '\*' in signature for method '\*': The interface must have a Protocol attribute specifying its wrapper type. + +### MT4130: The registrar cannot export static methods in generic classes ('*'). + -### MT4126 Cannot register two managed protocols ('\*' and '\*') with the same native name ('*'). +### MT4131: The registrar cannot export static properties in generic classes ('\*.\*'). + +### MT4132: The registrar found an invalid generic return type '\*' in the property '\*'. The return type must have an 'NSObject' constraint. -### MT4127 Cannot register more than one interface method for the method '\*' (which is implementing '\*'). + +### MT4133: Cannot construct an instance of the type '*' from Objective-C because the type is generic. [Runtime exception] + -### MT4128 The registrar found an invalid generic parameter type '\*' in the method '\*'. The generic parameter must have an 'NSObject' constraint. +### MT4134: Your application is using the '*' framework, which isn't included in the iOS SDK you're using to build your app (this framework was introduced in iOS *, while you're building with the iOS * SDK.) Please select a newer SDK in your app's iOS Build options. -### MT4129 The registrar found an invalid generic return type '\*' in the method '\*'. The generic return type must have an 'NSObject' constraint. + -### MT4130 The registrar cannot export static methods in generic classes ('*'). +### MT4135: The member '\*.\*' has an Export attribute that doesn't specify a selector. A selector is required. -### MT4131 The registrar cannot export static properties in generic classes ('\*.\*'). + -### MT4132 The registrar found an invalid generic return type '\*' in the property '\*'. The return type must have an 'NSObject' constraint. +### MT4136: The registrar cannot marshal the parameter type '\*' of the parameter '\*' in the method '\*.*' -### MT4133 Cannot construct an instance of the type '*' from Objective-C because the type is generic. [Runtime exception] + -### MT4134 Your application is using the '*' framework, which isn't included in the iOS SDK you're using to build your app (this framework was introduced in iOS *, while you're building with the iOS * SDK.) Please select a newer SDK in your app's iOS Build options. + -### MT4135 The member '\*.\*' has an Export attribute that doesn't specify a selector. A selector is required. +### MT4138: The registrar cannot marshal the property type '\*' of the property '\*.*'. -### MT4136 The registrar cannot marshal the parameter type '\*' of the parameter '\*' in the method '\*.*' + - +### MT4139: The registrar cannot marshal the property type '\*' of the property '\*.*'. Properties with the [Connect] attribute must have a property type of NSObject (or a subclass of NSObject). -### MT4138 The registrar cannot marshal the property type '\*' of the property '\*.*'. + -### MT4139 The registrar cannot marshal the property type '\*' of the property '\*.*'. Properties with the [Connect] attribute must have a property type of NSObject (or a subclass of NSObject). +### MT4140: The registrar found a signature mismatch in the method '*.*' - the selector indicates the variadic method takes * parameters, while the managed method has * parameters. -### MT4140 The registrar found a signature mismatch in the method '*.*' - the selector indicates the variadic method takes * parameters, while the managed method has * parameters. + -### MT4141 Cannot register the selector '\*' on the member '\*' because Xamarin.iOS implicitly registers this selector. +### MT4141: Cannot register the selector '\*' on the member '\*' because Xamarin.iOS implicitly registers this selector. This occurs when subclassing a framework type, and trying to implement a 'retain', 'release' or 'dealloc' method: -``` +```csharp class MyNSObject : NSObject { [Export ("retain")] @@ -1601,7 +2061,7 @@ class MyNSObject : NSObject It is however possible to override these methods if the class isn't the first subclass of the framework type: -``` +```csharp class MyNSObject : NSObject { } @@ -1621,98 +2081,174 @@ class MyCustomNSObject : MyNSObject In this case Xamarin.iOS will override `retain`, `release` and `dealloc` on the `MyNSObject` class, and there is no conflict. -### MT4142: Failed to register the type '*'. -### MT4143: The ObjectiveC class '*' could not be registered, it does not seem to derive from any known ObjectiveC class (including NSObject). -### MT4144: Cannot register the method '*' since it does not have an associated trampoline. Please file a bug report at http://bugzilla.xamarin.com. + -This indicates a bug in Xamarin.iOS. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT4142: Failed to register the type '*'. -### MT4145: Invalid enum '*': enums with the [Native] attribute must have a underlying enum type of either 'long' or 'ulong'. -### MT4146: The Name parameter of the Registrar attribute on the class '\*' ('\*') contains an invalid character: '\*' (\*). + + +### MT4143: The ObjectiveC class '*' could not be registered, it does not seem to derive from any known ObjectiveC class (including NSObject). + + + +### MT4144: Cannot register the method '*' since it does not have an associated trampoline. Please file a bug report at http://bugzilla.xamarin.com. + +This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). + + + +### MT4145: Invalid enum '*': enums with the [Native] attribute must have a underlying enum type of either 'long' or 'ulong'. + + + +### MT4146: The Name parameter of the Registrar attribute on the class '\*' ('\*') contains an invalid character: '\*' (\*). The name of an Objectice-C class can't contain whitespace, which means that the `Register` attribute on the corresponding managed class can't have a `Name` parameter can't contain whitespace either. Please verify that the `Register` attribute on the managed class mentioned in the error message does not contain any whitespace. -### MT4147: Detected a protocol inheriting from the JSExport protocol while using the dynamic registrar. It is not possible to export protocols to JavaScriptCore dynamically; the static registrar must be used (add '--registrar:static to the additional mtouch arguments in the project's iOS Build options to select the static registrar). -### MT4148: The registrar found a generic protocol: '*'. Exporting generic protocols is not supported. -### MT4149: Cannot register the method '\*.\*' because the type of the first parameter ('\*') does not match the category type ('\*'). -### MT4150: Cannot register the type '\*' because the Type property ('\*') in its Category attribute does not inherit from NSObject. -### MT4151: Cannot register the type '*' because the Type property in its Category attribute isn't set. -### MT4152: Cannot register the type '*' as a category because it implements INativeObject or subclasses NSObject. -### MT4153: Cannot register the type '\*' as a category because it's generic. -### MT4154: Cannot register the method '\*' as a category method because it's generic. -### MT4155: Cannot register the method '\*' with the selector '\*' as a category method on '*' because the Objective-C already has an implementation for this selector. -### MT4156: Cannot register two categories ('\*' and '\*') with the same native name ('*'). -### MT4157: Cannot register the category method '\*' because at least one parameter is required (and its type must match the category type '\*') -### MT4158: Cannot register the constructor * in the category * because constructors in categories are not supported. -### MT4159: Cannot register the method '*' as a category method because category methods must be static. + + +### MT4147: Detected a protocol inheriting from the JSExport protocol while using the dynamic registrar. It is not possible to export protocols to JavaScriptCore dynamically; the static registrar must be used (add '--registrar:static to the additional mtouch arguments in the project's iOS Build options to select the static registrar). + + + +### MT4148: The registrar found a generic protocol: '*'. Exporting generic protocols is not supported. + + + +### MT4149: Cannot register the method '\*.\*' because the type of the first parameter ('\*') does not match the category type ('\*'). + + + +### MT4150: Cannot register the type '\*' because the Type property ('\*') in its Category attribute does not inherit from NSObject. + + + +### MT4151: Cannot register the type '*' because the Type property in its Category attribute isn't set. + + + +### MT4152: Cannot register the type '*' as a category because it implements INativeObject or subclasses NSObject. + + + +### MT4153: Cannot register the type '\*' as a category because it's generic. + + + +### MT4154: Cannot register the method '\*' as a category method because it's generic. + + + +### MT4155: Cannot register the method '\*' with the selector '\*' as a category method on '*' because the Objective-C already has an implementation for this selector. + + + +### MT4156: Cannot register two categories ('\*' and '\*') with the same native name ('*'). -### MT4160: Invalid character '\*' (\*) found in selector '\*' for '\*'. + -### MT4161: The registrar found an unsupported structure '\*': All fields in a structure must also be structures (field '\*' with type '{2}' is not a structure). +### MT4157: Cannot register the category method '\*' because at least one parameter is required (and its type must match the category type '\*') + + + +### MT4158: Cannot register the constructor * in the category * because constructors in categories are not supported. + + + +### MT4159: Cannot register the method '*' as a category method because category methods must be static. + + + +### MT4160: Invalid character '\*' (\*) found in selector '\*' for '\*'. + + + +### MT4161: The registrar found an unsupported structure '\*': All fields in a structure must also be structures (field '\*' with type '{2}' is not a structure). The registrar found a structure with unsupported fields. All fields in a structure that is exposed to Objective-C must also be structures (not classes). -### MT4162: The type '\*' (used as * {2}) is not available in * * (it was introduced in * *)\* Please build with a newer * SDK (usually done by using the most recent version of Xcode. + + +### MT4162: The type '\*' (used as * {2}) is not available in * * (it was introduced in * *)\* Please build with a newer * SDK (usually done by using the most recent version of Xcode. The registrar found a type which is not included in the current SDK. Please upgrade Xcode. -### MT4163: Internal error in the registrar (*). Please file a bug report at http://bugzilla.xamarin.com + + +### MT4163: Internal error in the registrar (*). Please file a bug report at http://bugzilla.xamarin.com -This error indicates a bug in Xamarin.iOS. Please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This error indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT4164: Cannot export the property '\*' because its selector '\*' is an Objective-C keyword. Please use a different name. + + +### MT4164: Cannot export the property '\*' because its selector '\*' is an Objective-C keyword. Please use a different name. The selector for the property in question is not a valid Objective-C identifer. Please use a valid Objective-C identifier as selectors. -### MT4165: The registrar couldn't find the type 'System.Void' in any of the referenced assemblies. + + +### MT4165: The registrar couldn't find the type 'System.Void' in any of the referenced assemblies. + +This error most likely indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -This error most likely indicates a bug in Xamarin.iOS. Please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). + -### MT4166: Cannot register the method '\*' because the signature contains a type (\*) that isn't a reference type. +### MT4166: Cannot register the method '\*' because the signature contains a type (\*) that isn't a reference type. -This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This usually indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT4167: Cannot register the method '\*' because the signature contains a generic type (\*) with a generic argument type that isn't an NSObject subclass (*). + -This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT4167: Cannot register the method '\*' because the signature contains a generic type (\*) with a generic argument type that isn't an NSObject subclass (*). -### MT4168: Cannot register the type '{managed\_name}' because its Objective-C name '{exported\_name}' is an Objective-C keyword. Please use a different name. +This usually indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). + + + +### MT4168: Cannot register the type '{managed\_name}' because its Objective-C name '{exported\_name}' is an Objective-C keyword. Please use a different name. The Objective-C name for the type in question is not a valid Objective-C identifier. Please use a valid Objective-C identifier. -### MT4169: Failed to generate a P/Invoke wrapper for {method}: {message} + + +### MT4169: Failed to generate a P/Invoke wrapper for {method}: {message} Xamarin.iOS failed to generate a P/Invoke wrapper function for the mentioned. Please check the reported error message for the underlying cause. -### MT4170: The registrar can't convert from '{managed type}' to '{native type}' for the return value in the method {method}. + + +### MT4170: The registrar can't convert from '{managed type}' to '{native type}' for the return value in the method {method}. See the description of error MT4172. -### MT4171: The BindAs attribute on the member {member} is invalid: the BindAs type {type} is different from the property type {type}. + + +### MT4171: The BindAs attribute on the member {member} is invalid: the BindAs type {type} is different from the property type {type}. Please make sure the type in the BindAs attribute matches the type of the member it's attached to. -### MT4172: The registrar can't convert from '{native type}' to '{managed type}' for the parameter '{parameter name}' in the method {method}. + + +### MT4172: The registrar can't convert from '{native type}' to '{managed type}' for the parameter '{parameter name}' in the method {method}. The registrar does not support converting between the mentioned types. -This is a bug in Xamarin.iOS if the API in question is provided by Xamarin.iOS; -please file a bug at [http://bugzilla.xamarin.com][1]. +This is a bug in Xamarin.iOS if the API in question is provided by Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). If you run into this while developing a binding project for a native library, we're open to adding support for new combinations of types. If this is the -case, please file an enhancement request ([http://bugzilla.xamarin.com][2]) +case, please file an enhancement request on [github](https://github.com/xamarin/xamarin-macios/issues/new) with a test case and we'll evaluate it. [1]: https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS @@ -1798,25 +2334,29 @@ Reference: https://github.com/xamarin/xamarin-macios/issues/4072 MT51xx compilation --> -### MT5101 Missing '*' compiler. Please install Xcode 'Command-Line Tools' component - + +### MT5101: Missing '*' compiler. Please install Xcode 'Command-Line Tools' component -### MT5102 Failed to assemble the file '*'. Please file a bug report at http://bugzilla.xamarin.com + +### MT5102: Failed to assemble the file '*'. Please file a bug report at http://bugzilla.xamarin.com + -### MT5103 Failed to compile the file '*'. Please file a bug report at http://bugzilla.xamarin.com +### MT5103: Failed to compile the file '*'. Please file a bug report at http://bugzilla.xamarin.com + - -### MT5104 Could not find neither the '\*' nor the '\*' compiler. Please install Xcode 'Command-Line Tools' component +### MT5104: Could not find neither the '\*' nor the '\*' compiler. Please install Xcode 'Command-Line Tools' component -### MT5106: Could not compile the file(s) '*'. Please file a bug report at http://bugzilla.xamarin.com + + +### MT5106: Could not compile the file(s) '*'. Please file a bug report at http://bugzilla.xamarin.com -This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This usually indicates a bug in Xamarin.iOS; please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). ### MT52xx: Linking @@ -1824,17 +2364,27 @@ This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzil MT52xx linking --> -### MT5201 Native linking failed. Please review the build log and the user flags provided to gcc: * + + +### MT5201: Native linking failed. Please review the build log and the user flags provided to gcc: * -### MT5202 Native linking failed. Please review the build log. + -### MT5203 Native linking warning: * +### MT5202: Native linking failed. Please review the build log. + + + +### MT5203: Native linking warning: * -### MT5209 Native linking error: * + + +### MT5209: Native linking error: * -### MT5210: Native linking failed, undefined symbol: *. Please verify that all the necessary frameworks have been referenced and native libraries are properly linked in. + + +### MT5210: Native linking failed, undefined symbol: *. Please verify that all the necessary frameworks have been referenced and native libraries are properly linked in. This happens when the native linker cannot find a symbol that is referenced somewhere. There are several reasons this may happen: @@ -1857,9 +2407,9 @@ This happens when the native linker cannot find a symbol that is referenced some - If you can't modify the third-party binding, or you're linking manually with a third-party library, you can set the equivalent flag by passing -cxx to mtouch (this is done by modifying the additional mtouch arguments in the project's iOS Build options page. Remember that this must be done for every project configuration). + - -### MT5211: Native linking failed, undefined Objective-C class: \*. The symbol '\*' could not be found in any of the libraries or frameworks linked with your application. +### MT5211: Native linking failed, undefined Objective-C class: \*. The symbol '\*' could not be found in any of the libraries or frameworks linked with your application. This happens when the native linker cannot find an Objective-C class that is referenced somewhere. There are several reasons this may happen: the same as for [MT5210](#MT5210) and in addition: @@ -1872,13 +2422,12 @@ This happens when the native linker cannot find an Objective-C class that is ref { } + - -### MT5212: Native linking failed, duplicate symbol: *. +### MT5212: Native linking failed, duplicate symbol: *. This happens when the native linker encounters duplicated symbols between all the native libraries. Following this error there may be one or more [MT5213](#MT5213) errors with the location for each occurrence of the symbol. Possible reasons for this error: - * The same native library is included twice. * Two distinct native libraries happen to define the same symbols. * A native library is not correctly built, and contains the same symbol more than once. @@ -1901,7 +2450,6 @@ This happens when the native linker encounters duplicated symbols between all th - Request that the provider of the native library fix it and provide the updated version. - Fix it yourself by removing the extra object files (this only works if the problem is in fact duplicated object files) - # Find out if the library is a fat library, and which # architectures it contains. lipo -info libNative.a @@ -1923,7 +2471,6 @@ This happens when the native linker encounters duplicated symbols between all th # Reassemble the fat library lipo *.a -create -output libNative.a - - Ask the linker to remove unused code. Xamarin.iOS will do this automatically if all of the following conditions are met: - All third-party bindings' `[LinkWith]` attributes have enabled SmartLink: @@ -1932,16 +2479,19 @@ This happens when the native linker encounters duplicated symbols between all th - No `-gcc_flags` is passed to mtouch (in the additional mtouch arguments field of the project's iOS Build options). - It's also possible to ask the linker directly to remove unused code by adding `-gcc_flags -dead_strip` to the additional mtouch arguments in the project's iOS Build options. + -### MT5213: Duplicate symbol in: * (Location related to previous error) +### MT5213: Duplicate symbol in: * (Location related to previous error) This error is reported only together with [MT5212](#MT5212). Please see [MT5212](#MT5212) for more information. -### MT5214 Native linking failed, undefined symbol: *. This symbol was referenced the managed member *. Please verify that all the necessary frameworks have been referenced and native libraries linked. + + +### MT5214: Native linking failed, undefined symbol: *. This symbol was referenced the managed member *. Please verify that all the necessary frameworks have been referenced and native libraries linked. This error is reported when the managed code contains a P/Invoke to a native method that does not exist. For example: -``` +```csharp using System.Runtime.InteropServices; class MyImports { [DllImport ("__Internal")] @@ -1952,20 +2502,26 @@ class MyImports { There are a few possible solutions: - Remove the P/Invokes in question from the source code. - - Enable the managed linker for all assemblies (this is done in the project's iOS Build options, by setting "Linker Behavior" to "All assemblies"). This will effectively remove all the P/Invokes you don't use from the app (automatically, instead of manually like the previous point). The downside is that this will make your simulator builds somewhat slower, and it may break your app if it's using reflection - more information about the linker can be found [here](/guides/ios/advanced_topics/linker/) ) + - Enable the managed linker for all assemblies (this is done in the project's iOS Build options, by setting "Linker Behavior" to "All assemblies"). This will effectively remove all the P/Invokes you don't use from the app (automatically, instead of manually like the previous point). The downside is that this will make your simulator builds somewhat slower, and it may break your app if it's using reflection - more information about the linker can be found [here](~/ios/deploy-test/linker.md) ) - Create a second native library which contains the missing native symbols. Note that this is merely a workaround (if you happen to try to call those functions, your app will crash). -### MT5215: References to '*' might require additional -framework=XXX or -lXXX instructions to the native linker + + +### MT5215: References to '*' might require additional -framework=XXX or -lXXX instructions to the native linker This is a warning, indicating that a P/Invoke was detected to reference the library in question, but the app is not linking with it. -### MT5216: Native linking failed for *. Please file a bug report at http://bugzilla.xamarin.com + + +### MT5216: Native linking failed for *. Please file a bug report at http://bugzilla.xamarin.com This error is reported when linking the output from the AOT compiler. -This error most likely indicates a bug in Xamarin.iOS. Please file a bug report at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This error most likely indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT5217: Native linking possibly failed because the linker command line was too long (* characters). + + +### MT5217: Native linking possibly failed because the linker command line was too long (* characters). Native linking failed, and it's possible this occured because the linker command was too long. @@ -2021,7 +2577,9 @@ Possible solutions: keep referenced Objective-C classes. Thus disabling incremental builds will prevent this need. -### MT5218: Can't ignore the dynamic symbol {symbol} (--ignore-dynamic-symbol={symbol}) because it was not detected as a dynamic symbol. + + +### MT5218: Can't ignore the dynamic symbol {symbol} (--ignore-dynamic-symbol={symbol}) because it was not detected as a dynamic symbol. The command-line argument `--ignore-dynamic-symbol=symbol` was passed, but this symbol is not a symbol that was recognized as a dynamic symbol that must @@ -2041,31 +2599,39 @@ There are two main reasons for this: MT53xx other tools --> -### MT5301: Missing 'strip' tool. Please install Xcode 'Command-Line Tools' component - + +### MT5301: Missing 'strip' tool. Please install Xcode 'Command-Line Tools' component -### MT5302: Missing 'dsymutil' tool. Please install Xcode 'Command-Line Tools' component + +### MT5302: Missing 'dsymutil' tool. Please install Xcode 'Command-Line Tools' component + -### MT5303: Failed to generate the debug symbols (dSYM directory). Please review the build log. +### MT5303: Failed to generate the debug symbols (dSYM directory). Please review the build log. An error occurred when running dsymutil on the final .app directory to create the debug symbols. Please review the build log to see dsymutil's output and see how it can be fixed. -### MT5304: Failed to strip the final binary. Please review the build log. + + +### MT5304: Failed to strip the final binary. Please review the build log. An error occurred when running the 'strip' tool to remove debugging information from the application. -### MT5305: Missing 'lipo' tool. Please install Xcode 'Command-Line Tools' component + +### MT5305: Missing 'lipo' tool. Please install Xcode 'Command-Line Tools' component + -### MT5306: Failed to create the a fat library. Please review the build log. +### MT5306: Failed to create the a fat library. Please review the build log. An error occurred when running the 'lipo' tool. Please review the build log to see the error reported by 'lipo'. -### MT5307: Failed to sign the executable. Please review the build log. + + +### MT5307: Failed to sign the executable. Please review the build log. An error occurred when signing the application. Please review the build log to see the error reported by 'codesign'. @@ -2074,7 +2640,7 @@ An error occurred when signing the application. Please review the build log to s -# MT6xxx: mtouch internal tools error messages +## MT6xxx: mtouch internal tools error messages ### MT600x: Stripper @@ -2083,23 +2649,31 @@ An error occurred when signing the application. Please review the build log to s MT600x Stripper --> -### MT6001: Running version of Cecil doesn't support assembly stripping + + +### MT6001: Running version of Cecil doesn't support assembly stripping + + -### MT6002: Could not strip assembly `*`. +### MT6002: Could not strip assembly `*`. An error occurred when stripping managed code(removing the IL code) from the assemblies in the application. -### MT6003: [UnauthorizedAccessException message] + + +### MT6003: [UnauthorizedAccessException message] A security error ocurred while stripping debugging symbols from the application. -# MT7xxx: MSBuild error messages +## MT7xxx: MSBuild error messages -### MT7001: Could not resolve host IPs for WiFi debugger settings. + + +### MT7001: Could not resolve host IPs for WiFi debugger settings. *MSBuild task: DetectDebugNetworkConfigurationTaskBase* @@ -2110,179 +2684,267 @@ Troubleshooting steps: In some cases, it's a "local network" issue and it can be addressed by adding the unknown host `127.0.0.1 MyHost.local` in `/etc/hosts`. -### MT7002: This machine does not have any network adapters. This is required when debugging or profiling on device over WiFi. + + +### MT7002: This machine does not have any network adapters. This is required when debugging or profiling on device over WiFi. *MSBuild task: DetectDebugNetworkConfigurationTaskBase* -### MT7003: The App Extension '*' does not contain an Info.plist. + + +### MT7003: The App Extension '*' does not contain an Info.plist. *MSBuild task: ValidateAppBundleTaskBase* -### MT7004: The App Extension '*' does not specify a CFBundleIdentifier. + + +### MT7004: The App Extension '*' does not specify a CFBundleIdentifier. *MSBuild task: ValidateAppBundleTaskBase* -### MT7005: The App Extension '*' does not specify a CFBundleExecutable. + + +### MT7005: The App Extension '*' does not specify a CFBundleExecutable. *MSBuild task: ValidateAppBundleTaskBase* -### MT7006: The App Extension '\*' has an invalid CFBundleIdentifier (\*), it does not begin with the main app bundle's CFBundleIdentifier (*). + + +### MT7006: The App Extension '\*' has an invalid CFBundleIdentifier (\*), it does not begin with the main app bundle's CFBundleIdentifier (*). *MSBuild task: ValidateAppBundleTaskBase* -### MT7007: The App Extension '\*' has a CFBundleIdentifier (\*) that ends with the illegal suffix ".key". + + +### MT7007: The App Extension '\*' has a CFBundleIdentifier (\*) that ends with the illegal suffix ".key". *MSBuild task: ValidateAppBundleTaskBase* -### MT7008: The App Extension '*' does not specify a CFBundleShortVersionString. + + +### MT7008: The App Extension '*' does not specify a CFBundleShortVersionString. *MSBuild task: ValidateAppBundleTaskBase* -### MT7009: The App Extension '*' has an invalid Info.plist: it does not contain an NSExtension dictionary. + + +### MT7009: The App Extension '*' has an invalid Info.plist: it does not contain an NSExtension dictionary. *MSBuild task: ValidateAppBundleTaskBase* -### MT7010: The App Extension '*' has an invalid Info.plist: the NSExtension dictionary does not contain an NSExtensionPointIdentifier value. + + +### MT7010: The App Extension '*' has an invalid Info.plist: the NSExtension dictionary does not contain an NSExtensionPointIdentifier value. *MSBuild task: ValidateAppBundleTaskBase* -### MT7011: The WatchKit Extension '*' has an invalid Info.plist: the NSExtension dictionary does not contain an NSExtensionAttributes dictionary. + + +### MT7011: The WatchKit Extension '*' has an invalid Info.plist: the NSExtension dictionary does not contain an NSExtensionAttributes dictionary. *MSBuild task: ValidateAppBundleTaskBase* -### MT7012: The WatchKit Extension '*' does not have exactly one watch app. + + +### MT7012: The WatchKit Extension '*' does not have exactly one watch app. *MSBuild task: ValidateAppBundleTaskBase* -### MT7013: The WatchKit Extension '*' has an invalid Info.plist: UIRequiredDeviceCapabilities must contain the 'watch-companion' capability. + + +### MT7013: The WatchKit Extension '*' has an invalid Info.plist: UIRequiredDeviceCapabilities must contain the 'watch-companion' capability. *MSBuild task: ValidateAppBundleTaskBase* -### MT7014: The Watch App '*' does not contain an Info.plist. + + +### MT7014: The Watch App '*' does not contain an Info.plist. *MSBuild task: ValidateAppBundleTaskBase* -### MT7015: The Watch App '*' does not specify a CFBundleIdentifier. + + +### MT7015: The Watch App '*' does not specify a CFBundleIdentifier. *MSBuild task: ValidateAppBundleTaskBase* -### MT7016: The Watch App '\*' has an invalid CFBundleIdentifier (\*), it does not begin with the main app bundle's CFBundleIdentifier (*). + + +### MT7016: The Watch App '\*' has an invalid CFBundleIdentifier (\*), it does not begin with the main app bundle's CFBundleIdentifier (*). *MSBuild task: ValidateAppBundleTaskBase* -### MT7017: The Watch App '\*' does not have a valid UIDeviceFamily value. Expected 'Watch (4)' but found '\* (*)'. + + +### MT7017: The Watch App '\*' does not have a valid UIDeviceFamily value. Expected 'Watch (4)' but found '\* (*)'. *MSBuild task: ValidateAppBundleTaskBase* -### MT7018: The Watch App '*' does not specify a CFBundleExecutable + + +### MT7018: The Watch App '*' does not specify a CFBundleExecutable *MSBuild task: ValidateAppBundleTaskBase* -### MT7019: The Watch App '\*' has an invalid WKCompanionAppBundleIdentifier value ('\*'), it does not match the main app bundle's CFBundleIdentifier ('*'). + + +### MT7019: The Watch App '\*' has an invalid WKCompanionAppBundleIdentifier value ('\*'), it does not match the main app bundle's CFBundleIdentifier ('*'). *MSBuild task: ValidateAppBundleTaskBase* -### MT7020: The Watch App '*' has an invalid Info.plist: the WKWatchKitApp key must be present and have a value of 'true'. + + +### MT7020: The Watch App '*' has an invalid Info.plist: the WKWatchKitApp key must be present and have a value of 'true'. *MSBuild task: ValidateAppBundleTaskBase* -### MT7021: The Watch App '*' has an invalid Info.plist: the LSRequiresIPhoneOS key must not be present. + + +### MT7021: The Watch App '*' has an invalid Info.plist: the LSRequiresIPhoneOS key must not be present. *MSBuild task: ValidateAppBundleTaskBase* -### MT7022: The Watch App '*' does not contain a Watch Extension. + + +### MT7022: The Watch App '*' does not contain a Watch Extension. *MSBuild task: ValidateAppBundleTaskBase* -### MT7023: The Watch Extension '*' does not contain an Info.plist. + + +### MT7023: The Watch Extension '*' does not contain an Info.plist. *MSBuild task: ValidateAppBundleTaskBase* -### MT7024: The Watch Extension '*' does not specify a CFBundleIdentifier. + + +### MT7024: The Watch Extension '*' does not specify a CFBundleIdentifier. *MSBuild task: ValidateAppBundleTaskBase* -### MT7025: The Watch Extension '*' does not specify a CFBundleExecutable. + + +### MT7025: The Watch Extension '*' does not specify a CFBundleExecutable. *MSBuild task: ValidateAppBundleTaskBase* -### MT7026: The Watch Extension '\*' has an invalid CFBundleIdentifier (\*), it does not begin with the main app bundle's CFBundleIdentifier (*). + + +### MT7026: The Watch Extension '\*' has an invalid CFBundleIdentifier (\*), it does not begin with the main app bundle's CFBundleIdentifier (*). *MSBuild task: ValidateAppBundleTaskBase* -### MT7027: The Watch Extension '\*' has a CFBundleIdentifier (\*) that ends with the illegal suffix ".key". + + +### MT7027: The Watch Extension '\*' has a CFBundleIdentifier (\*) that ends with the illegal suffix ".key". *MSBuild task: ValidateAppBundleTaskBase* -### MT7028: The Watch Extension '*' has an invalid Info.plist: it does not contain an NSExtension dictionary. + + +### MT7028: The Watch Extension '*' has an invalid Info.plist: it does not contain an NSExtension dictionary. *MSBuild task: ValidateAppBundleTaskBase* -### MT7029: The Watch Extension '*' has an invalid Info.plist: the NSExtensionPointIdentifier must be "com.apple.watchkit". + + +### MT7029: The Watch Extension '*' has an invalid Info.plist: the NSExtensionPointIdentifier must be "com.apple.watchkit". *MSBuild task: ValidateAppBundleTaskBase* -### MT7030: The Watch Extension '*' has an invalid Info.plist: the NSExtension dictionary must contain NSExtensionAttributes. + + +### MT7030: The Watch Extension '*' has an invalid Info.plist: the NSExtension dictionary must contain NSExtensionAttributes. *MSBuild task: ValidateAppBundleTaskBase* -### MT7031: The Watch Extension '*' has an invalid Info.plist: the NSExtensionAttributes dictionary must contain a WKAppBundleIdentifier. + + +### MT7031: The Watch Extension '*' has an invalid Info.plist: the NSExtensionAttributes dictionary must contain a WKAppBundleIdentifier. *MSBuild task: ValidateAppBundleTaskBase* -### MT7032: The WatchKit Extension '*' has an invalid Info.plist: UIRequiredDeviceCapabilities should not contain the 'watch-companion' capability. + + +### MT7032: The WatchKit Extension '*' has an invalid Info.plist: UIRequiredDeviceCapabilities should not contain the 'watch-companion' capability. *MSBuild task: ValidateAppBundleTaskBase* -### MT7033: The Watch App '*' does not contain an Info.plist. + + +### MT7033: The Watch App '*' does not contain an Info.plist. *MSBuild task: ValidateAppBundleTaskBase* -### MT7034: The Watch App '*' does not specify a CFBundleIdentifier. + + +### MT7034: The Watch App '*' does not specify a CFBundleIdentifier. *MSBuild task: ValidateAppBundleTaskBase* -### MT7035: The Watch App '\*' does not have a valid UIDeviceFamily value. Expected '\*' but found '\* (\*)'. + + +### MT7035: The Watch App '\*' does not have a valid UIDeviceFamily value. Expected '\*' but found '\* (\*)'. *MSBuild task: ValidateAppBundleTaskBase* -### MT7036: The Watch App '*' does not specify a CFBundleExecutable. + + +### MT7036: The Watch App '*' does not specify a CFBundleExecutable. *MSBuild task: ValidateAppBundleTaskBase* -### MT7037: The WatchKit Extension '{extensionName}' has an invalid WKAppBundleIdentifier value ('\*'), it does not match the Watch App's CFBundleIdentifier ('\*'). + + +### MT7037: The WatchKit Extension '{extensionName}' has an invalid WKAppBundleIdentifier value ('\*'), it does not match the Watch App's CFBundleIdentifier ('\*'). *MSBuild task: ValidateAppBundleTaskBase* -### MT7038: The Watch App '*' has an invalid Info.plist: the WKCompanionAppBundleIdentifier must exist and must match the main app bundle's CFBundleIdentifier. + + +### MT7038: The Watch App '*' has an invalid Info.plist: the WKCompanionAppBundleIdentifier must exist and must match the main app bundle's CFBundleIdentifier. *MSBuild task: ValidateAppBundleTaskBase* -### MT7039: The Watch App '*' has an invalid Info.plist: the LSRequiresIPhoneOS key must not be present. + + +### MT7039: The Watch App '*' has an invalid Info.plist: the LSRequiresIPhoneOS key must not be present. *MSBuild task: ValidateAppBundleTaskBase* -### MT7040: The app bundle {AppBundlePath} does not contain an Info.plist. + + +### MT7040: The app bundle {AppBundlePath} does not contain an Info.plist. *MSBuild task: ValidateAppBundleTaskBase* -### MT7041: Main Info.plist path does not specify a CFBundleIdentifier. + + +### MT7041: Main Info.plist path does not specify a CFBundleIdentifier. *MSBuild task: ValidateAppBundleTaskBase* -### MT7042: Main Info.plist path does not specify a CFBundleExecutable. + + +### MT7042: Main Info.plist path does not specify a CFBundleExecutable. *MSBuild task: ValidateAppBundleTaskBase* -### MT7043: Main Info.plist path does not specify a CFBundleSupportedPlatforms. + + +### MT7043: Main Info.plist path does not specify a CFBundleSupportedPlatforms. *MSBuild task: ValidateAppBundleTaskBase* -### MT7044: Main Info.plist path does not specify a UIDeviceFamily. + + +### MT7044: Main Info.plist path does not specify a UIDeviceFamily. *MSBuild task: ValidateAppBundleTaskBase* -### MT7045: Unrecognized Format: *. + + +### MT7045: Unrecognized Format: *. *MSBuild task: PropertyListEditorTaskBase* @@ -2297,205 +2959,280 @@ Where * can be: - date - data -### MT7046: Add: Entry, *, Incorrectly Specified. + + +### MT7046: Add: Entry, *, Incorrectly Specified. *MSBuild task: PropertyListEditorTaskBase* -### MT7047: Add: Entry, *, Contains Invalid Array Index. + + +### MT7047: Add: Entry, *, Contains Invalid Array Index. *MSBuild task: PropertyListEditorTaskBase* -### MT7048: Add: * Entry Already Exists. + + +### MT7048: Add: * Entry Already Exists. *MSBuild task: PropertyListEditorTaskBase* -### MT7049: Add: Can't Add Entry, *, to Parent. + + +### MT7049: Add: Can't Add Entry, *, to Parent. *MSBuild task: PropertyListEditorTaskBase* -### MT7050: Delete: Can't Delete Entry, *, from Parent. + + +### MT7050: Delete: Can't Delete Entry, *, from Parent. *MSBuild task: PropertyListEditorTaskBase* -### MT7051: Delete: Entry, *, Contains Invalid Array Index. + + +### MT7051: Delete: Entry, *, Contains Invalid Array Index. *MSBuild task: PropertyListEditorTaskBase* -### MT7052: Delete: Entry, *, Does Not Exist. + + +### MT7052: Delete: Entry, *, Does Not Exist. *MSBuild task: PropertyListEditorTaskBase* -### MT7053: Import: Entry, *, Incorrectly Specified. + + +### MT7053: Import: Entry, *, Incorrectly Specified. *MSBuild task: PropertyListEditorTaskBase* -### MT7054: Import: Entry, *, Contains Invalid Array Index. + + +### MT7054: Import: Entry, *, Contains Invalid Array Index. *MSBuild task: PropertyListEditorTaskBase* -### MT7055: Import: Error Reading File: *. + + +### MT7055: Import: Error Reading File: *. *MSBuild task: PropertyListEditorTaskBase* -### MT7056: Import: Can't Add Entry, *, to Parent. + + +### MT7056: Import: Can't Add Entry, *, to Parent. *MSBuild task: PropertyListEditorTaskBase* -### MT7057: Merge: Can't Add array Entries to dict. + + +### MT7057: Merge: Can't Add array Entries to dict. *MSBuild task: PropertyListEditorTaskBase* -### MT7058: Merge: Specified Entry Must Be a Container. + + +### MT7058: Merge: Specified Entry Must Be a Container. *MSBuild task: PropertyListEditorTaskBase* -### MT7059: Merge: Entry, *, Contains Invalid Array Index. + + +### MT7059: Merge: Entry, *, Contains Invalid Array Index. *MSBuild task: PropertyListEditorTaskBase* -### MT7060: Merge: Entry, *, Does Not Exist. + + +### MT7060: Merge: Entry, *, Does Not Exist. *MSBuild task: PropertyListEditorTaskBase* -### MT7061: Merge: Error Reading File: *. + + +### MT7061: Merge: Error Reading File: *. *MSBuild task: PropertyListEditorTaskBase* -### MT7062: Set: Entry, *, Incorrectly Specified. + + +### MT7062: Set: Entry, *, Incorrectly Specified. *MSBuild task: PropertyListEditorTaskBase* -### MT7063: Set: Entry, *, Contains Invalid Array Index. + + +### MT7063: Set: Entry, *, Contains Invalid Array Index. *MSBuild task: PropertyListEditorTaskBase* -### MT7064: Set: Entry, *, Does Not Exist. + + +### MT7064: Set: Entry, *, Does Not Exist. *MSBuild task: PropertyListEditorTaskBase* -### MT7065: Unknown PropertyList editor action: *. + + +### MT7065: Unknown PropertyList editor action: *. *MSBuild task: PropertyListEditorTaskBase* -### MT7066: Error loading '*': *. + + +### MT7066: Error loading '*': *. *MSBuild task: PropertyListEditorTaskBase* -### MT7067: Error saving '*': *. + -*MSBuild task: PropertyListEditorTaskBase* +### MT7067: Error saving '*': *. +*MSBuild task: PropertyListEditorTaskBase* -# MT8xxx: Runtime error messages +## MT8xxx: Runtime error messages -### MT8001 Version mismatch between the native Xamarin.iOS runtime and monotouch.dll. Please reinstall Xamarin.iOS. + + +### MT8001: Version mismatch between the native Xamarin.iOS runtime and monotouch.dll. Please reinstall Xamarin.iOS. + + + +### MT8002: Could not find the method '\*' in the type '\*'. + + + +### MT8003: Failed to find the closed generic method '\*' on the type '\*'. + + + +### MT8004: Cannot create an instance of * for the native object 0x* (of type '*'), because another instance already exists for this native object (of type *). -### MT8002 Could not find the method '\*' in the type '\*'. + -### MT8003 Failed to find the closed generic method '\*' on the type '\*'. +### MT8005: Wrapper type '\*' is missing its native ObjectiveC class '\*'. -### MT8004: Cannot create an instance of * for the native object 0x* (of type '*'), because another instance already exists for this native object (of type *). + -### MT8005: Wrapper type '\*' is missing its native ObjectiveC class '\*'. +### MT8006: Failed to find the selector '\*' on the type '\*' -### MT8006: Failed to find the selector '\*' on the type '\*' + -### MT8007: Cannot get the method descriptor for the selector '\*' on the type '\*', because the selector does not correspond to a method +### MT8007: Cannot get the method descriptor for the selector '\*' on the type '\*', because the selector does not correspond to a method -### MT8008: The loaded version of Xamarin.iOS.dll was compiled for * bits, while the process is * bits. Please file a bug at http://bugzilla.xamarin.com. + -This indicates something is wrong in the build process. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT8008: The loaded version of Xamarin.iOS.dll was compiled for * bits, while the process is * bits. Please file a bug at http://bugzilla.xamarin.com. -### MT8009: Unable to locate the block to delegate conversion method for the method *.*'s parameter #*. Please file a bug at http://bugzilla.xamarin.com. +This indicates something is wrong in the build process. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -This indicates an API wasn't bound correctly. If this is an API exposed by Xamarin, please file a bug in our bugzilla ([http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS)), if it's a third-party binding, please contact the vendor. + -### MT8010: Native type size mismatch between Xamarin.[iOS|Mac].dll and the executing architecture. Xamarin.[iOS|Mac].dll was built for *-bit, while the current process is *-bit. +### MT8009: Unable to locate the block to delegate conversion method for the method *.*'s parameter #*. Please file a bug at http://bugzilla.xamarin.com. -This indicates something is wrong in the build process. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This indicates an API wasn't bound correctly. If this is an API exposed by Xamarin, please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new)., if it's a third-party binding, please contact the vendor. -### MT8011: Unable to locate the delegate to block conversion attribute ([DelegateProxy]) for the return value for the method *.*. Please file a bug at http://bugzilla.xamarin.com. + + +### MT8010: Native type size mismatch between Xamarin.[iOS|Mac].dll and the executing architecture. Xamarin.[iOS|Mac].dll was built for *-bit, while the current process is *-bit. + +This indicates something is wrong in the build process. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). + + + +### MT8011: Unable to locate the delegate to block conversion attribute ([DelegateProxy]) for the return value for the method *.*. Please file a bug at http://bugzilla.xamarin.com. Xamarin.iOS was unable to locate a required method at runtime (to convert a delegate to a block). -This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This usually indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT8012: Invalid DelegateProxyAttribute for the return value for the method *.*: DelegateType is null. Please file a bug at http://bugzilla.xamarin.com. + + +### MT8012: Invalid DelegateProxyAttribute for the return value for the method *.*: DelegateType is null. Please file a bug at http://bugzilla.xamarin.com. The DelegateProxy attribute for the method in question is invalid. -This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This usually indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT8013: Invalid DelegateProxyAttribute for the return value for the method *.*: DelegateType ({2}) specifies a type without a 'Handler' field. Please file a bug at http://bugzilla.xamarin.com. + -The DelegateProxy attribute for the method in question is invalid. +### MT8013: Invalid DelegateProxyAttribute for the return value for the method *.*: DelegateType ({2}) specifies a type without a 'Handler' field. Please file a bug at http://bugzilla.xamarin.com. -This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +The `[DelegateProxy]` attribute for the method in question is invalid. -### MT8014: Invalid DelegateProxyAttribute for the return value for the method *.*: The DelegateType's ({2}) 'Handler' field is null. Please file a bug at http://bugzilla.xamarin.com. +This usually indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -The DelegateProxy attribute for the method in question is invalid. + -This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT8014: Invalid DelegateProxyAttribute for the return value for the method *.*: The DelegateType's ({2}) 'Handler' field is null. Please file a bug at http://bugzilla.xamarin.com. -### MT8015: Invalid DelegateProxyAttribute for the return value for the method *.*: The DelegateType's ({2}) 'Handler' field is not a delegate, it's a *. Please file a bug at http://bugzilla.xamarin.com. +The `[DelegateProxy]` attribute for the method in question is invalid. -The DelegateProxy attribute for the method in question is invalid. +This usually indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). + -### MT8016: Unable to convert delegate to block for the return value for the method *.*, because the input isn't a delegate, it's a *. Please file a bug at http://bugzilla.xamarin.com. +### MT8015: Invalid DelegateProxyAttribute for the return value for the method *.*: The DelegateType's ({2}) 'Handler' field is not a delegate, it's a *. Please file a bug at http://bugzilla.xamarin.com. The DelegateProxy attribute for the method in question is invalid. -This usually indicates a bug in Xamarin.iOS; please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This usually indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). + + + +### MT8016: Unable to convert delegate to block for the return value for the method *.*, because the input isn't a delegate, it's a *. Please file a bug at http://bugzilla.xamarin.com. + +The `[DelegateProxy]` attribute for the method in question is invalid. + +This usually indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT8018: Internal consistency error. Please file a bug report at http://bugzilla.xamarin.com. + + +### MT8018: Internal consistency error. Please file a bug report at http://bugzilla.xamarin.com. -This indicates a bug in Xamarin.iOS. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT8019: Could not find the assembly * in the loaded assemblies. + -This indicates a bug in Xamarin.iOS. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT8019: Could not find the assembly * in the loaded assemblies. -### MT8020: Could not find the module with MetadataToken * in the assembly *. +This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -This indicates a bug in Xamarin.iOS. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). + -### MT8021: Unknown implicit token type: *. +### MT8020: Could not find the module with MetadataToken * in the assembly *. -This indicates a bug in Xamarin.iOS. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT8022: Expected the token reference * to be a *, but it's a *. Please file a bug report at http://bugzilla.xamarin.com. + -This indicates a bug in Xamarin.iOS. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT8021: Unknown implicit token type: *. -### MT8023: An instance object is required to construct a closed generic method for the open generic method: * (token reference: *). Please file a bug report at http://bugzilla.xamarin.com. +This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -This indicates a bug in Xamarin.iOS. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). + -### MT8024: Could not find a valid extension type for the smart enum '{smart_type}'. Please file a bug at https://bugzilla.xamarin.com. +### MT8022: Expected the token reference * to be a *, but it's a *. Please file a bug report at http://bugzilla.xamarin.com. -This indicates a bug in Xamarin.iOS. Please file a bug at [http://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT8025: Failed to compute the token reference for the type '{type.AssemblyQualifiedName}' because {reasons} + -This indicates a bug in Xamarin.iOS. Please file a bug at [https://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT8023: An instance object is required to construct a closed generic method for the open generic method: * (token reference: *). Please file a bug report at http://bugzilla.xamarin.com. -A potential workaround would be to disable the `register-protocols` -optimization, by passing `--optimize:-register-protocols` as an additional -mtouch argument in the project's iOS Build options. +This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). -### MT8026: * is not supported when the dynamic registrar has been linked away. + -This usually indicates a bug in Xamarin.iOS, because the dynamic registrar should not be linked away if it's needed. Please file a bug at [https://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +### MT8024: Could not find a valid extension type for the smart enum '{smart_type}'. Please file a bug at https://bugzilla.xamarin.com. It's possible to force the linker to keep the dynamic registrar by adding `--optimize=-remove-dynamic-registrar` to the additional mtouch arguments in @@ -2527,5 +3264,4 @@ There are a few reasons this may happen: * Incorrect bindings for third-party libraries. * Reference-counting bugs in third-party libraries. -* It could be a bug in Xamarin.iOS. If this is the case, please file a bug at - [https://bugzilla.xamarin.com](https://bugzilla.xamarin.com/enter_bug.cgi?product=iOS). +* This indicates a bug in Xamarin.iOS. Please file a new issue on [github](https://github.com/xamarin/xamarin-macios/issues/new). diff --git a/docs/website/optimizations.md b/docs/website/optimizations.md index f0d14b6a1a88..8bf8ad948aa1 100644 --- a/docs/website/optimizations.md +++ b/docs/website/optimizations.md @@ -468,7 +468,6 @@ Given the following Objective-C code: -(void) classCallback: (void (^)())completionHandler; -(void) callClassCallback; @end - @implementation ObjCBlockTester -(void) classCallback: (void (^)())completionHandler { diff --git a/docs/website/xamarin-ios-analysis.md b/docs/website/xamarin-ios-analysis.md index 25d65acd1dc1..4bea98af9116 100644 --- a/docs/website/xamarin-ios-analysis.md +++ b/docs/website/xamarin-ios-analysis.md @@ -1,12 +1,15 @@ --- -id: c29b69f5-08e4-4dcc-831e-7fd692ab0886 -title: Xamarin.iOS Analysis Rules -dateupdated: 2018-02-15 +title: "Xamarin.iOS Analysis Rules" +ms.topic: troubleshooting +ms.prod: xamarin +ms.assetid: C29B69F5-08E4-4DCC-831E-7FD692AB0886 +ms.technology: xamarin-ios +author: bradumbaugh +ms.author: brumbaug +ms.date: 03/06/2018 --- -[//]: # (The original file resides under https://github.com/xamarin/xamarin-macios/tree/master/docs/website/) -[//]: # (This allows all contributors (including external) to submit, using a PR, updates to the documentation that match the tools changes) -[//]: # (Modifications outside of xamarin-macios/master will be lost on future updates) +# Xamarin.iOS analysis rules Xamarin.iOS analysis is a set of rules that check your project settings to help you determine if better/more optimized settings are available. @@ -14,41 +17,55 @@ Run the analysis rules as often as possible to find possible improvements early To run the rules, in Visual Studio for Mac's menu, select **Project > Run Code Analysis**. -> ⚠️ **NOTE:** Xamarin.iOS analysis only runs on your currently selected configuration. We highly recommend running the tool for debug **and** release configurations. +> [!NOTE] +> Xamarin.iOS analysis only runs on your currently selected configuration. We highly recommend running the tool for debug **and** release configurations. -### XIA0001: DisabledLinkerRule + + +## XIA0001: DisabledLinkerRule - **Problem:** The linker is disabled on device for the debug mode. - **Fix:** You should try to run your code with the linker to avoid any surprises. To set it up, go to Project > iOS Build > Linker Behavior. -### XIA0002: TestCloudAgentReleaseRule + + +## XIA0002: TestCloudAgentReleaseRule - **Problem:** App builds that initialize the Test Cloud agent will be rejected by Apple when submitted, as they use private API. - **Fix:** Add or fix the necessary #if and defines in code. -### XIA0003: IPADebugBuildsRule + + +## XIA0003: IPADebugBuildsRule - **Problem:** Debug configuration that uses developer signing keys should not generate an IPA as it is only needed for distribution, which now uses the Publishing Wizard. - **Fix:** Disable IPA build in Project Options for the Debug configuration. -### XIA0004: Missing64BitSupportRule + + +## XIA0004: Missing64BitSupportRule - **Problem:** The supported architecture for "release | device" isn't 64 bit compatible, missing ARM64. This is a problem as Apple does not accept 32 bits only iOS apps in the AppStore. - **Fix:** Double click on your iOS project, go to Build > iOS Build and change the supported architectures so it has ARM64. -### XIA0005: Float32Rule + + +## XIA0005: Float32Rule - **Problem:** Not using the float32 option (--aot-options=-O=float32) leads to hefty performance cost, especially on mobile, where double precision math is measurably slower. Note that .NET uses double precision internally, even for float, so enabling this option affects precision and, possibly, compatibility. - **Fix:** Double click on your iOS project, go to Build > iOS Build and uncheck the "Perform all 32-bit float operations as 64-bit float". -### XIA0006: HttpClientAvoidManaged + + +## XIA0006: HttpClientAvoidManaged - **Problem:** We recommend using the native HttpClient handler instead of the managed one for better performance, smaller executable size, and to easily support the newer standards. - **Fix:** Double click on your iOS project, go to Build > iOS Build and change the HttpClient implementation to either NSUrlSession (iOS 7+) or CFNetwork to support version preceding iOS 7. -### XIA0007: UseLLVMRule + -- **Problem:** For Release|iPhone configuration we recommend enabling the LLVM compiler which generates code that is faster to execute at the expense of build time. -- **Fix:** Double click on your iOS project, go to Build > iOS Build and for Release|iPhone, check the LLVM optimizing compiler option. +## XIA0007: UseLLVMRule +- **Problem:** For Release|iPhone configuration we recommend enabling the LLVM compiler which generates code that is faster to execute at the expense of build time. +- **Fix:** Double click on your iOS project, go to Build > iOS Build and for Release|iPhone, check the LLVM optimizing compiler option. \ No newline at end of file diff --git a/external/Xamarin.MacDev b/external/Xamarin.MacDev index 39ea45bad4eb..53959f4d3590 160000 --- a/external/Xamarin.MacDev +++ b/external/Xamarin.MacDev @@ -1 +1 @@ -Subproject commit 39ea45bad4eb85358467b9f316fa6b30aa223e9c +Subproject commit 53959f4d35903d4e26a006548213d3cd0e2a592c diff --git a/jenkins/Jenkinsfile b/jenkins/Jenkinsfile index f6332702da16..e4a77987e088 100644 --- a/jenkins/Jenkinsfile +++ b/jenkins/Jenkinsfile @@ -13,6 +13,7 @@ xmPackageUrl = null utils = null errorMessage = null currentStage = null +failedStages = [] xiPackageFilename = null xmPackageFilename = null @@ -106,28 +107,99 @@ def appendFileComment (comment) writeFile (file: commentFile, text: comment) } +def markdownToSlack (value) +{ + def tmpfile = "/tmp/slacker.md" + writeFile (file: tmpfile, text: value) + try { + // this monstruousity converts markdown's [text](url) to slack's + sh ("sed -i '' 's/[[]\\(.*\\)[]][\\(]\\(.*\\)[\\)]/<\\2|\\1>/' '${tmpfile}'") + value = readFile (tmpfile) + } finally { + sh ("rm -f '${tmpfile}'") + } + return value +} + +def reportFinalStatusToSlack (err, gitHash, currentStage, fileContents) +{ + def status = currentBuild.currentResult + if ("${status}" == "SUCCESS" && err == "") + return // not reporting success to slack + + def authorName = null + def authorEmail = null + if (isPr) { + authorName = env.CHANGE_AUTHOR_DISPLAY_NAME + authorEmail = env.CHANGE_AUTHOR_EMAIL + slackMessage = "Pull Request #<${env.CHANGE_URL}|${env.CHANGE_ID}> failed to build." + } else { + authorName = sh (script: "git log -1 --pretty=%an", returnStdout: true).trim () + authorEmail = sh (script: "git log -1 --pretty=%ae", returnStdout: true).trim () + slackMessage = "Commit failed to build." + } + + def title = null + if (err != null) { + title = "Internal jenkins failed in stage '${currentStage}': ${err}" + } else { + title = "Internal jenkins failed in stage '${currentStage}'" + } + def text = "" + if (fileContents != null) + text = "\"text\": ${groovy.json.JsonOutput.toJson (markdownToSlack (fileContents))}," + // The attachments string must not start with a newline, it will produce a very helpful 'Invalid JSON String' exception with no additional info. + def attachments = """[ + { + \"author_name\": \"${authorName} (${authorEmail})\", + \"title\": \"${title}\", + \"title_link\": \"${env.RUN_DISPLAY_URL}\", + \"color\": \"danger\", + ${text} + \"fallback\": \"Build failed\" + } + ] + """ + echo (attachments) + slackSend (botUser: true, channel: "#ios-notifications", color: "danger", message: slackMessage, attachments: attachments) +} + def reportFinalStatus (err, gitHash, currentStage) { if (!createFinalStatus) return - def comment = null + def comment = "" def status = currentBuild.currentResult - if ("${status}" == "SUCCESS" && err == "") { + if ("${status}" == "SUCCESS" && err == "" && failedStages.size () == 0) { comment = "✅ [Jenkins job](${env.RUN_DISPLAY_URL}) (on internal Jenkins) succeeded" } else { - comment = "🔥 [Jenkins job](${env.RUN_DISPLAY_URL}) (on internal Jenkins) failed in stage '${currentStage}' 🔥" + // Aborted builds throw either a FlowInterruptedException or an AbortException (depending on what's executing), + // so treat either as an abortion (both can be thrown in other circumstances as well, so it's just a best guess). + if (err.contains ("FlowInterruptedException") || err.contains ("AbortException")) + comment += "❌ [Build was (probably) aborted](${env.RUN_DISPLAY_URL})\n\n" + comment += "🔥 [Jenkins job](${env.RUN_DISPLAY_URL}) (on internal Jenkins) failed" + if (currentStage != "" && !failedStages.contains (currentStage)) + failedStages.add (currentStage) + if (failedStages.size () > 0) + comment += " in stage(s) '${failedStages.join (', ')}'" + comment += " 🔥" if (err != "") comment += " : ${err}" manager.addErrorBadge (comment) manager.buildFailure () } - if (fileExists (commentFile)) - comment += "\n\n" + readFile ("${commentFile}") + def fileContents = null + if (fileExists (commentFile)) { + fileContents = readFile ("${commentFile}") + comment += "\n\n" + fileContents + } addComment ("${comment}") + + reportFinalStatusToSlack (err, gitHash, currentStage, fileContents) } def processAtMonkeyWrench (outputFile) @@ -171,21 +243,106 @@ def uploadFiles (glob, virtualPath) ]) } -def runXamarinMacTests (url, macOS) +// There must be a better way than this hack to show a +// message in red in the Jenkins Blue Ocean UI... +def echoError (message) +{ + try { + error (message) + } catch (e) { + // Ignore + } +} + +def indexOfElement (list, element) { + for (def i = 0; i < list.size (); i++) { + if (list [i] == element) + return i + } + return -1 +} + +def runXamarinMacTests (url, macOS, maccore_hash, xamarin_macios_hash) +{ + def failed = false + def workspace = "${env.HOME}/jenkins/workspace/xamarin-macios" + def failedTests = [] try { echo ("Executing on ${env.NODE_NAME}") echo ("URL: ${url}") - sh ("env") - sh ("rm -f *.zip") - sh ("curl -L '${url}' --output mac-test-package.zip") - sh ("rm -rf mac-test-package") - sh ("unzip -o mac-test-package.zip") - sh ("cd mac-test-package && ./system-dependencies.sh --provision-mono --ignore-autotools --ignore-xamarin-studio --ignore-xcode --ignore-osx --ignore-cmake") - sh ("make -C mac-test-package/tests exec-mac-dontlink") - sh ("make -C mac-test-package/tests exec-mac-apitest") + sh ("mkdir -p '${workspace}'") + dir ("${workspace}") { + // Download the script we need, and then execute it, so that we + // don't clone all of xamarin-macios to get a single file. + // Due to how github has implemented pull requests, this works + // even for pull requests from forks, since each commit in the pull request + // is also available from the main repository. + sh (""" + curl -fLO https://raw.githubusercontent.com/xamarin/xamarin-macios/${xamarin_macios_hash}/jenkins/prepare-packaged-macos-tests.sh + chmod +x prepare-packaged-macos-tests.sh + ./prepare-packaged-macos-tests.sh '${url}' '${maccore_hash}' + """) + def tests = [ "dontlink", "apitest", "introspection", "linksdk", "linkall", "xammac_tests" ]; + tests.each { test -> + def t = "${test}" + try { + timeout (time: 10, unit: 'MINUTES') { + sh ("make -C mac-test-package/tests exec-mac-${t} MONO_DEBUG=no-gdb-backtrace") + echo ("${t} succeeded") + } + } catch (error) { + echoError ("${t} failed with error: ${error}") + failed = true + failedTests.add (t) + } + } + } } finally { - sh ("rm -rf mac-test-package *.zip") + sh ("rm -rf ${workspace}/mac-test-package ${workspace}/*.zip") + // Find and upload any crash reports + sh (script: """ + rm -Rf ${workspace}/crash-reports + mkdir ${workspace}/crash-reports + find ~/Library/Logs/DiagnosticReports/ -mtime -10m -exec cp {} ${workspace}/crash-reports \\; + ls -la ${workspace}/crash-reports + """, + returnStatus: true /* Don't fail if something goes wrong */) + try { + if (findFiles (glob: "crash-reports/*").length > 0) { + archiveArtifacts ("${workspace}/crash-reports/*") + } else { + echo ("No crash reports found") + } + } catch (e) { + // Ignore any archiving errors. + } + } + if (failed) { + def failureMessage = "Xamarin.Mac tests on ${macOS} failed (${failedTests.join (', ')})" + manager.addErrorBadge (failureMessage) + error (failureMessage) + } +} + +def abortExecutingBuilds () +{ + def job = Jenkins.instance.getItemByFullName (env.JOB_NAME) + for (build in job.builds) { + if (!build.isBuilding ()) + continue + echo ("Current build: ${currentBuild.number} Checking build: ${build.number}"); + if (build.number > currentBuild.number) { + error ("There is already a newer build in progress (#${build.number})") + } else if (build.number < currentBuild.number) { + def exec = build.getExecutor () + if (exec == null) { + echo ("No executor for build ${build.number}") + } else { + exec.interrupt (Result.ABORTED, new CauseOfInterruption.UserInterruption ("Aborted by build #${currentBuild.number}")) + echo ("Aborted previous build: #${build.number}") + } + } } } @@ -224,14 +381,22 @@ timestamps { } if (isPr) { - if (!githubGetPullRequestLabels ().contains ("build-package")) { + def hasBuildPackage = githubGetPullRequestLabels ().contains ("build-package") + def hasRunInternalTests = githubGetPullRequestLabels ().contains ("run-internal-tests") + + if (!hasBuildPackage && !hasRunInternalTests) { // don't add a comment to the pull request, since the public jenkins will also add comments, which ends up being too much. createFinalStatus = false - echo ("Build skipped because the pull request doesn't have the label 'build-package'.") + echo ("Build skipped because the pull request doesn't have either of the labels 'build-package' or 'run-internal-tests'.") return } - skipLocalTestRunReason = "Not running tests here because they're run on public Jenkins." + + if (!hasRunInternalTests) + skipLocalTestRunReason = "Not running tests here because they're run on public Jenkins." + + // only aborting PR builds, since for normal branches we want to build as much as possible by default. + abortExecutingBuilds () } dir ("${workspace}") { @@ -366,8 +531,12 @@ timestamps { } else { def outputFile = "${workspace}/xamarin-macios/wrench-launch-external.output.tmp" try { + // VSTS does not allow any branch name anymore, it has to be an existing branch. + // Since pull requests don't create branches in the xamarin org (that VSTS sees at least), + // I've created a 'pull-request' branch which we'll use for pull requests. + def vsts_branch = isPr ? "pull-request" : branchName; withCredentials ([string (credentialsId: 'macios_provisionator_pat', variable: 'PROVISIONATOR_VSTS_PAT')]) { - sh ("make -C ${workspace}/xamarin-macios/tests wrench-launch-external MAC_PACKAGE_URL=${xmPackageUrl} IOS_PACKAGE_URL=${xiPackageUrl} WRENCH_URL=${env.RUN_DISPLAY_URL} BUILD_REVISION=${gitHash} BUILD_LANE=jenkins/${branchName} BUILD_WORK_HOST=${env.NODE_NAME} 2>&1 | tee ${outputFile}") + sh ("make -C ${workspace}/xamarin-macios/tests wrench-launch-external MAC_PACKAGE_URL=${xmPackageUrl} IOS_PACKAGE_URL=${xiPackageUrl} WRENCH_URL=${env.RUN_DISPLAY_URL} BUILD_REVISION=${gitHash} BUILD_LANE=${vsts_branch} BUILD_WORK_HOST=${env.NODE_NAME} 2>&1 | tee ${outputFile}") } processAtMonkeyWrench (outputFile) } catch (error) { @@ -414,9 +583,15 @@ timestamps { echo ("Generator diff: ${reportPrefix}/generator-diff/index.html") } + def hasXamarinMacTests = true stage ("Package XM tests") { currentStage = "${STAGE_NAME}" - sh ("make -C ${workspace}/xamarin-macios/tests package-tests") + def exitCode = sh (script: "make -C ${workspace}/xamarin-macios/tests package-tests", returnStatus: true) + if (exitCode != 0) { + hasXamarinMacTests = false + echoError ("Failed to package Xamarin.Mac tests (exit code: ${exitCode}") + failedStages.add (currentStage) + } uploadFiles ("tests/*.zip", virtualPath) } @@ -432,22 +607,47 @@ timestamps { def builders = [:] // Add test runs on older macOS versions - def url = "https://bosstoragemirror.blob.core.windows.net/wrench/${virtualPath}/tests/mac-test-package.zip" - def firstOS = sh (returnStdout: true, script: "grep ^MIN_OSX_SDK_VERSION= '${workspace}/xamarin-macios/Make.config' | sed 's/.*=//'").trim ().split ("\\.")[1].toInteger () - def lastOS = sh (returnStdout: true, script: "grep ^OSX_SDK_VERSION= '${workspace}/xamarin-macios/Make.config' | sed 's/.*=//'").trim ().split ("\\.")[1].toInteger () - for (os = firstOS; os < lastOS; os++) { - def macOS = "${os}" // Need to bind the label variable before the closure - builders ["XM tests on 10.${macOS}"] = { - try { - node ("xamarin-macios && macos-10.${macOS}") { - stage ("Running XM tests on '10.${macOS}'") { - runXamarinMacTests (url, "macOS 10.${macOS}") + if (hasXamarinMacTests) { + def url = "https://bosstoragemirror.blob.core.windows.net/wrench/${virtualPath}/tests/mac-test-package.zip" + def maccore_hash = sh (script: "grep NEEDED_MACCORE_VERSION ${workspace}/xamarin-macios/mk/xamarin.mk | sed 's/NEEDED_MACCORE_VERSION := //'", returnStdout: true).trim () + // Get the min and current macOS version from Make.config, + // and calculate all the macOS versions in between (including both end points). + // The trims/splits/toIntegers at the end are to select the minor part of the macOS version number, + // then we just loop from the minor part of the min version to the minor part of the current version. + def firstOS = sh (returnStdout: true, script: "grep ^MIN_OSX_SDK_VERSION= '${workspace}/xamarin-macios/Make.config' | sed 's/.*=//'").trim ().split ("\\.")[1].toInteger () + def lastOS = sh (returnStdout: true, script: "grep ^OSX_SDK_VERSION= '${workspace}/xamarin-macios/Make.config' | sed 's/.*=//'").trim ().split ("\\.")[1].toInteger () + def macOSes = [] + def excludedOSes = [] + for (os = firstOS; os <= lastOS; os++) + macOSes.add (os) + // If any macOS version needs to be excluded manually, it can be done like this (in this case to remove macOS 10.14): + // excludedOSes.add (14) + // Have in mind that the value in the list is only the minor part of the macOS version number. + for (i = 0; i < macOSes.size (); i++) { + def os = macOSes [i]; + def macOS = "${os}" // Need to bind the label variable before the closure + def excluded = indexOfElement (excludedOSes, os) >= 0 + def nodeText = excluded ? "ℹ️ XM tests not executed on 10.${macOS} ℹ️" : "XM tests on 10.${macOS}" + builders [nodeText] = { + try { + if (excluded) { + echo (nodeText) + } else { + node ("xamarin-macios && macos-10.${macOS}") { + stage ("Running XM tests on '10.${macOS}'") { + runXamarinMacTests (url, "macOS 10.${macOS}", maccore_hash, gitHash) + } + } } + } catch (err) { + currentStage = "Running XM tests on '10.${macOS}'" + def msg = err.getMessage (); + if (msg == "") + msg = "Xamarin.Mac tests on 10.${macOS} failed" + appendFileComment ("🔥 [${msg}](${env.RUN_DISPLAY_URL}) 🔥\n") + failedStages.add (currentStage) + throw err } - } catch (err) { - currentStage = "Running XM tests on '10.${macOS}'" - appendFileComment ("🔥 [Xamarin.Mac tests on 10.${macOS} failed](${env.RUN_DISPLAY_URL}) 🔥\n") - throw err } } } @@ -468,7 +668,13 @@ timestamps { stage ('Test docs') { currentStage = "${STAGE_NAME}" echo ("Building on ${env.NODE_NAME}") - sh ("make -C ${workspace}/xamarin-macios/tests wrench-docs") + def targetBranch = isPr ? githubGetPullRequestInfo () ["base"] ["ref"] : "${BRANCH_NAME}" + def testDocs = targetBranch == "master" + if (!testDocs) { + echo ("Skipping docs testing, it's only done on master (current (target) branch is ${targetBranch})") + } else { + sh ("make -C ${workspace}/xamarin-macios/tests wrench-docs") + } } } @@ -476,6 +682,8 @@ timestamps { parallel builders } } + + currentStage = "" } // dir ("xamarin-macios") } // dir ("${workspace}") } diff --git a/jenkins/README.md b/jenkins/README.md index 25b2c7f36032..8eb5792600e4 100644 --- a/jenkins/README.md +++ b/jenkins/README.md @@ -7,3 +7,29 @@ be executed is as follows: * build.sh : Builds the project. * run-tests.sh : Runs the tests. * build-api-diff.sh : Builds the API diff. + +# Jenkinsfile + +This file contains the logic to run on our internal Jenkins, available here: http://xamarin-jenkins/blue/organizations/jenkins/macios/activity + +The Jenkins job is a multi-branch pipeline job, it will execute in the +following conditions: + +* For all branches in the xamarin org (not forks) that has a + jenkins/Jenkinsfile file. +* For all pull requests from people with write access (also conditional on + having a jenkins/Jenkinsfile file). + +In very broad strokes, the Jenkins job will: + +* Checkout xamarin-macios +* Build +* Create packages, upload them to Azure and publish the links to the packages + as GitHub statuses. +* Run our test suite. +* Run selected Xamarin.Mac tests on all macOS versions we support. This is + done in parallel with the normal test run. + + If a particular macOS version must be excluded temporarily from testing, + search Jenkinsfile for `excludedOSes` and follow the instructions you'll + find. diff --git a/jenkins/build-api-diff.sh b/jenkins/build-api-diff.sh index cfdbabb53f14..f3b83f854c5e 100755 --- a/jenkins/build-api-diff.sh +++ b/jenkins/build-api-diff.sh @@ -9,6 +9,13 @@ report_error () } trap report_error ERR +# SC2154: ghprbPullId is referenced but not assigned. +# shellcheck disable=SC2154 +if test -n "$ghprbPullId" && ./jenkins/fetch-pr-labels.sh --check=skip-public-jenkins; then + echo "Skipping API diff because the label 'skip-public-jenkins' was found." + exit 0 +fi + export BUILD_REVISION=jenkins make -j8 -C tools/apidiff jenkins-api-diff diff --git a/jenkins/build.sh b/jenkins/build.sh index 2b0bd607cbea..aabbaf87e23b 100755 --- a/jenkins/build.sh +++ b/jenkins/build.sh @@ -15,7 +15,7 @@ fi ls -la "$WORKSPACE/jenkins" echo "$WORKSPACE/jenkins/pr-comments.md:" -cat "$WORKSPACE/jenkins/pr-comments.md" +cat "$WORKSPACE/jenkins/pr-comments.md" || true export BUILD_REVISION=jenkins @@ -27,6 +27,11 @@ if test -z "$ghprbPullId"; then echo "Could not find the environment variable ghprbPullId, so forcing a device build." ENABLE_DEVICE_BUILD=1 else + if ./jenkins/fetch-pr-labels.sh --check=skip-public-jenkins; then + echo "Skipping execution because the label 'skip-public-jenkins' was found." + printf "ℹ️ [Skipped execution](%s/console)\\n" "$BUILD_URL" >> "$WORKSPACE/jenkins/pr-comments.md" + exit 0 + fi echo "Listing modified files for pull request #$ghprbPullId..." if git diff-tree --no-commit-id --name-only -r "origin/pr/$ghprbPullId/merge^..origin/pr/$ghprbPullId/merge" > .tmp-files; then echo "Modified files found": diff --git a/jenkins/compare.sh b/jenkins/compare.sh index dddea51943e8..888f334edeb7 100755 --- a/jenkins/compare.sh +++ b/jenkins/compare.sh @@ -18,6 +18,10 @@ if test -n "$ghprbPullId"; then printf "❎ Skipped API comparison because the PR has the label 'skip-api-comparison'\\n" >> "$WORKSPACE/jenkins/pr-comments.md" exit 0 fi + if ./jenkins/fetch-pr-labels.sh --check=skip-public-jenkins; then + echo "Skipping API comparison because the label 'skip-public-jenkins' was found." + exit 0 + fi fi if test -z "$ghprbPullId"; then @@ -49,6 +53,7 @@ else URL_GENERATOR="$BUILD_URL/Generator_20Diff" fi +printf "✅ [API Diff (from PR only)](%s)" "$URL_API" >> "$WORKSPACE/jenkins/pr-comments.md" if ! grep "href=" jenkins-results/apicomparison/api-diff.html >/dev/null 2>&1; then printf "✅ [API Diff (from PR only)](%s) (no change)" "$URL_API" >> "$WORKSPACE/jenkins/pr-comments.md" elif perl -0777 -pe 's/
C# Interface TypeNSDictionary Storage Type
boolBoolean stored in an NSNumber
Enumeration valuesinteger stored in an NSNumber
int32-bit integer stored in an NSNumber
uint32-bit unsigned integer stored in an NSNumber
nintNSInteger stored in an NSNumber
nuintNSUInteger stored in an NSNumber
long64-bit integer stored in an NSNumber
float32-bit integer stored as an NSNumber
double64-bit integer stored as an NSNumber
NSObject and subclassesNSObject
NSDictionaryNSDictionary
stringNSString
NSStringNSString
C# Array of NSObjectNSArray
C# Array of enumerationsNSArray containing NSNumbers with the value