Overview¶
The vagga.yaml
has two sections:
containers
– description of the containerscommands
– a set of commands defined for the project
There is also two top-level options:
-
mixins
¶ -
**This functionality is experimental**. Some details can change in future.
¶ This is a list of vagga configs that will be “mixed in” into current config. This basically means that we import all the commands and containers from them literally.
When adding mixins, latter one overrides commands and containers in the former configs. And the ones in
vagga.yaml
override all the mixins.There are a few use-cases for mixins:
- Splitting config into several groups of things, while putting together containers and commands (latter contrasts to using includes).
- Use a generated parts of configs. Because non-existing or invalid mixins are ignored (with a warning) you can generate or update mixins by vagga commands without risk of making defunct vagga config.
- Use vagga config from a subproject (but be aware that paths resolve to
original
vagga.yaml
, not the included one) - Override things from git-commited
vagga.yaml
to custom one (note the latter requires not to commitvagga.yaml
itself, but only mixed in things)
New in version 0.7.1.
Changed in version 0.8.1: There are implicit mixins:
vagga.local.yaml
.vagga.local.yaml
(hidden).vagga/local.yaml
(in vagga dir)
They should be used to add or override local commands which shouldn’t be committed to a central repository. They work similarly as normal mixins and can contain additional mixins themselves.
-
minimum-vagga
¶ (default is no limit) Defines minimum version to run the configuration file. If you put:
minimum-vagga: v0.5.0
Into
vagga.yaml
other users will see the following error:Please upgrade vagga to at least "v0.5.0"
This is definitely optional, but useful if you start using new features, and want to communicate the version number to a team. Versions from testing work as well. To see your current version use:
$ vagga --version
Containers¶
Example of one container defined:
containers:
sphinx:
setup:
- !Ubuntu xenial
- !Install [python3-sphinx, make]
The YAML above defines a container named sphinx
, which is built with two
steps: download and unpack ubuntu xenial
base image, and install packages
name python-sphinx, make
inside the container.
Commands¶
Example of command defined:
commands:
build-docs: !Command
description: Build vagga documentation using sphinx
container: sphinx
work-dir: docs
run: [make]
The YAML above defines a command named build-docs
, which is run in
container named sphinx
, that is run in docs/
sub dir of project, and
will run command make
in container. So running:
$ vagga build-docs html
Builds html docs using sphinx inside a container.
See commands for comprehensive description of how to define commands.