tutorials/Building-Qt.md

+Previous: [Configure local minicoin](tutorials/Configure-Local-Minicoin)
+
+Now that `minicoin` is configured to make the most out of the local hardware
+and to keep a synchronized copy of the Qt sources on the VMs, and that the
+`windows11` machine is booted and provisioned, it's time to start building Qt.
+This tutorial assumes that the `dev` branch of the Qt super repository is
+checked out in `~/qt/dev`, which is also the path we added to the `mutagen`
+sync in the previous tutorial. Adjust the steps according to your local setup.
+
+# Running a build job
+
+Running a workload on the VM is done using the [`minicoin run`](Manual/Running-Jobs)
+command. The `run` command can execute a predefined `job` on the machine, and
+will use the current working directory on the host system to decide what files
+the job should work on.
+
+First, lets check what jobs there are available:
+
+```
+$ minicoin run --help`
+```
+
+This will list all [available jobs](Manual/Available-Jobs), a number of command
+line options for the `run` command, and standard options `minicoin` has
+inherited from `vagrant`. In this tutorial, we are using the `build` job, which
+configures and builds the Qt project in the current directory. That project can
+be Qt itself (either a toplevel build or a submodule), or a project using Qt -
+as long as there's a `CMakeLists.txt` file or a `.pro` project file for qmake,
+and as long as Qt has been built or installed on the VM, the `build` job will
+be able to execute the build.
+
+Let's see what the `build` job can do:
+
+```
+$ minicoin run build --help
+```
+
+This will print options that can be passed to the `build` job, such as
+`--configure`, `--target`, or `--clean`. For this first run, we only
+want to build the `Core` module of Qt, and we want to use the top-level
+build system from the `qt5.git` repository.
+
+```
+$ cd ~/qt/dev
+$ minicoin run build --target Core windows11
+```
+
+This will configure the Qt that lives in `~/qt/dev`, and then build the `Core`
+target. How long that takes and how much output is generated depends on what
+other modules are currently checked out in your `~/qt/dev` source tree. The
+build tree on the VM will be `C:\Users\vagrant\dev-build`.
+
+# Job output processing
+
+`minicoin` defines a number of pattern matchers for the output from common
+compilers so that warnings and errors are highlighted in yellow and red, and
+sent to the `stderr` stream rather than `stdout`. These matchers are configured
+through job-specific YAML files, and can be modified with user specific
+overrides as well.
+
+At the end of this job you should see the output from the configuration and
+build of Qt, perhaps with a few yellow warnings in the output, and with a last
+line "==> windows11: Job generated 1 problem messages" to inform you about
+warnings that might have been generated during the build (it's hard to write
+C++ that doesn't generate warnings with any compiler).
+
+# Running a test
+
+The `build` job can build any target that the build system supports, which
+in the case of Qt includes the `_check` targets for the auto tests. Let's make
+sure that our VM is not only correctly set up to run a build, but that we can
+also run some UI tests.
+
+```
+$ minicoin run build --target tst_QLineEdit_check windows11
+```
+
+This will do exactly the same as a local execution of
+
+```
+$ ninja tst_QLineEdit_check
+```
+
+Except that it will happen on the VM - which also means that we don't get
+disturbed by a lot of `QLineEdit` test windows opening up around us on our
+work station.
+
+If we want to see what's going on in the VM, we can bring up the UI of the
+VM with
+
+```
+$ minicoin gui windows11
+```
+
+and see the windows opening and closing once the test starts running, without
+any interference with our own mouse cursor.
+
+Once the test run is complete, we should see the output from the auto test in
+our local terminal, with `PASS`ing test functions marked in green, hopefully
+no red lines for `FAIL`ures, and perhaps a few yellow lines for skipped tests.
+
+Next: [Continuously running unit tests in a local VM](tutorial/Run-Test-Continuously)