Celedev Blog Archive

Since the very beginning, the main goal of CodeFlow is to bring real interactivity to iOS Apps development. Real interactivity implies a development environment that provides the highest possible level of responsiveness between the writing of the application's source code and the execution of this code on the target device, while giving to the developer access to every capability of the iOS platform and the comfort of using iOS familiar APIs.

The use of Lua as the programming language for dynamic code in CodeFlow comes therefore with the possibility to have access in Lua to the whole iOS SDK. Except for a few low-level frameworks, almost every API, type, classe, protocol and method defined in the SDK can be used in Lua, in a very straightforward and natural way. This is one of CodeFlow's big strengths: be fully transparent regarding the set of APIs usable from the code, avoiding thus the constraints of a proprietary API, and the pitfall of a narrow target application domain.

On the technical side, enabling the Lua code to use SDK native APIs requires some sort of interface components, which are called Bindings Libraries. In CodeFlow a Binding Library is a package containing two kinds of contents: Lua API modules (i.e. Lua source files containing a Lua translation of SDK APIs), and code libraries that will be linked - when needed - with the target application in Xcode. The code in these libraries handles the necessary conversions between a Lua dynamic environment and iOS native system APIs.

This could look a bit complex, but actually the the use of Bindings Libraries is fully transparent for the user. Once you have selected the SDK version that you want to use, CodeFlow takes care of everything: making code writing easier by proposing auto-completion for symbols in the SDK, configuring the Xcode project of the target application, so that it embeds the framework and bindings libraries needed by the Lua code... These things are automatically done, so you don't need to bother with bindings management.

Therefore Bindings Libraries are an essential component of a dynamic application development system like CodeFlow, because they act as a transparent communication path between the dynamic code and the rest of the system.

Accessing Application-Specific APIs

And for accessing application-specific APIs from Lua, how does that work?

In previous CodeFlow versions, prior to 0.9.15, it was definitely possible to reference (and to extend) specific compiled classes of the target application from the Lua code, to call their methods, or to use their properties and IBOutlets. In most cases that worked just well, but using such APIs was done somewhat in the blind, without completion support from the Lua editor in CodeFlow, and method calls were done in best-effort mode, relying on the (sometimes insufficient) information available in the Objective-C runtime. Besides, application-specific C types or functions were simply not accessible from Lua.

In a nutshell, before CodeFlow 0.9.15, integration between dynamic code and compiled code in an iOS application was a bit limited…

This is why I am happy to present the great new feature of CodeFlow 0.9.15: dynamic creation of Project Bindings Libraries, providing extended access from Lua to specific types and APIs of the target application.

Project Bindings Libraries, this means that all APIs defined in your application's header files can now be used from your Lua code in CodeFlow, with the same level of transparency and quality that was previously only available for APIs of the system SDK. Naturally, Project Bindings Libraries can also include the APIs of third-party libraries and CocoaPods used in your application project! 😃

Specifically, Project Bindings Libraries give access to the vast majority of symbols defined in .h files belonging to your Xcode project; this includes entities declared as #define, enum, struct, C function, const global variable (e.g. string constants declared as extern NSString* const), and, of course, Objective-C classes and protocols, with their methods and properties.

Each CodeFlow project has its own Project Bindings Library. This Bindings Library is automatically created and updated, so as to stay in-sync with the target application's Xcode project. You can configure the content of a Project Bindings Library through a dedicated interface in CodeFlow (read below).

Using Project Bindings

In CodeFlow 0.9.15, if a given CodeFlow project has an associated Xcode project, then a Project Bindings Library is automatically created, to provide Lua interfaces for the C and Objective-C APIs defined in this Xcode project. By default the Project Bindings Library includes APIs defined in all .h files of the Xcode project, but the list of visible header files can be modified in the corresponding Bindings Editor.

As an example, let's consider a WatchKit test application named WatchApp1, that show the following structure under Xcode:

If we select the Project Bindings Library in the associated CodeFlow project, we can see the Bindings Editor for it. The Bindings Editor presents a file tree that mirrors the Xcode project structure and that contains every .h file in this project.

Each .h file (and each group) can be individually selected or unselected, and only APIs declared in selected header files will be included in the Project Bindings Library. In this example, we are only interested in APIs in the "WatchKit Extension" group; so we have unchecked the "WatchApp1" group in the list.

In addition to the selection checkbox, the Bindings Editor displays for every header file in the project:

• a QuickLook button that shows a preview of the .h header file;
• a Bindings-generation-result indicator for this file: green in case of success, yellow if warnings were emitted during the generation, red if the generation did fail, or gray if the generation did not take place; a click on this indicator displays detailed information about the status;
• a direct access button to the generated Lua module API.

Project Bindings Libraries are automatically updated if one of the selected .h files is modified, or if the contents of the associated Xcode Project is changed (e.g. if you add a new .h file in the project). Conversely when you change the list of selected header files in the Bindings Editor, you have to explicitly tell CodeFlow to update the Bindings Library, by either clicking on the Refresh button in the Bindings Editor or by selecting the Update Lua Bindings… command in the Program menu.

And, well… that's about all you need to know for using this new Project Bindings feature in CodeFlow.

The actual usage of the Project Bindings Library in your code is transparently managed by CodeFlow, just as with SDK Bindings Libraries. Project APIs are added to code-completion proposals; Project Bindings code libraries are automatically added to the associated Xcode project if needed; and, during the target app execution, project-specific data are created with the expected types, project methods and function are called with the specified parameter types…

All this is made possible by Bindings Libraries. In CodeFlow they are an essential component of the live-coding system, almost invisible but so important. And with CodeFlow 0.9.15 and Project Bindings Libraries, live coding on iOS takes a major feature boost. And really, for the developer, It just works!