Skip to content

Building with msbuild or xbuild

Jump to bottom
Tom Bogle edited this page Dec 11, 2020 · 28 revisions

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 (to target x86)
OR
build64 /t:remakefw (to target x64)

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

build /t:mkall (to target x86)
OR
build64 /t:mkall (to target x64)

(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

Building Dependencies

See https://github.com/sillsdev/FwDocumentation/wiki/Dependencies-on-Other-Repos#building-dependencies-locally

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 mkall or remakefw targets, so under Tools -> Options -> General (tab) -> User Interface your normal build process will include only English. Further documentation is at https://docs.google.com/document/d/1Xt3mAyU-42QfunzkSJgePIP9brHFVv5pmcmiCT-zQ6A. To build localizations locally:

One-Time Setup

  • Install .NET Core 2.1 (required for Overcrowdin)
    • If you have never installed a dotnet tool, run dotnet tool install -g overcrowdin and restart your terminal to refresh your PATH
  • Ask a senior developer to help you set the CROWDIN_API_KEY environment variable
  • In C:\fwrepo or ~/fwrepo, run: 
    fwmeta/initrepo -m    # (make sure you include the FwLocalizations project)
git clone git@github.com:sillsdev/liblcm.git
    Note: the FwLocalizations repository is no longer needed starting in FieldWorks 9.0.8.
  • Make sure that fwrepo/fw/Build/LibraryDevelopment.properties includes the property LcmLocalArtifactsDir (build /t:UpdateDevelopmentPropertiesFile or your favorite text editor).

Building Localizations

This will copy the localization files into several places for each language (where ?? = es, fr, etc.):

  • strings-??.xml files under DistFiles/Language Explorer/Configuration
  • LocalizedLists-??.zip files under DistFiles/Templates
  • A folder with resource files under Output/??

Building Installers

One-Time Setup

  • Complete setup for Building Localizations
  • Rerun fwmeta/initrepo -m, including at least FieldWorks FwHelps FwLocalizatiotns PatchableInstaller
  • Install the WiX Toolset (3.11), including the Visual Studio Extension

Building Installers

  • To build a base installer, run build /p:config=release /t:BuildBaseInstaller
  • To build a patch installer, run build /p:config=release /t:BuildPatchInstaller /p:BuildVersionSegment=2 (you will need to increment the BuildVersionSegment each time you build, if you plan to install your patches in sequence)
Clone this wiki locally