Documentation
¶
Overview ¶
Package ensure contains methods and types for interacting with the 'ensure file format'.
The format is used by the cipd client to describe the desired state of a cipd installation. This states can be asserted with the cipd client 'ensure' command. The state is essentialy a list of packages, their versions and their installation subdirectories ("subdirs").
Format Description ¶
The file is line-oriented. All statements fit on a single line.
A line can be blank, a comment, a setting, a directive, or a package.
A comment begins with a # and goes to the end of the line. It is ignored.
Settings ¶
A setting looks like `$name value`. Settings are global and can only be set once per file. The following settings are allowed:
- ServiceURL is the url for the cipd service. It can be used in lieu of the -service-url command line parameter.
Directives ¶
A directive looks like `@name value`. Directives are 'sticky' and apply until the next same-name directive. The following directives are allowed:
- Subdir allows you to change the subdirectory that packages are installed to. The subdir value is relative to the root of the cipd installation (the directory containing the .cipd folder). The value of Subdir before any @Subdir directives is "", or the root of the cipd installation.
Package Definitions ¶
A package line looks like `<package_template> <version>`. Package templates are cipd package names, with optional expansion parameters `${os}` and `${arch}`. These placeholders can appear anywhere in the package template except for the first letter. All other characters in the template are taken verbatim.
${os} will expand to one of the following, based on the value of this client's runtime.GOOS value:
- windows
- mac
- linux
${arch} will expand to one of the following, based on the value of this client's runtime.GOARCH value:
- 386
- amd64
- armv6l
Since these two often appear together, a convenience placeholder `${platform}` expands to the equivalent of `${os}-${arch}`.
Both of these paramters also support the syntax ${var=possible,values}. What this means is that the package line will be expanded if, and only if, var equals one of the possible values. If that var does not match a possible value, the line is ignored. This allows you to do, e.g.:
path/to/package/${os=windows} windows_release
path/to/package/${os=linux} linux_release
# no version for mac
path/to/posix/tool/${os=mac,linux} some_tag:value
That's all there is to it.
Example ¶
Here is an example ensure file which demonstrates all the various features.
# This is an ensure file!
$ServiceURL https://chrome-infra-packages.appspot.com/
# This is the cipd client itself
infra/tools/cipd/${os}-${arch} latest
@Subdir python
python/wheels/pip version:8.1.2
# use the convenience placeholder
python/wheels/coverage/${platform} version:4.1
@Subdir infra/support
infra/some/other/package deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type File ¶
type File struct {
ServiceURL string
PackagesBySubdir map[string]PackageSlice
}
File is an in-process representation of the 'ensure file' format.
func ParseFile ¶
ParseFile parses an ensure file from the given reader. See the package docs for the format of this file.
This file will contain unresolved template strings for package names as well as unpinned package versions. Use File.Resolve() to obtain resolved+pinned versions of these.
func (*File) Resolve ¶
func (f *File) Resolve(rslv VersionResolver) (*ResolvedFile, error)
Resolve takes the current unresolved File and expands all package templates using common.TemplateArgs(), and also resolves all versions with the provided VersionResolver.
func (*File) ResolveWith ¶
func (f *File) ResolveWith(rslv VersionResolver, templateArgs map[string]string) (*ResolvedFile, error)
ResolveWith takes the current unresolved File and expands all package templates using the provided values of arch and os, and also resolves all versions with the provided VersionResolver.
templateArgs is a mapping of expansion parameter to value. Usually you'll want to pass common.TemplateArgs().
type PackageDef ¶
type PackageDef struct {
PackageTemplate string
UnresolvedVersion string
// LineNo is set while parsing an ensure file by the ParseFile method. It is
// used by File.Resolve to give additional context if an error occurs.
LineNo int
}
PackageDef defines a package line parsed out of an ensure file.
func (*PackageDef) Resolve ¶
func (p *PackageDef) Resolve(rslv VersionResolver, templateArgs map[string]string) (pin common.Pin, err error)
Resolve takes a Package definition containing a possibly templated package name, and a possibly unresolved version string and attempts to resolve them into a Pin.
templateArgs is a mapping of expansion parameter to value. Usually you'll want to pass common.TemplateArgs().
func (*PackageDef) String ¶
func (p *PackageDef) String() string
type PackageSlice ¶
type PackageSlice []PackageDef
PackageSlice is a sortable slice of PackageDef
func (PackageSlice) Len ¶
func (ps PackageSlice) Len() int
func (PackageSlice) Less ¶
func (ps PackageSlice) Less(i, j int) bool
func (PackageSlice) Swap ¶
func (ps PackageSlice) Swap(i, j int)
type ResolvedFile ¶
type ResolvedFile struct {
ServiceURL string
PackagesBySubdir common.PinSliceBySubdir
}
ResolvedFile only contains valid, fully-resolved information and is the result of calling File.Resolve.
type VersionResolver ¶
VersionResolver is expected to tranform a {PackageName, Version} tuple into a resolved instance ID.
- `pkg` is guaranteed to pass common.ValidatePackageName
- `vers` is guaranteed to pass common.ValidateInstanceVersion
The returned `instID` will NOT be checked (so that you can provide a pass-through resolver, if you like).
Source Files