EBuild supports a range of command-line switches you can use to control the build, and also defines a number of build settings that make sense to override from the command-line, as well.
In general, the EBuild command-line expects a single file name parameter (which can be a
.elements project file), as well as zero or more switches (which always start with
--. Running EBuild without a file name parameter, or passing the
--help switch, will show a summary of all available commands, and exit with a positive exit code.
EBuild can run one of three actions on the project (or solution), determined by one of the following three command-line switches being passed.
--build– incrementally build the project
--rebuild– rebuild the project from scratch, ignoring all cached output from previous builds
--clean– delete all output from previous builds, including intermediate files and final binaries
If none of the three switches is passed,
--build is implied.
EBuild will exit with a 0 exit code if it successfully performed the action, or with a positive code if any errors or problems occurred.
Projects can have one or more named configurations, usually called "
Debug" and "
--configuration switch can be passed to decide which configuration will be built; if not passed, "
Release" is assumed:
Choosing which Projects to Build
When building a
.sln with multiple projects, it is often desirable to only have a subset of the contained projects built. EBuild provides switches to specify one or more explicit projects (plus their dependencies) to build, or to exclude one or more projects from the build (even if they are dependencies of a different, not included project):
--projects:<list of project ids or names>
--skip-projects:<list of project ids or names>
Each switch can be followed by a semicolon-separated list of one or more project IDs (GUID) or project names (as specified in the project's
<Name> setting or, when not set, the project's filename without extension.
--projects, EBuild will process the project or projects listed, as well as any other projects that the listed projects depend on.
--skip-projects, EBuild will process all projects in the solution, except those listed. If other projects depend on one or more listed projects, EBuild will try and resolve this dependency based on output from previous builds, but it will not, under any circumstances build the listed projects.
--skip-projects switch is used by Fire and Water to exclude disabled projects from being build.
Choosing which Targets to Build
If you are working with multi-target projects, you can similarly specify a list of targets to build, or to exclude from the build:
--targets:<list of target names>
--skip-targets:<list of target names>
Each switch can be followed by a semicolon-separated list of target names.
--targets, only targets matching one of the names will be built. For projects with no target matching the name, no action will occur.
--skip-targets, only targets not matching any of the names will be built. For projects with no target matching the name, no action will occur.
--skip-targets switch is used by Fire and Water to exclude disabled targets from being build.
Another option to limit what to build is to specify a single project (and, optionally, a single target in that project) as a build goal.
In this mode, EBuild will build the specified project (either all of it's targets, or the one specified), and and projects it depends on. It will not build any projects that aren't necessary for the build goal.
EBuild will still honor the
--skip-targets switches, allowing you to further narrow down the scope of what gets build. Even if a project is set to be skipped, it will still be looked at for dependencies, and its dependencies will still be included in the build. This allows you to selectively skip projects anywhere on the dependency chain (including even the goal project, itself).
This switch is used by Fire and Water when executing a Run, Deploy or Test command, to build ony the and its (enabled) dependencies. It is not used when doing a Build or Rebuild, those commands will always build all enabled projects.
By default, projects generate their final output to the folder specified by the
<OutputPath> project setting, which can be absolute, or relative to the project (and, if not specified, defaults to
You can override this target folder with the
--output-folder switch, which takes a path that can be absolute or relative to the current working directory (!!).
Optionally, you can also have the output folder appended by either the target name, and/or the name of the Mode or SubMode. This applies regardless of whether the base output folder was overridden from the command-line with the previously discussed switch, or is taken from the project.
This is particularly useful when building multiple projects or targets that would otherwise generate similarly-named output that would overwrite each other:
--output-folder-uses-submode-name or rather, the
OutputPathUsesSubModes setting that this switch affects, already defaults to
True for Cocoa and for Island projects.
Finally, you can also override the folder where EBuild will place and look for intermediate files and cache files generated as part of the build, using the
You can enable Parallel Builds in order to build multi-project or multi-target solutions more quickly on multi-code systems, with the
Overriding Arbitrary Project Settings
You can use the
--setting switch to override any setting used by the build chain, including all the known and documented project settings normally stored inside the project. This includes settings that go into the compiler, as well as those handled by other parts of the build chain.
--setting switch can of course be repeated as many times as needed, to override multiple settings. If the same setting name is provided more than once, the last occurence "wins".
Commonly used Settings
Most settings that are core to the project will be set in the project file, and make very little sense to override from the command-line. For example, little good will come out of changing the
Mode of a project for a build.
But there are a handful settings that are common and useful to set from the command-line and from build scripts:
--setting:AdditionalReferencePaths=<list of folders> – a semicolon-separated list of additional folders where to look for references. This can be helpful e.g. if you run EBuild multiple times on different solutions, and want to to see files generated by earlier runs.
False– make the build fail, if any non-fatal warnings are encountered.
--setting:CrossBox=<Name of your CrossBox Server> – pass a different CrossBox 2 Server to be used for the build of Cocoa projects.
False– toggle whether to build an iOS, tvOS or watchOS project for device, or not (default is
False– toggle whether to build an iOS, tvOS or watchOS project for Simulator, or not (default is
Note that you can pass both
--setting:Simulator=True to have both versions built in one go.
--setting:ToffeeSDKFolder=<folder> – pass an optional path to the Cocoa base SDK files, to use instead of the default.
--setting:IslandSDKFolder=<folder> – pass an optional path to the Island base SDK files, to use instead of the default.
Cocoa and Island
--setting:Architecture=<list of architectures> – – a semicolon-separated list of architectures to build. You can also pass
All, to build all architectures known for the platform and be future-proof.
Debug– control how chatty EBuild is as it does its work.
Normalis the default, and should be fine in most scenarios.
Debugwill enable additional levels of detail (but also clutter).
--statistics– emit statictics about which build phases took the longest times, at the end of the build.
--no-cache– ignore any cached info from previous builds (implied when doing a
--no-package-cache– ignore any information in the local Gradle or NuGet Package References caches and re-resolve and re-download all packages (also implied when doing a
--debug– emit even more diagnostic messages as part of the build, useful for debugging un-obvious build proplems or problems with EBuild itself. Implies
--debug-caching– emit additional debug logging for cache resolving issues.
--debug-smart-copy– emit additional debug logging for incremental/smart copy.
Fire– choose the layout of the console output.
Consoleis the default and meant for human-readability;
Fireadds additional machine-parsable output and is what is used by the Fire and Water IDEs to parse the output.
--xml:<filename> – emit an XML file with error messages, fix-its and other details about the build.
--help– emit a list of all available switches.
--wait– wait for a press of the Enter key after the build finishes.