build

Documentation

Overview

Package build implements utilities to collect VDL build information and run the parser and compiler.

VDL Packages

VDL is organized into packages, where a package is a collection of one or more source files. The files in a package collectively define the types, constants, services and errors belonging to the package; these are called package elements.

The package elements in package P may be used in another package Q. First package Q must import package P, and then refer to the package elements in P. Imports define the package dependency graph, which must be acyclic.

Build Strategy

The steps to building a VDL package P:

1. Compute the transitive closure of P's dependencies DEPS.
2. Sort DEPS in dependency order.
3. Build each package D in DEPS.
3. Build package P.

Building a package P requires that all elements used by P are understood, including elements defined outside of P. The only way for a change to package Q to affect the build of P is if Q is in the transitive closure of P's package dependencies. However there may be false positives; the change to Q might not actually affect P.

The build process may perform more work than is strictly necessary, because of these false positives. However it is simple and correct.

The TransitivePackages* functions implement build steps 1 and 2.

The Build* functions implement build steps 3 and 4.

Other functions provide related build information and utilities.

Index

• func BuildConfig(fileName string, src io.Reader, implicit *vdl.Type, imports []string, ...) *vdl.Value
• func BuildConfigValue(fileName string, src io.Reader, imports []string, env *compile.Env, ...)
• func BuildExprs(data string, types []*vdl.Type, env *compile.Env) []*vdl.Value
• func BuildPackage(pkg *Package, env *compile.Env) *compile.Package
• func IsDirPath(path string) bool
• func IsImportPath(path string) bool
• func ParsePackage(pkg *Package, opts parse.Opts, errs *vdlutil.Errors) (pfiles []*parse.File)
• func RootDir(errs *vdlutil.Errors) string
• func SrcDirs(errs *vdlutil.Errors) []string
• type Opts
• type Package
  • func TransitivePackages(paths []string, mode UnknownPathMode, opts Opts, errs *vdlutil.Errors) []*Package
  • func TransitivePackagesForConfig(fileName string, src io.Reader, opts Opts, errs *vdlutil.Errors) []*Package
  • func (p *Package) CloseFiles() error
  • func (p *Package) OpenFiles() (map[string]io.Reader, error)
• type UnknownPathMode
  • func (m UnknownPathMode) String() string

Functions

func BuildConfig

func BuildConfig(fileName string, src io.Reader, implicit *vdl.Type, imports []string, env *compile.Env) *vdl.Value

BuildConfig parses and compiles the given config src and returns it. Errors are reported in env; fileName is only used for error reporting.

The implicit type is applied to the exported config const; untyped consts and composite literals with no explicit type assume the implicit type. Errors are reported if the implicit type isn't assignable from the final value. If the implicit type is nil, the exported config const must be explicitly typed.

All packages that the config src depends on must have already been compiled and populated into env. The imports are injected into the parsed src, behaving as if the src had listed the imports explicitly.

func BuildConfigValue

func BuildConfigValue(fileName string, src io.Reader, imports []string, env *compile.Env, value interface{})

BuildConfigValue is a convenience function that runs BuildConfig, and then converts the result into value. The implicit type used by BuildConfig is inferred from the value.

func BuildExprs

func BuildExprs(data string, types []*vdl.Type, env *compile.Env) []*vdl.Value

BuildExprs parses and compiles the given data into a slice of values. The input data is specified in VDL syntax, with commas separating multiple expressions. There must be at least one expression specified in data. Errors are reported in env.

The given types specify the type of each returned value with the same slice position. If there are more types than returned values, the extra types are ignored. If there are fewer types than returned values, the last type is used for all remaining values. Nil entries in types are allowed, and indicate that the expression itself must be fully typed.

All imports that the input data depends on must have already been compiled and populated into env.

func BuildPackage

func BuildPackage(pkg *Package, env *compile.Env) *compile.Package

BuildPackage parses and compiles the given pkg, updates env with the compiled package and returns it. Errors are reported in env.

All imports that pkg depend on must have already been compiled and populated into env.

func IsDirPath

func IsDirPath(path string) bool

IsDirPath returns true iff the path is absolute, or begins with a . or .. element. The path denotes the package in that directory.

func IsImportPath

func IsImportPath(path string) bool

IsImportPath returns true iff !IsDirPath. The path P denotes the package in directory DIR/src/P, for some DIR listed in SrcDirs.

func ParsePackage

func ParsePackage(pkg *Package, opts parse.Opts, errs *vdlutil.Errors) (pfiles []*parse.File)

ParsePackage parses the given pkg with the given parse opts, and returns a slice of parsed files, sorted by name. Errors are reported in errs.

func RootDir

func RootDir(errs *vdlutil.Errors) string

RootDir returns the VDL root directory, based on the VDLROOT environment variable.

VDLROOT is a single directory specifying the location of the standard vdl packages. It has the same requirements as VDLPATH components. The returned string may be empty, if VDLROOT is empty or unset.

func SrcDirs

func SrcDirs(errs *vdlutil.Errors) []string

SrcDirs returns a list of package root source directories, based on the VDLPATH and VDLROOT environment variables.

VDLPATH is a list of directories separated by filepath.ListSeparator; e.g. the separator is ":" on UNIX, and ";" on Windows. The path below each VDLPATH directory determines the vdl import path.

See RootDir for details on VDLROOT.

Types

type Opts

type Opts struct {
	// VDLConfigName specifies the name of the optional config file in each vdl
	// source package.  If empty we use "vdl.config" by default.
	VDLConfigName string
}

Opts specifies additional options for collecting build information.

type Package

type Package struct {
	// Name is the name of the package, specified in the vdl files.
	// E.g. "bar"
	Name string
	// IsRoot is true iff this package is a vdlroot standard package.
	IsRoot bool
	// IsBuiltIn is true iff the data for this package is built-in to the binary,
	// rather than read off files from the filesystem.
	IsBuiltIn bool
	// Path is the package path; the path used in VDL import clauses.
	// E.g. "foo/bar".
	Path string
	// GenPath is the package path to use for code generation.  It is the same as
	// Path, except for vdlroot standard packages.
	// E.g. "v.io/v23/vdlroot/time"
	GenPath string
	// Dir is the absolute directory containing the package files.
	// E.g. "/home/user/vanadium/vdl/src/foo/bar"
	Dir string
	// BaseFileNames is the list of sorted base vdl file names for this package.
	// Join these with Dir to get absolute file names.
	BaseFileNames []string
	// Config is the configuration for this package, specified by an optional
	// "vdl.config" file in the package directory.  If no "vdl.config" file
	// exists, the zero value of Config is used.
	Config vdltool.Config

	// OpenFilesFunc is a function that opens the files with the given fileNames,
	// and returns a map from base file name to file contents.
	OpenFilesFunc func(fileNames []string) (map[string]io.ReadCloser, error)
	// contains filtered or unexported fields
}

Package represents the build information for a vdl package.

func TransitivePackages

func TransitivePackages(paths []string, mode UnknownPathMode, opts Opts, errs *vdlutil.Errors) []*Package

TransitivePackages takes a list of paths, and returns the corresponding packages and transitive dependencies, ordered by dependency. Each path may either be a directory (IsDirPath) or an import (IsImportPath).

A path is a pattern if it includes one or more "..." wildcards, each of which can match any string, including the empty string and strings containing slashes. Such a pattern expands to all packages found in SrcDirs with names matching the pattern. As a special-case, x/... matches x as well as x's subdirectories.

The special-case "all" is a synonym for "...", and denotes all packages found in SrcDirs.

Import path elements and file names are not allowed to begin with "." or "_"; such paths are ignored in wildcard matches, and return errors if specified explicitly.

The mode specifies whether we should ignore or produce errors for paths that don't resolve to any packages. The opts arg specifies additional options.

func TransitivePackagesForConfig

func TransitivePackagesForConfig(fileName string, src io.Reader, opts Opts, errs *vdlutil.Errors) []*Package

TransitivePackagesForConfig takes a config file represented by its file name and src data, and returns all package dependencies in transitive order.

The opts arg specifies additional options.

func (*Package) CloseFiles

func (p *Package) CloseFiles() error

CloseFiles closes all files returned by OpenFiles. Returns nil if all files were closed successfully, otherwise returns one of the errors, dropping the others. Regardless of whether an error is returned, Close will be called on all files.

func (*Package) OpenFiles

func (p *Package) OpenFiles() (map[string]io.Reader, error)

OpenFiles opens all files in the package and returns a map from base file name to file contents. CloseFiles must be called to close the files.

type UnknownPathMode

type UnknownPathMode int

UnknownPathMode specifies the behavior when an unknown path is encountered.

const (
	UnknownPathIsIgnored UnknownPathMode = iota // Silently ignore unknown paths
	UnknownPathIsError                          // Produce error for unknown paths
)

func (UnknownPathMode) String

func (m UnknownPathMode) String() string