Machfile

Simple task runner, for when a full build system is overkill

This project provides both a library and a CLI utility. The CLI is the primary implementation of the library, and provides the basic functionality of the task runner. The binary is called mach.

Installation

You can install the binary with cargo:

cargo install machfile-cli --locked

Or clone the repository and install manually:

git clone https://github.com/machfile/machfile.git
cd mach
cargo install --path .

Auto-complete setup

Mach supports dynamic auto completion in ZSH and bash:

# Setup dynamic mach auto-complete
source <(mach setup_complete [zsh|bash])

Configuration

Mach can be configured with mach.toml, mach.yaml or mach.yml files. When inside a git repository, mach will search the directory tree upwards until finding a config file (stopping at the root directory of the git repository). If not inside a git repository, mach must be called from within the same directory as the configuration file.

Tasks

Machfiles are made up of several individual tasks. This is the standard unit that is normally called. A task has a name, and something that can be executed. This can be a script or a list of dependencies (deps). The task can also have an optional description (desc) and several options.

[do_stuff]
script = "touch test"
desc = "Create a test file"
deps = ["remove_old_test"]
options.working_directory = "/tmp"

do_stuff:
  script: "touch test"
  desc: "Create a test file"
  deps:
    - "remove_old_test"
  options:
    working_directory: "/tmp"

script

The script is a (multiline) string containing one or several commands that will be executed in order one after the other. If provided with a multiline-string, the string is separated into the different lines. Each command string will then be separated into the command (the first word) and its arguments (everything after) and executed in an isolated shell. This shell inherits the environment from the mach process.

Any exit code other than 0 will cancel the execution of following commands and exit the programm with an error.

Pipes, cd and other shell features do NOT work in the script tag. If you have the need for these, write your complex script as a bash script and use that as an argument for script.

Either a script or at least one dependency is required for the task to be valid.

desc

Desc should contain a description for your task. The mach CLI will display this text in it's help messages (mach --help) and in the autocomplete functionality.

deps

The dependencies are a list of tasks that should be executed before the task in which the dependencies are configured. The dependencies will be executed in order, and the execution will be stopped if any dependencies results in an error.

A task with dependencies but without a script is completely valid.

options

Options modify the task execution. They do not affect dependencies.

The following options are currently supported:

• working_directory - Sets the working directory of the script commands relative to the used configuration file
• environment - Dictonary of keys and values that will be injected into the execution environment of the script commands.

Configuration examples

The following is an example configuration written in toml:

[run]
script = "cargo run"
desc = "Run with debug logging"
options.environment.RUST_LOG = "mach=debug,info"

[clean]
script = "rm -rf target"
desc = "Remove cache and outputs"

[check_target_size]
script = "du -d1 -h"
desc = "Check directory sizes of cache dirs"
options.working_directory = "target"

[install]
script = "cargo install --path ."
deps = ["clean"]

The same configuration can also be written in yaml:

run:
  script: "cargo run"
  desc: "Run with debug logging"
  options:
    environment:
      RUST_LOG: "mach=debug,info"

clean:
  script: "rm -rf target"
  desc: "Remove cache and outputs"

check_target_size:
  script: "du -d1 -h"
  desc: "Check directory sizes of cache dirs"
  options:
    working_directory: "target"

install:
  script: "cargo install --path ."
  deps:
    - "clean"

Usage

Consult the --help command for usage instructions

mach --help

Development

Setting the environment variable MACH_CONFIG_PATH allows using a specific custom configuration file.

MACH_CONFIG_PATH=tests/example.toml cargo run -- --help