// README // Dumbarton // // Copyright (C) 2006 imeem, inc. All rights reserved. // // This library is free software; you can redistribute it and/or // modify it under the terms of the GNU Lesser General Public // License as published by the Free Software Foundation; either // version 2.1 of the License, or (at your option) any later version. // // This library is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU // Lesser General Public License for more details. // // You should have received a copy of the GNU Lesser General Public // License along with this library; if not, write to the Free Software // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA // Overview -------- Dumbarton is an Objective-C framework that works as an interface into the Mono C API for embedding. Functionally, it works like an ObjC<->C# language bridge. It was originally written in order to bring imeem (http://www.imeem.com) to OS X to allow for the usability of a native Cocoa application without requiring developers to reimplement the core code that had already been written for the Windows client that had been written in C#/.NET. Dumbarton provides: - Mapping of memory management between Mono and Objective-C. If you understand memory management in ObjC, memory management of Dumbarton objects is no different. - A set of ObjC categories to facilitate easy conversion between Application Kit objects and their C# equivalents. More will be added as demand requires. - Conversion (and re-throwing) of managed .NET exceptions to Objective-C exceptions. Prerequisites ------------- - Install Mono.Framework. You can get Mono.Framework from http://www.mono-project.com/Downloads - Install the Dumbarton.Framework in this package into /Library/Frameworks Provided examples ----------------- DBCommandLineExample demonstrates a number of Dumbarton features - Calling native functions from managed code - Calling managed code (functions, properties, fields) from native code - Writing a Dumbarton wrapper for a C# class - Exception handling DBCocoaExample is the classic Currency Converter application; it demonstrates a simple frontend that uses mono for its backend. Creating a new project ---------------------- To setup a new XCode project using Dumbartion: - Create an empty project normally, make sure it builds - Add Mono.Framework and Dumbarton.Framework as to your project (option-click in Groups & Files, Add->Existing Frameworks...) - Add the output of the shell command "pkg-config mono --libs" to the "Other Linker Flags" section of your project build settings. Also, add "-bind_at_load" to the same setting if you want to supress a linker warning. You may want to replace the explicit version number from the pkg-config output with the word "Current" in order to avoid build problems after upgrading your installation of Mono. (example: /Library/Frameworks/Mono.framework/Versions/1.1.13.2/lib becomes: /Library/Frameworks/Mono.framework/Versions/Current/lib) - Similarly, do the same with "pkg-config mono --cflags" and the "Other C Flags" section of your project build settings. You should also do the same Mono version replacement as described in the previous step. - Add /Library/Frameworks to "Framework Search Paths" - turn off ZeroLink on your Debug target, since it doesn't work against mono - enabled Objective C exceptions in your project build settings. Dumbarton catches managed exceptions and rethrows them as ObjC exceptions. - Add any build steps required for compiling your .cs files. The examples just use a simple shell script build step that compiles the C# code into a dll. Depending on your project, you may want to create a separate target for your managed .dll(s) and make your application target depends on the managed .dll targets. Building the project -------------------- At this point, your project should build cleanly and run without linker errors. To Do ----- - Because Mono/Dumbarton do not ship with OS X, you may want to ship Mono and the Dumbarton framework with your application. This is mostly a matter of copying the Mono libraries, Dumbarton.framework, and the parts of the GAC that your managed code requires into your application bundle. You then need to rewrite the install names of your binaries so that they are relative to @executable_path. This will eventually be demonstrated in the release target of the Cocoa example application.