Guix is all about empowering people, so it should come as no surprise that one\ncan extend it with new guix\ncommands. You\ncan show the commands available in your current Guix through the help command:
$ guix help\nIf you are using a recent Guix, there are a number of extensions at your\ndisposal, they are available as individual packages, and as a meta-package\nproviding a collection of\nextensions. Try\nthem out with:
$ guix shell guix guile guix-extension-collection\nI'm adding the guix and guile packages to the shell because we want the\ndifferent Guile and Guix search paths to be adjusted in the shell. To know\nmore about why this is needed, read Search\nPaths.
You will notice that the help menu has been extended with information about the available extensions:
\n$ guix help\n...\n extension commands\n explore interactively explore a Guix System configuration\n removals keep up to date with package removals\n compose docker compose compatibility layer\n toys Explore packages and services through REST API\n xsearch search for packages using a fast Xapian cache\n...Since this blog post is called "Extending Guix", let's write an extension, shall we?
\nGuix locates extensions by looking up\nGUIX_EXTENSIONS_PATH. Recently\nGuix has introduced a new way of writing extensions. The old way would search\nextensions under /path/to/guix/extensions and the extensions modules would be\nnamed (guix extensions NAME). The new schema expects extensions to be under\n/path/to/SCHEMA_VERSION; the name of the module will still be (guix extensions NAME).
The advantage of this new schema is the Guix can treat the extension module as a\nstandard Guile module, meaning that the runtime is able to find the compiled\n.go file of the extension. The old schema was relaying on runtime evaluation;\nthe load machinery was not handling compiled files. This has a considerable\nimprovement on performance, so you are encouraged to update any old extension to\nthe new schema.
Enough introductions, let's write a basic extension.
\nThe first step is to create the project structure. Remember that the extension\nmachinery expects modules to be named (guix extensions NAME).
We start by creating, in our project root, the directories for the extension.
\n$ mkdir -p guix/extensions\nNow, we create the file guix/extensions/hello.scm with the following contents:
(define-module (guix extensions hello))\nA blank canvas...
We import (guix scripts) to get the define-command macro. We declare it and\nexport it so the extension machinery can find the command in the public\ninterface of the module.
(define-module (guix extensions hello)\n #:use-module (guix scripts)\n #:export (guix-hello))\n(define-command (guix-hello . args)\n (category extension)\n (synopsis "say hello")\n (display "hello, I'm a Guix extension!\\n"))With this, we already have a working Guix extension. We can run the extension like this from the root of the project.
\n$ GUIX_EXTENSIONS_PATH=$PWD guix hello\nhello, I'm a Guix extension!Since we would like our extension to be discoverable by users, we will add a\nhelp message which will make the extension display in the guix help menu.
We will use (srfi srfi-37) to write the option parser, and (guix ui) for the\ninternationalized strings; you will see that I import these modules when I show\nyou the complete extension. Let's focus on the option definitions:
(define (show-help)\n (display (G_ "Usage: guix hello\\n"))\n (display (G_ "Just say hello, it's not that complicated.\\n"))\n (display (G_ "\n --help display this message"))\n (newline))\n(define %options\n (list (option '(#\\h "help") #f #f\n (lambda args\n (leave-on-EPIPE (show-help))\n (exit 0)))))Since we are only handling the arguments for showing the help message, we just need to call the parser at the start of the command:
\n(define-command (guix-hello . args)\n (category extension)\n (synopsis "say hello")\n (parse-command-line args %options (list '()))\n (display "hello, I'm a Guix extension!\\n"))Here you have the complete extension module:
\n(define-module (guix extensions hello)\n #:use-module (guix scripts)\n #:use-module (guix ui)\n #:use-module (srfi srfi-37)\n #:export (guix-hello))\n(define (show-help)\n (display (G_ "Usage: guix hello\\n"))\n (display (G_ "Just say hello, it's not that complicated.\\n"))\n (display (G_ "\n --help display this message"))\n (newline))\n(define %options\n (list (option '(#\\h "help") #f #f\n (lambda args\n (leave-on-EPIPE (show-help))\n (exit 0)))))\n(define-command (guix-hello . args)\n (category extension)\n (synopsis "say hello")\n (parse-command-line args %options (list '()))\n (display "hello, I'm a Guix extension!\\n"))With that, our extension will be present when we ask Guix for help:
\n$ GUIX_EXTENSIONS_PATH=$PWD guix help\n...\n extension commands\n hello say helloIt also takes a --help flag:
$ GUIX_EXTENSIONS_PATH=$PWD guix hello --help\nUsage: guix hello\nJust say hello, it's not that complicated.\n --help display this messageAt the time of writing, we don't have a dedicated Guix\nbuild-system\nfor extensions. Fortunately, the\nguile-build-system\nis close enough for this use case.
Let's make a package definition for our new hello extension that uses our local\nsources. Create a guix.scm file at the root of the project with the following\ncontents:
(use-modules (gnu packages package-management)\n (guix build-system guile)\n (guix gexp)\n (guix git-download)\n (guix packages)\n ((guix licenses) #:prefix license:))\n(define vcs-file?\n ;; Return true if the given file is under version control.\n (or\n (git-predicate\n (dirname (canonicalize-path\n (assq-ref (current-source-location) 'filename))))\n (const #t)))\n(define-public guix-hello\n (package\n (name "guix-hello")\n (version "0.0.0-git")\n (source (local-file (assume-valid-file-name ".")\n "pin-checkout"\n #:recursive? #t\n #:select? vcs-file?))\n (build-system guile-build-system)\n (arguments\n (list\n #:scheme-file-regexp\n #~(lambda (file stat)\n (and ((file-name-predicate #$default-scheme-file-regexp)\n file stat)\n (not ((file-name-predicate "^(guix|channels|manifest)\\\\.scm$")\n file stat))))\n #:phases\n #~(modify-phases %standard-phases\n (add-after 'build 'move-to-extension-directory\n (lambda _\n (with-directory-excursion #$output\n (mkdir-p "share/guix/extensions/1.5/guix/extensions")\n (rename-file (string-append "share/guile/site/"\n (target-guile-effective-version)\n "/guix/extensions/hello.scm")\n "share/guix/extensions/1.5/guix/extensions/hello.scm")))))))\n (native-inputs (list guix))\n (inputs (list (lookup-package-input guix "guile")))\n (home-page "https://codeberg.org/guix-extensions")\n (synopsis "Make Guix say hello")\n (description\n "This extension provides the @command{guix hello} command,\nwhich makes Guix say hello.")\n (license license:gpl3+)))\nguix-helloWe can test this new extension like this:
\n$ guix shell -CW -f guix.scm -- guix hello\nThe flags passed to guix shell are the following:
-C (--container ): To prevent your environment from interfering.-W (--nesting ): To bring the current Guix you are using into the
container so it can load the extension.
Since this example is using the new extension scheme, the guix command you\nare running must be at or newer than commit\nde069958fc.
I hope you find this small introduction to Guix extensions useful and that you start to write your own Guix extensions.
\nI would like to encourage everyone reading this to submit their extensions to\nthe guix-extensions Codeberg\norganization. The idea is to make this organization a central hub for everyone\nto participate in the development of useful extensions for the community.
\nUnless otherwise stated, blog posts on this site are\ncopyrighted by their respective authors and published under the terms of\nthe CC-BY-SA 4.0 license and those of the GNU Free Documentation License (version 1.3 or later, with no Invariant Sections, no\nFront-Cover Texts, and no Back-Cover Texts).
","headings":[{"level":1,"text":"Extending Guix","id":"extending-guix"},{"level":1,"text":"How does Guix locate extensions?","id":"how-does-guix-locate-extensions"},{"level":1,"text":"Writing an extension","id":"writing-an-extension"},{"level":1,"text":"Packaging a Guix extension","id":"packaging-a-guix-extension"},{"level":1,"text":"Closing words","id":"closing-words"}]}}