Manual/Running-Jobs.md

+Jobs are executed using the `minicoin run` command.
+
+`$ minicoin run test ubuntu2004`
+
+This starts the `ubuntu2004` machine if it's not already running, uploads the
+`jobs/test` subdirectory to the machine, and then runs the `main.sh` script
+(if the guest is Linux or Mac; on Windows the `main.cmd` script).
+
+Parameters directly following the `run` command modify how the job is executed.
+Parameters following the `job` are specific to the job, and will be validated by
+minicoin. Any parameters after a double dash `--` following the machine names
+will be passed on to the job's `main` script without any validation. For example,
+
+`$ minicoin run --repeat 2 build --target tst_qstring_check ubuntu2004 -- --testargs toUpper`
+
+This command will run the `build` job for target `tst_qstring_check` two times
+on the ubuntu2004 machine, passing also `--testargs toUpper` through to the job.
+
+For all jobs, the directory on the guest that maps to the current working
+directory on the host, and the current working directory on the host, are passed
+as the first two parameters to the job script. This allows the job to operate
+on the correct directory.
+
+Jobs are by default executed on the guest as the `vagrant` user.
+
+# Job documentation
+
+For a list of available jobs, run
+
+`$ minicoin run --help`
+
+Which parameters the job supports depends on each job. To see the documentation
+for a job, run
+
+`$ minicoin run [job] --help`
+
+The most important job is:
+
+`$ minicoin run build [machines...]`
+
+This job builds the local source tree on the listed machines. The local
+source tree can be a toplevel Qt repo, a single Qt module, or a Qt project.
+The Qt toolkit from the last build of qtbase will be used.
+
+# Run options
+
+The way the run command executes the job can be modified with parameters
+after the `run` command. The most important options are
+
+* `--privileged` executes the command with elevated privileges
+
+Some scripts require privileged access, esp on Windows when software needs
+to be installed.
+
+* `--parallel` executes the job on all machines at the same time
+
+* `--console` on Windows, runs the job directly in the WinRM session rather
+than launching it in an interactive desktop session via psexec. This saves
+a fair amount of execution overhead, but the job won't be able to interact
+with the desktop. This parameter has no effect on Linux or macOS guests.
+
+* `--repeat COUNT` runs the job COUNT times in a loop. This is useful for
+running flaky tests.
+
+* `--continous` runs the job in a loop, waiting for changes to files in
+the current working directory after each iteration. Can be combined with
+`--repeat`, otherwise runs until interrupted with Ctrl-C.
+
+See
+
+`$ minicoin run --help`
+
+for a complete list of run options.
+