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). .NET Core
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. .NET Core
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.) .NET Core
NETCoreSDKVersion Typically inferred from the NETCoreRuntimeVersion setting, this can override the SDK version to be used. .NET Core  
NETRuntimeVersion The version of the .NET Framework (not Core) runtime to build for. .NET
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, Visual Studio
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
Debug Engine 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 Visual Studio
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.

See Also