Building with msbuild or xbuild

Building Everything

The basic process to build the entire FieldWorks system (everything a developer needs to run FieldWorks; all that is omitted is installers and localizations) is as follows:

cd c:\fwrepo\fw\Build
build /t:remakefw

If you don't want to discard everything and start from scratch, you can use

build /t:mkall

(default if no arguments are specified) to build everything that needs it, based on dependencies.

There are several additional command line arguments that may be helpful:

/property:action=test will run unit tests. At least for everything that is built, possibly more (todo: find out exactly). Look for a section in the output headed "NUnit Summary report:" to see whether all the tests passed.

/m causes the build to do as much as possible in parallel. I've once seen this fail, with different threads contending to write to the same file, but if it works it seems to work right. I thought it could speed things up significantly, but Alistair says nothing much is happening in parallel, and the speedup was probably just more stuff being cached.

/v:m reduces the "verbosity" of the output, suppressing the many warnings our build generates and other stuff...unfortunately including the report of elapsed time for the whole build. A major advantage is that the NUnit summary ends up at the end of the build report.

/ds is interesting to use with /m. It gives a detailed summary of how the different cores were applied to the build task. We can potentially use this to find bottlenecks and optimize the process to be able to use more cores more of the time. Instructions on interpreting it are at here. Gotcha: /v:m totally suppresses the output of /ds.

I've found it quite helpful to redirect the output of the build to a file (>foo.txt). Especially without /v:m, the output is so verbose it can exceed the 9999 line limit of a dos box. Unfortunately you then can't see the progress. To see the progress you can pipe the output to tee (there's also a Windows implementation of a similar tool):

build /t:remakefw /p:action=test | tee foo.txt

Release builds

To do a release build, add /property:config=release to the command line.

NOTE: On Linux be careful when you combine the properties into a single argument because the semicolon is interpreted as the start of a new command. You probably would have to use quotes around the argument. It's easier to set the properties using multiple arguments:

build /t:remakefw /p:action=test /p:config=release

Run Tests

Note: If you have Fieldworks already installed from an installer, some tests may fail on Windows if the FieldWorks Remote Database Connector Service is running. Stop this service first in the Windows Component Services.

build /t:mkall /p:action=test /v:m

Build parts

It is also possible to build just one or two projects (and their dependencies; we haven't found the equivalent of "-nodep" in MSBuild yet).

build /t:xworkstests /property:action=test /v:m

to build just the xWorksTests project and its dependencies and run the tests at minimal verbosity.

Then you'll probably want an NUnitReport to see how the tests went, since the test results are scattered through the build output. NUnitReport defaults to minimal verbosity.

nunitreport /a

will grab all the available nUnit output files and run the report, or alternatively you can do:

nunitreport {testproject}

in order to run a report just on one project's tests (e.g. nunitreport discoursetests), or:

nunitreport {testproject} /v:n
nunitreport {testproject} /v:d

for normal and detailed verbosity.

Building on Linux

On Linux you can replace build with ./build and basically follow the instructions above. A typical sequence to do a complete build would be:

cd Build
./build /t:remakefw /p:action=test

Note that you might want to run the tests in a xephyr window so that they you can keep working on other things. You can then start the build with:

DISPLAY=:2 AssertUiEnabled=false ./build /t:remakefw /p:action=test

Localization for Developers

Localizations are not built by default for Debug versions, so under Tools -> Options -> General (tab) -> User Interface your normal build process will only include English. From the main repo, in order to build the localization files do:

fwmeta/initrepo -m (make sure you include the FwLocalizations project)

cd fw/Build
build /t:localize    # on Linux: ./build /t:localize

This will copy the localization files into several places. On a developer machine, it will put various strings-??.xml files under DistFiles/Language Explorer/Configuration. Also, it will build a folder for each interface language with resource files under Output/??, where ?? = es, fr, etc.