Project Settings Reference
This page provides a reference of all project settings understood by the Elements compiler and EBuildx build tool chain. Most of these options can be set from inside the IDE (see here for how to do this in Fire and Water and in Visual Studio, respectively), but can also be configured manually in the project file, .user file, or passed as parameters to a command line build with MSBuild/XBuild.
Application Settings
The Application Settings control basic attributes of the build project/application, such as target platform versions, executable type, etc.
| Name | Description | Platforms | IDE |
|---|---|---|---|
| ApplicationIcon | The optional .ico file to be used as the application icon for Windows executables. |
.NET, Windows | |
| ApplicationManifest | The optional application manifest .xml file for use for Windows executables. | Island/Windows | |
| Architecture | The CPU architecture or architectures (as semicolon-separated list) to build for, or "all" to build all supported architectures. |
.NET, Cocoa, Island | |
| BinaryName | The file name of the generated executable, without file-extension or prefix. | ||
| CrossBox | The CrossBox server to use for building Cocoa apps from Visual Studio on Windows. See CrossBox for details. | ||
| CrossBoxDeviceID | The mobile device, simulator or emulator to build for or run on. | Cocoa, Android | |
| DefaultLangauge | Specifies the default language for new files added via templates, in Fire. This can be set in multi-language projects to control the default shown in the New File dialog. | Fire, Water | |
| Deployment Target | Optionally specifies the minimm OS version needed to run this app. See Deployment Targets for details. | Cocoa, Android Island | |
| ExtensionType | For Cocoa projects with OutputType of Extension, the type of extension to build. |
Cocoa | |
| InternalAssemblyName | An optional internal name for the generated .NET executable (not the name of the generated fine, which is determined by the BinaryName setting). | .NET | |
| MacCatalystArchitecture | The CPU architecture or architectures (as semicolon-separated list) to build for when targeting Mac Catalyst, or "all" to build all supported architectures. |
iOS | |
| NETCoreRuntime | The type of .NET Core runtime to use (e.g. regular .NET Core, ASP.NET Core, or, on Windows, Windows Desktop). | ||
| NETCoreRuntimeVersion | The version of the .NET Core runtime to build for. If not set, the project will build for the latest supported runtime that is installed at build time. | ||
| NETCoreSDK | Typically inferred from the NETCoreRuntime setting, this can override the type of .NET Core SDK to use (e.g. regular .NET Core, ASP.NET Core, or, on Windows, Windows Desktop.) |
||
| NETCoreSDKVersion | Typically inferred from the NETCoreRuntimeVersion setting, this can override the SDK version to be used. |
||
| NETRuntimeVersion | The version of the .NET Framework (not Core) runtime to build for. | ||
| OuputType | The type of executable to generate, e.g. Executable, Library, or the like. |
||
| ProjectGuid | Read-only, the unique ID for the project, used for project references and inter-project dependencies. | ||
| SimulatorArchictures | The CPU architecture or architectures (as semicolon-separated list) to build for when targeting the Simulator, or "all" to build all supported architectures. |
iOS, tvOS, watchOS | |
| SupportMacCatalyst | For iOS projects, specifies whether the project should build to also run on macOS via Mac Catalyst. | iOS | |
| TargetFramework | Specifies the type and minumum version of the .NET runtime to build against. If no version is specified, the most approriate version will be determined at build time. | .NET | |
| SDK | Specifies the name and version of the platform SDK to build against. If no version is specified, the most approriate version will be determined at build time. | Cocoa, Android, Island |
Legacy Settings
| Name | Description | Platforms | IDE |
|---|---|---|---|
| TargetFrameworkVersion | Superseded by TargetFramework. | .NET |
Code Signing Settings (Cocoa)
The Code Signing Settings for Cocoa control whether and how executables or .app bundles will be signed for deployment. Code signing is needed for deployment to iOS devices and Mac App Store apps, and is recommended for all Mac apps. See Code Signing for more details.
| Name | Description | Platforms |
|---|---|---|
| Codesign Certificate Name | The optional name or fingerprint of a certificate that should be used to sign the app. macOS apps will only be signed if a certificate is set, while the other Cocoa platforms require signing and will try to find a default certificate to use, when one is specified. | Cocoa |
| Codesign Options | Additional options to be passed to the codesign command. |
Cocoa |
| EntitlementsFile | An (optional) .entitlements file to be used when signing the app. When using a Provisioning Profile, data from this file may be combined with entitlements provided by the profile. |
Cocoa |
| MacCatalystCodesignCertificateName | For Mac Catalyst, a separate certificate to (optionally) use to sign the app. | Mac Catalyst |
| MacCatalystEntitlementsFile | For Mac Catalyst, a separate .entitlements file can be provided to be used for macOS, since macOS and iOS might require different entitlements. |
Mac Catalyst |
| HardenedRuntime | If enabled, the binary will be signed to run on the more stricter Hardened Runtime on macOS 10.14 and later. Read more here. | macOS |
| Keychain | Optionally, the path and filename of a non-default Keychain to be used to look for certificates. If not set, the default keychain for the current user will be used. | Cocoa |
| KeychainPassword | Optionally, the password for the keychain, so that builds can access it even when the keychain is locked (locally, or when building over SSH via CrossBox). | Cocoa |
| ProvisioningProfile | The ID of the provisioning profile to be used for signing | iOS, tvOS, watchOS |
| ProvisioningProfileName | The name of the provisioning profile set for the above setting. Name and ID will be kept in sync when changing the setting in the IDE, and the name will be used as a fallback to locate the right profile, if it can't be found by ID. | iOS, tvOS, watchOS |
| Team | The ID if the development team registered with Apple for this project (used to filter the values made available for other settings to avoid clutter for developers who are part of multiple teams). | Cocoa |
Packaging & Deployment Settings (Cocoa)
The Packaging Settings for Cocoa control whether and how an .app bundle will be created with the compiled executable.
| Name | Description | Platforms |
|---|---|---|
| ApplicationIcon | The .icns file to be used as the application icon for the macOS app bundles. |
macOS, Mac Catalyst |
| BundleExtension | The file extension for the created bundle (i.e. ".app", for an application, or ".framework" for a framework. |
Cocoa |
| BundleIdentifier | The unique identifier for the project, in reverse dotted domain notation. This will be injected into the final Info.plist file, and also used in other parts of the build, such as for provisioning. |
Cocoa |
| BundleIdentifier for Mac Catalyst | A separate identifier to be used for the Mac Catalyst build of an iOS app. | Mac Catalyst |
| BundlePackageType | The four-letter package type, e.g. "APPL" for an application. |
Cocoa |
| Bundle Version | The three-part dotted version number for the app, to be injected into the final Info.plist file during build. |
Cocoa |
| CreateAppBundle | If enabled, an .app bundle will be created for the project, rather than just an executable binary. Most settings in this category only have an effect if this or the next option is on. |
Cocoa |
| CreateFrameworkBundle | If enabled, a .framework bundle will be created for the dynamic library project, rather than just an .dylib. |
Cocoa |
| CreateIPA | If enabled, an .ipa file is created, conaining the app bundle and additional files and ready for upload to the Apple App Store. |
iOS, tvOS |
| InfoPListFile | The name of the base .plist file to be used as the Info.plist for the bundle. The build will use the data from this file and extend and update it as needed to generate the final Info.plist that will be bundled. |
Cocoa |
Code Signing Settings (Java and Android)
The Code Signing Settings for Java and Android control whether and how .jar and .apk files will be signed for deployment.
| Name | Description | Platforms | IDE |
|---|---|---|---|
| JavaDigestAlgorithm | Java, Android | ||
| JavaKeyPassword | Java, Android | ||
| JavaKeyStore | Java, Android | ||
| JavaKeyStorePassword | Java, Android | ||
| JavaKeyStoreType | Java, Android | ||
| JavaSign | Java, Android | ||
| JavaSignatureAlgorithm | Java, Android | ||
| JavaSignignAlias | Java, Android | ||
| JavaTimeServer | Java, Android |
Packaging & Deployment Settings (Android)
The Packaging Settings for Android control whether and how the .apk package will be created from the compiled Java executable.
| Name | Description | Platforms | IDE |
|---|---|---|---|
| AndroidArchiveName | (Android | ||
| AndroidAssetsFolder | (Android | ||
| AndroidDexMode | |||
| AndroidJavaResourcesFolder | (Android | ||
| AndroidMainDexListFile | |||
| AndroidNativeLibrariesFolder | (Android | ||
| AndroidPackageName | (Android | ||
| AndroidPackMultidex | |||
| AndroidResourcesFolder | (Android | ||
| UseAAPT2 | |||
| UseD8 |
Code Signing Settings (.NET)
The Code Signing Settings for .NET
| Name | Description | Platforms | IDE |
|---|---|---|---|
| AssemblyKeyFile | .NET | ||
| AssemblyKeyName | .NET | ||
| AssemblyDelaySign | .NET | ||
| AssemblyVersion | .NET | ||
| AssemblyFileVersion | .NET |
Packaging & Deployment Settings (.NET Core)
Settings involving packaging and Deployment for .NET Core
| Name | Description | Platforms | IDE |
|---|---|---|---|
| Publish | .NET Core | ||
| SpaRoot | ASP.NET Core |
Build Settings
The Build Settings control basic compiler behavior and options.
| Name | Description | Platforms |
|---|---|---|
| AllowUnsafeCode | Off by default, this setting enables the use of "unsafe" Code such as Pointers. It is necessary only on the .NET platform. Cocoa and Island projects always allow pointer support, and unsafe code is not available at all on the Java and Android SDK platforms. | .NET |
| AllowUnsafeCodeImplicitly | Off by default, this setting enables the use of "unsafe" Code such as Pointers on the .NET platform, and drops the requirement to explicitly mark each method (or, in C#, type) that contains such code with the unsafe keyword. |
.NET |
| CheckForOverflowUnderflow | Off by default, this setting enables checks for integer under-flow and overflow. When set, integer operations that would exceed the range of values that can be held by the type will cause a runtime Exception. Also available on a file-by-file basis via the {$Q+/-} or {$OVERFLOW ON/OFF/DEFAULT} Compiler Directives in Oxygene. |
|
| CheckWhitespace | Off by default, this setting enables the compiler to emit warnings when the indentation of begin/end or {/} pairs does not match. This can be helpful for maintaining well-formatted code, and can also help narrow down "mismatched begin/end or {/}" errors in complex code. |
|
| CompilerFlags | Cocoa, Island | |
| ConditionalDefines | A ;-separated list of custom conditional defines. See Conditional Defines and Conditional Compilation for more details. |
|
| CreateFXFile | If enabled (the default for library projects on Cocoa and Island), an .fx file with additional compiler metadata for the binary will be emitted. |
|
| CreateHeaderFile | If enabled (the default for library projects on Cocoa and Island), a C-compatible .h header file will be emitted to allow the library to be used from C/C++/Objective-C and other compilers that are capable of importing C headers. |
Cocoa, Island |
| CrossPlatform | Enables enhanced cross-platform compatibility in the languages. Also available on a file-by-file basis via the {$CROSSPLATFORM ON/OFF/DEFAULT} (Oxygene) or #pragma crossplatform on/off/default (C#, Swift and Java) Compiler Directives. |
|
| DefaultObjectModel | Island/Darwin only, this option controls the default object model used for classes and interfaces defined without explicit ancestor. The default is "Island", and other valid values include "Cocoa" and "Swift". See Object Models for more details. |
Island/Darwin |
| DefaultUses | A list of namespaces, separated by ;, that will be considered "in scope" for every file in the project, as if they had been specified in a uses/using/import/Import statement. |
|
| DeploymentTargetVersionHints | If enabled the compiler will emit hints and warnings when using APIs that are ot available on all deployment targets. the available() can be used to conditionally execute code only on newer OS versions. |
Cocoa, Android |
| EmitTailCalls | Off by default, this setting enables the compiler to emit optimized recursive calls via a technology called Tail Calls. Also available on a file-by-file basis via the * {$TAILCALLS ON/OFF/DEFAULT} Compiler Directives in Oxygene |
.NET |
| EnableInlining | On by default, this setting enables the compiler to inline methods marked as inline (Oxygene), __inline (C#) or @inline (Swift). |
|
| ExportAllTypes | ||
| FutureHelperClassName | ||
| GenerateBitcode | Emits Bitcode in addition to CPU-native code. The setting might be required when submitting to the Apple App Store for tvOS and watchOS. | Cocoa |
| GenerateIRFile | Enables the generation of intermediate .ll files that contain LLVM IR code as plain text; mainly for diagnostics purposes. |
Cocoa, Island |
| Incremental | Improves the speed of subsequent builds by only updating the .o files affected by changes to the project, rather than compiling the entire project each time. |
Cocoa, Island |
| LinkerOptions | Additional custom command line options to pass to the ld or lld linker executable. |
Cocoa, Island |
| LinkerRPaths | Cocoa | |
| MangleTypeNames | Cocoa | |
| Optimize | On by default, this setting makes the compiler optimize code for size and performance, sacrificing debuggability and readability of the final binary. Optimize can be set to True (the default) or False. On Island, it can also be set to a numerical value between 0 and 3, for more fine-grained control. |
|
| OutputPath | The base output path, absolute or relative to the folder containing the project file, where to place the output generated by the project. Note: when passed via the command line to EBuild.exe as --out, a relative path will be treated as relative to the current folder. |
|
| OutputPathUsesModes | If enabled, the Mode of the current project or Target will be appended to the OutputPath as subfolder. This is useful in multi-target projects to keep the output for different platforms apart. |
|
| OutputPathUsesSubModes | If enabled, the SUbMode of the current project or Target will be appended to the OutputPath as subfolder. This is useful in multi-target projects to keep the output for different platforms apart. |
|
| OutputPathUsesTargets | If enabled, the name fo the current Target will be appended to the OutputPath as subfolder. This is useful in multi-target projects to keep the output for different platforms apart. |
|
| Prefer32Bits | If enabled, marks a .NET binary to run as 32-bit rather than 64-bit, even when the latter is available at runtime. This can be useful, for example, if the .NET process is expected to load unmanaged .dlls that are available only as 32-bit. |
.NET |
| RequireExplicitLocalInitialization | Oxygene only, enabling this forces the compiler to require all locals to be initialized explicitly. (By default, Oxygene initializes all locals to the equivalent of 0/nil.) |
|
| RootNamespace | The root namespace for the project that all Swift, Go and Mercury source files will place their content in, unless otherwise specified. Also the default namespace generated in new Oxygene, C# and Java files added to the project. | |
| StartupClass | Specifies a class that will provide the static Main() entry-point for an executable project. This is only required if there otherwise is ambiguity. |
|
| StripBitcode | Remove the native CPU instructions from a binary compiled with Bitcode, leaving only the Bitcode. Projects built with this setting cannot be run, but the setting is required when submitting Bitcode to the Apple App Store. | Cocoa |
| SuppressedWarnings | A list of warning codes, separated by , or ;, that will be ignored by the compiler and not emit any messages. |
|
| TreatFixableErrorsAsWarnings | Off by default (except when compiling from the IDE), this setting causes the compiler to "ignore" errors that have a trivial fix (such as a misspelled identifier or a missing semicolon), and report them as warnings instead. If a project compiles without any other non-fixable errors, the compile will succeed as it would if the trivial fixes had been applied. Note that this setting will not actually fix or touch the code (although the IDEs support an Auto-Fix feature for certain errors that can be turned on separately from this compiler option). |
|
| TreatWarningsAsErrors | Off by default, this setting will instruct the compiler to fail compilation if any warnings are encountered during the compile phase, even if there were no errors. This setting is helpful to enforce a "zero warnings" code policy. Note that this does not affect hints and warnings generated during other parts of the build. | |
| UseLegacyToffeeMode | Enabled by default; if disabled, a project with a mode of Toffee/Compiler/BackEnds/Toffee will use the newer Island/Darwin compiler back-end, but with provisionings to make it more compatible with classic Toffee mode. See here for more details. | Cocoa (Toffee) |
| VBOptionStrict | For Mercury, setting this option to False makes the compiler less strict for enforcing types, as documented here |
|
| VerifyBitcode | Runs an extra phase to verify the generated Bitcode. | Cocoa |
| WarnOnCaseMismatch | Even though Oxygene and Mercury are case sensitive, with this option enabled (the default), the compiler will emit warnings when the case of an identifier does not match the case it was declared with. | |
| WarnOnDynamic | Off by default, this setting causes the compiler to emit a warning when inadvertently calling members of a dynamic type. This can be helpful when converting code to be more strongly typed, especially on Cocoa, where the use of id is very common, but can lead to subtle unexpected side effects. |
|
| WarnOnImplicitNotNullableCast | Off by default, this setting instructs the compiler to emit a warning when potential null values are passed to values marked as expecting non-null values only. See Nullability for more details. | |
| WarnOnMissingExceptionAnnotations | Off by default, this setting instructs the compiler to emit a warning when methods are missing Throws Definitions on the Java platform. | Java, Android SDK |
Delphi Compatibility Build Settings (Oxygene Language Only)
The Compatibility Settings for Oxygene are provided to make the language more compatible with legacy Pascal code imported from or shared with Delphi or other legacy Pascal language implementations. We recommend keeping these settings off (the default) for new projects.
| Name | Description |
|---|---|
| AllowLegacyCreate | Allow legacy Delphi .Create syntax for constructors. |
| AllowLegacyOutParams | Allow calling methods with= out and var parameters without specifying the appropriate parametrer modifier. |
| AllowLegacyWith | Allow Delphi's unsafe legacy with syntax. |
| AllowLegacyEnums | Allow enums declared in the current project to be accessed unscoped, without prefixing the enum's type name. |
| DefaultGlobalsToPublic | Make all globals public (instead of assembly/internal by default. |
| DelphiCompatibility | Turn on a range of Delphi Compatibility syntaxes for improved code compatibility. Also available via the {$DELPHI ON/OFF/DEFAULT} Compiler Directive. |
| DelphiDivide | Turns on Delphi-style behavior of the div and / operators. |
Note: the DelphiCompatibility is a master switch and (in addition to a wide range of compatibility), enabled the AllowLegacy* and DelphiDivide options implicitly, when turned on.
Debug Settings
The Debug Settings control whether and how the application will be built with the ability to be debugged.
| Name | Description | Platforms | IDE |
|---|---|---|---|
| AndroidAllowDebugging | Determnines whether an Android application is marked as allowing debugging or not. By default, this is tied to the presence of Debug Symbols via the GenerateDebugInfo setting, but changing this setting explicitly allows to override that behavior – for example to ship debug symbols to the Play Store, even though the store requires this option not be False. |
Android SDK | |
| AssertMethodName | |||
| DebugClass | |||
| EnableAsserts | Off by default, this setting enables Assertions, via Class Contracts or the assert() System Function. When turned on, Asserts raise an error and break execution flow. When off, Asserts and Class Contracts will not be compiled into the final code. |
||
| GenerateDebugInfo | Turns on the generation of debug information. | ||
| GenerateDSym | Extracts debug symbols from the binary into a separate .dSYM bundle. |
Cocoa | |
| GenerateMDB | Turns on the generation of Mono .mdb information. |
Mono and .NET, except for .NET Core | |
| GeneratePDB | Turns on the generation of .NET .pdb debug information. |
.NET, .NET Core | Water, |
| PDBType | .NET, .NET Core |
Run Settings
The Run Settings control how your application is executed when running from the IDE. Currently, some these settings are used by Fire and Water only, as Visual Studio has different mechanisms for configuring these on a Solution level.
| Name | Description | Platforms | IDE |
|---|---|---|---|
| AndroidDebugActivity | The name of the activity to launch when running an Android app in the debugger. If not set, the name of the Main Activity will be determined from the manifest. | Android SDK | Fire |
| DebugArchitecture | Can be used to select/override a specific architecture for debugging p[Island](/Compiler/BackEnds/Island projects. | ||
| DebugEngine | Which debug engine to use for debugging (e.g. CLR vs Mono for .NET projects on Windows, or pure-Java vs Mixed Mode Debugging for Android. | Cocoa, Island, Android SDK, .NET on Windows. | |
| DebugHost | Name and path of an executable to launch instead of the binary built by the current project – for example to debug Library projects hosted inside a third party app. |
||
| DebugHostActivity | The name of the activity inside the package specified by DebugHostPackageName to launch. See Android Debug Hosts. |
Android SDK | |
| DebugHostAPK | The local path to an existing Android .apk to install and launch when debugging, instead of the binary created by the current project. See Android Debug Hosts. |
Android SDK | |
| DebugHostPackageName | The package name/ID of an existing Android app to launch when debugging, instead of the binary created by the current project. This can be the name of an app already installed, or the name of the .apk specified for the DebugHostAPK setting. See Android Debug Hosts. |
Android SDK | |
| DebugIgnorePersistentState | Sets a macOS app to launch without reopening the previous state. This is done by adding -ApplePersistenceIgnoreState YES to the command line arguments. |
macOS | Fire, Water |
| DebugIndexHtmlFile | WebAssembly/Web | ||
| DebugNodeEntryPoint | WebAssembly/Node.js | ||
| DebugRootFolder | WebAssembly | ||
| DebugUrl | WebAssembly/Web | ||
| DebugWorkingDiretcory | |||
| DebugZombieEnabled | Sets a Cocoa app to launch in zombie mode, to assist with debugging memory allocation issues. This is done by adding NSZombieEnabled=YES to the environment variables. |
macOS | Fire, Water |
| EnableUnmanagedDebugging | Runs the project using Visual Studio's unmanaged/native debugger (for C++ & Co) in addition to the .NET debugger. | .NET | |
| GenerateLLDBDebuggerSupport | Generates support for Mixed Mode Debugging of an Android NDK extension within an Android SDK app. | Android NDK. | |
| TestProject | Specifies an alternate EUnit test project in the current solution to be run instead of the project's binary, when Testing via ⌘T/Ctrl+T. | Fire, Water | |
| TestTarget | Specifies an alternate Target within the above test project to be run instead of the project's binary when Testing. | Fire, Water |
Note: Debug Arguments and Environment Variables are no longer stored as project settings, to allow more flexible management.
Documentation Settings
The Documentation Settings control whether and how XMLDoc documentation files will be generated from comments found in source code. XMLDOc comments start with three forward slashes, /// (or three single quotes in Mercury, '''), and can contain either XML or a plain text description.
| Name | Description |
|---|---|
| XmlDoc | Enables the processing of XMLDoc comments and the generation of .xml documentation files next to the compiler output. |
| XmlDocWarningLevel | Determines the level of warnings for code without matching documentation tags. |
| XmlDocAllMembers |
Settings for Import Projects (Cocoa and Island)
| Name | Description | Platforms | IDE |
|---|---|---|---|
| Mode | |||
| SubMode | |||
| SDK | |||
| Project GUID | |||
| Binary Name | |||
| RootNamespace | |||
| ConditionalDefines | |||
| OutputType | Read-Only, must be Import |
||
| Header Search Paths | |||
| Link Names | |||
| Namespace Override | |||
| Force Includes | |||
| Black-listed Headers | |||
| CodeGen | |||
| SDK | |||
| Architecture | |||
| SimulatorArchitecture | |||
| MacCatalyst |
Website (ASP.NET, Fire only)
| Name | Description | Platforms | IDE |
|---|---|---|---|
| UsePublishing | Enables publishing of changed files on ⌘S for ASP.NET web site projects, via FTPS. | .NET | Fire |
| PublishingServer | FTPS/SSH server to connect to. | .NET | Fire |
| PublishingUser | SSH user to connect as (key required). | .NET | Fire |
| PublishingFolder | Remote folder to publish to. | .NET | Fire |
"Undocumented" and Unexposed Settings
The following settings are provided for legacy support and are not recommended to be used. They are not exposed in the IDEs, but can of course be set in the .elements project file, manually. Rely on these options at your own risk, as they are subject to change without warning.
| Name | Description |
|---|---|
| NoGo | Do not let # references or other logic add an implied Go Base Library reference. |
| NoMercury | Do not let # references or other logic add an implied Mercury Base Library reference. |
| NoSwift | Do not let # references or other logic add an implied Swift Base Library reference. |
| UseLegacyPreprocessor | Turns on the legacy Elements 9 and earlier macro preprocessor for {$IF and #if processing. This bypasses the more modern Conditional Compilation engine and disables certain advanced features such as using defined(). It is only recommended for legacy projects. Since enabling this option is highly discouraged, this option is not available from the IDEs and needs to be set manually in the .elements project file. |