其他分享
首页 > 其他分享> > Gopkg.toml简明介绍

Gopkg.toml简明介绍

作者:互联网

Gopkg.toml是在执行dep init时创建,主要被手动编辑,可以使用以下规则声明方式来改变dep的行为:

 

要注意的是,任何required,或者ignored字段,必须出现在所有的[[constraint]]以及[[override]]之前

 

 

 

依赖规则[[constraint]] and [[override]]

都允许包含如下字段

name - the import path corresponding to the source root of a dependency (generally: where the VCS root is)

A full example (invalid, actually, as it has more than one version rule, for illustrative purposes) of either one of these stanzas looks like this:

[[constraint]]
  # Required: the root import path of the project being constrained.
  name = "github.com/user/project"
  # Recommended: the version constraint to enforce for the project.
  # Note that only one of "branch", "version" or "revision" can be specified.
  version = "1.0.0"
  branch = "master"
  revision = "abc123"

  # Optional: an alternate location (URL or import path) for the project's source.
  source = "https://github.com/myfork/package.git"

  # Optional: metadata about the constraint or override that could be used by other independent systems
  [metadata]
  key1 = "value that convey data to other systems"
  system1-data = "value that is used by a system"
  system2-data = "value that is used by another system"

[[constraint]]

[[constraint]] stanza defines rules for how a direct dependency must be incorporated into the dependency graph. Dep respects these declarations from the current project's Gopkg.toml, as well as the Gopkg.toml files found in any dependencies.

Use this for: having a direct dependency use a specific branch, version range, revision, or alternate source (such as a fork).

[[override]]

An [[override]] stanza differs from a [[constraint]] in that it applies to all dependencies, direct and transitive, and supersedes all other [[constraint]] declarations for that project. However, only overrides from the current project's Gopkg.toml are incorporated.

Use this for: Overrides are primarily intended as a way of eliminating disagreements between multiple irreconcilable [[constraint]] declarations on a single dependency. However, they will also be your primary recourse if you need to constrain a transitive dependency's version?

Overrides should be used cautiously and temporarily, when possible.

source

source rule can specify an alternate location from which the name'd project should be retrieved. It is primarily useful for temporarily specifying a fork for a repository.

source rules are generally brittle and should only be used when there is no other recourse. Using them to try to circumvent network reachability issues is typically an antipattern.

 

 

版本号规则

[[constraint]]和[[override]]都可以指定版本号规则,可以使用version, branch, revision其中之一来指定(也只能选择一种);

 

 

 

version对应于VCS的tag,或者一个版本号范围(or a semantic version, or a range of semantic version):

version="=1.2.3"用来指定确切的版本号,也就是1.2.3这个版本;

version="!=1.2.3"用来排除某个版本号,也就是说只要不是1.2.3这个版本就行;

version="1.2.3-2.1.2"用来指定版本号范围;

类似还有:

>, >=, <, <=

不过,你可能没想到的还有,

version = "~1.2.3"意思是,只允许最后一段版本号变化;

 

version = "^1.2.3"意思是,除了非0的最大的一段版本号不允许变化,后面的版本号都可以变化;

^1.2.3 means 1.2.3 <= X < 2.0.0

^0.2.3 means 0.2.3 <= X < 0.3.0

^0.0.3 means 0.0.3 <= X < 0.1.0

 

另外还允许通配符(肯定脑子进水了,才这样去做事情)。

 

所以,要想锁定一个版本号,你要这样做:

[[constraint]]

name = "github.com/pkg/errors"

version = "=0.8.0"

 

有时候,有些仓库不会使用version,而是使用branch。语法是:

branch="feature_support_dynamic_routing"

然而,如果你指定branch="master"不是个好主意。因为master从来不意味着不再改变。

 

 

一般情况下,应该优先使用语义上的版本(you should prefer semantic versions to branches, when a project has made them available),而不是branch。

revision是底层的不可变的标识符,就像git commit的sha1. (While it is allowed to constrain to a revision, doing so is almost always an antipattern)

 

老夫看的萌萌的,一句话就是尽量别用revision来约束。

 

 

 

 

 The required and ignored rules manipulate that graph, in ways that are roughly dual to each other: required adds import paths to the graph, and ignored removes them.

required

required lists a set of packages (not projects) that must be included in Gopkg.lock. This list is merged with the set of packages imported by the current project.

required = ["github.com/user/thing/cmd/thing"]

Use this for: linters, generators, and other development tools that

Please note that this only pulls in the sources of these dependencies. It does not install or compile them. So, if you need the tool to be installed you should still run the following (manually or from a Makefile) after each dep ensure:

cd vendor/pkg/to/install
go install .

This only works reliably if this is the only project to install these executables. This is not enough if you want to be able to run a different version of the same executable depending on the project you're working. In that case you have to use a different GOBIN for each project, by doing something like this before running the above commands:

export GOBIN=$PWD/bin
export PATH=$GOBIN:$PATH

You might also try virtualgo, which installs dependencies in the required list automatically in a project specific GOBIN.

ignored

用来指定dep静态分析代码生成Gopkg.lock时需要忽略的包列表(如果包依赖了其他包X,并且X包只在这里被依赖,那么X也将被忽略),注意这里说的包可以是dependency中的包。ignored = ["github.com/user/project/badpkg"]

你还是可以用通配符的:

ignored = ["github.com/user/project/badpkg*"]

 

 

metadata可以在Gopkg.toml中root级别存在,也可以在constraint, override中存在。

dep会假装看不见metadata.

 

 

 

 

 

 

 

prune defines the global and per-project prune options for dependencies. The options determine which files are discarded when writing the vendor/ tree.

The following are the current available options:

Out of an abundance of caution, dep non-optionally preserves files that may have legal significance.

Pruning options are disabled by default. However, generating a Gopkg.toml via dep init will add lines to enable go-tests and unused-packages prune options at the root level.

[prune]
  go-tests = true
  unused-packages = true

The same prune options can be defined per-project. An additional name field is required and, as with [[constraint]] and [[override]], should be a source root, not just any import path.

[prune]
  non-go = true

  [[prune.project]]
    name = "github.com/project/name"
    go-tests = true
    non-go = false

Almost all projects will be fine without setting any project-specific rules, and enabling the following pruning rules globally:

[prune]
  unused-packages = true
  go-tests = true

It is usually safe to set non-go = true, as well. However, as dep only has a clear model for the role played by Go files, and non-Go files necessarily fall outside that model, there can be no comparable general definition of safety.

 

noverify

The noverify field is a list of paths, typically project roots, to exclude from vendor verification.

Dep uses per-project hash digests, computed after pruning and recorded in Gopkg.lock, to determine if the contents of vendor/ are as expected. If the recorded digest and the hash of the corresponding tree in vendor/ differ, that project is considered to be out of sync:

It is strongly recommended that you leave vendor/ unmodified, in whatever state dep puts it in. However, this isn't always feasible. If you have no choice but to modify vendor/ for a particular project, then add the project root for that project to noverify. This will have the following effects:

noverify can also be used to preserve certain excess paths that would otherwise be removed; for example, adding WORKSPACE to the noverify list would allow you to preserve vendor/WORKSPACE, which can help with some Bazel-based workflows.

Scope

dep evaluates

only in the root project, i.e. the project where dep runs. For example, if you have a project: github.com/urname/goproject, and github.com/foo/bar is a dependency for your project, then dep will evaluate the Gopkg.toml files of these projects as follows:

github.com/urname/goprojectgithub.com/foo/bar
[[constraint]] ✔[[constraint]] ✔
[[override]] ✔[[override]] ✖
required ✔required ✖
ignored ✔ignored ✖

✔ : Evaluated ✖ : Not evaluated

Example

Here's a sample Gopkg.toml with most elements present.

required = ["github.com/user/thing/cmd/thing"]

ignored = [
  "github.com/user/project/pkgX",
  "bitbucket.org/user/project/pkgA/pkgY"
]

noverify = ["github.com/something/odd"]

[metadata]
codename = "foo"

[prune]
  non-go = true

  [[prune.project]]
    name = "github.com/project/name"
    go-tests = true
    non-go = false

[[constraint]]
  name = "github.com/user/project"
  version = "1.0.0"

  [constraint.metadata]
  property1 = "value1"
  property2 = 10

[[constraint]]
  name = "github.com/user/project2"
  branch = "dev"
  source = "github.com/myfork/project2"

[[override]]
  name = "github.com/x/y"
  version = "2.4.0"

  [override.metadata]
  propertyX = "valueX"

标签:github,constraint,dep,简明,project,Gopkg,version,toml,com
来源: https://blog.csdn.net/herongoal/article/details/117228887