blob: 7f0f7c09c52b798b0580a3e27fecc9141c538c08 [file] [log] [blame]
// Copyright 2017 The LUCI Authors.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
// 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 essentially 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 package, or a directive.
// Comments
// A comment begins with a # and goes to the end of the line. It is ignored.
// Example:
// # This is a comment. It has no effect.
// Settings
// A setting looks like `$name value`. Settings are global and can only be set
// once per file. The following settings are allowed:
// - `$ServiceURL <url>` is the url for the CIPD service. It can be used in
// lieu of the -service-url command line parameter.
// - `$VerifiedPlatform <platform> [ <platform>]*` allows the manifest to
// specify a list of ${platform} expansions to use for verification.
// Multiple $VerifiedPlatform directives can be specified, and will
// accumulate.
// - `$ParanoidMode NotParanoid|CheckPresence|CheckIntegrity` controls how
// paranoid CIPD should be when checking the state of already installed
// packages. `NotParanoid` (default) indicates that CIPD should trust that
// no one is messing with the installation root directory. `CheckPresence`
// indicates CIPD should verify all files that are supposed to be already
// installed are indeed present (this incurs additional overhead). And
// finally `CheckIntegrity` will verify that files weren't modified since
// they were installed (this incurs even more overhead).
// - `$ResolvedVersions <filename>` is a path (either relative to the ensure
// file or absolute) to a file that contains "frozen" instance IDs (hashes)
// of all packages for all verified platforms, resolved at the time the
// "frozen" file was generated by `cipd ensure-file-resolve`. The CIPD
// client will use these instance IDs (instead of contacting the backend)
// when installing packages in `cipd ensure`. Using this file allows to
// cryptographically bind the intended state of the deployment to a git
// commit, since all hashes of all packages become part of the git commit
// object. Use this if you want to reduce trust in the CIPD backend and root
// in the git server instead.
// - `$OverrideInstallMode copy` forces all packages in this ensure-file to be
// installed with copy mode, regardless of what the package manifests list.
// `symlink` mode only works on mac/linux, and causes more problems than it
// solves. We recommend that all ensure files have this setting, and in the
// future this will become automatically set. See for
// additional discussion.
// Package Definitions
// A package line looks like `<package_template> <version>`. Package templates
// are CIPD package names, with optional expansion parameters `${os}`,
// `${arch}`, and `${platform}`. 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, the convenience placeholder
// `${platform}` expands to the equivalent of `${os}-${arch}`.
// All of these parameters 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
// # no version for windows
// Directives
// A directive looks like `@name value`. Directives are 'sticky' and apply until
// the next same-name directive. The following directive names are allowed:
// - `@Subdir` allows you to change the subdirectory that subsequent packages
// are installed to.
// * The subdir value is always 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.
// * You can reset the directory back to root by doing `@Subdir` by itself,
// without a value.
// * @Subdir directives also support expansion parameters `${os}`, `${arch}`
// and `${platform}`. Using a subdir expansion like `${param=val}` will
// cause that subdirectory, and any packages in it, to only exist if the
// param matches one of the values.
// Example
// Here is an example ensure file which demonstrates all the various features.
// # This is an ensure file!
// $ServiceURL
// $ParanoidMode CheckPresence
// $ResolvedVersions cipd_lock.versions
// # 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
// # only exists on windows machines
// @Subdir support/${os=windows}-${arch}
// some/support/package latest
// some/other/support/package latest
// # Always exists, but the directory changes based on the os
// @Subdir platform/${os}
// a/platform/package latest
package ensure