compiler

Documentation

Overview

Package compiler contains types for compilers, which are a particular type of service.

Index

• Variables
• func MockSet() map[id.ID]Instance
• func OnCompilerConfig(m Message, obs ...Observer)
• func OnCompilerConfigEnd(obs ...Observer)
• func OnCompilerConfigStart(nCompilers int, obs ...Observer)
• func OnCompilerConfigStep(i int, c Named, obs ...Observer)
• func SelectLevels(in Inspector, c *Compiler) (map[string]optlevel.Level, error)
• func SelectMOpts(in Inspector, c *Compiler) (stringhelp.Set, error)
• type Compiler
• type Config
• type ConfigMap
• type Inspector
• type Instance
  • func MockPower9GCCOpt() Instance
  • func MockX86Gcc() Instance
  • func (c Instance) AddName(name id.ID) *Named
  • func (c Instance) Interpolations() map[string]string
  • func (c Instance) SelectedOptName() string
  • func (c Instance) String() string
• type InstanceMap
  • func (m InstanceMap) Get(cid id.ID) (Instance, error)
  • func (m InstanceMap) Map(cid id.ID, f func(*Instance) error) error
• type Job
  • func NewJob(k Target, c *Instance, out string, in ...string) *Job
  • func (j *Job) CompilerRun() *service.RunInfo
  • func (j *Job) SelectedMOptName() string
  • func (j *Job) SelectedOptName() string
• type Message
• type Named
  • func (n Named) FullID() (id.ID, error)
• type Observer
• type Prober
• type Target
  • func (i Target) String() string

Examples

• Instance.AddName
• Named.FullID
• Named.FullID (Dotarch)

Variables

var (
	// ErrConfigNil occurs if we try to select optimisation levels for a nil compiler.
	ErrConfigNil = errors.New("can't select levels for nil compiler")
	// ErrNoSuchLevel occurs if a Selection enables an optimisation level that isn't available.
	ErrNoSuchLevel = errors.New("no such optimisation level")
)

var ErrCompilerMissing = errors.New("compiler not found")

ErrCompilerMissing occurs when we can't find the compiler with a given name.

Functions

func MockSet

func MockSet() map[id.ID]Instance

MockSet produces a mock compiler set.

func OnCompilerConfig

func OnCompilerConfig(m Message, obs ...Observer)

OnCompilerConfig sends an OnCompilerConfig message to each observer in obs.

func OnCompilerConfigEnd

func OnCompilerConfigEnd(obs ...Observer)

OnCompilerConfigEnd sends an compiler config-end message to each observer in obs.

func OnCompilerConfigStart

func OnCompilerConfigStart(nCompilers int, obs ...Observer)

OnCompilerConfigStart sends a compiler config-start message to each observer in obs.

func OnCompilerConfigStep

func OnCompilerConfigStep(i int, c Named, obs ...Observer)

OnCompilerConfigStep sends an compiler config-step message to each observer in obs.

func SelectLevels

func SelectLevels(in Inspector, c *Compiler) (map[string]optlevel.Level, error)

SelectLevels selects from in the optimisation levels permitted by the configuration c.

func SelectMOpts

func SelectMOpts(in Inspector, c *Compiler) (stringhelp.Set, error)

SelectMOpts selects from in the machine optimisation profiles (-march, etc.) permitted by the configuration c.

Types

type Compiler

type Compiler struct {
	// Disabled specifies whether this compiler has been disabled.
	Disabled bool `toml:"disabled,omitempty" json:"disabled,omitempty"`

	// Style is the declared style of the compile.
	Style id.ID `toml:"style" json:"style"`

	// Arch is the architecture (or 'emits') ID for the compiler.
	Arch id.ID `toml:"arch,omitempty" json:"arch,omitempty"`

	// Run contains information on how to run the compiler.
	Run *service.RunInfo `toml:"run,omitempty" json:"run,omitempty"`

	// MOpt contains information on the 'mopt' (compiler architecture tuning) levels to select for the compiler.
	MOpt *optlevel.Selection `toml:"mopt,optempty" json:"mopt,omitempty"`

	// Opt contains information on the optimisation levels to select for the compiler.
	Opt *optlevel.Selection `toml:"opt,omitempty" json:"opt,omitempty"`
}

Compiler represents fully prepared baseline configuration for a compiler.

The distinction between Compiler and Config is that the latter represents a raw form of a Compiler coming from a config file; the distinction between Compiler and Instance is that the latter is the former plus a set of decisions on the specific invocation the compiler will have for a test run (eg, optimisation levels, mutant indices, etc).

type Config

type Config Compiler

Config denotes raw configuration for a Compiler.

type ConfigMap

type ConfigMap map[string]Config

ConfigMap is a map of raw compiler configuration.

type Inspector

type Inspector interface {
	// DefaultOptLevels retrieves a set of optimisation levels that are enabled by default for compiler c.
	DefaultOptLevels(c *Compiler) (stringhelp.Set, error)
	// OptLevels retrieves a set of potential optimisation levels for compiler c.
	// This map shouldn't be modified, as it may be global.
	OptLevels(c *Compiler) (map[string]optlevel.Level, error)
	// DefaultMOpts retrieves a set of machine optimisation directives that are enabled by default for compiler c.
	DefaultMOpts(c *Compiler) (stringhelp.Set, error)
}

Inspector is the interface of types that support optimisation level lookup.

type Instance

type Instance struct {
	// SelectedMOpt refers to an architecture tuning level chosen using the compiler's configured march selection.
	SelectedMOpt string `json:"selected_mopt,omitempty"`
	// SelectedOpt refers to an optimisation level chosen using the compiler's configured optimisation selection.
	SelectedOpt *optlevel.Named `json:"selected_opt,omitempty"`
	// ConfigTime captures the time at which this compiler configuration was generated.
	//
	// An example of when this may be useful is when using a compiler with run-time mutations enabled; we can use the
	// configuration time as a seed (by interpolating it out into the arguments or environment variables) to choose
	// mutations.
	ConfigTime time.Time `json:"config_time,omitempty"`
	// Mutant captures any mutant ID attached to this compiler instance.
	Mutant mutation.Mutant `json:"mutant,omitempty"`
	Compiler
}

Instance represents a fully configured instance of a compiler.

func MockPower9GCCOpt

func MockPower9GCCOpt() Instance

MockPower9GCCOpt produces a GCC-compatible instance with Power9 architecture and optimisation configuration.

func MockX86Gcc

func MockX86Gcc() Instance

MockX86Gcc produces a GCC-compatible instance with X86 architecture.

func (Instance) AddName

func (c Instance) AddName(name id.ID) *Named

AddName names this Instance with ID name, lifting it to a Named.

Example

ExampleInstance_AddName is a runnable example for Instance.AddName.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/id"
	"github.com/c4-project/c4t/internal/model/service/compiler"
)

func main() {
	c := compiler.Instance{
		Compiler: compiler.Compiler{
			Style: id.CStyleGCC,
			Arch:  id.ArchX8664,
		},
	}
	nc := c.AddName(id.FromString("gcc.native"))

	fmt.Println(nc.ID)
	fmt.Println(nc.Arch)
	fmt.Println(nc.Style)

}

Output:

gcc.native
x86.64
gcc

func (Instance) Interpolations

func (c Instance) Interpolations() map[string]string

Interpolations gets a map of variable interpolations that should be used in any job constructed from this instance.

func (Instance) SelectedOptName

func (c Instance) SelectedOptName() string

SelectedOptName returns the name of the selected optimisation level, or the empty string if there isn't one.

func (Instance) String

func (c Instance) String() string

String outputs a human-readable but machine-separable summary of this compiler configuration.

type InstanceMap

type InstanceMap map[id.ID]Instance

InstanceMap is shorthand for a map from compiler IDs to instantiated compilers.

func (InstanceMap) Get

func (m InstanceMap) Get(cid id.ID) (Instance, error)

Get is a wrapper around map getting that returns ErrCompilerMissing if cid doesn't exist.

func (InstanceMap) Map

func (m InstanceMap) Map(cid id.ID, f func(*Instance) error) error

Map maps f over the compiler at ID cid. It errors if cid doesn't exist, or if f fails.

type Job

type Job struct {
	// Compiler describes the compiler to use for the compilation.
	Compiler *Instance

	// In is the list of files to be sent to the compiler.
	In []string
	// Out is the file to be received from the compiler.
	Out string

	// Kind is the kind of file being produced by this compile.
	Kind Target
}

Job represents a request to compile a list of files to a particular target given a particular compiler.

func NewJob

func NewJob(k Target, c *Instance, out string, in ...string) *Job

NewJob is a convenience constructor for compiles.

func (*Job) CompilerRun

func (j *Job) CompilerRun() *service.RunInfo

CompilerRun gets the job's compiler run information if present; else, nil.

func (*Job) SelectedMOptName

func (j *Job) SelectedMOptName() string

SelectedMOptName gets the name of this job's compiler's selected machine optimisation profile, if present; else, "".

func (*Job) SelectedOptName

func (j *Job) SelectedOptName() string

SelectedOptName gets the name of this job's compiler's selected optimisation level, if present; else, "".

type Message

type Message struct {
	observing.Batch
	// Configuration carries a named compiler configuration, if we're on a build-step.
	Configuration *Named `json:"configuration,omitempty"`
}

Message is the type of builder observation messages.

type Named

type Named struct {
	// ID is the ID of the compiler.
	ID id.ID `toml:"id" json:"id"`

	Instance
}

Named wraps an Instance with its ID.

func (Named) FullID

func (n Named) FullID() (id.ID, error)

FullID gets a fully qualified identifier for this configuration, consisting of the compiler name, followed by 'oOpt' where 'Opt' is its selected optimisation name, and 'mMopt' where 'Mopt' is its selected machine profile.

Where Opt or Mopt contain '.', these become '_'. This behaviour may change.

Example

ExampleNamed_FullID is a runnable example for Named.FullID.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/model/service/compiler/optlevel"

	"github.com/c4-project/c4t/internal/id"
	"github.com/c4-project/c4t/internal/model/service/compiler"
)

func main() {
	c := compiler.Instance{SelectedMOpt: "arch=skylake", SelectedOpt: &optlevel.Named{
		Name:  "3",
		Level: optlevel.Level{},
	}}
	i, _ := c.AddName(id.FromString("gcc.4")).FullID()
	fmt.Println(i)

}

Output:

gcc.4.o3.march=skylake

Example (Dotarch)

ExampleNamed_FullID_dotarch is a runnable example for Named.FullID where the mopt contains dots.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/id"
	"github.com/c4-project/c4t/internal/model/service/compiler"
)

func main() {
	c := compiler.Instance{SelectedMOpt: "arch=armv8.1-a"}
	i, _ := c.AddName(id.FromString("gcc.8")).FullID()
	fmt.Println(i)

}

Output:

gcc.8.o.march=armv8_1-a

type Observer

type Observer interface {
	// OnCompilerConfig sends a compiler configuration observation message.
	OnCompilerConfig(Message)
}

Observer is the interface for things that observe the production of compiler configurations.

type Prober

type Prober interface {
	// Probe uses sr to probe for compilers.
	// It returns them as a map of the right type to slot into RawCompilers in a machine config, hence the string keys.
	Probe(ctx context.Context, sr service.Runner) (ConfigMap, error)
}

Prober is the interface of types that support compiler probing.

type Target

type Target uint8

Target is the enumeration of kinds of single-file compilation output.

const (
	// Exe refers to executable binary compilations.
	Exe Target = iota
	// Obj refers to object file compilations.
	Obj
)

func (Target) String

func (i Target) String() string