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 IsFromDirective(repo *rule.Rule) bool
• func ListRepositories(workspace *rule.File) (repos []*rule.Rule, repoFileMap map[string]*rule.File, err error)
• 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) PopulateFromGoMod(goModPath 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)
  • func (r *RemoteCache) RootStatic(importPath string) (root, name string, err error)
• type Repo
• type RepoMacro
  • func ParseRepositoryMacroDirective(directive string) (*RepoMacro, 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 IsFromDirective

func IsFromDirective(repo *rule.Rule) bool

IsFromDirective returns true if the repo rule was defined from a directive.

func ListRepositories

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

ListRepositories extracts metadata about repositories declared in a file.

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) PopulateFromGoMod

func (r *RemoteCache) PopulateFromGoMod(goModPath string) (err error)

PopulateFromGoMod reads a go.mod file and adds entries to the r.root map based on the file's require directives. PopulateFromGoMod does not override entries already in the cache. This should help avoid going out to the network for external dependency resolution, and it should let static dependency resolution succeed more often.

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.

func (*RemoteCache) RootStatic

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

RootStatic checks the cache to see if the provided importpath matches any known roots. If no matches are found, rather than going out to the network to determine the root, nothing is returned.

type Repo

type Repo struct {
	Name, GoPrefix, Remote, VCS string
}

Repo describes details of a Go repository known in advance. It is used to initialize RemoteCache so that some repositories don't need to be looked up.

DEPRECATED: Go-specific details should be removed from RemoteCache, and lookup logic should be moved to language/go. This means RemoteCache will need to be initialized in a different way.

type RepoMacro

type RepoMacro struct {
	Path    string
	DefName string
	Leveled bool
}

func ParseRepositoryMacroDirective

func ParseRepositoryMacroDirective(directive string) (*RepoMacro, error)

ParseRepositoryMacroDirective checks the directive is in proper format, and splits path and defName. Repository_macros prepended with a "+" (e.g. "# gazelle:repository_macro +file%def") indicates a "leveled" macro, which loads other macro files.