Skip to content

task.md

Latest commit

 

History

History
346 lines (283 loc) · 5.56 KB

task.md

File metadata and controls

346 lines (283 loc) · 5.56 KB
Raw

vix task

vix task runs reusable project tasks.

Use it when you want to define common workflows once in vix.json and run them by name.

Usage

vix task <name> [args...]
vix task --list
vix task --help

What it does

vix task is a small task runner built into the Vix CLI. It can run built-in project tasks, custom tasks from vix.json, task dependencies, multiple commands in order, platform-specific commands, commands with variables, commands with environment variables, and commands from a specific working directory.

Basic usage

vix task dev
vix task check
vix task --list
vix task --help

Built-in tasks

Task Command
dev Run in development mode with hot reload
run Run the application
fmt Format code
check Validate build, tests, runtime, and sanitizers
build Build project
test Run tests with CTest

Custom tasks

Custom tasks are defined in vix.json:

{
  "tasks": {
    "fmt": "vix fmt",
    "ci": ["vix fmt --check", "vix check --tests"]
  }
}

Task formats

A task can be defined as a string, array, or object.

String task

{
  "tasks": {
    "fmt": "vix fmt"
  }
}

Array task

{
  "tasks": {
    "ci": [
      "vix fmt --check",
      "vix check --tests"
    ]
  }
}

If one command fails, the task stops instead of continuing.

Object task

{
  "tasks": {
    "release": {
      "description": "Release pipeline",
      "deps": ["fmt", "test"],
      "vars": {
        "preset": "release"
      },
      "env": {
        "VIX_LOG_LEVEL": "info"
      },
      "cwd": "${project_dir}",
      "commands": [
        "vix build --preset ${preset}",
        "vix check --preset ${preset} --tests"
      ]
    }
  }
}

Task dependencies

{
  "tasks": {
    "fmt": "vix fmt --check",
    "test": "vix tests",
    "ci": {
      "deps": ["fmt", "test"],
      "commands": ["vix check --tests"]
    }
  }
}

Execution order: fmt → test → ci

Variables

Global variables are defined in the root vars object:

{
  "vars": {
    "preset": "dev-ninja"
  },
  "tasks": {
    "build": "vix build --preset ${preset}"
  }
}

Task variables override global variables:

{
  "vars": {
    "preset": "dev-ninja"
  },
  "tasks": {
    "release": {
      "vars": {
        "preset": "release"
      },
      "command": "vix build --preset ${preset}"
    }
  }
}

Built-in variables

Variable Meaning
${task} Current task
${task_name} Current task name
${platform} Current platform
${project_dir} Project directory
${root} Project root

Environment variables

{
  "tasks": {
    "debug": {
      "env": {
        "VIX_LOG_LEVEL": "debug"
      },
      "command": "vix run"
    }
  }
}

Working directory

{
  "tasks": {
    "build-api": {
      "cwd": "${project_dir}/apps/api",
      "command": "vix build"
    }
  }
}

Platform-specific tasks

Supported platform override keys: linux, windows, macos.

{
  "tasks": {
    "build": {
      "linux": {
        "command": "vix build --preset release"
      },
      "windows": {
        "command": "vix build --preset dev-msvc"
      },
      "macos": {
        "command": "vix build --preset release"
      }
    }
  }
}

Passing arguments to tasks

vix task release -- --verbose

CLI arguments are appended only to the final command of the selected task. Dependencies run normally.

Custom tasks take priority

If a custom task has the same name as a built-in task, the custom task wins.

Non-interactive mode

VIX_NONINTERACTIVE=1 vix task ci
CI=1 vix task ci

Full example

{
  "vars": {
    "preset": "dev-ninja"
  },
  "tasks": {
    "fmt": "vix fmt --check",
    "test": "vix tests",
    "dev": "vix dev",
    "ci": [
      "vix fmt --check",
      "vix check --tests"
    ],
    "release": {
      "description": "Release pipeline",
      "deps": ["fmt", "test"],
      "vars": {
        "preset": "release"
      },
      "env": {
        "VIX_LOG_LEVEL": "info"
      },
      "cwd": "${project_dir}",
      "commands": [
        "vix build --preset ${preset}",
        "vix check --preset ${preset} --tests",
        "vix pack --name api --version 1.0.0"
      ],
      "linux": {
        "command": "vix build --preset ${preset}"
      },
      "windows": {
        "command": "vix build --preset dev-msvc"
      }
    }
  }
}

Recommended project tasks

{
  "tasks": {
    "dev": "vix dev",
    "run": "vix run",
    "fmt": "vix fmt",
    "check": "vix check --tests",
    "test": "vix tests",
    "build": "vix build",
    "ci": [
      "vix fmt --check",
      "vix check --tests"
    ],
    "release": [
      "vix build --preset release",
      "vix check --preset release --tests"
    ]
  }
}

Common workflows

vix task dev
vix task ci
vix task release
vix task --list
vix task release -- --verbose

Common mistakes

Forgetting to define tasks under tasks

Wrong:

{
  "ci": "vix check --tests"
}

Correct:

{
  "tasks": {
    "ci": "vix check --tests"
  }
}

Related commands

Command Purpose
vix dev Run development server
vix run Build and run app
vix build Build project
vix check Validate project
vix tests Run tests
vix fmt Format source files
vix pack Package project

Next step

Continue with all CLI commands.

Open the all commands guide