wsl

Documentation

Overview

Package WSL provides functions for interacting with WSL.

Index

• Variables
• func SetDefaultDistribution(ctx context.Context, d Distribution) (err error)
• func SetDefaultVersion(ctx context.Context, v Version) (err error)
• func Shutdown(ctx context.Context) (err error)
• type CommandOptions
• type Distribution
  • func DefaultDistribution(ctx context.Context) (d Distribution, err error)
  • func ListInstalled(ctx context.Context) ([]Distribution, error)
  • func ListOnline(ctx context.Context) ([]Distribution, error)
  • func ListRunning(ctx context.Context) ([]Distribution, error)
  • func SystemDistribution() Distribution
  • func (d Distribution) CommandContext(ctx context.Context, opts *CommandOptions, name string, args ...string) *exec.Cmd
  • func (d Distribution) SetVersion(ctx context.Context, v Version) (err error)
  • func (d Distribution) String() string
  • func (d Distribution) Terminate(ctx context.Context) (err error)
• type ShellType
  • func (st ShellType) Get() any
  • func (st *ShellType) Set(s string) error
  • func (st ShellType) String() string
• type Version
  • func DefaultVersion(ctx context.Context) (ver Version, err error)

Variables

var (
	ErrDistributionNotFound = errors.New("distribution not found")
	ErrVersionParse         = errors.New("cannot parse version")
	ErrNameNotResolved      = errors.New("cannot resolve DNS name")
	ErrVersion1NotSupported = errors.New("WSL1 is not supported")
)

Known errors returned by WSL.

Functions

func SetDefaultDistribution

func SetDefaultDistribution(ctx context.Context, d Distribution) (err error)

SetDefaultDistributions sets the given as the default.

func SetDefaultVersion

func SetDefaultVersion(ctx context.Context, v Version) (err error)

SetDefaultVersion sets the version of WSL to use by default for new distributions.

func Shutdown

func Shutdown(ctx context.Context) (err error)

Shutdown stops all running distributions and shuts down WSL2 virtual machine.

Types

type CommandOptions

type CommandOptions struct {
	ShellType ShellType // Type of shell to use (standard, login or none).
	Directory string    // Working directory for the process.
	User      string    // User to run as.
	UseShell  bool      // Use the shell to interpret the command.
}

CommandOptions influence how a command is executed inside WSL

type Distribution

type Distribution struct {
	Name         string // Select distribution with the given name.
	FriendlyName string // Only when populated by ListOnline.
	// contains filtered or unexported fields
}

Distribution is a container running under WSL or WSL2 management.

Distributions are identified by name. A special, unnamed system distribution exists to manage WSL itself. That distribution has certain limitations, as inability to become the default distribution, be terminated or removed.

func DefaultDistribution

func DefaultDistribution(ctx context.Context) (d Distribution, err error)

DefaultDistribution returns the default distribution to use.

func ListInstalled

func ListInstalled(ctx context.Context) ([]Distribution, error)

ListInstalled returns the list of installed WSL distributions.

func ListOnline

func ListOnline(ctx context.Context) ([]Distribution, error)

ListOnline returns the list of WSL distributions available for installation.

func ListRunning

func ListRunning(ctx context.Context) ([]Distribution, error)

ListRunning returns the list of running WSL distributions.

func SystemDistribution

func SystemDistribution() Distribution

SystemDistribution is an unnamed distribution used to operate WSL itself.

func (Distribution) CommandContext

func (d Distribution) CommandContext(ctx context.Context, opts *CommandOptions, name string, args ...string) *exec.Cmd

CommandContext returns a command ready to execute in the given distribution.

func (Distribution) SetVersion

func (d Distribution) SetVersion(ctx context.Context, v Version) (err error)

SetVersion sets the version of WSL to use for the given distribution.

func (Distribution) String

func (d Distribution) String() string

String returns the name of the distribution.

func (Distribution) Terminate

func (d Distribution) Terminate(ctx context.Context) (err error)

Terminate forcibly stops the given distribution.

type ShellType

type ShellType string

ShellType is the type of shell to use when executing a command.

const (
	Standard ShellType = "standard"
	Login    ShellType = "login"
	None     ShellType = "none"
)

Known values of ShellType.

The semantics inside WSL is hard to understand.

func (ShellType) Get

func (st ShellType) Get() any

Get implements flag.Getter.

func (*ShellType) Set

func (st *ShellType) Set(s string) error

Set sets the shell type to the given string or returns an error if the type is unknown.

Set implements flag.Value.

func (ShellType) String

func (st ShellType) String() string

String returns "standard", "login" or "none"

String implements flag.Value.

type Version

type Version string

Version is the major version of WSL itself.

WSL has two versions as of this time: WSL1 with Windows emulating Linux and WSL2 with Windows running Linux inside a virtual machine.

const (
	// Version1 or WSL1 is the emulated Linux environment running directly on top of Windows kernel.
	//
	// Version1 has numerous limitations and does not support large chunks of Linux APIs.
	// Version1 has better interoperability with Windows file systems (access is faster).
	Version1 Version = "1"
	// Version2 or WSL2 is the virtualized Linux environment running inside Hyper-V.
	//
	// Version2 has access to large number of Linux-specific APIs.
	// Version2 has much better performance when accessing Linux file systems and
	// degraded performance when accessing Windows file systems, at least as
	// compared to Wsl1.
	Version2 Version = "2"
)

Available versions of WSL.

func DefaultVersion

func DefaultVersion(ctx context.Context) (ver Version, err error)

DefaultVersion returns the version of WSL to use by default for new distributions.