origin Reference (GNU Guix Reference Manual)

8.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.

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.

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.

Procedure: git-fetch/lfs ref hash-algo hash: This is a variant of the git-fetch procedure that supports the Git LFS (Large File Storage) extension. This may be useful to pull some binary test data to run the test suite of a package, for example.

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.

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 #f.

Data Type: hg-reference

This data type represents a Mercurial reference for hg-fetch to retrieve.

url: The URL of the Mercurial repository to clone.
changeset: This string denotes changeset to fetch.

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

Procedure: svn-fetch ref hash-algo hash [name]: Return a fixed-output derivation that fetches ref, a <svn-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: svn-reference

This data type represents a Subversion reference for svn-fetch to retrieve.

url: The URL of the Subversion repository to clone.
revision: This string denotes revision to fetch specified as a number.
recursive? (default: #f): This Boolean indicates whether to recursively fetch Subversion “externals”.
user-name (default: #f): The name of an account that has read-access to the repository, if the repository isn’t public.
password (default: #f): Password to access the Subversion repository, if required.

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

Procedure: bzr-fetch ref hash-algo hash [name]: Return a fixed-output derivation that fetches ref, a <bzr-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: bzr-reference

This data type represents a Bazaar reference for bzr-fetch to retrieve.

url: The URL of the Bazaar repository to clone.
revision: This string denotes revision to fetch specified as a number.

For CVS repositories, the module (guix cvs-download) defines the cvs-fetch origin method and cvs-reference data type for support of the Concurrent Versions System (CVS).

Procedure: cvs-fetch ref hash-algo hash [name]: Return a fixed-output derivation that fetches ref, a <cvs-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: cvs-reference

This data type represents a CVS reference for cvs-fetch to retrieve.

root-directory: The CVS root directory.
module: Module to fetch.
revision: Revision to fetch.

The example below denotes a version of gnu-standards to fetch:

(cvs-reference
  (root-directory ":pserver:anonymous@cvs.savannah.gnu.org:/sources/gnustandards")
  (module "gnustandards")
  (revision "2020-11-25"))

8.2.2 origin Reference

8.2.2 `origin` Reference