Modes & SubModes

EBuild of course supports building projects on all the Platforms and Sub-Platforms supported by the Elements compiler. EBuild refers to platform and sub-platform as Mode and SubMode (as in, "which mode of the compiler is used"), so this topic will adhere to the same nomenclature, as well.

Mode will be equivalent to the Compiler Back-end used (except for Toffee projects that opt out of Legacy Toffee V1 Mode, which EBuild will internally map over to use Island mode).

This topic will dive into specifics on how EBuild determines the Mode and SubMode for a given project or target, and also explain any caveats that targeting a specific platform might entail.

Determining Mode and SubMode

Mode (and SubMode) can be set either globally for a project or – for multi-target projects – for each individual target. There are two ways how EBuild will determine the mode:

For legacy projects compatible with the old MSBuild tool chain, EBuild analyzes the <Import> tags and determines the mode from the name of the imported RemObjects.Elements.*.targets file(s). (Different than MSBuild, EBuild does not actually process these <Imports>, beyond looking at their name).

EBuild recognizes the following names, and sets the Mode and SubMode setting accordingly:

  • RemObjects.Elements.Echoes.targets (.NET)
  • RemObjects.Elements.Cooper.targets (Java/Plain)
  • RemObjects.Elements.Cooper.Android.targets (Java/Android)
  • RemObjects.Elements.Toffee.targets (Cocoa, SubMode determined by SDK)
  • RemObjects.Elements.Nougat.targets (Cocoa, SubMode determined by SDK)
  • RemObjects.Elements.Island.*.targets (Island, SubMode determined by *)

For non-legacy EBuild-specific projects (projects that do not have one of the above targets included), EBuild expects the <Mode> setting to be present, either on project level, or for each individual target; for Island and Toffee modes, the <SubMode> also must be set.

Note that non-legacy projects can (optionally) import the RemObjects.Elements.targets file, which allows them to be built with EBuild, hosted in MSBuild. Please refer to this topic for more details on this.

Mode Echoes (.NET Platform)

Echoes projects compile for the Common Language Runtime (CLR) in all its variations. Echoes projects do not require a <SubMode> to be set, as EBuild will determine the appropriate SubMode as part of the ElementsPrepareEchoesPlatform task by looking at the TargetFramework or the (deprecated) TargetFrameworkVersion project setting. If neither is set, a default of (currently) v4.6.2 is assumed, for backward compatibility.

TargetFramework can contain either a plain .NET Framework version number (e.g. v4.6.2), or a standard Framework Type+Version specifier in either long (e.g. .NETStandard,Version=2.0) or short (e.g. .NETStandard2.0) format.

If only a version number is provided, the SubMode is assumed to be the full .NET Framework (SubMode = "Classic"). Otherwise, the following supported SubModes will be derived from the TargetFramework value:

  • .NETStandard (.NET Standard)
  • .NETCore (.NET Core)
  • .NET (Full Framework)
  • Universal (Windows 10)
  • WindowsPhone (8.1 or later)
  • Portable
  • Mono

After ElementsPrepareEchoesPlatform finishes, SubMode will be set to one of the above values. The SubMode will determine reference resolving and the behavior of other build tasks.

Mode Cooper (Java/JVM Platform, including Android SDK)

Cooper projects compile for the Java Virtual Machine (JVM). If no SubMode is set, the ElementsPrepareCooperPlatform task will set a value of Plain. Valid SubModes are:

  • Plain (regular Java/JVM)
  • Android (Java-based Android SDK)

The SubMode will determine reference resolving (e.g. whether base types are referenced from installed JDK or android.jar) and the behavior of other build tasks, including support for .aar references on Android, and pre- and post-compile Android-specific tasks such as DEX and APK generation.

Mode Toffee (Cocoa Platform)

Toffee projects compile for Cocoa and the Objective-C Runtime. The SubMode is determined in the ElementsPrepareToffeePlatform task by looking at the SDK setting or vice versa. If the SDK value is present, SubMode will be set/overwritten accordingly; if no SDK value is set, the latest SDK for the specified SubMode will be set. (PrepareToffeePlatform will fail if neither value is provided.)

Valid SubModes are:

  • macOS
  • iOS
  • tvOS
  • watchOS

The SubMode will determine which base SDK will be used, as well as the behavior of other build tasks, including linking and .app bundle creation.

Mode Island (Native Island Platform)

Island projects compile to CPU-native binaries for a range of Sub-Platforms. Different than for the other three modes, a SubMode is required for Island projects. Valid SubModes are:

The SubMode will determine which base SDK will be used, as well as the behavior of other build tasks.