Command-Line Switches

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 .sln or .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.

Build Action

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.

Configurations

Projects can have one or more named configurations, usually called "Debug" and "Release". The --configuration switch can be passed to decide which configuration will be built; if not passed, "Release" is assumed:

  • --configuration:Debug

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.

When specifying --projects, EBuild will process the project or projects listed, as well as any other projects that the listed projects depend on.

When specifying --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.

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.

When specifying --targets, only targets matching one of the names will be built. For projects with no target matching the name, no action will occur.

When specifying --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.

Output Folders

By default, projects generate their final output to the folder specified by the <OutputFolder> or <OutputPath> project setting, which can be absolute, or relative to the project (and, if not specified, defaults to ./Bin/<Configuration>).

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 (!!).

  • --output-folder:<folder>
  • --out:<folder>

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-target-name
  • --output-folder-uses-mode-name
  • --output-folder-uses-submode-name

Note that --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 --intermediatebasefolder switch.

  • --intermediatebasefolder:<folder>

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:<Name>=<Value>

The --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:

General

  • --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.
  • --setting:TreatWarningsAsErrors=True/False – make the build fail, if any non-fatal warnings are encountered.

Cocoa:

  • --setting:CrossBox=<Name of your CrossBox Server> – pass a different CrossBox 2 Server to be used for the build of Cocoa projects.
  • --setting:Device=True/False – toggle whether to build an iOS, tvOS or watchOS project for device, or not (default is True).
  • --setting:Simulator=True/False – toggle whether to build an iOS, tvOS or watchOS project for Simulator, or not (default is True).

Note that you can pass both --setting:Device=True and --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.

Island

  • --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.

Other Switches

  • --verbosity:Silent/Quiet/Normal/Verbose/Debug – control how chatty EBuild is as it does its work. Normal is the default, and should be fine in most scenarios. Verbose or Debug will 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.

Caching

  • --no-cache – ignore any cached info from previous builds (implied when doing a --rebuild)
  • --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 --rebuild)

Debugging

  • --debug – emit even more diagnostic messages as part of the build, useful for debugging un-obvious build proplems or problems with EBuild itself. Implies --verbosity:Debug
  • --debug-caching – emit additional debug logging for cache resolving issues.
  • --debug-smart-copy – emit additional debug logging for incremental/smart copy.

IDE

  • --logger:Console/Fire – choose the layout of the console output. Console is the default and meant for human-readability; Fire adds 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

  • --help – emit a list of all available switches.
  • --wait – wait for a press of the Enter key after the build finishes.