the what

First and foremost, for the requirements.
In my case, the requisites are simple, even if hard to get when one thinks about.
I need a distracting free environment to concentrate on what really matters: the content I’m willing to share. For sure, I do need to remain within my working environment, that’s to say, #emacs. I need to switch context quickly between any current activity and writing prose when something comes up; while writing, I need to stay focus. Similarly, I want to switch back to previous context when the writing is complete. No doubt, I need to complete previous posts when I have something new to include or to correct, so I need a means of retrieving previous posts quickly. Needless to say, I need a #freesoftware tool I may tune to my needs, fixing issues or including new features.
Last, but not least, I privilege a way to push remotely without complicated compilations of anything at all: a couple of keystrokes, and the post is sent online under its right form, including some markup and images. Updating previous versions if necessary should be that simple too, and I must be able to check the rendering with any web browser, included eww under emacs, so no javascript or fancy stuff involved. That’s it by now.
Easy, right ?

the how

My current choice goes for writefreely as an open, decentralized and free alternative to web publishing on the web, which concentrates on providing a simple reading experience. This solution may be self-hosted, but there are also some friendly communities around helping out. Infosec.press is one of them. Blog posts show up in the #fediverse under the (platform) user account, so that they are easy to follow. Server side, this is more than what I need.
But, client side ?, you must be asking. To write text, I’m using #orgmode, with all of its facilities, and not the markdown supported by default by the platform. Then, writefreely.el takes care of exporting contents, handling the data exchange with the server through the provided api. I had to fix a couple of issues before, mostly trivial side effects. This is one of the biggest advantages of #freesoftware, having the possibility to contribute to bug fixing, improving a common.
As for the question on how to access the blog contents locally, I opt for a different #plaintext file by blog ticket, that I manipulate as any other #orgroam node. Orgroam allows to quickly retrieve, manipulate and insert as links previous notes. When I type the name of a non-existing note, it creates a new one for me, based on a custom template which incorporates the necessary headings, title, tags and the like. It resuls in something like:

:PROPERTIES:
:ID:       ID-6dd1-45d7-a70e-ae5c99c2797a
:END:
#+TITLE: on writting freely
#+OPTIONS: toc:nil -:nil \n:t
#+LINK: srht https://repo/pics/%s
#+filetags: :tag1:tag2:
# a comment
[[srht:image.png]]
Donec neque quam, dignissim in, mollis nec, sagittis eu, wisi ... <!--more-->
Nunc eleifend leo vitae magna.

You’ll figure it out.
Remains the question of images: just simply, they are hosted on an unlisted git repository, from where they are fetched. Now, with my working environment and with a couple of keys, I may pop up a new buffer, write some content, then publish, delete or update a new article within seconds, checking the results with #eww, all without leaving #emacs. You’ll get a set of local variables append to you buffer when you publish for the first time, something like

# Local Variables:
# writefreely-post-id: "ID"
# writefreely-post-token: nil
# End:

which allows to retrieve the post online afterwards.
Put the whole under #git control, and the perfect blogging setup is ready for you to enjoy writing ! Simple, elegant and efficient.
Finally, I have packaged writefreely.el and sent a patch to #guix so that it will hopefully get merged upstream soon.

Curious about everything
#FreeSoftware and computer science #freedom as a basic right
Doing public #research in France
Using #emacs, what else ?

sr.ht ◦ cv-fr ◦ cv-hal ◦ orcid ◦ bibtex ◦ gitlab.com ◦ perso

install

First things first. You need to be root to proceed to a binary guix installation. Just download the installer, and follow the instructions.
After that, you’ll be using guix as a regular user, and all what follows must be run without any special rights beyond accessing to your home directory. Behind the curtains, guix computes what’s necessary through the running guix daemon, handled by your host’s systemd.

packages

Packages are built definitions. At no surprise, they are installed (or removed) with

guix search synthesis
guix install yosys
guix remove python

Definitions, in turn, are guile descriptions on how and where to obtain code source, a precise and unambiguous reference to it, how to process and how to install it, along with the necessary input dependencies, its kind, and how to use them. Definitions may be seen as customized default build templates, which avoids complicated package definitions, simplifying its design. Thus, a default build template called python-build-system exist, for example, for producing python packages. A package definition customizes the way this template is used, modifying its default package, source, etc. fields.
Definitions are built on isolated, minimalistic environments. Once built, packages are deposit in the guix store under /gnu/store. Each package is given a unique hash: changing the definition, or any of its inputs, produces a different package and hash. This is what usually is referred to as functional package management of #dependencies.
A package may have multiple outputs (out, by default, but also doc, etc.). Packages are built locally following the package definition. To avoid long run times and wasting cpu cycles, guix introduces substitutes or pre-built packages available on remote (substitute) servers. When available, substitutes are downloaded, which avoids having to built packages locally. Otherwise, your local computing resources will be put to contribution, which is far from ideal, so better configure your substitute servers before anything else (check your systemd guix-daemon file). It is possible to verify substitute availability with

guix weather ghdl-clang

  https://guix.bordeaux.inria.fr ☀
--> 100.0 % des substituts sont disponibles (1 sur 1)  <--
    6,2 Mio de fichiers nar (compressés)
    39,6 Mio sur le disque (décompressé)
    0,777 secondes par requête (0,8 secondes en tout)
    1,3 requêtes par seconde

It is crucial to understand that a given package built will be identical to any other build of this same package, regardless of the host computer, which is what holds the validity of the very idea of substitutes, and guarantees #reproducibility. This holds for any guix construction, including shell containers (see below).
Keep that in mind.

profiles and generations

After first install, guix will create on your behalf a default profile under ~/.guix-profile. All operations (install, remove) will affect this profile, unless you decide to point somewhere else (with the modifier -p $GUIX_PROFILE).

guix package -p $GUIX_PROFILE --list-installed

coreutils       9.1     out     /gnu/store/fk39d3y3zyr6ajyzy8d6ghd0sj524cs5-coreutils-9.1
git             2.46.0  out     /gnu/store/wyhw9f49kvc7qvbsbfgm09lj0cpz1wlb-git-2.46.0
fw-open-logic   3.0.1   out     /gnu/store/hrgdvswmvqcyai4pqmr7df0kpyyak94j-fw-open-logic-3.0.1
osvvm-scripts   2024.09 out     /gnu/store/xhxr3y1k8838my6mfk992kn392pwszjm-osvvm-scripts-2024.09
osvvm-uart      2024.09 out     /gnu/store/x3pjf95h8p3mbcx4zxb6948xfq3y3vg8-osvvm-uart-2024.09
fd              9.0.0   out     /gnu/store/nx0hz1y3g7iyi4snyza7rl5600z73xyn-fd-9.0.0
make            4.4.1   out     /gnu/store/963iman5zw7zdf128mqhklihvjh6habm-make-4.4.1
tcllib          1.19    out     /gnu/store/443vgrmwac1mvipyhin5jblsml9lplxf-tcllib-1.19
tcl             8.6.12  out     /gnu/store/w2icygvc0h294bzak0dyfafq649sdqvn-tcl-8.6.12
ghdl-clang      4.1.0   out     /gnu/store/sy0ryysxwbkzj6gpfka20fs27knmgmkd-ghdl-clang-4.1.0

Each profile generation will consist on a set of symbolic links pointing to /gnu/store. A new generation is produced when you install or remove something. This will only redefine your profile’s links, and so the status of the profile (and the packages you have access to). Generations are roughly the equivalent of #git commits, if this helps. They are nothing but collections of links pointing to the store, where packages are installed. Each collection defines a generation and so the current status of a guix profile.
You may roll back to previous generations, or move forward, but only linear generation histories are allowed. In you go back n generations, and then create a new one, your previous history is lost.

guix package -p $GUIX_PROFILE --list-generations

In addition to creating links, a profile redefines the environment variables (following the profle contents), appending, prepending or replacing the current ones. This way, the user enters an augmented context, having access to the packages in the profile.
Note that, inside a profile, the user still have access to the external system: for example, the PATH env variable is augmented with the profile bin directory, but former binaries are still there. To get a higher degree of isolation, we need shell containers (see below).

clean

From time to time, don’t forget to clean the store, removing stuff no profile and generation is pointing to, with

guix gc

Before that, remove old generations from your profiles, unless you plan to make use of them at some point.

upgrade

Upgrade guix current profile with

guix pull && guix upgrade

This will create a new generation in your default profile, including updates to all your packages in current profile. Pulling syncs local guix with remote guix repository, fetching updates locally. Upgrade will deploy these updates to your profile.
Remember also to

sudo -i guix pull
sudo systemctl daemon-reload
sudo systemctl restart guix-daemon

to upgrade the system daemon, so that it is never too delayed with respect to your guix in use.

manifest, channels

If not already clear from the previous, remember that it is possible to replicate environments (contexts, profiles, dependencies) using a couple of #plaintext files.
First, the #manifest.scm, which includes the list of packages in the environment. As an example, export your current profile with

guix package -p $GUIX_PROFILE --export-manifest > manifest.scm

Put it somewhere under version control, and replicate your environment somewhere else with

guix package -p $GUIX_PROFILE -m manifest.scm

That’s all it takes to get exactly the same development context in another host, for example.
But you’re right, I see you follow. This is not enough. You also need to freeze which guix version you’re using (guix, as any other package manager, not always installs the same version of some package). You need also a #channels.scm file. It may be produced with

guix describe --format=channels -p $GUIX_PROFILE > channels.scm

and includes the list of channels in use, along with a hash to identify which version of the channels to use, among the whole history of channel revisions (the #git commit of the channel repository). Then, import it somewhere else with

guix pull -C channels.scm

examples

Fixing your channels, its revision and the list of packages is all you need to eliminate any ambiguity, achieving #reproducibility and #determinism. Remember that this is the best advantage of guix, after all. Say you publish something (report, article, paper, blog ticket). If you provide a git repository with these two files, anyone else will be
able, hopefully, to replicate your asserts.
As a typical example, when you have a complex #vhdl design, including a large set of dependencies, you need a means to handle them. Here, we assume the #dependencies may be vhdl compilers, tcl shells, python interpreters, unit testing libraries, verification frameworks. etc. ... but also other vhdl modules, each in its own git repository.
At this point, you’ll need, first, to fix your channels.scm to “freeze” the repositories status. Here we are using, for example, the electronics, guix-science and guix channels, each in a fix release given by a commit hash.

(list (channel
       (name 'electronics)
       (url "https://git.sr.ht/~csantosb/guix.channel-electronics")
       (branch "main")
       (commit
        "2cad57b4bb35cc9250a7391d879345b75af4ee0a")
       (introduction
        (make-channel-introduction
         "ba1a85b31202a711d3e3ed2f4adca6743e0ecce2"
         (openpgp-fingerprint
          "DA15 A1FC 975E 5AA4 0B07  EF76 F1B4 CAD1 F94E E99A"))))
      (channel
       (name 'guix-science)
       (url "https://codeberg.org/guix-science/guix-science.git")
       (branch "master")
       (commit
        "1ced1b3b913b181e274ca7ed2239d6661c5154c9")
       (introduction
        (make-channel-introduction
         "b1fe5aaff3ab48e798a4cce02f0212bc91f423dc"
         (openpgp-fingerprint
          "CA4F 8CF4 37D7 478F DA05  5FD4 4213 7701 1A37 8446"))))
      (channel
       (name 'guix)
       (url "https://git.savannah.gnu.org/git/guix.git")
       (branch "master")
       (commit
        "3e2442de5268782213b04048463fcbc5d76accd7")
       (introduction
        (make-channel-introduction
         "9edb3f66fd807b096b48283debdcddccfea34bad"
         (openpgp-fingerprint
          "BBB0 2DDF 2CEA F6A8 0D1D  E643 A2A0 6DF2 A33A 54FA")))))

Then, you need the list of dependencies necessary to your design. These are provided in a manifest.scm file, as for example in

(specifications->manifest
 (list "ghdl-clang"
       "tcl"
       "tcllib"
       "make"
       "python-vunit"
       "osvvm-uart"
       "osvvm-scripts"
       "fw-open-logic"
       "git"
       "which"
       "findutils"
       "coreutils"))

One may include these two files in the design, in a different testing #git branch, for example. Then, all it takes to run your design in a reproducible way is cloning the design git repository, checking out the testing branch, and running #guix time machine (see next) to replicate a local profile containing all the design’s dependencies. Remember that here we include also all third party firmware modules instantiated in our design.

time machine

How guix guarantees that it is possible to reproduce a profile in the future ? The trick consist on asking current guix version to call a previous guix version (the one we define), to deploy the profile with the packages we need.
For example: let's ask guix-5 to make use of guix-4 to install emacs-30 package, which is only available in the guix-4 repositories, whereas guix-5 only provides emacs-32.
This mechanism is called time-machine. It is used as, for example:

guix time-machine --channels=channels.scm -- package -p $GUIX_PROFILE -m manifest.scm

Here, up-to-date guix uses time machine to roll back to the former guix version defined in channels.scm. Then, former guix calls the package command to install under $GUIX_PROFILE the list of packages defined in the manifest.scm file.
What’s important to understand here is that this will produce exactly the same output regardless of the host and the point in time when we run this command. The profile we produce is always the same, by design. And this is what is relevant for #modernhw.

shell containers

Guix includes a command to create independent environments from the rest of our host system. This provides an increased degree of isolation when compared to profiles, as the later lie on top of, and only augment, our current shell. Shell containers create a new, almost empty by default, minimalistic context for us to install packages.

guix shell --container --link-profile --emulate-fhs coreutils which python-vunit osvvm-uart
guix shell --container --link-profile --emulate-fhs -m manifest.scm

or, if one needs determinism

guix time-machine --channels=channels.scm -- shell --container --link-profile --emulate-fhs -m manifest.scm

The --link-profile flag will link the contents of $GUIX_PROFILE under /gnu/store to ~/.guix-profile.
The --emulate-fs will, well, reproduce the standard file system under /, as some packages expect this layout and fail otherwise.
coreutils and which packages will be helpful, otherwise, not even ls command is present within the container. Minimalistic, I said. I should have use isolated instead.

packs

Great. But. What if guix is not around ? How do I use it in a cluster, or in another host where guix is not yet available ? How do I distribute my dependencies, environments, etc. to a non-yet-guix-user ? No problem, guix pack is intended to be used as a simple way of “packaging” guix contexts (understood as a set of packages), deploying them afterward in a target host. This is next step after profiles and shell containers.
Guix pack comes equipped with several different backends, producing contexts in the most habitual and useful formats. For example, the following command will pack #emacs, #ghdl and #yosys for you to use where you need it.

guix pack -f docker emacs ghdl-clang yosys

In the context of #modernhw, #docker images may be used for #ci tests, uploading the image to a remote #gitforge registry; #apptainer containers can be sent and run in a #hpc cluster; .tar.gz compresses files are a clean may of installing non-existing software in a remote machine. Furthermore, one has the possibility of packaging all the project #dependencies in a manifest.scm file, and distribute it along with the source code to anyone willing to use it. No instructions about the proper environment to run the project, no complicated installation of dependencies. Stop asking third party users in your README to handle your dependencies for you.
A simple docker pull pointing to a #forge image repository is enough when guix is not locally available. Long run times ? Use a #forge #ci custom runner in your own hardware with your #singularity image. Remote work to an #ssh server with obsolete software ? Pack, send and untar your favorite development tools and create a custom profile, no admin rights needed. The possibilities are endless.
And most important: the advantage of this approach over a classical docker or singularity files for producing the images is #reproducibility: every single time you build the image, you’ll get the exact same binary product. Use the --save-provenance flag to store in the image itself the manifest you used to create it.
Good luck trying to achieve the same with a docker file.

importing

Now, guix is not a universal tool for installing anything around. What about this obscure #python package no one uses but you ? You’d absolutely need this #emacs package you just found on #codeberg which guix doesn’t provide. Rust, go ... There are plenty of pieces of code around not being yet packaged along with guix. No problem. Guix incorporates a simple and elegant way of extending the amount of packages you’ll be able to install. Just import them.

guix import pypi itsdangerous
guix import crate becareful
guix import gem wow

Previous commands will issue a new package definition corresponding to a package already handled by the language own package manager. #Dependencies, you say ? Use the --recursive flag. Once you have the definition, you’ll be able to build, install and use the corresponding package.
Check in the documentation the surprising amount of backends available, you’ll be gratefully surprised.

software heritage

Last, but not least.
You have guix, its package definitions and all the fancy tools which come along. But. What if you don’t have access to the source code ? In this case, all the previous becomes meaningless: remember that guix is a fully bootstrapped distribution, being built from the very bottom up. Building a package from its source means having access to the source, which most of the time is hosted in a #gitforge. But #forges disappear, especially proprietary ones, repositories relocate or are just obsoleted and get replaced.
In this case, guix gets you covered by falling back to Software Heritage (#SH). This initiative, with support of the UNESCO, collects, preserves, and shares the source code of all software that is publicly available, including its full development history. The collection is trigger automatically by a crawler, manually with a browser plugin or by guix itself when developers lint package definitions.
If, in ten years, you try to replicate one of your papers, and you plan to recreate your environment to run your code and reproduce your plots, you won’t be bothered by nowadays python 3.10 having being obsoleted, abandon and buried in history of computers by #guile. SH keeps a copy for you to sleep better at night.

channels

Channels, as a feature to extend guix repository of definitions, deserve its own chapter.

usual suspects

Other than guix channel itself, you may have a feeling of what a guix channel looks like taking a look at the guix-science organization. In there, you’ll find collections of package definitions intended to be used in a context of specific research domains, both in its free and nonfree forms. For one reason or another, they have not their place in the main guix repository, and they live their life in here. Interesting enough, guix-past channel brings old-fashioned software to the present, which reveals useful to reproduce results older than guix itself. Another interesting examples are guixrus, by the ~whereiseveryone collective, providing packages not yet fully tested, nightly releases or alpha quality software; or the guix-hpc channel, with packages related to high performance computing; also guix-bioc, containing bioconductor packages, etc. You get the idea.
To include additional channels, other than the default ones, in your ~/.config/guix/channels.scm file, follow the documentation, and check with guix describe: you’ll get a list of all the channels in use next time you do a guix pull. At this point, you’ll have plenty of new packages to install at your hands ! Just remember the discussion about substitutes: some channels provide substitute servers, some not. This might be an issue, or not, depending of the computing resources necessary to build certain packages.

your first personal channel

Guix channels are simple to create and use. Just put your #guile modules, containing your package definitions, in a git repository. To use them, complete the default guix load path as in

guix install -L ~/guix-channel PACKAGE

You may opt to include this local channel into your ~/.config/guix/channels.scm file, or include the -L flag in your commands. As an alternative, guix searches for package definitions in the $GUIX_PACKAGE_PATH, so you may put your channel path in this variable. Remember that guix builds packages by compiling source code: no substitute server will do the job for you in this case, so plan accordingly with your local resources and patience.

electronics channel

This is about #modernhw after all, so let’s see an example more on detail, my own guix-electronics channel which complements the ./gnu/packages/electronics.scm guix module. This is the channel I’m using daily, where I include all the packages I need and doesn’t yet exist upstream. When they get merged somewhere else, I remove them from here. In the meantime, I’m a happy user of my custom packages.
I classify all my package definitions in #guile modules under ./electronics/packages/MODULE.scm. This is the reason why the compilers module, for example, starts by

(define-module (electronics packages compilers)

Then, proceed as usual (check the guix repo itself for inspiration), putting your packages below

(define-public mypackage
  (package
    (name "mypackage")
    ...
    ))

I create a git repo, commit my changes and push it online to a #gitforge.
I need a .guix-channel file with the url of my channel and a version number. If the code in the channel depends on other channels other than main guix channel, one needs to specify this information in this file too. In this case, for example, several of the package definitions include a dependency on ghdl-clang, provided by guix-science channel, so I need to declare it in here too.
It is also necessary a .guix-authorizations file, with the (GPG key) list of developers with right to push to this channel. This is how guix authenticates channels. Finally, it is important to create a readme file or similar where introduce the channel (first commit, signing key fingerprint). That’s it. Include the channel introduction into your ~/.config/guix/channels.scm file, and you’ll be pulling from your online guix channel.

contributing

The advantage of using a custom channel is to benefit from an increased degree of freedom when using guix, without being dependent of someone’s else time availability to consider your particular needs. Remember, guix is a huge project which follows closely the #freesoftware paradigm, and collaboration works in two directions. You take advantage of other developers contributions to guix, while you participate yourself to improving guix repositories with your package definitions, once they have been tested.
Take for example the list of packages in my electronics channel. I have included here utilities for #vhdl code editing under #emacs, specific to the electronic digital design field, which are not yet available in guix upstream channel. There is also a cosimulation library, #cocotb, which allows coupling #python and #ghdl to simulate a design. I have submitted a patch to include this in guix itself, similarly to python-vunit; once merged, I’ll remove them from here.
Some packages, like open fpga loader are now part of guix. Some others, like the gnat ada compiler and ghdl-clang stable have been merged already on guix-science, as gnat package is obtained from binaries (and so ghdl-clang is also impacted, from guix perspective). I include here a more recent ghdl-clang, non yet released, as it includes some fixes and improvements I am interested in, without having to wait until guix incorporates a new release.
Catch the idea ?
Contributing your code to guix comes to sending #email with your patches attached, it’s that simple. Dont be intimidated by the workflow (this is used by the linux project, for example). Once your patches are submitted, a review of your code folllows, see details. Some tools, like mumi, are helpful to that purpose.
These simple steps will allow you to start contributing to guix:

• git clone guix itselft
  
• add and commit your changes, watch the commit message
  
• don’t forget to use guix lint/style/refresh -l to check your code
  
• use git send-email to create and send a patch
  
• cosider reviews, if any, updating your patch accordingly with git ammend
  
• resend a new patch including a patch version (v1, v2 ...)
  

Interested ? Consult the doc for details, you’ll learn a lot about how to contribute to a common good and collaboration with other people.