Package description
A package description is composed of two parts:
- the package source (required)
- a data structure that describes where to retrieve the files of a package, and how to assemble them (e.g. whether to rename some files, make some of them executable, etc.)
- additional package metadata (optional)
- other, optional metadata (like the author/publisher of the file, a homepage, labels, tags...)
Example¶
To get an idea how a full, 'working' package description looks like, here's one that lets you install the pandoc binary, an application to convert between document formats:
info:
homepage: https://pandoc.org/
slug: Universal markup converter
desc: |
Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library.
tags:
- document-formats
- convert
- markdown
labels:
executable_type: binary
language: haskell
source:
type: github_release
user_name: jgm
repo_name: pandoc
url_regex:
- https://github\.com/jgm/pandoc/releases/download/(?P<version>.*)/pandoc-(?P=version)-(?P<os>[^-.]*)(-(?P<arch>[^-.]*))?(\.tar\.gz|\.zip)$
aliases:
arch:
x86_64: amd64
os:
darwin: macOS
artefact:
type: archive
transform:
- bin/pandoc:
mode: 755
path: pandoc
You can use the explain subcommand to debug a package, and print out the data it collects:
> bring explain pkg [path_to_pandoc_desc_file].pkg.br Package binaries.pandoc (Universal markup converter) desc Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library. homepage https://pandoc.org/ Variables arch The architecture the binary is built for. default -- no default -- required yes type string allowed amd64 (alias: x86_64) i386 os The operating system to run on. default -- no default -- required yes type string allowed 3 macOS (alias: darwin) linux osx windows version The version of the package. default latest required yes type string allowed 2.10.1 (aliases: stable, latest) 2.10 2.9.2.1 2.9.2 2.9.1.1 2.9.1 2.9 2.8.1 2.8.0.1 2.8 2.7.3 2.7.2 2.7.1 2.7 2.6 2.5 2.4 2.3.1 2.3 2.2.3.2 2.2.3.1 2.2.2.1 2.2.2 2.2.1 2.2 2.1.3 2.1.2 2.1.1 2.1 2.0.6 2.0.5 2.0.4 2.0.3 2.0.2 2.0.1.1 2.0.1 2.0.0.1 2.0 1.12.4.2
section: 'source'¶
A packacke description must have a section with the key source. Ideally, it describes a package in a way that is idempotent, which means that, if given the same input values, it'll always yield the exact same files, in the exact same folder structure. In some cases that is not possible/required, but we'll ignore that for now and assume idempotency.
The source section itself can be split up into 3 different sub-sections:
key: 'type'¶
The name of the package type plugin that will read and process this data. bring supports multiple such package types, to accomodate for the different ways people publish their files. Currently available, official package types are:
-
git_files: a package type to retrieve one or several files from a git repository -
git_repo: a package that represents a git repository and its content -
github_files: a package type to retrieve one or several files from a git repository that is hosted on GitHub -
github_release: a package type that tracks GitHub release artefacts -
gitlab_files: a package type to retrieve one or several files from a git repository that is hosted on GitLab -
template_url: a package type to resolve packages whose artifacts are published with static urls that can be templated
type-specific keys¶
Each package type has different required and optional arguments. Check their respective documentation for details.
common keys (optional)¶
bring uses package-type plugins to retrieve source files for packages, but then uses the same code to post-process those files. This code also can take some input in order to costumize the final structure of a package.
Those keys are currently supported:
aliases¶
A dictionary with the variable names as keys, and an alias dictionary (with alias as key, and final value as, well, ...value).
E.g., for:
os:
linux: unknown-linux-gnu
darwin: apple-darwin
...an input value of linux for the os variable would resolve to unknown-linux-gnu. Package types sometimes provider their own aliases (for example 'latest' as a pointer to the latest version of a github release).
args¶
A dictionary to let you control how package arguments are presented to the user. bring comes with default argument configurations for 3 argument keys: version, arch, os. If your package has other input variables (or if you want to override the defaults), you can do that here.
Here is a list of available configuration keys (all of them optional):
doc: a string describing the argumenttype: the type of the argument. supported: "any", "string", "integer", "list", "dict", "boolean" (and a few others, to be documented later -- defaults to "any")default: a default value if none is provided for the (no default)required: whether the argument is required or optional (defaults to 'true')multiple: whether a only a single, or multiple values are allowed (defaults to 'false')allowed: a list of allowed values (not implemented yet -- no default)
As an example for the: the kubernetes.ingress requires an extra provider argument, to determine the exact yaml manifest file to select. This variable is described with data like:
args:
provider:
doc: The provider to deploy to.
default: cloud
This will change the output of the package install help command to be:
> bring install kubernetes.ingress-nginx --help
Usage: bring install kubernetes.ingress-nginx [OPTIONS]
Options:
--provider PROVIDER The provider to deploy to.
--version VERSION The version of the package.
-h, --help Show this message and exit.
And it will use cloud as value for that key if not specified otherwise by the user.
artefact¶
An optional hint to specify the type of source package artefact for a package (which could be a tar.gz- or zip-archive, a folder, a single-file, etc.). Internally, bring requires each package to be a folder containing one or several files. This argument helps transform single-file artefacts (archive, normal file) into a folder (for example by extracting it, or move a single downloaded file into a newly created temporary folder). In most cases, you won't need to specify it. For the cases where that is not true, those values are currently supported:
file- a plain, single filefolder- a folder (for example when the artefact is a git repository)archive- an archive file (currently supported archive types: zip, tar, tar.gz, tar.bz2, xtar)
If artefact is not specified, a semi-smart detection mechanism is used (which should work for most cases).
transform¶
Optional configuration to control which files that are contained in the original artefact will end up in the package. This is the most used configuration option, as often you are not interested in supplementary files (licenses, configuration examples, etc.) to be installed into the target.
Configuration for this value is done via providing a list of items as input. Each item can either be a string (for simple filtering), or a dictionary of values (if more advanced configuration is necessary).
If no value for transform is provided, all files of the package will be copied into the target. If one or several list items are set, only those will be used, and all non-matching files will be ignored.
If a list item is a string, the full path to that file is looked up in the source package folder, and copied over to the target using the exact same path/filename. If a dictionary is provided, those are the available configuration keys:
from(required string): the path to the file/the filename in the sourceto(optional string): the target path/filename (defaults to the value offrom)mode(optional, string or integeer): the permissions of the file on the target (e.g. '0755', 644, ...)
All variables that are used to resolve a version of a package are allowed in variable placeholders (${var_name}).
An full example from the binaries.k3d package, which renames an os-specificly named file to a more generic name, and also makes the file executable:
transform:
- path: k3d
from: "k3d-${ os }-amd64"
mode: 755
Other configuration keys are not supported currently, neither is selecting files via globs/regexs. There are plans to do that in the future though. Mixing string and dictionary items is allowed.
metadata sections:¶
section: 'info'¶
Contains information about the package itself, the most important sub-keys are: slug (description of the package), homepage.
section: "tags"¶
A list of strings containing tags that apply to the package. This is not used at the moment, but will be later to filter/select packages.
section: "labels"¶
A list of strings containing labels that apply to the package. This is not used at the moment, but will be later to filter/select packages.