Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history 
Yup
  • Loading branch information
@gaearon
gaearon committed Sep 13, 2013
1 parent 1a6c20a commit 08e3a07
Showing 1 changed file with 65 additions and 18 deletions.
83 changes: 65 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,16 @@

This project implements MonoTouch C# bindings for [HockeyApp SDK](https://github.com/bitstadium/HockeySDK-iOS). Please refer to the original [HockeyApp SDK documentation](https://github.com/bitstadium/HockeySDK-iOS#introduction) to learn what it does and why you might want to use it.

## Integration

You can git clone this project or [download a compiled binary](https://github.com/downloads/stampsy/hockeyapp-monotouch/hockeyapp-monotouch.zip) and reference it like a normal .NET library.
The specific version of HockeySDK we're linking against is 3.0 ([source](https://github.com/bitstadium/HockeySDK-iOS/tree/3.0.0), [binaries](http://download.hockeyapp.net/sdk/ios/HockeySDK-iOS-3.0.0.zip)).
You don't need to download them but the source is useful to find method signatures for bindings.

If you clone the binding, copy `HockeyApp` folder to your solution folder alongside with your project. Then add a reference to the `HockeyApp/HockeyApp.csproj` in Projects tab.
## Integration

If you downloaded just the binaries, place the `*.dll` wherever you will in your project and then locate it using .NET Assembly tab in Add Reference dialog, as you would normally do.
You can git clone this project or [download a compiled binary](https://github.com/stampsy/hockeyapp-monotouch/releases/download/v3.0/HockeyApp.dll) and reference it like a normal .NET library.

There is one benefit to using the binaries over the source code. MonoDevelop doesn't play nice with binding projects yet and highlights all the code using them red. Autocompletion is also not available when referencing binding project.
You should probably want to use the binary over the source code: Xamarin Studio autocompletion doesn't recognize classes from binding projects and this gets in the way. Your project will also build faster if you reference the binary.

There is no such problem if you reference the compiled `*.dll` itself.
Whichever way you decide to link the binding, there are four things you need to do next.
There are **four important things** you need to do next, or they will hunt you down and bite you in the arse later.

------

Expand All @@ -23,23 +21,23 @@ Your `AppDelegate` should end up looking like [this](https://github.com/stampsy/

----

### Add Resource Bundle

First, copy `HockeySDKResources.bundle` from the binding directory to your **application project** (not the binding project!). Right-click your project in Solution Explorer and check Show All Files in Display Options. Find `HockeySDKResources.bundle` in your project tree, right-click it and click Include in Project. You can uncheck Show All Files now.

### Specify App Version

HockeyApp uses short bundle identifier in its user interface to differentiate between versions and it makes sense to set a different one each time you upload a new build on HockeyApp. To do so, open your `Info.plist` on Advanced tab and add a string value called `CFBundleShortVersionString`. It has no strict format.

### Tell HockeyApp to Get Going
### Find You HockeyApp App ID

[There's a website for that.](http://support.hockeyapp.net/kb/how-tos/how-to-find-the-app-identifier)

You need to tell HockeyApp to activate and [give it your HockeyApp Public ID](http://support.hockeyapp.net/kb/how-tos/how-to-find-the-app-identifier). You will probably want to do it in `FinishedLaunching` method inside your `AppDelegate`. You can wrap HockeyApp activation in `#if !DEBUG` directive so it is stripped out of debug builds.
### Initialize HockeyApp in AppDelegate

You need to call a few methods to configure HockeyApp. You will probably want to do it in `FinishedLaunching` method [inside your `AppDelegate`](https://github.com/stampsy/hockeyapp-monotouch/blob/master/src/SampleApp/AppDelegate.cs). You can wrap HockeyApp activation in `#if !DEBUG` directive so it is stripped out of debug builds. Don't forget to **pass your app ID** to `Configure` method.

### Add Null Reference Exception Fix

**This piece is super duper important. Your app will crash if you don't do this.**

Any iOS crash reporting library overrides signal handlers to catch crashes. Unfortunately Mono needs to handle `SIGSEGV` and `SIGBUS` itself, or any null reference exception will crash your app, whether it was handled or not.
Any iOS crash reporting library overrides signal handlers to catch crashes. Unfortunately Mono needs to handle `SIGSEGV` and `SIGBUS` itself, or any null reference exception will crash your app, whether it was handled or not.

Fortunately, [adding some extra code to AppDelegate fixes the problem](http://stackoverflow.com/a/14499336/458193).

Expand All @@ -49,9 +47,58 @@ Skip this section if you're familiar with HockeyApp or TestFlight process.

In order to decode your crash reports, you need to actually **upload the exact builds you have deployed to HockeyApp along with the corresponding debug symbols**. If you get a crash report from a build that is not uploaded on HockeyApp, you will not see the crash stack trace.

MonoDevelop will happily generate `*.ipa` and `*.dSYM` that HockeyApp wants if you check “Build ad-hoc/enterprise package (IPA)” in iPhone IPA Options in your Project Settings. Again, `*.dSYM` is actually a directory, so you'll need to zip it before uploading to HockeyApp. This quickly becomes a pain in the ass if you want to upload many builds a day so we wrote a Python script to bump bundle version on each Release build and upload it to HockeyApp with the debug symbols right away.

Unfortunately this script is somewhat buggy and tailored to specific our project so we don't release it yet but if you think it can be useful to you, ping me at [email protected] and I'll get in touch with you.
MonoDevelop will happily generate `*.ipa` and `*.dSYM` that HockeyApp wants if you check “Build ad-hoc/enterprise package (IPA)” in iPhone IPA Options in your Project Settings. Again, `*.dSYM` is actually a directory, so you'll need to zip it before uploading to HockeyApp.

## Where's My Managed Stack Trace?

The stack traces you will receive will be close to managed code, but not quite. They may look somewhat like this:

```
Thread 0 Crashed:
1 libsystem_kernel.dylib _pthread_kill + 8
2 libsystem_c.dylib _abort + 95
3 FizzBuzz monotouch_throw_monotouch_exception (monotouch-glue.m:1369)
4 FizzBuzz mono_invoke_unhandled_exception_hook (mini-exceptions.c:2745)
5 FizzBuzz mono_thread_abort_dummy (mini.c:2809)
6 FizzBuzz mono_handle_exception_internal + 2149
7 FizzBuzz mono_handle_exception (mini-exceptions.c:1972)
8 FizzBuzz mono_arm_throw_exception (exceptions-arm.c:162)
9 FizzBuzz throw_exception + 68
10 FizzBuzz FB_BL_Managers_FBRegisterManager_OnRegisterSelected_int (FBRegisterManager.cs:97)
11 FizzBuzz FB_AL_TableSource_RowSelected_MonoTouch_UIKit_UITableView_MonoTouch_Foundation_NSIndexPath (TableSource.cs:137)
12 FizzBuzz wrapper_runtime_invoke_object_runtime_invoke_dynamic_intptr_intptr_intptr_intptr + 200
13 FizzBuzz mono_jit_runtime_invoke (mini.c:6457)
14 FizzBuzz mono_runtime_invoke (object.c:2827)
15 FizzBuzz native_to_managed_trampoline_FB_AL_TableSource_RowSelected (registrar.m:1809)
16 UIKit -[UITableView _selectRowAtIndexPath:animated:scrollPosition:notifyDelegate:] + 877
17 UIKit -[UITableView _userSelectRowAtPendingSelectionIndexPath:] + 157
18 Foundation __NSFireDelayedPerform + 451
19 CoreFoundation __CFRUNLOOP_IS_CALLING_OUT_TO_A_TIMER_CALLBACK_FUNCTION + 15
20 CoreFoundation CFRunLoopDoTimer + 273
21 CoreFoundation __CFRunLoopRun + 1233
22 CoreFoundation _CFRunLoopRunSpecific + 357
23 CoreFoundation _CFRunLoopRunInMode + 105
24 GraphicsServices _GSEventRunModal + 75
25 UIKit _UIApplicationMain + 1121
26 FizzBuzz wrapper_managed_to_native_MonoTouch_UIKit_UIApplication_UIApplicationMain_int_string_intptr_intptr (:1)
27 FizzBuzz MonoTouch_UIKit_UIApplication_Main_string___string_string (UIApplication.cs:38)
```

As you can see, there is some relevant information there hidden in the noise:

```
...
10 FizzBuzz FB_BL_Managers_FBRegisterManager_OnRegisterSelected_int (FBRegisterManager.cs:97)
11 FizzBuzz FB_AL_TableSource_RowSelected_MonoTouch_UIKit_UITableView_MonoTouch_Foundation_NSIndexPath (TableSource.cs:137)
...
16 UIKit -[UITableView _selectRowAtIndexPath:animated:scrollPosition:notifyDelegate:] + 877
17 UIKit -[UITableView _userSelectRowAtPendingSelectionIndexPath:] + 157
...
```

But this is still a bummer if you want to know the exception's message and type.

Luckily, you can log most unhandled managed exceptions in `Main` method and tell HockeyApp to read from your log file and attach any information you need to the crash report it generates. [More about this approach here.](https://github.com/stampsy/hockeyapp-monotouch/issues/5#issuecomment-24361780)

## Scope and Contributions

Expand Down

4 comments on commit 08e3a07

@icnatejackson
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gaearon I'm not sure you really meant to remove the section called "Add Resource Bundle" did you? Without taking those steps, crash reports do not flow to the HockeyApp environment.

@gaearon
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@icnatejackson

In fact I meant it, because Xamarin tools got a little smarter since I wrote it last time.

At least with the recent versions of Xamarin Studio, you can just add files with BundleResource action to DLLs, and they will be correcty copied to the output .app when referencing that DLLs from your app project. So you no longer need to attach it explicitly, I guess.

(I just checked with a clean build, and this seems to be the case: BundleResource files must be somehow embedded in the DLL.)
Is there something I'm missing? Thanks.

@icnatejackson
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gaearon

When I was evaluating these bindings a couple weeks ago, I was unable to use the compiled HockeyApp.dll assembly that was in the repo at the time. I got a bunch of compile/linker exceptions. I traced it back to the issue described here(I'm on Xamarin's Alpha Channel):

http://forums.xamarin.com/discussion/1475/changes-to-assembly-strongnames-in-xamarin-ios-6-2-0

In order for me to use the bindings, I had to pull the source and compile the HockeyApp.dll for myself against my local copies of monotouch.dll. Then, in my actual project, I needed to include the BundleResource and reference the HockeyApp.dll I'd built locally.

To be honest, I didn't even try to reference the newer compiled HockeyApp.dll that you put into the repo recently.

However, when I sync'd my local repo with your recent commits and recompiled the HockeyApp.dll locally, I tried to simply reference the local DLL in a new test project. But, since I was using the readme.md as a guide, I'd failed to include the BundleResource in this new project. Everything seemed like it was working. I forced my test app to crash. The next time I launched the app, it asked me if I wanted to submit the crash report. I clicked "Send Report." But, nothing appeared on the HockeyApp site. I didn't attach a network profiler to the app, so I do not know if my App simply did not send anything, or if it was malformed in some way and rejected by HockeyApp.

As soon as I manually included the ResourceBundle in my test app, the Crash Dumps started flowing to HockeyApp.

FYI, I just reviewed my local HockeyApp bindings project and the HockeySDKResources.bundle are set to BuildAction "BundleResource." I'm unsure if my local environment is building the HockeyApp.dll differently than your environment due to some other setting.

@gaearon
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@icnatejackson

I suppose this was because compiled DLL that was in the repo at the time was built with a different Mono version (I think I used a pre-release 3.0, versus the released one). This should definitely be fixed by now.

What you describe is odd, I'll check on that tomorrow.

Please sign in to comment.