repo

Documentation

Overview

Package repo provides functionality for managing Go repository rules.

UNSTABLE: The exported APIs in this package may change. In the future, language extensions should implement an interface for repository rule management. The update-repos command will call interface methods, and most if this package's functionality will move to language/go. Moving this package to an internal directory would break existing extensions, since RemoteCache is referenced through the resolve.Resolver interface, which extensions are required to implement.

Index

• func FindExternalRepo(repoRoot, name string) (string, error)
• func GenerateRule(repo Repo) *rule.Rule
• func ImportRepoRules(filename string, repoCache *RemoteCache) ([]*rule.Rule, error)
• func MergeRules(genRules []*rule.Rule, existingRules map[*rule.File][]string, ...) []*rule.File
• type RemoteCache
  • func NewRemoteCache(knownRepos []Repo) (r *RemoteCache, cleanup func() error)
  • func (r *RemoteCache) Head(remote, vcs string) (commit, tag string, err error)
  • func (r *RemoteCache) Mod(importPath string) (modPath, name string, err error)
  • func (r *RemoteCache) ModVersion(modPath, query string) (name, version, sum string, err error)
  • func (r *RemoteCache) Remote(root string) (remote, vcs string, err error)
  • func (r *RemoteCache) Root(importPath string) (root, name string, err error)
• type Repo
  • func ListRepositories(workspace *rule.File) (repos []Repo, repoNamesByFile map[*rule.File][]string, err error)
  • func UpdateRepo(rc *RemoteCache, modPath string) (Repo, error)

Functions

func FindExternalRepo

func FindExternalRepo(repoRoot, name string) (string, error)

FindExternalRepo attempts to locate the directory where Bazel has fetched the external repository with the given name. An error is returned if the repository directory cannot be located.

func GenerateRule

func GenerateRule(repo Repo) *rule.Rule

GenerateRule returns a repository rule for the given repository that can be written in a WORKSPACE file.

func ImportRepoRules

func ImportRepoRules(filename string, repoCache *RemoteCache) ([]*rule.Rule, error)

ImportRepoRules reads the lock file of a vendoring tool and returns a list of equivalent repository rules that can be merged into a WORKSPACE file. The format of the file is inferred from its basename.

func MergeRules

func MergeRules(genRules []*rule.Rule, existingRules map[*rule.File][]string, destFile *rule.File, kinds map[string]rule.KindInfo, pruneRules bool) []*rule.File

MergeRules merges a list of generated repo rules with the already defined repo rules, and then updates each rule's underlying file. If the generated rule matches an existing one, then it inherits the file where the existing rule was defined. If the rule is new then its file is set as the destFile parameter. If pruneRules is set, then this function will prune any existing rules that no longer have an equivalent repo defined in the Gopkg.lock/go.mod file. A list of the updated files is returned.

Types

type RemoteCache

type RemoteCache struct {
	// RepoRootForImportPath is vcs.RepoRootForImportPath by default. It may
	// be overridden so that tests may avoid accessing the network.
	RepoRootForImportPath func(string, bool) (*vcs.RepoRoot, error)

	// HeadCmd returns the latest commit on the default branch in the given
	// repository. This is used by Head. It may be stubbed out for tests.
	HeadCmd func(remote, vcs string) (string, error)

	// ModInfo returns the module path and version that provides the package
	// with the given import path. This is used by Mod. It may be stubbed
	// out for tests.
	ModInfo func(importPath string) (modPath string, err error)

	// ModVersionInfo returns the module path, true version, and sum for
	// the module that provides the package with the given import path.
	// This is used by ModVersion. It may be stubbed out for tests.
	ModVersionInfo func(modPath, query string) (version, sum string, err error)
	// contains filtered or unexported fields
}

RemoteCache stores information about external repositories. The cache may be initialized with information about known repositories, i.e., those listed in the WORKSPACE file and mentioned on the command line. Other information is retrieved over the network.

Public methods of RemoteCache may be slow in cases where a network fetch is needed. Public methods may be called concurrently.

TODO(jayconrod): this is very Go-centric. It should be moved to language/go. Unfortunately, doing so would break the resolve.Resolver interface.

func NewRemoteCache

func NewRemoteCache(knownRepos []Repo) (r *RemoteCache, cleanup func() error)

NewRemoteCache creates a new RemoteCache with a set of known repositories. The Root and Remote methods will return information about repositories listed here without accessing the network. However, the Head method will still access the network for these repositories to retrieve information about new versions.

A cleanup function is also returned. The caller must call this when RemoteCache is no longer needed. RemoteCache may write files to a temporary directory. This will delete them.

func (*RemoteCache) Head

func (r *RemoteCache) Head(remote, vcs string) (commit, tag string, err error)

Head returns the most recent commit id on the default branch and latest version tag for the given remote repository. The tag "" is returned if no latest version was found.

TODO(jayconrod): support VCS other than git. TODO(jayconrod): support version tags. "" is always returned.

func (*RemoteCache) Mod

func (r *RemoteCache) Mod(importPath string) (modPath, name string, err error)

Mod returns the module path for the module that contains the package named by importPath. The name of the go_repository rule for the module is also returned. For example, calling Mod on "github.com/foo/bar/v2/baz" would give the module path "github.com/foo/bar/v2" and the name "com_github_foo_bar_v2".

If a known repository *could* provide importPath (because its "importpath" is a prefix of importPath), Mod will assume that it does. This may give inaccurate results if importPath is in an undeclared nested module. Run "gazelle update-repos -from_file=go.mod" first for best results.

If no known repository could provide importPath, Mod will run "go list" to find the module. The special patterns that Root uses are ignored. Results are cached. Use GOPROXY for faster results.

func (*RemoteCache) ModVersion

func (r *RemoteCache) ModVersion(modPath, query string) (name, version, sum string, err error)

ModVersion looks up information about a module at a given version. The path must be the module path, not a package within the module. The version may be a canonical semantic version, a query like "latest", or a branch, tag, or revision name. ModVersion returns the name of the repository rule providing the module (if any), the true version, and the sum.

func (*RemoteCache) Remote

func (r *RemoteCache) Remote(root string) (remote, vcs string, err error)

Remote returns the VCS name and the remote URL for a repository with the given root import path. This is suitable for creating new repository rules.

func (*RemoteCache) Root

func (r *RemoteCache) Root(importPath string) (root, name string, err error)

Root returns the portion of an import path that corresponds to the root directory of the repository containing the given import path. For example, given "golang.org/x/tools/go/loader", this will return "golang.org/x/tools". The workspace name of the repository is also returned. This may be a custom name set in WORKSPACE, or it may be a generated name based on the root path.

type Repo

type Repo struct {
	// Name is the value of the "name" attribute of the repository rule.
	Name string

	// GoPrefix is the portion of the Go import path for the root of this
	// repository. Usually the same as Remote.
	GoPrefix string

	// Commit is the revision at which a repository is checked out (for example,
	// a Git commit id).
	Commit string

	// Tag is the name of the version at which a repository is checked out.
	Tag string

	// Remote is the URL the repository can be cloned or checked out from.
	Remote string

	// VCS is the version control system used to check out the repository.
	// May also be "http" for HTTP archives.
	VCS string

	// Version is the semantic version of the module to download. Exactly one
	// of Version, Commit, and Tag must be set.
	Version string

	// Sum is the hash of the module to be verified after download.
	Sum string

	// Replace is the Go import path of the module configured by the replace
	// directive in go.mod.
	Replace string
}

Repo describes an external repository rule declared in a Bazel WORKSPACE file or macro file.

func ListRepositories

func ListRepositories(workspace *rule.File) (repos []Repo, repoNamesByFile map[*rule.File][]string, err error)

ListRepositories extracts metadata about repositories declared in a file.

func UpdateRepo

func UpdateRepo(rc *RemoteCache, modPath string) (Repo, error)

UpdateRepo returns an object describing a repository at the most recent commit or version tag.

This function uses RemoteCache to retrieve information about the repository. Depending on how the RemoteCache was initialized and used earlier, some information may already be locally available. Frequently though, information will be fetched over the network, so this function may be slow.