Building Projects w/ EBuild
EBuild can build both individual Elements projects (
.elements), as well as Visual Studio-style Solution files (
.sln) as used by Elements both in Visual Studio and also in Fire and Water.
Builds can be done both from the command-line, from within the IDEs and hosted in MSBuild.
Building from the Command-Line
EBuild executable is installed as part of the Elements setup (Windows) or installing the External Compiler from the Command-Line Zip Distro (Mac, Linux and Windows). See the Installing the Command-Line Compiler topic for more details.
You can confirm that everything is installed correctly by opening a Terminal or Command Prompt window and simply typing
ebuild and pressing enter – which will show the EBuild command-line help and also tell you which version is installed, e.g.:
RemObjects EBuild. An open source build engine for Elements and beyond. Copyright RemObjects Software 2016-2018. All Rights Reserved. Version 10.0.0.2262 (develop) built on talax, 20180306-124819. Commit 53408a6. Syntax: ebuild [project or solution file] <switches>
To build a project or a solution with multiple projects, in most cases you can simply pass the project or solution filename as only parameter, and EBuild will go off and build.
Additional Command-Line Switches can be provided to control the build process, including limiting the set of projects in a solution that will be built, changing build log verbosity, overriding project settings, or more.
By default, EBuild will build the configuration named "
Release", if present, or the first configuration found, otherwise. You can override this by passing the
ebuild MyProject.elements --cofiguration:Debug
Also by default, EBuild will perform an incremental
build that only performs those tasks that need performing, based on what files in our project have changed and what tasks ran before. You can optionally pass
--rebuild to have EBuild start fresh and build all parts of your project from scratch. Or you can pass
--clean to "undo" a build and have EBuild remove all cached information and all output files files generated by a previous build. (Rebuild actually performs a clean, followed by a Build.)
ebuild MyProject.elements --rebuild
Building from the Fire and Water
Both Fire and Water use EBuild as the default build chain, as of early 2018. That means whenever you do Build (⌘B or Ctrl+B) or a related task in the IDE, you are already using EBuild to build, rebuild or clean the project.
By the way: As first line of the Build Log (which you can bring up by pressing ⌘⌥B in Fire or Ctrl+Alt+B in Water), you can see the full command-line with which the IDE is invoking EBuild. You can copy/paste that into a Terminal window or a build script, if needed, or just look at it to see what options the IDE might be passing.
Fire and Water also use EBuild within the IDE to resolve the references in your project. You can select the "References" node in your project tree to see the log file from this process – which can be helpful for diagnosing problems or broken references.
Should you ever need to, Fire and Water allow you to switch back to using MSBuild (Windows) or xbuild (Mac) instead of EBuild, by checking the "Use legacy build toolchain" option in Preferences. But this should rarely be necessary, and do note that the legacy MSBuild-based build tasks are no longer being maintained and will grow old with time, as the platforms evolve.
Building from Visual Studio
Visual Studio will automatically use EBuild (hosted in MSBuild, as described in the Building with EBuild within MSBuild section, below) when building Cooper, Toffee, Island and standard .NET projects.
For some .NET sub-platforms, such as Silverlight, WInRT and UWP, using EBuild is still opt-in: the project can be "Converted to EBuild" by right-clicking the project node in Solution explorer and choosing "Converted to EBuild". After conversion, these projects too will be built with EBuild hosted in MSBuild.
Building with Train
Train, our free open source build script tool has built-in support for running EBuild via the
ebuild.runEBuild() task. The method takes two parameters, the name of a project or solution, and an optional string with command line parameters.
runEBuild() will automatically locate the installed version of Elements and EBuild.
Building with EBuild within MSBuild
EBuild comes with a special MSBuild task that allows you to use EBuild within the MSBuild build chain to build projects. This can be useful if you have mixed solutions that include non-Elements projects EBuild cannot process, or have a larger build infrastructure structured around MSBuild.
To do this, simply make sure that your project uses the new, EBuild-specific
<Import> target called
RemObjects.Elements.targets (i.e. one that does not include a platform name, such as
Echoes.Legacy), and that your project has its
<Mode> set explicitly. Please refer to this topic for mode details.
If your project is set up this way, simply passing a solution that contains it to MSBuild (or xbuild) will work. The bulk of your solution will be build in MSBuild as you'd expect, and MSBuild will automatically host EBuild to build the Elements project(s) in question.
Note that when built within Visual Studio and/or MSBuild, .NET projects containing legacy
<Imports> with .targets files that include the platform name ("Echoes") will, for now, continue to build using the old MSBuild-based tasks (which are no longer being maintained and will grow old with time, as the platforms evolve). Cooper, Toffee and Island projects already always use the new EBuild-based tasks.