Bug 19543 - Add link to registrar documentation for new registrar errors, particularly "MT5210: Native linking failed"
Summary: Add link to registrar documentation for new registrar errors, particularly "M...
Alias: None
Product: iOS
Classification: Xamarin
Component: Tools ()
Version: 7.2.3
Hardware: PC Mac OS
: --- enhancement
Target Milestone: mtvs-2.0
Assignee: Bugzilla
Depends on:
Reported: 2014-05-05 21:36 UTC by Brendan Zagaeski (Xamarin Team, assistant)
Modified: 2014-05-07 06:14 UTC (History)
4 users (show)

Is this bug a regression?: ---
Last known good build:

Notice (2018-05-24): bugzilla.xamarin.com is now in read-only mode.

Please join us on Visual Studio Developer Community and in the Xamarin and Mono organizations on GitHub to continue tracking issues. Bugzilla will remain available for reference in read-only mode. We will continue to work on open Bugzilla bugs, copy them to the new locations as needed for follow-up, and add the new items under Related Links.

Our sincere thanks to everyone who has contributed on this bug tracker over the years. Thanks also for your understanding as we make these adjustments and improvements for the future.

Please create a new report on Developer Community or GitHub with your current version information, steps to reproduce, and relevant error messages or log files if you are hitting an issue that looks similar to this resolved bug and you do not yet see a matching new report.

Related Links:

Description Brendan Zagaeski (Xamarin Team, assistant) 2014-05-05 21:36:57 UTC
Although it's mentioned on the release notes [1], as well as in various forum threads and bug reports, I suspect the new registrar behavior is still going to stump a bunch of people who decide to upgrade during the next wave of stables.

> [1] http://docs.xamarin.com/releases/ios/xamarin.ios_7/xamarin.ios_7.2/#1

To help ease the transition for those users, maybe the a link to the registrar documentation [2] could be added to the appropriate error messages.

> [2] http://docs.xamarin.com/releases/ios/xamarin.ios_7/xamarin.ios_7.2/#1

For example, two error messages that look like they're going to be fairly common when users upgrade are:

1. Error MT5210: Native linking failed, undefined symbol: _foo. Please verify that all the necessary frameworks have been referenced and native libraries are properly linked in. (MT5210)

2. Error MT5211: Native linking failed, undefined Objective-C class: _OBJC_CLASS_$_MyDelegate. If '_OBJC_CLASS_$_MyDelegate' is a protocol from a third-party binding, please check that it has the [Protocol] attribute in its api definition file, otherwise verify that all the necessary frameworks have been referenced and native libraries are properly linked in. (MT5211)

## Possible improvements

It looks like the error message for (2) might have been updated recently to reflect the requirement to include the [Protocol] attribute.

If sensible, it would be nice to update (1) similarly. One potential complication is that compared to (2), I think (1) can more often happen for reasons _other_ than the new registrar behavior. Still maybe it would be OK to add a link to the registrar documentation [3] within the text of this error?

> [3] http://docs.xamarin.com/guides/ios/advanced_topics/registrar/#Must_link_to_existing_symbols

This hint from that page is excellent:
"This usually happens when a binding has existed for some time, and the native code has been modified during that time so that a particular native class has either been removed or renamed, while the binding has not been updated."

Adding a link to the registrar documentation for error (2) [4] might be also helpful, but that error message already has fairly good searchability, so it's probably OK as-is.

> [4] http://docs.xamarin.com/guides/ios/advanced_topics/registrar/#Protocols_must_have_the_Protocol_attribute

Many thanks!

## Version information
Comment 1 Brendan Zagaeski (Xamarin Team, assistant) 2014-05-05 21:43:43 UTC
[2] was supposed to be:
> [2] http://docs.xamarin.com/guides/ios/advanced_topics/registrar/
Comment 2 Sebastien Pouliot 2014-05-05 22:08:51 UTC
While being more accurate is a good idea (in fact Rolf added a new warning just today) but I'm not sure adding details is always good (or the best way to help).

1. By the time we release an update to most people (i.e. stable) it will have lost a lot of it's helping power...

2. Long error messages are often more confusing than helping. When you start saying "If" or "when", "or", "either" in an error message then might hide the solution as much as help finding it.

One thing we should do (well complete) is to have all error codes in web pages and have the tools (e.g. XS) navigate to the URL (e.g. double click). That would allow us to give longer [1] explanation (as long as it requires to explain the issue), examples (bad and good) and (when needed) a quick way to update the information (i.e. without waiting for a new release).
Comment 3 Sebastien Pouliot 2014-05-05 22:17:03 UTC
Jan 31, 2012 -> https://app.asana.com/0/77259014252/431409776833

IIRC there's a google doc (or repo) that Rolf started a while ago (with a similar goal)
Comment 4 Rolf Bjarne Kvinge [MSFT] 2014-05-06 02:29:21 UTC
It's here:

Comment 5 Rolf Bjarne Kvinge [MSFT] 2014-05-07 06:14:59 UTC
I've added (more) text for MT5210 to explain this.

documentation/mtouch-error-messages: 5b14210ac7afb15e68103921ae7f516067009675