Getting Started

PDF for offline use

Let us know how you feel about this

Translation Quality


0/250

last updated: 2016-08

⚠️

WARNING: Objective Sharpie is a tool for experienced Xamarin developers with advanced knowledge of Objective-C (and by extension, C). Before attempting to bind an Objective-C library you should have solid knowledge of how to build the native library on the command line (and a good understanding of how the native library works).

Installing Objective Sharpie

Objective Sharpie is currently a standalone command line tool for Mac OS X 10.10 and newer, and is not a fully supported Xamarin product. It should only be used by advanced developers to assist in creating a binding project to a 3rd party Objective-C library.

Objective Sharpie can be downloaded as a standard OS X package installer. Run the installer and follow all of the on-screen prompts from the installation wizard:

Tip: use the sharpie update command to update to the latest version.

Basic Walkthrough

Objective Sharpie is a command line tool provided by Xamarin that assists in creating the definitions required to bind a 3rd party Objective-C library to C#. Even when using Objective Sharpie, the developer will need to modify the generated files after Objective Sharpie finishes to address any issues that could not be automatically handled by the tool.

Where possible, Objective Sharpie will annotate APIs with which it has some doubt on how to properly bind (many constructs in the native code are ambiguous). These annotations will appear as [Verify] attributes.

The output of Objective Sharpie is a pair of files - ApiDefinition.cs and StructsAndEnums.cs - that can be used to create a binding project which compiles into a library you can use in Xamarin apps.

⚠️

Objective Sharpie comes with one major rule for proper usage: you must absolutely pass it the correct clang compiler command line arguments in order to ensure proper parsing. This is because the Objective Sharpie parsing phase is simply a tool implemented against the clang libtooling API.

This means that Objective Sharpie has the full power of Clang (the C/Objective-C/C++ compiler that actually compiles the native library you would bind) and all of its internal knowledge of the header files for binding. Instead of translating the parsed AST to object code, Objective Sharpie translates the AST to a C# binding "scaffold" suitable for input to the bmac and btouch Xamarin binding tools.

If Objective Sharpie errors out during parsing, it means that clang errored out during its parsing phase trying to construct the AST, and you need to figure out why.

NEW! version 3.0 attempts address some of this complexity by supporting Xcode projects directly. If a native library has a valid Xcode project, Objective Sharpie can evaluate the project for a specified target and configuration to deduce the necessary input header files and compiler flags.

If no Xcode project is available, you will need to be more familiar with the project by deducing the correct input header files, header file search paths, and other necessary compiler flags. It is important to realize that the compiler flags used to build the native library are the same that must be passed to Objective Sharpie. This is a more manual process, and one that does require a bit of familiarity with compiling native code on the command line with the Clang toolchain.

NEW! version 3.0 also introduces a tool for easily binding CocoaPods via the sharpie pod command. If the library you're interested in is available as a CocoaPod, we recommend you start by attempting to bind the CocoaPod with Objective Sharpie (versus attempting to bind against the source directly).

Telemetry Submission

Objective Sharpie by default submits information back to Xamarin about each binding attempt as Xamarin is very actively trying to improve the quality and reliability of Objective Sharpie.

The following data will be submitted to Xamarin for analysis on each run of the sharpie bind tool:

  • all command line arguments passed to sharpie bind
  • the name of the current working directory
  • the output of the xcodebuild -showBuildSettings command as run against the current working directory
  • unhandled exceptions

No source code, libraries, or binaries will be submitted to Xamarin.

The following telemetry options can be used to disable or limit data to be sent to Xamarin for analysis. These options must be specified on each run of the sharpie bind tool. Options below should be specified before the bind tool name (e.g. sharpie -tlm-do-not-submit bind Foo.h). All data mentioned above is submitted by default to Xamarin.

-tlm-about               Show a detailed overview of what usage and binding
                        information will be submitted to Xamarin by
                        default when using Objective Sharpie.

-tlm-do-not-submit       Do not submit any usage or binding information to
                        Xamarin. Run 'sharpie -tml-about' for more
                        information.

-tlm-do-not-identify     Do not submit Xamarin account information when
                        submitting usage or binding information to Xamarin
                        for analysis. Binding attempts and usage data will
                        be submitted anonymously if this option is
                        specified.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.