A ``Hello World'' package (GNU Guix Cookbook)

2.1.1 A “Hello World” package

The “Defining Packages” section of the manual introduces the basics of Guix packaging (see Defining Packages in GNU Guix Reference Manual). In the following section, we will partly go over those basics again.

GNU Hello is a dummy project that serves as an idiomatic example for packaging. It uses the GNU build system (./configure && make && make install). Guix already provides a package definition which is a perfect example to start with. You can look up its declaration with guix edit hello from the command line. Let’s see how it looks:

(define-public hello
  (package
    (name "hello")
    (version "2.10")
    (source (origin
              (method url-fetch)
              (uri (string-append "mirror://gnu/hello/hello-" version
                                  ".tar.gz"))
              (sha256
               (base32
                "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
    (build-system gnu-build-system)
    (synopsis "Hello, GNU world: An example GNU package")
    (description
     "GNU Hello prints the message \"Hello, world!\" and then exits.  It
serves as an example of standard GNU coding practices.  As such, it supports
command-line arguments, multiple languages, and so on.")
    (home-page "https://www.gnu.org/software/hello/")
    (license gpl3+)))

As you can see, most of it is rather straightforward. But let’s review the fields together:

‘name’

The project name. Using Scheme conventions, we prefer to keep it lower case, without underscore and using dash-separated words.

‘source’

This field contains a description of the source code origin. The origin record contains these fields:

The method, here url-fetch to download via HTTP/FTP, but other methods exist, such as git-fetch for Git repositories.
The URI, which is typically some https:// location for url-fetch. Here the special ‘mirror://gnu‘ refers to a set of well known locations, all of which can be used by Guix to fetch the source, should some of them fail.
The sha256 checksum of the requested file. This is essential to ensure the source is not corrupted. Note that Guix works with base32 strings, hence the call to the base32 function.

‘build-system’

This is where the power of abstraction provided by the Scheme language really shines: in this case, the gnu-build-system abstracts away the famous ./configure && make && make install shell invocations. Other build systems include the trivial-build-system which does not do anything and requires from the packager to program all the build steps, the python-build-system, the emacs-build-system, and many more (see Build Systems in GNU Guix Reference Manual).

‘synopsis’

It should be a concise summary of what the package does. For many packages a tagline from the project’s home page can be used as the synopsis.

‘description’

Same as for the synopsis, it’s fine to re-use the project description from the homepage. Note that Guix uses Texinfo syntax.

‘home-page’

Use HTTPS if available.

‘license’

See guix/licenses.scm in the project source for a full list of available licenses.

Time to build our first package! Nothing fancy here for now: we will stick to a dummy my-hello, a copy of the above declaration.

As with the ritualistic “Hello World” taught with most programming languages, this will possibly be the most “manual” approach. We will work out an ideal setup later; for now we will go the simplest route.

Save the following to a file my-hello.scm.

(use-modules (guix packages)
             (guix download)
             (guix build-system gnu)
             (guix licenses))

(package
  (name "my-hello")
  (version "2.10")
  (source (origin
            (method url-fetch)
            (uri (string-append "mirror://gnu/hello/hello-" version
                                ".tar.gz"))
            (sha256
             (base32
              "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  (build-system gnu-build-system)
  (synopsis "Hello, Guix world: An example custom Guix package")
  (description
   "GNU Hello prints the message \"Hello, world!\" and then exits.  It
serves as an example of standard GNU coding practices.  As such, it supports
command-line arguments, multiple languages, and so on.")
  (home-page "https://www.gnu.org/software/hello/")
  (license gpl3+))

We will explain the extra code in a moment.

Feel free to play with the different values of the various fields. If you change the source, you’ll need to update the checksum. Indeed, Guix refuses to build anything if the given checksum does not match the computed checksum of the source code. To obtain the correct checksum of the package declaration, we need to download the source, compute the sha256 checksum and convert it to base32.

Thankfully, Guix can automate this task for us; all we need is to provide the URI:

$ guix download mirror://gnu/hello/hello-2.10.tar.gz

Starting download of /tmp/guix-file.JLYgL7
From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz...
following redirection to `https://mirror.ibcp.fr/pub/gnu/hello/hello-2.10.tar.gz'...
 …10.tar.gz  709KiB                                 2.5MiB/s 00:00 [##################] 100.0%
/gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i

In this specific case the output tells us which mirror was chosen. If the result of the above command is not the same as in the above snippet, update your my-hello declaration accordingly.

Note that GNU package tarballs come with an OpenPGP signature, so you should definitely check the signature of this tarball with ‘gpg‘ to authenticate it before going further:

$ guix download mirror://gnu/hello/hello-2.10.tar.gz.sig

Starting download of /tmp/guix-file.03tFfb
From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz.sig...
following redirection to `https://ftp.igh.cnrs.fr/pub/gnu/hello/hello-2.10.tar.gz.sig'...
 ….tar.gz.sig  819B                                                                                                                       1.2MiB/s 00:00 [##################] 100.0%
/gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig
0q0v86n3y38z17rl146gdakw9xc4mcscpk8dscs412j22glrv9jf
$ gpg --verify /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
gpg: Signature made Sun 16 Nov 2014 01:08:37 PM CET
gpg:                using RSA key A9553245FDE9B739
gpg: Good signature from "Sami Kerola <kerolasa@iki.fi>" [unknown]
gpg:                 aka "Sami Kerola (http://www.iki.fi/kerolasa/) <kerolasa@iki.fi>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 8ED3 96E3 7E38 D471 A005  30D3 A955 3245 FDE9 B739

You can then happily run

$ guix package --install-from-file=my-hello.scm

You should now have my-hello in your profile!

$ guix package --list-installed=my-hello
my-hello	2.10	out
/gnu/store/f1db2mfm8syb8qvc357c53slbvf1g9m9-my-hello-2.10

We’ve gone as far as we could without any knowledge of Scheme. Before moving on to more complex packages, now is the right time to brush up on your Scheme knowledge. See A Scheme Crash Course to get up to speed.