cache

type BuildCache ¶

type BuildCache struct {
	GOOS      string
	GOARCH    string
	GOROOT    string
	GOPATH    string
	BuildTags []string

	// Version should be set to compiler.Version
	Version string

	// TestedPackage is the import path of the package being tested, or
	// empty when not building for tests. The package under test is built
	// with *_test.go sources included so we should always skip reading
	// and writing cache in that case. Since we are caching prior to
	// type-checking for generics, any package importing the package under
	// test should be unaffected.
	TestedPackage string
}

BuildCache manages build artifacts that are cached for incremental builds.

Cache is designed to be non-durable: any store and load errors are swallowed and simply lead to a cache miss. The caller must be able to handle cache misses. Nil pointer to BuildCache is valid and simply disables caching.

BuildCache struct fields represent build parameters which change invalidates the cache. For example, any artifacts that were cached for a Linux build must not be reused for a non-Linux build. GopherJS version change also invalidates the cache. It is callers responsibility to ensure that artifacts passed the Store function were generated with the same build parameters as the cache is configured.

There is no upper limit for the total cache size. It can be cleared programmatically via the Clear() function, or the user can just delete the directory if it grows too big.

The cached files are gzip compressed, therefore each file uses the gzip checksum as a basic integrity check performed after reading the file.

TODO(nevkontakte): changes in the input sources or dependencies doesn't currently invalidate the cache. This is handled at the higher level by checking cached package timestamp against loaded package modification time.

func (bc *BuildCache) Load(c Cacheable, importPath string, srcModTime time.Time) bool

func (bc *BuildCache) Store(c Cacheable, importPath string, buildTime time.Time) bool

func (bc BuildCache) String() string

type Cache ¶ added in v1.20.0

type Cache interface {
	// Store stores the package with the given import path in the cache.
	// Any error inside this method will cause the cache not to be persisted.
	//
	// The passed in buildTime is used to determine if the package is out-of-date when reloaded.
	// Typically it should be set to the srcModTime or time.Now().
	Store(c Cacheable, importPath string, buildTime time.Time) bool

	// Load reads a previously cached package at the given import path,
	// if it was previously stored.
	//
	// The loaded package would have been built with the same configuration as
	// the build cache was.
	Load(c Cacheable, importPath string, srcModTime time.Time) bool
}

Cache defines methods to store and load cacheable objects.

type Cacheable ¶ added in v1.20.0

type Cacheable interface {
	Write(encode func(any) error) error
	Read(decode func(any) error) error
}

Cacheable defines methods to serialize and deserialize cachable objects. This object should represent a package's build artifact.

The encode and decode functions are typically wrappers around gob.Encoder.Encode and gob.Decoder.Decode, but other formats are possible as well, the same way as FileSet.Write and FileSet.Read work with any encode/decode functions.