Previous: package
Reference, Up: Defining Packages [Contents][Index]
origin
ReferenceThis 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.
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.
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.
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.
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
.
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.
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.
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
.
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 the 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.
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
.
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 the 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.
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
.
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).
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
.
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"))
Previous: package
Reference, Up: Defining Packages [Contents][Index]