Documentation

Overview

Package compileopts contains the configuration for a single to-be-built binary.

Index

Constants

This section is empty.

Variables

View Source
var WindowsBuildNotSupportedErr = errors.New("Building Windows binaries is currently not supported. Try specifying a different target")

WindowsBuildNotSupportedErr is being thrown, when goos is windows and no target has been specified.

Functions

This section is empty.

Types

type Config

type Config struct {
	Options        *Options
	Target         *TargetSpec
	GoMinorVersion int
	ClangHeaders   string // Clang built-in header include path
	TestConfig     TestConfig
}

Config keeps all configuration affecting the build in a single struct.

func (*Config) AutomaticStackSize

func (c *Config) AutomaticStackSize() bool

AutomaticStackSize returns whether goroutine stack sizes should be determined automatically at compile time, if possible. If it is false, no attempt is made.

func (*Config) BinaryFormat

func (c *Config) BinaryFormat(ext string) string

BinaryFormat returns an appropriate binary format, based on the file extension and the configured binary format in the target JSON file.

func (*Config) BuildTags

func (c *Config) BuildTags() []string

BuildTags returns the complete list of build tags used during this build.

func (*Config) CFlags

func (c *Config) CFlags() []string

CFlags returns the flags to pass to the C compiler. This is necessary for CGo preprocessing.

func (*Config) CPU

func (c *Config) CPU() string

CPU returns the LLVM CPU name, like atmega328p or arm7tdmi. It may return an empty string if the CPU name is not known.

func (*Config) CgoEnabled

func (c *Config) CgoEnabled() bool

CgoEnabled returns true if (and only if) CGo is enabled. It is true by default and false if CGO_ENABLED is set to "0".

func (*Config) CodeModel

func (c *Config) CodeModel() string

CodeModel returns the code model used on this platform.

func (*Config) Debug

func (c *Config) Debug() bool

Debug returns whether to add debug symbols to the IR, for debugging with GDB and similar.

func (*Config) DumpSSA

func (c *Config) DumpSSA() bool

DumpSSA returns whether to dump Go SSA while compiling (-dumpssa flag). Only enable this for debugging.

func (*Config) ExtraFiles

func (c *Config) ExtraFiles() []string

ExtraFiles returns the list of extra files to be built and linked with the executable. This can include extra C and assembly files.

func (*Config) Features

func (c *Config) Features() []string

Features returns a list of features this CPU supports. For example, for a RISC-V processor, that could be ["+a", "+c", "+m"]. For many targets, an empty list will be returned.

func (*Config) FuncImplementation

func (c *Config) FuncImplementation() string

FuncImplementation picks an appropriate func value implementation for the target.

func (*Config) GC

func (c *Config) GC() string

GC returns the garbage collection strategy in use on this platform. Valid values are "none", "leaking", "extalloc", and "conservative".

func (*Config) GOARCH

func (c *Config) GOARCH() string

GOARCH returns the GOARCH of the target. This might not always be the actual archtecture: for example, the AVR target is not supported by the Go standard library so such targets will usually pretend to be linux/arm.

func (*Config) GOOS

func (c *Config) GOOS() string

GOOS returns the GOOS of the target. This might not always be the actual OS: for example, bare-metal targets will usually pretend to be linux to get the standard library to compile.

func (*Config) LDFlags

func (c *Config) LDFlags() []string

LDFlags returns the flags to pass to the linker. A few more flags are needed (like the one for the compiler runtime), but this represents the majority of the flags.

func (*Config) LLVMFeatures

func (c *Config) LLVMFeatures() string

func (*Config) NeedsStackObjects

func (c *Config) NeedsStackObjects() bool

NeedsStackObjects returns true if the compiler should insert stack objects that can be traced by the garbage collector.

func (*Config) OpenOCDConfiguration

func (c *Config) OpenOCDConfiguration() (args []string, err error)

OpenOCDConfiguration returns a list of command line arguments to OpenOCD. This list of command-line arguments is based on the various OpenOCD-related flags in the target specification.

func (*Config) OptLevels

func (c *Config) OptLevels() (optLevel, sizeLevel int, inlinerThreshold uint)

OptLevels returns the optimization level (0-2), size level (0-2), and inliner threshold as used in the LLVM optimization pipeline.

func (*Config) PanicStrategy

func (c *Config) PanicStrategy() string

PanicStrategy returns the panic strategy selected for this target. Valid values are "print" (print the panic value, then exit) or "trap" (issue a trap instruction).

func (*Config) Programmer

func (c *Config) Programmer() (method, openocdInterface string)

Programmer returns the flash method and OpenOCD interface name given a particular configuration. It may either be all configured in the target JSON file or be modified using the -programmmer command-line option.

func (*Config) RelocationModel

func (c *Config) RelocationModel() string

RelocationModel returns the relocation model in use on this platform. Valid values are "static", "pic", "dynamicnopic".

func (*Config) Scheduler

func (c *Config) Scheduler() string

Scheduler returns the scheduler implementation. Valid values are "none", "coroutines" and "tasks".

func (*Config) Triple

func (c *Config) Triple() string

Triple returns the LLVM target triple, like armv6m-none-eabi.

func (*Config) VerifyIR

func (c *Config) VerifyIR() bool

VerifyIR returns whether to run extra checks on the IR. This is normally disabled but enabled during testing.

func (*Config) WasmAbi

func (c *Config) WasmAbi() string

WasmAbi returns the WASM ABI which is specified in the target JSON file, and the value is overridden by `-wasm-abi` flag if it is provided

type Options

type Options struct {
	Target          string
	Opt             string
	GC              string
	PanicStrategy   string
	Scheduler       string
	PrintIR         bool
	DumpSSA         bool
	VerifyIR        bool
	PrintCommands   bool
	Debug           bool
	PrintSizes      string
	PrintAllocs     *regexp.Regexp // regexp string
	PrintStacks     bool
	Tags            string
	WasmAbi         string
	GlobalValues    map[string]map[string]string // map[pkgpath]map[varname]value
	TestConfig      TestConfig
	Programmer      string
	OpenOCDCommands []string
	LLVMFeatures    string
}

Options contains extra options to give to the compiler. These options are usually passed from the command line.

func (*Options) Verify

func (o *Options) Verify() error

Verify performs a validation on the given options, raising an error if options are not valid.

type TargetSpec

type TargetSpec struct {
	Inherits         []string `json:"inherits"`
	Triple           string   `json:"llvm-target"`
	CPU              string   `json:"cpu"`
	Features         []string `json:"features"`
	GOOS             string   `json:"goos"`
	GOARCH           string   `json:"goarch"`
	BuildTags        []string `json:"build-tags"`
	GC               string   `json:"gc"`
	Scheduler        string   `json:"scheduler"`
	Linker           string   `json:"linker"`
	RTLib            string   `json:"rtlib"` // compiler runtime library (libgcc, compiler-rt)
	Libc             string   `json:"libc"`
	AutoStackSize    *bool    `json:"automatic-stack-size"` // Determine stack size automatically at compile time.
	DefaultStackSize uint64   `json:"default-stack-size"`   // Default stack size if the size couldn't be determined at compile time.
	CFlags           []string `json:"cflags"`
	LDFlags          []string `json:"ldflags"`
	LinkerScript     string   `json:"linkerscript"`
	ExtraFiles       []string `json:"extra-files"`
	Emulator         []string `json:"emulator" override:"copy"` // inherited Emulator must not be append
	FlashCommand     string   `json:"flash-command"`
	GDB              []string `json:"gdb"`
	PortReset        string   `json:"flash-1200-bps-reset"`
	FlashMethod      string   `json:"flash-method"`
	FlashVolume      string   `json:"msd-volume-name"`
	FlashFilename    string   `json:"msd-firmware-name"`
	UF2FamilyID      string   `json:"uf2-family-id"`
	BinaryFormat     string   `json:"binary-format"`
	OpenOCDInterface string   `json:"openocd-interface"`
	OpenOCDTarget    string   `json:"openocd-target"`
	OpenOCDTransport string   `json:"openocd-transport"`
	OpenOCDCommands  []string `json:"openocd-commands"`
	JLinkDevice      string   `json:"jlink-device"`
	CodeModel        string   `json:"code-model"`
	RelocationModel  string   `json:"relocation-model"`
	WasmAbi          string   `json:"wasm-abi"`
}

Target specification for a given target. Used for bare metal targets.

The target specification is mostly inspired by Rust: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_target/spec/struct.TargetOptions.html https://github.com/shepmaster/rust-arduino-blink-led-no-core-with-cargo/blob/master/blink/arduino.json

func LoadTarget

func LoadTarget(target string) (*TargetSpec, error)

Load a target specification.

func (*TargetSpec) LookupGDB

func (spec *TargetSpec) LookupGDB() (string, error)

LookupGDB looks up a gdb executable.

type TestConfig

type TestConfig struct {
	CompileTestBinary bool
}