flake

Documentation

Overview

Package flake parses and formats Nix flake references.

Index

• Constants
• type Installable
  • func ParseInstallable(raw string) (Installable, error)
  • func (fi Installable) SplitOutputs() []string
  • func (fi Installable) String() string
• type Ref
  • func ParseRef(ref string) (Ref, error)
  • func (r Ref) String() string

Constants

const (
	TypeIndirect = "indirect"
	TypePath     = "path"
	TypeFile     = "file"
	TypeGit      = "git"
	TypeGitHub   = "github"
	TypeTarball  = "tarball"
)

Flake reference types supported by this package.

const (
	// DefaultOutputs specifies that the package-defined default outputs
	// should be installed.
	DefaultOutputs = ""

	// AllOutputs specifies that all package outputs should be installed.
	AllOutputs = "*"
)

Special values for Installable.Outputs.

Types

type Installable

type Installable struct {
	// Ref is the flake reference portion of the installable.
	Ref Ref `json:"ref,omitempty"`

	// AttrPath is an attribute path of the flake, encoded as a URL
	// fragment.
	AttrPath string `json:"attr_path,omitempty"`

	// Outputs is the installable's output spec, which is a comma-separated
	// list of package outputs to install. The outputs spec is anything
	// after the last caret '^' in an installable. Unlike the
	// attribute path, output specs are not URL-encoded.
	//
	// The special values DefaultOutputs ("") and AllOutputs ("*") specify
	// the default set of package outputs and all package outputs,
	// respectively.
	//
	// ParseInstallable cleans the list of outputs by removing empty
	// elements and sorting the results. Lists containing a "*" are
	// simplified to a single "*".
	Outputs string `json:"outputs,omitempty"`
}

Installable is a Nix command line argument that specifies how to install a flake. It can be a plain flake reference, or a flake reference with an attribute path and/or output specification.

Some examples are:

• "." installs the default attribute from the flake in the current directory.
• ".#hello" installs the hello attribute from the flake in the current directory.
• "nixpkgs#hello" installs the hello attribute from the nixpkgs flake.
• "github:NixOS/nixpkgs/unstable#curl^lib" installs the the lib output of curl attribute from the flake on the nixpkgs unstable branch.

The flake installable syntax is only valid in Nix command line arguments, not in Nix expressions. See Ref and the Nix manual for details on the differences between flake references and installables.

func ParseInstallable

func ParseInstallable(raw string) (Installable, error)

ParseInstallable parses a flake installable. The raw string must contain a valid flake reference parsable by ParseRef, optionally followed by an #attrpath and/or an ^output.

func (Installable) SplitOutputs

func (fi Installable) SplitOutputs() []string

SplitOutputs splits and sorts the comma-separated list of outputs. It skips any empty outputs. If one or more of the outputs is a "*", then the result will be a slice with a single "*" element.

func (Installable) String

func (fi Installable) String() string

String encodes the installable as a Nix command line argument. It normalizes the result such that if two installable values are equal, then their strings will also be equal.

String always cleans the outputs spec as described by the Outputs field's documentation. The same normalization rules from Ref.String still apply.

type Ref

type Ref struct {
	// Type is the type of flake reference. Some valid types are "indirect",
	// "path", "file", "git", "tarball", and "github".
	Type string `json:"type,omitempty"`

	// ID is the flake's identifier when Type is "indirect". A common
	// example is nixpkgs.
	ID string `json:"id,omitempty"`

	// Path is the path to the flake directory when Type is "path".
	Path string `json:"path,omitempty"`

	// Owner and repo are the flake repository owner and name when Type is
	// "github".
	Owner string `json:"owner,omitempty"`
	Repo  string `json:"repo,omitempty"`

	// Rev and ref are the git revision (commit hash) and ref
	// (branch or tag) when Type is "github" or "git".
	Rev string `json:"rev,omitempty"`
	Ref string `json:"ref,omitempty"`

	// Dir is non-empty when the directory containing the flake.nix file is
	// not at the flake root. It corresponds to the optional "dir" query
	// parameter when Type is "github", "git", "tarball", or "file".
	Dir string `json:"dir,omitempty"`

	// Host overrides the default VCS host when Type is "github", such as
	// when referring to a GitHub Enterprise instance. It corresponds to the
	// optional "host" query parameter when Type is "github".
	Host string `json:"host,omitempty"`

	// URL is the URL pointing to the flake when type is "tarball", "file",
	// or "git". Note that the URL is not the same as the raw unparsed
	// flake ref.
	URL string `json:"url,omitempty"`
}

Ref is a parsed Nix flake reference. A flake reference is a subset of the Nix CLI "installable" syntax. An Installable may specify an attribute path and derivation outputs with a flake reference using the '#' and '^' characters. For example, the string "nixpkgs" and "./flake" are valid flake references, but "nixpkgs#hello" and "./flake#app^bin,dev" are not.

The JSON encoding of Ref corresponds to the exploded attribute set form of the flake reference in Nix. See the Nix manual for details on flake references.

func ParseRef

func ParseRef(ref string) (Ref, error)

ParseRef parses a raw flake reference. Nix supports a variety of flake ref formats, and isn't entirely consistent about how it parses them. ParseRef attempts to mimic how Nix parses flake refs on the command line. The raw ref can be one of the following:

• Indirect reference such as "nixpkgs" or "nixpkgs/unstable".
• Path-like reference such as "./flake" or "/path/to/flake". They must start with a '.' or '/' and not contain a '#' or '?'.
• URL-like reference which must be a valid URL with any special characters encoded. The scheme can be any valid flake ref type except for mercurial, gitlab, and sourcehut.

ParseRef does not guarantee that a parsed flake ref is valid or that an error indicates an invalid flake ref. Use the "nix flake metadata" command or the builtins.parseFlakeRef Nix function to validate a flake ref.

func (Ref) String

func (r Ref) String() string

String encodes the flake reference as a URL-like string. It normalizes the result such that if two Ref values are equal, then their strings will also be equal.

There are multiple ways to encode a flake reference. String uses the following rules to normalize the result:

• the URL-like form is always used, even for paths and indirects.
• the scheme is always present, even if it's optional.
• paths are cleaned per path.Clean.
• fields that can be put in either the path or the query string are always put in the path.
• query parameters are sorted by key.

If f is missing a type or has any invalid fields, String returns an empty string.