One of the strengths of the Elements compiler has always been that it allows full and unfettered access to platform APIs and all the third party libraries out there for the platform you are targeting – including those created not by Elements but the platform-vendor's own tool chain.

That way, you can leverage all the great WinForms or WPF components on .NET, all the available Java and Android libraries out there, and of course any Objective-C-based framework on iOS and macOS.

But using Objective-C frameworks has not been as easy as it should have been in the past, especially compared to using .NET and Java libraries. The reason is that .NET .dlls and Java .jar files contain rich metadata that describes the library. The compiler can directly reference the file, and knows everything about it — the available types, their methods, and so on. By contrast, a Cocoa binary has no machine-readable description of its content; the compiler needs to learn what's inside it elsewhere. Cocoa .frameworks bundle .h header files for this, but header files are cumbersome, slow and sometimes ambiguous to parse. Elements pre-processes them by importing the framework and generating a .fx file with binary and easy-to-read metadata gathered from .h files. To the compiler, a .fx file is just as easy to load up as a .dll or .jar file.

Import Projects

In the past, importing frameworks was done manually by a command line tool called Header Importer, and the process was cumbersome and error prone. A few weeks ago, we improved this process vastly, with the addition of two things: (a) Import Projects and (b) support for easily creating them in the Fire and Water IDEs.

An Import Project is a special .elements project type. Instead of taking source code and building it into a binary, it takes a .framework (or, optionally, a static or dynamic library and its .h files), and generates the matching .fx file from it.

That .fx file can then be referenced directly in other projects, even as Project Reference.

Creating an Import Project for a .framework is as easy as dragging the framework into your solution.

We've made a video to show how this works:

What can be Imported

Import projects work for the "Toffee" Cocoa platform, and all Island platforms.

For Cocoa (both Toffee, and Island/Darwin), you can import .frameworks as shown above. This is the easiest option to set up, because the .framework has all the relevant information in one place, so it's just a drag & drop.

For Cocoa and all Island platforms, you can import static libraries (.a or .lib) and dynamic libraries (.so on Linux, .dylib on Mac or unmanaged .dlls, on Windows), if you have the .h files that describe their C or Objective-C APIs. Because the .h files need to be provided externally by you, this takes a bit more setup — essentially you will create an Import Project from template, and then specify the binary and #import clauses for one or more of the header files that describe it.

Import Projects and all their capabilities are described in more detail on our documentation site in the FXGen|Import Projects topic.