Legacy Cocoa Mode

In the future, the classic "Toffee" platform for creating applications for the Cocoa platform is being migrated to use the new Island/Darwin compiler and tool chain back-end. This will enable better interoperability with Island and Swift Runtime objects, provide other under-the-hood benefits and improvements, and eliminate the overhead of supporting two separate tool chains for Cocoa.

Right now, the new mode is inactive, and can be enabled by explicitly setting the UseLegacyToffeeMode project setting to False. The setting currently defaults to True. The default will change once the new mode is fully functional and compatible, and the option will be removed completely eventually, when the legacy Cocoa mode will be discontinued (probably not for quite a while).

Disabling UseLegacyToffeeMode in a Cocoa project (or project target) has the following effects:

  • The effective Mode during bulld will be "Island" and the SubMode will be "Darwin".
  • The SDK, if not set explicitly, will be se to the origial sub-mode (e.g. "iOS", "macOS", etc.)
  • the Default Object Model setting will be set to "Cocoa".
  • The COCOA, TOFFEE and (new) TOFFEEV2 Conditional defines will be set (as will be ISLAND (!!)).
  • Reference resolving will be instructed to consider "ToffeeV2" subfolders when looking up library referendes such as Elements RTL, with priority over the "Island/Darwin" ones.
  • Reference resolving will ignore references to libToffee, which is no longer required.

By the combination of these effects, existing "Toffee" Cocoa projects should compile and act mostly as they did before, even though they are now using the newer Island compiler backend. In particular, classes and interfaces will still default to Objective-C runtime types (the only type supported by the old Cocoa mode). But there are a few differences:

  • Cocoa code now has access to Island classes, including Island RTL, GoBaseLibrary and any second or third party Island libraries.
  • Island code can be intermixed within the Cocoa project seamlessly, if needed.
  • Swift Projects now reference the Island-native version of the Swift Base Library, which is relieved from some limitations of the Toffee Cocoa compiler back-end (such as no interfaces on structs).
  • Once available1, Cocoa code will also have access to Swift Runtime classes.

Some caveats include:

  • The ISLAND define will now be set, even for Cocoa projects. Cross-platform projects that use conditional compilation using the ISLAND and TOFFEE or COCOA defines might need to be reviewed to change the order the defines are checked or add additional checks, as necessary.

Elements RTL

Projects using Elements RTL will, by default, continue to reference a special Cocoa-based version of the library, where most types are mapped against their Cocoa counterparts (e.g. List<T> continues to map to NSArray, instead of the Island-native List<T>.

This ensures best interoperability of Elements RTL types with system APIs for Cocoa projects.

See Also

  1. Swift runtime object model support will be added once Apple Swift has stabilized both its ABI and its Module format. In theory, this features has been delivered by Apple in late 2019, but it is not very well documented and we have doubts about its long-term stability. We are slowly investigating and adding support for it, over time. ↩