Running Jobs

Jobs are executed using the minicoin run command.

$ minicoin run test ubuntu2004

This starts the ubuntu2004 machine if it's not already running (see note), 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

This command will run the build job for target tst_qstring_check two times on the ubuntu2004 machine. Some jobs support trailing options as well, e.g.

$ minicoin run ctest ubuntu2004 -- -L corelib/kernel

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 executed on the guest as the vagrant user, and the working directory is the home directory. If the directory on the host does not map to any path on the guest (either via folder sharing or via file system syncing), then minicoin will generate a warning, but will nevertheless attempt to run the job.

Note: It is often a good idea to start the machine explicitly and let the file system syncing finish before running jobs. See the documentation on managing virtual machines for relevant commands.

Job documentation

For a list of available jobs, run

$ minicoin run --help

Which parameters the job supports depends on each job, and a properly implemented job also provides help text. To see the documentation for a job, run

$ minicoin run [job] --help

E.g.

$ minicoin run build --help

will inform about the command line arguments the build job supports.

Run options

The way the run command executes the job can be modified with parameters after the run command. The most important options are

• '--env KEY=VALUEruns the job with additional environment variables set. Multiple variables can be set by providing a comma-separated list, e.g.SETTING=blah,STUFF=foo. To add a new value to an existing variable, use the +=operator, e.g.PATH+=foo`. Note that this will prepend the value so that it has precedence.

• --privileged executes the command with elevated privileges

• --parallel executes the job on all machines at the same time

• --jobconfig selects a predefined configuration for the job. See implicit job parameters

• --console on Windows, runs the job directly in the WinRM session instead of launching it in an interactive desktop session via a scheduled task. 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.

• --fswait 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.