Documentation
¶
Overview ¶
Package dep defines an interface for listing raw dependencies and resolving them, and registering handlers to perform these tasks.
Toolchains should register two handlers to list and resolve dependencies:
*Lister:* this performs a quick pass over the declared dependencies of a source unit and emits whatever information can be determined without an expensive dependency resolution process. For example, the Go lister simply lists the packages imported by each file in the source unit.
*Resolver:* this resolves a RawDependency (emitted from a Lister), determining the defining repository, source unit, version, etc. For example, the Ruby resolver queries rubygems.org (and consults a hard-coded list) to determine this information. Note that the only necessary field in ResolvedTarget is ToRepoCloneURL; the other fields are for future use.
In code, this looks like:
package my_toolchain
func init() {
dep.RegisterLister(PythonPackage{}, pip)
dep.RegisterResolver("pip-package", pip)
}
type pip struct {}
func (p *pip) List(dir string, unit unit.SourceUnit, c *config.Repository) ([]*dep.RawDependency, error) {
// return each line in requirements.txt, perhaps (or do something more robust in Docker)
// return something like:
return []*dep.RawDependency{{TargetType: "pip-package", Target: "Django==1.6"}}, nil
}
func (p *pip) Resolve(rawDep *dep.RawDependency, c *config.Repository) (*dep.ResolvedTarget, error) {
// query pypi.python.org or use cheerio, and then return something like:
return &dep.ResolvedTarget{
ToRepoCloneURL: "git://github.com/django/django.git",
}, nil
}
Separating the list and resolution steps allows us to more easily pare down the total number of unique resolutions we must perform. If multiple source units all depend on the same external library, then those duplicate RawDependencies only yield a single call to Resolve. This saves even more work when finding dependencies for all of a repository's history (because most commits likely won't add or update dependency declarations).
TODO(sqs): update these docs after we removed deplist
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Resolution ¶
type Resolution struct {
// Raw is the original raw dep that this was resolution was attempted on.
Raw interface{}
// Target is the resolved dependency, if resolution succeeds.
Target *ResolvedTarget `json:",omitempty"`
// Error is the resolution error, if any.
Error string `json:",omitempty"`
}
START Resolution OMIT Resolution is the result of dependency resolution: either a successfully resolved target or an error.
func (*Resolution) KeyId ¶
func (r *Resolution) KeyId() string
func (*Resolution) RawKeyId ¶
func (r *Resolution) RawKeyId() (string, error)
type ResolveDepsRule ¶
type ResolveDepsRule struct {
Unit *unit.SourceUnit
Tool *srclib.ToolRef
// contains filtered or unexported fields
}
func (*ResolveDepsRule) Prereqs ¶
func (r *ResolveDepsRule) Prereqs() []string
func (*ResolveDepsRule) Recipes ¶
func (r *ResolveDepsRule) Recipes() []string
func (*ResolveDepsRule) SourceUnit ¶
func (r *ResolveDepsRule) SourceUnit() *unit.SourceUnit
func (*ResolveDepsRule) Target ¶
func (r *ResolveDepsRule) Target() string
type ResolvedDep ¶
type ResolvedDep struct {
// FromRepo is the repository from which this dependency originates.
FromRepo string `json:",omitempty"`
// FromCommitID is the VCS commit in the repository that this dep was found
// in.
FromCommitID string `json:",omitempty"`
// FromUnit is the source unit name from which this dependency originates.
FromUnit string
// FromUnitType is the source unit type from which this dependency originates.
FromUnitType string
// ToRepo is the repository containing the source unit that is depended on.
//
// TODO(sqs): include repo clone URLs as well, so we can add new
// repositories from seen deps.
ToRepo string
// ToUnit is the name of the source unit that is depended on.
ToUnit string
// ToUnitType is the type of the source unit that is depended on.
ToUnitType string
// ToVersion is the version of the dependent repository (if known),
// according to whatever version string specifier is used by FromRepo's
// dependency management system.
ToVersionString string
// ToRevSpec specifies the desired VCS revision of the dependent repository
// (if known).
ToRevSpec string
}
func ResolutionsToResolvedDeps ¶
func ResolutionsToResolvedDeps(ress []*Resolution, unit *unit.SourceUnit, fromRepo string, fromCommitID string) ([]*ResolvedDep, error)
ResolutionsToResolvedDeps converts a []*Resolution for a source unit to a []*ResolvedDep (which is a data structure that includes the source unit type/name/etc., so elements are meaningful even if the associated source unit struct is not available).
Resolutions with Errors are omitted from the returned slice and no such errors are returned.
type ResolvedTarget ¶
type ResolvedTarget struct {
// ToRepoCloneURL is the clone URL of the repository that is depended on.
//
// When graphers emit ResolvedDependencies, they should fill in this field,
// not ToRepo, so that the dependent repository can be added if it doesn't
// exist. The ToRepo URI alone does not specify enough information to add
// the repository (because it doesn't specify the VCS type, scheme, etc.).
ToRepoCloneURL string
// ToUnit is the name of the source unit that is depended on.
ToUnit string
// ToUnitType is the type of the source unit that is depended on.
ToUnitType string
// ToVersion is the version of the dependent repository (if known),
// according to whatever version string specifier is used by FromRepo's
// dependency management system.
ToVersionString string
// ToRevSpec specifies the desired VCS revision of the dependent repository
// (if known).
ToRevSpec string
}
START ResolvedTarget OMIT ResolvedTarget represents a resolved dependency target.
Source Files