mxrun

mxrun runs one build entry across local and remote machines in parallel.

It syncs the project tree, starts the same make target on each machine, and can mirror back only the final artefacts your project lists.

Why

Projects often need one local build and one or more remote builds, such as FreeBSD or Linux VMs. mxrun keeps that flow in one terminal UI instead of many shells and ad-hoc rsync steps.

What mxrun owns

• Target loading from MXRUN_CONFIG or --config
• Remote directory creation and project sync with rsync
• Running one build entry on every target
• Optional result mirroring from build/.mxrun/<entry>.paths

What the project owns

• The actual make or gmake targets
• The manifest of final deliverables
• Any project-specific build logic

Quick start

export MXRUN_CONFIG=mxrun.conf
mxrun run devel

Mirror back listed outputs:

export MXRUN_CONFIG=mxrun.conf
mxrun run devel --mirror-results

Validate the config file:

mxrun init

Add a remote host:

mxrun -a 203.0.113.10

Config format

targets:
  - local
  - FreeBSD amd64 builder@freebsd-vm:work/example-mxrun
  - GNU/Linux x86_64 builder@linux-vm:work/example-mxrun

project:
  ignore:
    - /generated/
    - '*.cache'
  build:
    src:
      - target/debug/example
    dst: target/platforms

project.ignore entries are passed to rsync as exclusion patterns. They can name files, directories, or globs; / anchors a pattern at the project root. Existing remote files are not deleted.

project.build collects each listed workspace-relative path after a target succeeds. Results go to <dst>/<platform>-<arch>/, preserving normal rsync source-to-directory behavior. For example, target/debug/example is collected as target/platforms/GNU_Linux-x86_64/example.

Set project.build.files to copy only selected files from directory sources. The file paths are relative to each directory source; direct file sources are always copied normally.

project:
  build:
    src:
      - target/debug
      - target/release
      - target/release/helper
    files:
      - app
    dst: target/platforms

This copies target/debug/app to target/platforms/<platform>-<arch>/debug/app, while target/release/helper is copied directly.

Legacy target-only configs remain supported:

local

If the config file does not exist yet, mxrun creates the YAML form with a local target and an empty ignore list.

Producer contract

For an entry named devel, the project writes:

build/.mxrun/devel.paths

The file is a line-based list of relative paths to mirror back after a successful build.

Example

See example/README.md for a minimal producer project.

More docs

• Full user guide: doc/README.md
• Man page source: doc/manpage/buildfarm.1.md

Licence

MIT. See LICENSE.