13.4 Invoquer guix home

Une fois que vous avez écrit une déclaration d’environnement personnel (voir Déclarer l'environnement personnel), elle peut être instanciée avec la commande guix home. Voici le résumé de la commande :

guix home options… action file

file doit être le nom d’un fichier contenant une déclaration home-environment. action spécifie comment l’environnement personnel est instancié, mais il y a quelques actions supplémentaires qui ne l’instancient pas. Actuellement les valeurs suivantes sont prises en charge :

search

Affiche les définitions des types de services personnels disponibles qui correspondent aux expressions régulières données, triées par pertinence :

$ guix home search shell
name: home-shell-profile
location: gnu/home/services/shells.scm:100:2
extends: home-files
description: Create `~/.profile', which is used for environment initialization of POSIX compliant login shells.
+ This service type can be extended with a list of file-like objects.
relevance: 6

name: home-fish
location: gnu/home/services/shells.scm:640:2
extends: home-files home-profile
description: Install and configure Fish, the friendly interactive shell.
relevance: 3

name: home-zsh
location: gnu/home/services/shells.scm:290:2
extends: home-files home-profile
description: Install and configure Zsh.
relevance: 1

name: home-bash
location: gnu/home/services/shells.scm:508:2
extends: home-files home-profile
description: Install and configure GNU Bash.
relevance: 1

…

As for guix search, the result is written in recutils format, which makes it easy to filter the output (voir GNU recutils databases dans GNU recutils manual).

conteneur

Spawn a shell in an isolated environment—a container—containing your home as specified by file.

For example, this is how you would start an interactive shell in a container with your home:

guix home container config.scm

This is a throw-away container where you can lightheartedly fiddle with files; any changes made within the container, any process started—all this disappears as soon as you exit that shell.

As with guix shell, several options control that container:

--network

-N

Enable networking within the container (it is disabled by default).

--expose=source[=cible]

--share=source[=cible]

As with guix shell, make directory source of the host system available as target inside the container—read-only if you pass --expose, and writable if you pass --share (voir --expose and --share).

Additionally, you can run a command in that container, instead of spawning an interactive shell. For instance, here is how you would check which Shepherd services are started in a throw-away home container:

guix home container config.scm -- herd status

The command to run in the container must come after -- (double hyphen).

edit

Edit or view the definition of the given Home service types.

For example, the command below opens your editor, as specified by the EDITOR environment variable, on the definition of the home-mcron service type:

guix home edit home-mcron

reconfigure

Build the home environment described in file, and switch to it. Switching means that the activation script will be evaluated and (in basic scenario) symlinks to configuration files generated from home-environment declaration will be created in ~. If the file with the same path already exists in home folder it will be moved to ~/timestamp-guix-home-legacy-configs-backup, where timestamp is a current UNIX epoch time.

Remarque : Il est grandement recommandé de lancer guix pull une fois avant de lancer guix home reconfigure pour la première fois (voir Invoquer guix pull).

This effects all the configuration specified in file. The command starts Shepherd services specified in file that are not currently running; if a service is currently running, this command will arrange for it to be upgraded the next time it is stopped (e.g. by herd stop service or herd restart service).

Cette commande crée une nouvelle génération dont le numéro est un de plus que la génération actuelle (rapportée par guix home list-generations). Si cette génération existe déjà, elle sera réécrite. Ce comportement correspond à celui de guix package (voir Invoquer guix package).

À la fin, le nouveau dossier personel est déployé dans ~/.guix-home. Ce répertoire contient les métadonnées de provenance : la liste des canaux utilisés (voir Canaux) et le fichier lui-même, s’il est disponible. Vous pouvez voir les informations de provenance avec :

guix home describe

Cette information est utile si vous voulez plus tard inspecter comment une génération particulière a été construite. En fait, en supposant que file est auto-contenu, vous pouvez reconstruire la génération n de votre environnement personnel avec :

guix time-machine \
  -C /var/guix/profiles/per-user/USER/guix-home-n-link/channels.scm -- \
  home reconfigure \
  /var/guix/profiles/per-user/USER/guix-home-n-link/configuration.scm

Vous pouvez considérer cela comme une sorte de contrôle de version intégré ! Votre dossier personnel n’est pas seulement un artefact binaire : il contient ses propres sources.

switch-generation

Bascule à une génération du dossier personnel existante. Cette action bascule de manière atomique à la génération du dossier personnel spécifiée.

La génération cible peut être spécifiée explicitement par son numéro de génération. Par exemple, l’invocation suivante passerait à la génération 7 du dossier personnel :

guix home switch-generation 7

La génération cible peut aussi être spécifiée relativement à la génération actuelle avec la forme +N ou -N, où +3 signifie « trois générations après la génération actuelle » et -1 signifie « une génération précédent la génération actuelle ». Lorsque vous spécifiez un nombre négatif comme -1, il doit être précédé de -- pour éviter qu’il ne soit compris comme une option. Par exemple :

guix home switch-generation -- -1

Cette action échouera si la génération spécifiée n’existe pas.

roll-back

Passe à la génération précédente du dossier personnel. C’est le contraire de reconfigure, et c’est exactement comme invoquer switch-generation avec pour argument -1.

delete-generations

Supprimer des générations du dossier personnel, ce qui les rend disponibles pour le ramasse-miettes (voir Invoquer guix gc, pour des informations sur la manière de lancer le « ramasse-miettes »).

Cela fonctionne comme pour ‘guix package --delete-generations’ (voir --delete-generations). Avec aucun argument, toutes les générations du dossier personnel sauf la génération actuelle sont supprimées :

guix home delete-generations

Vous pouvez aussi choisir les générations que vous voulez supprimer. L’exemple plus bas supprime toutes les génération du dossier personnel plus vieilles que deux mois :

guix home delete-generations 2m

build

Construit la dérivation de l’environnement personnel, ce qui comprend tous les fichiers de configuration et les programmes requis. Cette action n’installe rien.

describe

Décrit la génération du dossier personnel actuel : son nom de fichier, ainsi que les informations de provenance si elles sont disponibles.

list-generations

Affiche un résumé de chaque génération de l’environnement personnel disponible sur le disque, dans un format lisible pour un humain. C’est similaire à l’option --list-generations de guix package (voir Invoquer guix package).

Éventuellement, on peut spécifier un motif, avec la même syntaxe utilisée pour guix package --list-generations, pour restreindre la liste des générations affichées. Par exemple, la commande suivante affiche les générations de moins de 10 jours :

$ guix home list-generations 10d

import

Génère un environnement personnel à partir des paquets du profil par défaut et des fichiers de configuration qui se trouvent dans votre répertoire personnel. Les fichiers de configuration sont copiés vers le répertoire donné, et un fichier home-configuration.scm sera rempli avec l’environnement personnel. Remarquez que les services personnels existants ne sont pas tous pris en charge (voir Services du dossier personnel).

$ guix home import ~/guix-config
guix home: « /home/alice/guix-config » rempli avec tous les fichiers de configuration du dossier personnel

And there’s more! guix home also provides the following sub-commands to visualize how the services of your home environment relate to one another:

extension-graph

Emit to standard output the service extension graph of the home environment defined in file (voir Composition de services, for more information on service extensions). By default the output is in Dot/Graphviz format, but you can choose a different format with --graph-backend, as with guix graph (voir --backend):

La commande :

guix home extension-graph file | xdot -

montre les relations d’extension entre les services.

shepherd-graph

Emit to standard output the dependency graph of shepherd services of the home environment defined in file. Voir Services Shepherd, for more information and for an example graph.

Encore une fois, le format de sortie par défaut est Dot/Graphviz, mais vous pouvez passer --graph-backend pour en choisir un autre.

options peut contenir n’importe quelle option commune de construction (voir Options de construction communes). En plus, options peut contenir l’une de ces options :

--expression=expr

-e expr

Considère l’environnement personnel en lequel s’évalue expr. C’est une alternative à la spécification d’un fichier qui s’évalue en un environnement personnel.

--allow-downgrades

Instruct guix home reconfigure to allow system downgrades.

Just like guix system, guix home reconfigure, by default, prevents you from downgrading your home to older or unrelated revisions compared to the channel revisions that were used to deploy it—those shown by guix home describe. Using --allow-downgrades allows you to bypass that check, at the risk of downgrading your home—be careful!