origin Reference (GNU Guix Reference Manual)

9.2.2 `origin` Reference

This section documents origins. An origin declaration specifies data that must be “produced”—downloaded, usually—and whose content hash is known in advance. Origins are primarily used to represent the source code of packages (see Defining Packages). For that reason, the origin form allows you to declare patches to apply to the original source code as well as code snippets to modify it.

Data Type: origin

This is the data type representing a source code origin.

uri

An object containing the URI of the source. The object type depends on the method (see below). For example, when using the url-fetch method of (guix download), the valid uri values are: a URL represented as a string, or a list thereof.

method

A monadic procedure that handles the given URI. The procedure must accept at least three arguments: the value of the uri field and the hash algorithm and hash value specified by the hash field. It must return a store item or a derivation in the store monad (see The Store Monad); most methods return a fixed-output derivation (see Derivations).

Commonly used methods include url-fetch, which fetches data from a URL, and git-fetch, which fetches data from a Git repository (see below).

sha256

A bytevector containing the SHA-256 hash of the source. This is equivalent to providing a content-hash SHA256 object in the hash field described below.

hash

The content-hash object of the source—see below for how to use content-hash.

You can obtain this information using guix download (see Invoking guix download) or guix hash (see Invoking guix hash).

file-name (default: #f)

The file name under which the source code should be saved. When this is #f, a sensible default value will be used in most cases. In case the source is fetched from a URL, the file name from the URL will be used. For version control checkouts, it is recommended to provide the file name explicitly because the default is not very descriptive.

patches (default: '())

A list of file names, origins, or file-like objects (see file-like objects) pointing to patches to be applied to the source.

This list of patches must be unconditional. In particular, it cannot depend on the value of %current-system or %current-target-system.

snippet (default: #f)

A G-expression (see G-Expressions) or S-expression that will be run in the source directory. This is a convenient way to modify the source, sometimes more convenient than a patch.

patch-flags (default: '("-p1"))

A list of command-line flags that should be passed to the patch command.

patch-inputs (default: #f)

Input packages or derivations to the patching process. When this is #f, the usual set of inputs necessary for patching are provided, such as GNU Patch.

modules (default: '())

A list of Guile modules that should be loaded during the patching process and while running the code in the snippet field.

patch-guile (default: #f)

The Guile package that should be used in the patching process. When this is #f, a sensible default is used.

Data Type: content-hash value [algorithm]

Construct a content hash object for the given algorithm, and with value as its hash value. When algorithm is omitted, assume it is sha256.

value can be a literal string, in which case it is base32-decoded, or it can be a bytevector.

The following forms are all equivalent:

(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
              sha256)
(content-hash (base32
               "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
(content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
              sha256)

Technically, content-hash is currently implemented as a macro. It performs sanity checks at macro-expansion time, when possible, such as ensuring that value has the right size for algorithm.

As we have seen above, how exactly the data an origin refers to is retrieved is determined by its method field. The (guix download) module provides the most common method, url-fetch, described below.

Scheme Procedure: url-fetch url hash-algo hash [name] [#:executable? #f]

Return a fixed-output derivation that fetches data from url (a string, or a list of strings denoting alternate URLs), which is expected to have hash hash of type hash-algo (a symbol). By default, the file name is the base name of URL; optionally, name can specify a different file name. When executable? is true, make the downloaded file executable.

When one of the URL starts with mirror://, then its host part is interpreted as the name of a mirror scheme, taken from %mirror-file.

Alternatively, when URL starts with file://, return the corresponding file name in the store.

Likewise, the (guix git-download) module defines the git-fetch origin method, which fetches data from a Git version control repository, and the git-reference data type to describe the repository and revision to fetch.

Scheme Procedure: git-fetch ref hash-algo hash: Return a fixed-output derivation that fetches ref, a <git-reference> object. The output is expected to have recursive hash hash of type hash-algo (a symbol). Use name as the file name, or a generic name if #f.

Data Type: git-reference

This data type represents a Git reference for git-fetch to retrieve.

url: The URL of the Git repository to clone.
commit: This string denotes either the commit to fetch (a hexadecimal string), or the tag to fetch. You can also use a “short” commit ID or a git describe style identifier such as v1.0.1-10-g58d7909c97.
recursive? (default: #f): This Boolean indicates whether to recursively fetch Git sub-modules.

The example below denotes the v2.10 tag of the GNU Hello repository:

(git-reference
  (url "https://git.savannah.gnu.org/git/hello.git")
  (commit "v2.10"))

This is equivalent to the reference below, which explicitly names the commit:

(git-reference
  (url "https://git.savannah.gnu.org/git/hello.git")
  (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))

For Mercurial repositories, the module (guix hg-download) defines the hg-fetch origin method and hg-reference data type for support of the Mercurial version control system.

Scheme Procedure: hg-fetch ref hash-algo hash [name]: Return a fixed-output derivation that fetches ref, a <hg-reference> object. The output is expected to have recursive hash hash of type hash-algo (a symbol). Use name as the file name, or a generic name if #false.

9.2.2 origin Reference

9.2.2 `origin` Reference