5.5 Invoking guix import

The guix import command is useful for people who would like to add a package to the distribution with as little work as possible—a legitimate demand. The command knows of a few repositories from which it can “import” package metadata. The result is a package definition, or a template thereof, in the format we know (see Defining Packages).

The general syntax is:

guix import importer options…

importer specifies the source from which to import package metadata, and options specifies a package identifier and other options specific to importer. Currently, the available “importers” are:

gnu

Import metadata for the given GNU package. This provides a template for the latest version of that GNU package, including the hash of its source tarball, and its canonical synopsis and description.

Additional information such as the package dependencies and its license needs to be figured out manually.

For example, the following command returns a package definition for GNU Hello:

guix import gnu hello

Specific command-line options are:

--key-download=policy

As for guix refresh, specify the policy to handle missing OpenPGP keys when verifying the package signature. See --key-download.

pypi

Import metadata from the Python Package Index⁹. Information is taken from the JSON-formatted description available at pypi.python.org and usually includes all the relevant information, including package dependencies. For maximum efficiency, it is recommended to install the unzip utility, so that the importer can unzip Python wheels and gather data from them.

The command below imports metadata for the itsdangerous Python package:

guix import pypi itsdangerous

gem

Import metadata from RubyGems¹⁰. Information is taken from the JSON-formatted description available at rubygems.org and includes most relevant information, including runtime dependencies. There are some caveats, however. The metadata doesn’t distinguish between synopses and descriptions, so the same string is used for both fields. Additionally, the details of non-Ruby dependencies required to build native extensions is unavailable and left as an exercise to the packager.

The command below imports metadata for the rails Ruby package:

guix import gem rails

cpan

Import metadata from MetaCPAN¹¹. Information is taken from the JSON-formatted metadata provided through MetaCPAN’s API and includes most relevant information, such as module dependencies. License information should be checked closely. If Perl is available in the store, then the corelist utility will be used to filter core modules out of the list of dependencies.

The command command below imports metadata for the Acme::Boolean Perl module:

guix import cpan Acme::Boolean

cran

Import metadata from CRAN, the central repository for the GNU R statistical and graphical environment.

Information is extracted from the DESCRIPTION file of the package.

The command command below imports metadata for the Cairo R package:

guix import cran Cairo

When --recursive is added, the importer will traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

When --archive=bioconductor is added, metadata is imported from Bioconductor, a repository of R packages for for the analysis and comprehension of high-throughput genomic data in bioinformatics.

Information is extracted from the DESCRIPTION file of a package published on the web interface of the Bioconductor SVN repository.

The command below imports metadata for the GenomicRanges R package:

guix import cran --archive=bioconductor GenomicRanges

texlive

Import metadata from CTAN, the comprehensive TeX archive network for TeX packages that are part of the TeX Live distribution.

Information about the package is obtained through the XML API provided by CTAN, while the source code is downloaded from the SVN repository of the Tex Live project. This is done because the CTAN does not keep versioned archives.

The command command below imports metadata for the fontspec TeX package:

guix import texlive fontspec

When --archive=DIRECTORY is added, the source code is downloaded not from the latex sub-directory of the texmf-dist/source tree in the TeX Live SVN repository, but from the specified sibling directory under the same root.

The command below imports metadata for the ifxetex package from CTAN while fetching the sources from the directory texmf/source/generic:

guix import texlive --archive=generic ifxetex

json

Import package metadata from a local JSON file¹². Consider the following example package definition in JSON format:

{
  "name": "hello",
  "version": "2.10",
  "source": "mirror://gnu/hello/hello-2.10.tar.gz",
  "build-system": "gnu",
  "home-page": "https://www.gnu.org/software/hello/",
  "synopsis": "Hello, GNU world: An example GNU package",
  "description": "GNU Hello prints a greeting.",
  "license": "GPL-3.0+",
  "native-inputs": ["gcc@6"]
}

The field names are the same as for the <package> record (See Defining Packages). References to other packages are provided as JSON lists of quoted package specification strings such as guile or guile@2.0.

The importer also supports a more explicit source definition using the common fields for <origin> records:

{
  …
  "source": {
    "method": "url-fetch",
    "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
    "sha256": {
      "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
    }
  }
  …
}

The command below reads metadata from the JSON file hello.json and outputs a package expression:

guix import json hello.json

nix

Import metadata from a local copy of the source of the Nixpkgs distribution¹³. Package definitions in Nixpkgs are typically written in a mixture of Nix-language and Bash code. This command only imports the high-level package structure that is written in the Nix language. It normally includes all the basic fields of a package definition.

When importing a GNU package, the synopsis and descriptions are replaced by their canonical upstream variant.

Usually, you will first need to do:

export NIX_REMOTE=daemon

so that nix-instantiate does not try to open the Nix database.

As an example, the command below imports the package definition of LibreOffice (more precisely, it imports the definition of the package bound to the libreoffice top-level attribute):

guix import nix ~/path/to/nixpkgs libreoffice

hackage

Import metadata from the Haskell community’s central package archive Hackage. Information is taken from Cabal files and includes all the relevant information, including package dependencies.

Specific command-line options are:

--stdin

-s

Read a Cabal file from standard input.

--no-test-dependencies

-t

Do not include dependencies required only by the test suites.

--cabal-environment=alist

-e alist

alist is a Scheme alist defining the environment in which the Cabal conditionals are evaluated. The accepted keys are: os, arch, impl and a string representing the name of a flag. The value associated with a flag has to be either the symbol true or false. The value associated with other keys has to conform to the Cabal file format definition. The default value associated with the keys os, arch and impl is ‘linux’, ‘x86_64’ and ‘ghc’, respectively.

The command below imports metadata for the latest version of the HTTP Haskell package without including test dependencies and specifying the value of the flag ‘network-uri’ as false:

guix import hackage -t -e "'((\"network-uri\" . false))" HTTP

A specific package version may optionally be specified by following the package name by an at-sign and a version number as in the following example:

guix import hackage mtl@2.1.3.1

stackage

The stackage importer is a wrapper around the hackage one. It takes a package name, looks up the package version included in a long-term support (LTS) Stackage release and uses the hackage importer to retrieve its metadata. Note that it is up to you to select an LTS release compatible with the GHC compiler used by Guix.

Specific command-line options are:

--no-test-dependencies

-t

Do not include dependencies required only by the test suites.

--lts-version=version

-r version

version is the desired LTS release version. If omitted the latest release is used.

The command below imports metadata for the HTTP Haskell package included in the LTS Stackage release version 7.18:

guix import stackage --lts-version=7.18 HTTP

elpa

Import metadata from an Emacs Lisp Package Archive (ELPA) package repository (see Packages in The GNU Emacs Manual).

Specific command-line options are:

--archive=repo

-a repo

repo identifies the archive repository from which to retrieve the information. Currently the supported repositories and their identifiers are:

• - GNU, selected by the gnu identifier. This is the default.

  Packages from elpa.gnu.org are signed with one of the keys contained in the GnuPG keyring at share/emacs/25.1/etc/package-keyring.gpg (or similar) in the emacs package (see ELPA package signatures in The GNU Emacs Manual).

• - MELPA-Stable, selected by the melpa-stable identifier.
• - MELPA, selected by the melpa identifier.

--recursive

-r

Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

crate

Import metadata from the crates.io Rust package repository crates.io.

The structure of the guix import code is modular. It would be useful to have more importers for other package formats, and your help is welcome here (see Contributing).