Skip to content

Advanced Set up new FieldWorks development workstation

Jump to bottom
Hasso edited this page May 20, 2022 · 4 revisions

Note: These instructions show how to set up a machine to develop FieldWorks from scratch, and using the vagrants that you download and provision on your own machine. A newer, simpler process can be found at Set up new FieldWorks development workstation.

Instructions to set up a FieldWorks development workstation on Linux. For instructions to set up a Windows workstation or general FieldWorks developer information, visit our wiki on GitHub.

Table of Contents

Develop in a vagrant virtual machine

Instead of setting up a Linux FieldWorks development machine manually, you can provision a vagrant machine to do Linux FieldWorks development.

Install vagrant and virtualbox

Ubuntu 16.04 

    sudo apt-get install vagrant virtualbox virtualbox-guest-additions-iso

Ubuntu 14.04

In Ubuntu 14.04 it might be possible to use the vagrant and virtualbox in the Ubuntu repositories. They may or may not be new enough. (If not, use the Ubuntu 12.04 steps.) 

    sudo apt-get install virtualbox vagrant

Ubuntu 12.04

Windows 7

From a package manager 
    choco install virtualbox
    choco install vagrant
Or from web sites

Set up machine

  • Get the vagrant setup information. First cd to a desired location to clone the repository with the Vagrant definitions.
    host$ git clone https://github.com/sillsdev/FwSupportTools.git
  • Note that the provisioner will copy your host's .gitconfig file and ssh key into the guest, to authenticate with gerrit in the guest.
  • Build machine. If your host is Windows, you may need to do these steps using git bash rather than Command.
    host$ cd FwSupportTools/vagrant/development/ubuntu-14.04
    host$ time vagrant up
  • The provisioning process will download dependencies and code repositories and spend time compiling, so it can be good to start before leaving work at the end of the day or before a meeting. Note that cloning the code repositories doesn't report progress, so don't cancel it thinking it has stalled.
  • After provisioning has finished, reboot the vagrant a couple times. Note that the git history viewer launcher is on the desktop to start with, not the launcher bar.
  • You now need to manually launch either
    • monodevelop, open the fwrepo/fw/RunFieldWorks.csproj file, and use Edit > Preferences - .NET Runtimes to set the mono from /opt/mono-sil (eg version 3.4) as the default runtime; or
    • Visual Studio Code and open fwrepo/fw/fw.code-workspace.
  • If you trash your machine, don't want to spend time fixing something that went wrong, or for whatever reason want to re-create your vagrant guest, you can delete and re-create it using:
    host$ echo y | vagrant destroy && vagrant box update && time vagrant up
  • Note that in vagrant, the username is vagrant and the password is vagrant.

FieldWorks test vagrant machine

You can also set up a FieldWorks test machine.

Note that although you can enable various llso package repositories within a provisioned guest, you may find it useful to edit vagrant/testing/provision-fw-test-machine to enable specific llso package repositories before provisioning. Note that when provisioning a test machine, the fieldworks packages and dependencies are downloaded but not installed so that each provision is a clean machine. 

    host$ cd FwSupportTools/vagrant/testing/wasta-1604-64  # or wasta-1404-64 or ubuntu-1404-64
    host$ vagrant up

Note that as of 2015-08, a bug is preventing smooth provisioning and usage of the wasta-1404-64 test machine.

Note that as of 2016-03, after provisioning a Wasta 16.04 test machine and rebooting into the GUI, the login may fail, saying "Failed to start session". If this happens, click the small circle logo above and to the right of the password box, choose "Cinnamon" or "Cinnamon (Software Rendering)", and try again. The username is ubuntu and the password is ubuntu.

Set up a Linux Environment from Scratch (without Vagrant)

  1. Download and burn the Ubuntu Desktop 64-bit .iso for Ubuntu 14.04 LTS (not a more recent version except at your own pioneering risk).
  2. Install Ubuntu onto your physical machine or in a virtual machine. Some special-purpose virtual machine instructions here may be useful.
    If using a proxy at your location: Launch System Settings. Open Hardware - Network. Click Network proxy. Set a proxy and click Apply system wide. Close the Network window.
    If using Debian, enable the contrib repo so ttf-mscorefonts-installer will install.
  3. Update your system by launching Update Manager (or Software Updater), checking for updates, and installing all available updates. (But do not upgrade to a newer release of Ubuntu.)
  4. Install some helpful packages:
    5. sudo apt-get install git-gui terminator meld kdiff3-qt vim links2 gdb wget synaptic ack-grep geany xchat chromium-browser indicator-multiload dconf-tools git-cola mercurial python-pyinotify
  5. Core developers: Follow the instructions for core developers. You can continue setting up your machine before completing all of these steps, but you may need to return to re-run initrepo.
    Note: If you already have a private key on another machine that you use to authenticate with gerrit, it is probably in a file called id_rsa or id_dsa in $HOME/.ssh/, and can be copied into the $HOME/.ssh/ directory of this new machine being set up. To do that, on the new machine install openssh-server and make the ~/.ssh directory (mkdir ~/.ssh ; sudo apt-get install openssh-server) and use scp on the previous machine to transfer the private key file (scp .ssh/id_rsa new_machine_username@new_machine_hostname:.ssh/)
  6. Configure public git name and email, and other settings by editing ~/.gitconfig and inserting the following, changing name and email.
    To create this file which may not yet exist, launch Text Editor (aka gedit), choose File > New, File > Save As, in the Name box paste ~/.gitconfig and click Save.
    7. [user] name = Bob Smith email = bob_smith@sil.org [gui] editor = gedit [diff] tool = meld [merge] conflictstyle = diff3 tool = kdiff3 [color] ui = true [rerere] enabled = true [rebase] autosquash = true
  7. Launch Terminator. Add package repositories with these commands. You can paste commands into Terminator by pressing CTRL-SHIFT-V.
    8. sudo echo have sudo wget -qO - http://linux.lsdev.sil.org/downloads/sil-testing.gpg | sudo apt-key add - wget -qO - http://packages.sil.org/sil.gpg | sudo apt-key add - DISTRO="$(lsb_release -si)" sudo add-apt-repository "deb http://packages.sil.org/${DISTRO,,} $(lsb_release -sc) main" sudo add-apt-repository "deb http://packages.sil.org/${DISTRO,,} $(lsb_release -sc)-experimental main" sudo add-apt-repository "deb http://linux.lsdev.sil.org/${DISTRO,,} $(lsb_release -sc) main" sudo add-apt-repository "deb http://linux.lsdev.sil.org/${DISTRO,,} $(lsb_release -sc)-updates main" sudo add-apt-repository "deb http://linux.lsdev.sil.org/${DISTRO,,} $(lsb_release -sc)-proposed main" sudo add-apt-repository "deb http://linux.lsdev.sil.org/${DISTRO,,} $(lsb_release -sc)-experimental main" sudo apt-get update
  8. Clone FieldWorks repositories:
    9. git clone https://github.com/sillsdev/fwmeta.git ~/fwrepo cd ~/fwrepo fwmeta/initrepo
  9. Install FieldWorks build dependencies:
    10. ~/fwrepo/fw/Build/Agent/install-deps When you are prompted to accept an EULA, press Tab to select the <OK> button, then press Enter.
  10. Build and install our custom mono: (Note that the following assumes that you cloned directly into your user directory.)
    11. sudo echo have sudo cd ~/fwrepo/mono && mono-calgary/BuildOptMono.sh
  11. Download root certificates from Mozilla (because Mono is too skeptical about SSL/TLS; see this Mono FAQ).
    12. mozroots --import --ask-remove
  12. Install Monodevelop
    13. Follow the instructions at Install_and_use_Monodevelop#Install.
  13. Prepare Monodevelop for building, running, and debugging FieldWorks.
    1. Get the FwSupportTools repo:
      2. cd ~/fwrepo fwmeta/initrepo -m For "Repos to clone", paste in the list of existing managed repos (which is in parentheses), as well as: FwSupportTools
    2. Install RunFieldWorks project to more easily Run and Debug FieldWorks from Monodevelop:
      3. cp -a ~/fwrepo/FwSupportTools/building/RunFieldWorks.csproj ~/fwrepo/fw/
    3. Close Monodevelop if it is open. Add build scripts to the MonoDevelop Tools menu config file (unless you have already been adding custom menu items):
      4. mkdir -p "$HOME/.config/MonoDevelop-5.0" FILE="$HOME/.config/MonoDevelop-5.0/MonoDevelop-tools.xml" cat > "$FILE" <<ENDOFFILE <?xml version="1.0" encoding="utf-8"?> <Tools version="2.0"> <ExternalTool menuCommand="fw build recent (_t)" command="/home/USERNAME/fwrepo/FwSupportTools/building/fw-build-recent" arguments="" initialDirectory="/home/USERNAME/fwrepo/fw" promptForArguments="False" useOutputPad="True" saveCurrentFile="False" /> <ExternalTool menuCommand="fw build all" command="/home/USERNAME/fwrepo/FwSupportTools/building/fw-build-all" arguments="" initialDirectory="/home/USERNAME/fwrepo/fw" promptForArguments="False" useOutputPad="True" saveCurrentFile="False" /> <ExternalTool menuCommand="fw build remakefw" command="/home/USERNAME/fwrepo/FwSupportTools/building/fw-build-remakefw" arguments="" initialDirectory="/home/USERNAME/fwrepo/fw" promptForArguments="False" useOutputPad="True" saveCurrentFile="False" /> <ExternalTool menuCommand="fw build remakefw with tests" command="/home/USERNAME/fwrepo/fw/agent-build-fw.sh" arguments="" initialDirectory="/home/USERNAME/fwrepo/fw" promptForArguments="False" useOutputPad="True" saveCurrentFile="False" /> </tools> ENDOFFILE sed -i "$FILE" -e "s/USERNAME/$USER/g"
    4. On the Monodevelop Tools menu, there will be menu items to build FieldWorks using xbuild. Remember to save your files before building (File > Save All).
      5. The menu items are:
      • fw build recent: Builds any projects with files changed in the last 30 minutes. It's fast, but it may not build in the right order, and dependencies won't know to rebuild.
      • fw build all: Builds all projects.
      • fw build remakefw: Does a clean full build.
      • fw build remakefw with tests: Does a clean full build and runs unit tests.
  14. The FieldWorks code is in ~/fwrepo/fw in a git repository. Build FieldWorks by launching Monodevelop and choosing Tools > fw build remakefw.
  15. Create launcher for git-gui and gitk:
    16. [Desktop Entry] Version=1.0 Type=Application Terminal=false Exec=bash -c 'cd \$HOME/fwrepo/fw && (gitk --branches --remotes --tags& git gui& )' Name=FW Git Tools Icon=/usr/share/git-gui/lib/git-gui.ico ENDOFLAUNCHER chmod +x "$LAUNCHER"
  16. Create launcher for Xephyr:
    17. [Desktop Entry] Version=1.0 Type=Application Terminal=false Exec=bash -c 'Xephyr :2 -screen 1000x700& sleep 2s; DISPLAY=:2 metacity& DISPLAY=:2 xclock& DISPLAY=:2 xterm& DISPLAY=:2 ibus-daemon &' Name=Xephyr ENDOFLAUNCHER chmod +x "$LAUNCHER"
  17. Configure Monodevelop:
    1. Launch Monodevelop from the desktop icon. (If your desktop environment hides desktop icons, look in ~/Desktop)
    2. Choose File > Open and open project ~/fwrepo/fw/RunFieldWorks.csproj
    3. Choose Edit > Preferences. Under Projects, click .NET Runtimes. Add the runtime from /opt/mono-sil and set it as default. You may need to set the default runtime again later for it to stick.
    4. Under Projects click Build. Uncheck Build solution before running.
    5. Uncheck Build solution before executing unit tests.
    6. Click OK.
  18. In Monodevelop, choose Run > Start Without Debugging to launch FieldWorks.

More information can be found at Build_FieldWorks, Building_mono_from_source, Install_and_use_Monodevelop, and https://github.com/sillsdev/FwDocumentation/wiki/Getting-Started-with-FieldWorks-Development.

Xephyr

  • Running FieldWorks in a Xephyr window makes debugging SWF events easier, eases interaction with the monodevelop debugger, and lets you confine and separate UI interaction of FieldWorks to a particular location.
  • Because running FW in a Xephyr window will not be using Compiz visual effects like when running on your main desktop (:0), there will be some slight UI behavioural differences.
  • To make a Xephyr window, do one of the following:
    • Double-click the Xephyr icon on your desktop that was made as part of Set up. Or,
    • Run in its own terminal the following (to not pollute the current terminal with output messages).
      • $ Xephyr :2 -screen 1000x700& sleep 2s; DISPLAY=:2 metacity& DISPLAY=:2 xclock&
  • To configure MonoDevelop to run FieldWorks inside the Xephyr window, do the following:
    1. Launch Monodevelop.
    2. Choose File > Open and open the project RunFieldWorks.csproj in fwrepo/fw
    3. In the Solution pane, right-click the RunFieldWorks project and choose Options.
      The Project Options - RunFieldWorks dialog appears.
    4. Click Run - General. Change the DISPLAY variable from :0 to :2.
    5. Click OK.

FLExBridge

  • FLExBridge allows users to send and receive FLEx data with other users. You can clone it using
    • git clone https://github.com/sillsdev/flexbridge.git ~/fwrepo/flexbridge
  • FLEx locates FLExBridge on Linux using an environment variable, which you can set in the Project Options - Run - General for RunFieldWorks.
    • FLEXBRIDGEDIR=/home/YOURUSERNAME/fwrepo/flexbridge/output/DebugMono

Notes

  • Some instructions on the wiki about developing FieldWorks are old, and may not be compatible with your setup. Some instructions may work, but still reference the Calgary/WW branch, in which case you'll need to use fwrepo/fw instead.
  • Don't commit RunFieldWorks.csproj into the repository, so that individual developers can configure how their Monodevelop launches FieldWorks.
  • To edit code in Monodevelop, add other projects to the solution alongside RunFieldWorks.
  • Projects may not compile if their References do not have <HintPath> tags in the .csproj.
  • You may find helpful some old notes of tips and overcoming quirks when using Monodevelop.
  • To build, do a command such as the following. More information.
    • fwrepo/fw$ (. environ && cd Build && xbuild /t:refreshTargets && xbuild /v:m)
  • It may be useful to review information about running unit tests outside of monodevelop.
  • To run FieldWorks outside of monodevelop, run a command such as the following, changing :0 to :2 to run in a Xephyr window, and changing Flex to TE to run TE.
    • $ cd ~/fwrepo/fw/Output/Debug Output/Debug$ cd ../../Output/Debug && export PROJ="$HOME/fwrepo/fw/DistFiles/ReleaseData/Sena 3/Sena 3.fwdata" && export FIELDWORKS_ENVIRON="$HOME/fwrepo/fw/environ" && DISPLAY=:0 mono FieldWorks.exe -app Flex -proj "$PROJ"
  • Terminator is more powerful than Terminal, and can let you split your window into panes.
  • Mono simulates a registry for FieldWorks installations at ~/.config/fieldworks/registry (~/fwrepo/fw/Output_x86_64/registry for debug builds, so debug registry is wiped on remake).
  • To do something similar to attaching a debugger to a process (e.g. for debugging FLExBridge), use http://stackoverflow.com/a/12395786 and in your code change the Process.Start usage from running "foo.exe" with args "a b c" to instead run "mono" with args "--debug --debugger-agent=... a b c". Start one monodevelop listening and then start the main program in another monodevelop. When the main program does Process.Start, the second monodevelop will start debugging it.
  • To debug Chorus or Palaso code run from within FieldWorks (not through FLExBridge), copy the dll's and mdb's into the FW output directory (you can use flexbridge/UpdateFLExDependencies.sh), comment out the appropriate section of CopyDlls in ~/fwrepo/fw/Build/makeall.targets, and build FW.

Update

To later update the whole range of your dependencies, tools, code, and rebuild:

  1. Update your system by launching Update Manager (or Software Updater), checking for updates, and installing all available updates. (But do not upgrade to a newer release of Ubuntu.)
  2. Update the mono for building and running FieldWorks with these instructions.
  3. Update other tools and dependency code:
    4. $ cd ~/fwrepo/libcom && git pull
  4. Update FieldWorks code:
    5. $ cd ~/fwrepo/fw && git pull
  5. Rebuild by doing one of the following:
    • Launch Monodevelop and choose Tools > fw build remakefw.
    • Build from the command line (xbuild behaves similarly to build.bat):
      • $ cd ~/fwrepo/fw && . environ && cd Build && Agent/install-deps && xbuild /t:remakefw
    • Or build from commandline (this also runs all unit tests, which can take upwards of half an hour):
      • $ cd ~/fwrepo/fw && ./agent-build-fw.sh
Clone this wiki locally