This is guix.pt_BR.info, produced by makeinfo version 6.7 from guix.pt_BR.texi. Copyright © 2012-2022 Ludovic Courtès Copyright © 2013, 2014, 2016 Andreas Enge Copyright © 2013 Nikita Karetnikov Copyright © 2014, 2015, 2016 Alex Kost Copyright © 2015, 2016 Mathieu Lirzin Copyright © 2014 Pierre-Antoine Rault Copyright © 2015 Taylan Ulrich Bayırlı/Kammer Copyright © 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari Copyright © 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Ricardo Wurmus Copyright © 2016 Ben Woodcroft Copyright © 2016, 2017, 2018, 2021 Chris Marusich Copyright © 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner Copyright © 2016 John Darrington Copyright © 2016, 2017 Nikita Gillmann Copyright © 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen Copyright © 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller Copyright © 2016 Alex ter Weele Copyright © 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines Copyright © 2017, 2018, 2019 Clément Lassieur Copyright © 2017, 2018, 2020, 2021, 2022 Mathieu Othacehe Copyright © 2017 Federico Beffa Copyright © 2017, 2018 Carlo Zancanaro Copyright © 2017 Thomas Danckaert Copyright © 2017 humanitiesNerd Copyright © 2017, 2021 Christine Lemmer-Webber Copyright © 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke Copyright © 2017, 2019, 2020, 2022 Hartmut Goebel Copyright © 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer Copyright © 2017–2022 Tobias Geerinckx-Rice Copyright © 2017 George Clemmer Copyright © 2017 Andy Wingo Copyright © 2017, 2018, 2019, 2020 Arun Isaac Copyright © 2017 nee Copyright © 2018 Rutger Helling Copyright © 2018, 2021 Oleg Pykhalov Copyright © 2018 Mike Gerwitz Copyright © 2018 Pierre-Antoine Rouby Copyright © 2018, 2019 Gábor Boskovits Copyright © 2018, 2019, 2020, 2022 Florian Pelz Copyright © 2018 Laura Lazzati Copyright © 2018 Alex Vong Copyright © 2019 Josh Holland Copyright © 2019, 2020 Diego Nicola Barbato Copyright © 2019 Ivan Petkov Copyright © 2019 Jakob L. Kreuze Copyright © 2019 Kyle Andrews Copyright © 2019 Alex Griffin Copyright © 2019, 2020, 2021, 2022 Guillaume Le Vaillant Copyright © 2020 Liliana Marie Prikler Copyright © 2019, 2020, 2021, 2022 Simon Tournier Copyright © 2020 Wiktor Żelazny Copyright © 2020 Damien Cassou Copyright © 2020 Jakub Kądziołka Copyright © 2020 Jack Hill Copyright © 2020 Naga Malleswari Copyright © 2020, 2021 Brice Waegeneire Copyright © 2020 R Veera Kumar Copyright © 2020, 2021 Pierre Langlois Copyright © 2020 pinoaffe Copyright © 2020 André Batista Copyright © 2020, 2021 Alexandru-Sergiu Marton Copyright © 2020 raingloom Copyright © 2020 Daniel Brooks Copyright © 2020 John Soo Copyright © 2020 Jonathan Brielmaier Copyright © 2020 Edgar Vincent Copyright © 2021, 2022 Maxime Devos Copyright © 2021 B. Wilson Copyright © 2021 Xinglu Chen Copyright © 2021 Raghav Gururajan Copyright © 2021 Domagoj Stolfa Copyright © 2021 Hui Lu Copyright © 2021 pukkamustard Copyright © 2021 Alice Brenon Copyright © 2021, 2022 Josselin Poiret Copyright © 2021 muradm Copyright © 2021, 2022 Andrew Tropin Copyright © 2021 Sarah Morgensen Copyright © 2022 Remco van ’t Veer Copyright © 2022 Aleksandr Vityazev Copyright © 2022 Philip M^{c}Grath Copyright © 2022 Karl Hallsby Copyright © 2022 Justin Veilleux Copyright © 2022 Reily Siegel Copyright © 2022 Simon Streit Copyright © 2022 ( Copyright © 2022 John Kehayias Permissão concedida para copiar, distribuir e/ou modificar este documento sob os termos da Licença de Documentação Livre GNU, Versão 1.3 ou qualquer versão mais recente publicada pela Free Software Foundation; sem Seções Invariantes, Textos de Capa Frontal, e sem Textos de Contracapa. Uma cópia da licença está incluída na seção intitulada “GNU Free Documentation License”. INFO-DIR-SECTION Administração de Sistemas START-INFO-DIR-ENTRY * Guix: (guix). Gerencie softwares instalados e configuração do sistema. * guix package: (guix)Invocando guix package. Instalando, removendo e atualizando pacotes. * guix gc: (guix)Invocando guix gc. Recuperando espaço em disco não utilizado. * guix pull: (guix)Invocando guix pull. Atualize a lista de pacotes disponíveis. * guix system: (guix)Invocando guix system. Gerencie a configuração do sistema operacional. * guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts. END-INFO-DIR-ENTRY INFO-DIR-SECTION Desenvolvimento de software START-INFO-DIR-ENTRY * guix shell: (guix)Invoking guix shell. Creating software environments. * guix environment: (guix)Invocando guix environment. Compilando ambientes de desenvolvimento com Guix. * guix build: (guix)Invocando guix build. Compilando pacotes. * guix pack: (guix)Invocando guix pack. Criando pacotes de binários. END-INFO-DIR-ENTRY  File: guix.pt_BR.info, Node: Invoking guix deploy, Next: Executando Guix em uma VM, Prev: Invocando guix system, Up: Configuração do sistema 12.16 Invoking ‘guix deploy’ ============================ We’ve already seen ‘operating-system’ declarations used to manage a machine’s configuration locally. Suppose you need to configure multiple machines, though—perhaps you’re managing a service on the web that’s comprised of several servers. ‘guix deploy’ enables you to use those same ‘operating-system’ declarations to manage multiple remote hosts at once as a logical “deployment”. Nota: The functionality described in this section is still under development and is subject to change. Get in touch with us on ! guix deploy FILE Such an invocation will deploy the machines that the code within FILE evaluates to. As an example, FILE might contain a definition like this: ;; This is a Guix deployment of a "bare bones" setup, with ;; no X11 display server, to a machine with an SSH daemon ;; listening on localhost:2222. A configuration such as this ;; may be appropriate for virtual machine with ports ;; forwarded to the host's loopback interface. (use-service-modules networking ssh) (use-package-modules bootloaders) (define %system (operating-system (host-name "gnu-deployed") (timezone "Etc/UTC") (bootloader (bootloader-configuration (bootloader grub-bootloader) (targets '("/dev/vda")) (terminal-outputs '(console)))) (file-systems (cons (file-system (mount-point "/") (device "/dev/vda1") (type "ext4")) %base-file-systems)) (services (append (list (service dhcp-client-service-type) (service openssh-service-type (openssh-configuration (permit-root-login #t) (allow-empty-passwords? #t)))) %base-services)))) (list (machine (operating-system %system) (environment managed-host-environment-type) (configuration (machine-ssh-configuration (host-name "localhost") (system "x86_64-linux") (user "alice") (identity "./id_rsa") (port 2222))))) The file should evaluate to a list of MACHINE objects. This example, upon being deployed, will create a new generation on the remote system realizing the ‘operating-system’ declaration ‘%system’. ‘environment’ and ‘configuration’ specify how the machine should be provisioned—that is, how the computing resources should be created and managed. The above example does not create any resources, as a ‘'managed-host’ is a machine that is already running the Guix system and available over the network. This is a particularly simple case; a more complex deployment may involve, for example, starting virtual machines through a Virtual Private Server (VPS) provider. In such a case, a different ENVIRONMENT type would be used. Do note that you first need to generate a key pair on the coordinator machine to allow the daemon to export signed archives of files from the store (*note Invocando guix archive::), though this step is automatic on Guix System: # guix archive --generate-key Each target machine must authorize the key of the master machine so that it accepts store items it receives from the coordinator: # guix archive --authorize < coordinator-public-key.txt ‘user’, in this example, specifies the name of the user account to log in as to perform the deployment. Its default value is ‘root’, but root login over SSH may be forbidden in some cases. To work around this, ‘guix deploy’ can log in as an unprivileged user and employ ‘sudo’ to escalate privileges. This will only work if ‘sudo’ is currently installed on the remote and can be invoked non-interactively as ‘user’. That is, the line in ‘sudoers’ granting ‘user’ the ability to use ‘sudo’ must contain the ‘NOPASSWD’ tag. This can be accomplished with the following operating system configuration snippet: (use-modules ... (gnu system)) ;for %sudoers-specification (define %user "username") (operating-system ... (sudoers-file (plain-file "sudoers" (string-append (plain-file-content %sudoers-specification) (format #f "~a ALL = NOPASSWD: ALL~%" %user))))) For more information regarding the format of the ‘sudoers’ file, consult ‘man sudoers’. Once you’ve deployed a system on a set of machines, you may find it useful to run a command on all of them. The ‘--execute’ or ‘-x’ option lets you do that; the example below runs ‘uname -a’ on all the machines listed in the deployment file: guix deploy FILE -x -- uname -a One thing you may often need to do after deployment is restart specific services on all the machines, which you can do like so: guix deploy FILE -x -- herd restart SERVICE The ‘guix deploy -x’ command returns zero if and only if the command succeeded on all the machines. Below are the data types you need to know about when writing a deployment file. -- Data Type: machine This is the data type representing a single machine in a heterogeneous Guix deployment. ‘sistema operacional’ The object of the operating system configuration to deploy. ‘environment’ An ‘environment-type’ describing how the machine should be provisioned. ‘configuration’ (default: ‘#f’) An object describing the configuration for the machine’s ‘environment’. If the ‘environment’ has a default configuration, ‘#f’ may be used. If ‘#f’ is used for an environment with no default configuration, however, an error will be thrown. -- Data Type: machine-ssh-configuration This is the data type representing the SSH client parameters for a machine with an ‘environment’ of ‘managed-host-environment-type’. ‘host-name’ ‘build-locally?’ (default: ‘#t’) If false, system derivations will be built on the machine being deployed to. ‘system’ The system type describing the architecture of the machine being deployed to—e.g., ‘"x86_64-linux"’. ‘authorize?’ (default: ‘#t’) If true, the coordinator’s signing key will be added to the remote’s ACL keyring. ‘port’ (padrão: ‘22’) ‘user’ (default: ‘"root"’) ‘identity’ (default: ‘#f’) If specified, the path to the SSH private key to use to authenticate with the remote host. ‘host-key’ (default: ‘#f’) This should be the SSH host key of the machine, which looks like this: ssh-ed25519 AAAAC3Nz... root@example.org When ‘host-key’ is ‘#f’, the server is authenticated against the ‘~/.ssh/known_hosts’ file, just like the OpenSSH ‘ssh’ client does. ‘allow-downgrades?’ (default: ‘#f’) Whether to allow potential downgrades. Like ‘guix system reconfigure’, ‘guix deploy’ compares the channel commits currently deployed on the remote host (as returned by ‘guix system describe’) to those currently in use (as returned by ‘guix describe’) to determine whether commits currently in use are descendants of those deployed. When this is not the case and ‘allow-downgrades?’ is false, it raises an error. This ensures you do not accidentally downgrade remote machines. ‘safety-checks?’ (default: ‘#t’) Whether to perform “safety checks” before deployment. This includes verifying that devices and file systems referred to in the operating system configuration actually exist on the target machine, and making sure that Linux modules required to access storage devices at boot time are listed in the ‘initrd-modules’ field of the operating system. These safety checks ensure that you do not inadvertently deploy a system that would fail to boot. Be careful before turning them off! -- Data Type: digital-ocean-configuration This is the data type describing the Droplet that should be created for a machine with an ‘environment’ of ‘digital-ocean-environment-type’. ‘ssh-key’ The path to the SSH private key to use to authenticate with the remote host. In the future, this field may not exist. ‘tags’ A list of string “tags” that uniquely identify the machine. Must be given such that no two machines in the deployment have the same set of tags. ‘region’ A Digital Ocean region slug, such as ‘"nyc3"’. ‘tamanho’ A Digital Ocean size slug, such as ‘"s-1vcpu-1gb"’ ‘enable-ipv6?’ Whether or not the droplet should be created with IPv6 networking.  File: guix.pt_BR.info, Node: Executando Guix em uma VM, Next: Definindo serviços, Prev: Invoking guix deploy, Up: Configuração do sistema 12.17 Usando o Guix em uma Máquina Virtual ========================================== To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image distributed at . This image is a compressed image in QCOW format. You can pass it to an emulator such as QEMU (https://qemu.org/) (see below for details). This image boots the Xfce graphical environment and it contains some commonly used tools. You can install more software in the image by running ‘guix package’ in a terminal (*note Invocando guix package::). You can also reconfigure the system based on its initial configuration file available as ‘/run/current-system/configuration.scm’ (*note Usando o sistema de configuração::). Instead of using this pre-built image, one can also build their own image using ‘guix system image’ (*note Invocando guix system::). If you built your own image, you must copy it out of the store (*note O armazém::) and give yourself permission to write to the copy before you can use it. When invoking QEMU, you must choose a system emulator that is suitable for your hardware platform. Here is a minimal QEMU invocation that will boot the result of ‘guix system image -t qcow2’ on x86_64 hardware: $ qemu-system-x86_64 \ -nic user,model=virtio-net-pci \ -enable-kvm -m 2048 \ -device virtio-blk,drive=myhd \ -drive if=none,file=guix-system-vm-image-1.4.0.x86_64-linux.qcow2,id=myhd Here is what each of these options means: ‘qemu-system-x86_64’ This specifies the hardware platform to emulate. This should match the host. ‘-nic user,model=virtio-net-pci’ Enable the unprivileged user-mode network stack. The guest OS can access the host but not vice versa. This is the simplest way to get the guest OS online. ‘model’ specifies which network device to emulate: ‘virtio-net-pci’ is a special device made for virtualized operating systems and recommended for most uses. Assuming your hardware platform is x86_64, you can get a list of available NIC models by running ‘qemu-system-x86_64 -nic model=help’. ‘-enable-kvm’ If your system has hardware virtualization extensions, enabling the virtual machine support (KVM) of the Linux kernel will make things run faster. ‘-m 2048’ RAM available to the guest OS, in mebibytes. Defaults to 128 MiB, which may be insufficient for some operations. ‘-device virtio-blk,drive=myhd’ Create a ‘virtio-blk’ drive called “myhd”. ‘virtio-blk’ is a “paravirtualization” mechanism for block devices that allows QEMU to achieve better performance than if it were emulating a complete disk drive. See the QEMU and KVM documentation for more info. ‘-drive if=none,file=/tmp/qemu-image,id=myhd’ Use our QCOW image, the ‘guix-system-vm-image-1.4.0.x86_64-linux.qcow2’ file, as the backing store of the “myhd” drive. The default ‘run-vm.sh’ script that is returned by an invocation of ‘guix system vm’ does not add a ‘-nic user’ flag by default. To get network access from within the vm add the ‘(dhcp-client-service)’ to your system definition and start the VM using ‘$(guix system vm config.scm) -nic user’. An important caveat of using ‘-nic user’ for networking is that ‘ping’ will not work, because it uses the ICMP protocol. You’ll have to use a different command to check for network connectivity, for example ‘guix download’. 12.17.1 Connecting Through SSH ------------------------------ To enable SSH inside a VM you need to add an SSH server like ‘openssh-service-type’ to your VM (*note ‘openssh-service-type’: Serviços de Rede.). In addition you need to forward the SSH port, 22 by default, to the host. You can do this with $(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22 To connect to the VM you can run ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost The ‘-p’ tells ‘ssh’ the port you want to connect to. ‘-o UserKnownHostsFile=/dev/null’ prevents ‘ssh’ from complaining every time you modify your ‘config.scm’ file and the ‘-o StrictHostKeyChecking=no’ prevents you from having to allow a connection to an unknown host every time you connect. Nota: If you find the above ‘hostfwd’ example not to be working (e.g., your SSH client hangs attempting to connect to the mapped port of your VM), make sure that your Guix System VM has networking support, such as by using the ‘dhcp-client-service-type’ service type. 12.17.2 Using ‘virt-viewer’ with Spice -------------------------------------- As an alternative to the default ‘qemu’ graphical client you can use the ‘remote-viewer’ from the ‘virt-viewer’ package. To connect pass the ‘-spice port=5930,disable-ticketing’ flag to ‘qemu’. See previous section for further information on how to do this. Spice also allows you to do some nice stuff like share your clipboard with your VM. To enable that you’ll also have to pass the following flags to ‘qemu’: -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5 -chardev spicevmc,name=vdagent,id=vdagent -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,\ name=com.redhat.spice.0 You’ll also need to add the ‘(spice-vdagent-service)’ to your system definition (*note Spice service: Serviços diversos.).  File: guix.pt_BR.info, Node: Definindo serviços, Prev: Executando Guix em uma VM, Up: Configuração do sistema 12.18 Definindo serviços ======================== The previous sections show the available services and how one can combine them in an ‘operating-system’ declaration. But how do we define them in the first place? And what is a service anyway? * Menu: * Composição de serviço:: O modelo para serviços de composição. * Tipos de Service e Serviços:: Tipos e serviços. * Referência de Service:: Referência de API. * Serviços de Shepherd:: Um tipo em particular de serviço. * Complex Configurations:: Defining bindings for complex configurations.  File: guix.pt_BR.info, Node: Composição de serviço, Next: Tipos de Service e Serviços, Up: Definindo serviços 12.18.1 Composição de serviço ----------------------------- Here we define a “service” as, broadly, something that extends the functionality of the operating system. Often a service is a process—a “daemon”—started when the system boots: a secure shell server, a Web server, the Guix build daemon, etc. Sometimes a service is a daemon whose execution can be triggered by another daemon—e.g., an FTP server started by ‘inetd’ or a D-Bus service activated by ‘dbus-daemon’. Occasionally, a service does not map to a daemon. For instance, the “account” service collects user accounts and makes sure they exist when the system runs; the “udev” service collects device management rules and makes them available to the eudev daemon; the ‘/etc’ service populates the ‘/etc’ directory of the system. Guix system services are connected by “extensions”. For instance, the secure shell service _extends_ the Shepherd—the initialization system, running as PID 1—by giving it the command lines to start and stop the secure shell daemon (*note ‘openssh-service-type’: Serviços de Rede.); the UPower service extends the D-Bus service by passing it its ‘.service’ specification, and extends the udev service by passing it device management rules (*note ‘upower-service’: Serviços de desktop.); the Guix daemon service extends the Shepherd by passing it the command lines to start and stop the daemon, and extends the account service by passing it a list of required build user accounts (*note Serviços base::). All in all, services and their “extends” relations form a directed acyclic graph (DAG). If we represent services as boxes and extensions as arrows, a typical system might provide something like this: [image src="images/service-graph.png" alt="Typical service extension graph."] At the bottom, we see the “system service”, which produces the directory containing everything to run and boot the system, as returned by the ‘guix system build’ command. *Note Referência de Service::, to learn about the other service types shown here. *Note the ‘guix system extension-graph’ command: system-extension-graph, for information on how to generate this representation for a particular operating system definition. Technically, developers can define “service types” to express these relations. There can be any number of services of a given type on the system—for instance, a system running two instances of the GNU secure shell server (lsh) has two instances of ‘lsh-service-type’, with different parameters. The following section describes the programming interface for service types and services.  File: guix.pt_BR.info, Node: Tipos de Service e Serviços, Next: Referência de Service, Prev: Composição de serviço, Up: Definindo serviços 12.18.2 Tipos de Service e Serviços ----------------------------------- A “service type” is a node in the DAG described above. Let us start with a simple example, the service type for the Guix build daemon (*note Invocando guix-daemon::): (define guix-service-type (service-type (name 'guix) (extensions (list (service-extension shepherd-root-service-type guix-shepherd-service) (service-extension account-service-type guix-accounts) (service-extension activation-service-type guix-activation))) (default-value (guix-configuration)))) It defines three things: 1. A name, whose sole purpose is to make inspection and debugging easier. 2. A list of “service extensions”, where each extension designates the target service type and a procedure that, given the parameters of the service, returns a list of objects to extend the service of that type. Every service type has at least one service extension. The only exception is the “boot service type”, which is the ultimate service. 3. Optionally, a default value for instances of this type. In this example, ‘guix-service-type’ extends three services: ‘shepherd-root-service-type’ The ‘guix-shepherd-service’ procedure defines how the Shepherd service is extended. Namely, it returns a ‘’ object that defines how ‘guix-daemon’ is started and stopped (*note Serviços de Shepherd::). ‘account-service-type’ This extension for this service is computed by ‘guix-accounts’, which returns a list of ‘user-group’ and ‘user-account’ objects representing the build user accounts (*note Invocando guix-daemon::). ‘activation-service-type’ Here ‘guix-activation’ is a procedure that returns a gexp, which is a code snippet to run at “activation time”—e.g., when the service is booted. A service of this type is instantiated like this: (service guix-service-type (guix-configuration (build-accounts 5) (extra-options '("--gc-keep-derivations")))) The second argument to the ‘service’ form is a value representing the parameters of this specific service instance. *Note ‘guix-configuration’: guix-configuration-type, for information about the ‘guix-configuration’ data type. When the value is omitted, the default value specified by ‘guix-service-type’ is used: (service guix-service-type) ‘guix-service-type’ is quite simple because it extends other services but is not extensible itself. The service type for an _extensible_ service looks like this: (define udev-service-type (service-type (name 'udev) (extensions (list (service-extension shepherd-root-service-type udev-shepherd-service))) (compose concatenate) ;concatenate the list of rules (extend (lambda (config rules) (match config (($ udev initial-rules) (udev-configuration (udev udev) ;the udev package to use (rules (append initial-rules rules))))))))) This is the service type for the eudev device management daemon (https://wiki.gentoo.org/wiki/Project:Eudev). Compared to the previous example, in addition to an extension of ‘shepherd-root-service-type’, we see two new fields: ‘compose’ This is the procedure to “compose” the list of extensions to services of this type. Services can extend the udev service by passing it lists of rules; we compose those extensions simply by concatenating them. ‘extend’ This procedure defines how the value of the service is “extended” with the composition of the extensions. Udev extensions are composed into a list of rules, but the udev service value is itself a ‘’ record. So here, we extend that record by appending the list of rules it contains to the list of contributed rules. ‘description’ This is a string giving an overview of the service type. The string can contain Texinfo markup (*note (texinfo)Overview::). The ‘guix system search’ command searches these strings and displays them (*note Invocando guix system::). There can be only one instance of an extensible service type such as ‘udev-service-type’. If there were more, the ‘service-extension’ specifications would be ambiguous. Still here? The next section provides a reference of the programming interface for services.  File: guix.pt_BR.info, Node: Referência de Service, Next: Serviços de Shepherd, Prev: Tipos de Service e Serviços, Up: Definindo serviços 12.18.3 Referência de Service ----------------------------- We have seen an overview of service types (*note Tipos de Service e Serviços::). This section provides a reference on how to manipulate services and service types. This interface is provided by the ‘(gnu services)’ module. -- Scheme Procedure: service TYPE [VALUE] Return a new service of TYPE, a ‘’ object (see below). VALUE can be any object; it represents the parameters of this particular service instance. When VALUE is omitted, the default value specified by TYPE is used; if TYPE does not specify a default value, an error is raised. For instance, this: (service openssh-service-type) is equivalent to this: (service openssh-service-type (openssh-configuration)) In both cases the result is an instance of ‘openssh-service-type’ with the default configuration. -- Scheme Procedure: service? OBJ Return true if OBJ is a service. -- Scheme Procedure: service-kind SERVICE Return the type of SERVICE—i.e., a ‘’ object. -- Scheme Procedure: service-value SERVICE Return the value associated with SERVICE. It represents its parameters. Here is an example of how a service is created and manipulated: (define s (service nginx-service-type (nginx-configuration (nginx nginx) (log-directory log-directory) (run-directory run-directory) (file config-file)))) (service? s) ⇒ #t (eq? (service-kind s) nginx-service-type) ⇒ #t The ‘modify-services’ form provides a handy way to change the parameters of some of the services of a list such as ‘%base-services’ (*note ‘%base-services’: Serviços base.). It evaluates to a list of services. Of course, you could always use standard list combinators such as ‘map’ and ‘fold’ to do that (*note List Library: (guile)SRFI-1.); ‘modify-services’ simply provides a more concise form for this common pattern. -- Scheme Syntax: modify-services SERVICES (TYPE VARIABLE => BODY) ... Modify the services listed in SERVICES according to the given clauses. Each clause has the form: (TYPE VARIABLE => BODY) where TYPE is a service type—e.g., ‘guix-service-type’—and VARIABLE is an identifier that is bound within the BODY to the service parameters—e.g., a ‘guix-configuration’ instance—of the original service of that TYPE. The BODY should evaluate to the new service parameters, which will be used to configure the new service. This new service will replace the original in the resulting list. Because a service’s service parameters are created using ‘define-record-type*’, you can write a succinct BODY that evaluates to the new service parameters by using the ‘inherit’ feature that ‘define-record-type*’ provides. Clauses can also have the following form: (delete TYPE) Such a clause removes all services of the given TYPE from SERVICES. *Note Usando o sistema de configuração::, for example usage. Next comes the programming interface for service types. This is something you want to know when writing new service definitions, but not necessarily when simply looking for ways to customize your ‘operating-system’ declaration. -- Data Type: service-type This is the representation of a “service type” (*note Tipos de Service e Serviços::). ‘name’ This is a symbol, used only to simplify inspection and debugging. ‘extensions’ A non-empty list of ‘’ objects (see below). ‘compose’ (default: ‘#f’) If this is ‘#f’, then the service type denotes services that cannot be extended—i.e., services that do not receive “values” from other services. Otherwise, it must be a one-argument procedure. The procedure is called by ‘fold-services’ and is passed a list of values collected from extensions. It may return any single value. ‘extend’ (default: ‘#f’) If this is ‘#f’, services of this type cannot be extended. Otherwise, it must be a two-argument procedure: ‘fold-services’ calls it, passing it the initial value of the service as the first argument and the result of applying ‘compose’ to the extension values as the second argument. It must return a value that is a valid parameter value for the service instance. ‘description’ This is a string, possibly using Texinfo markup, describing in a couple of sentences what the service is about. This string allows users to find about the service through ‘guix system search’ (*note Invocando guix system::). ‘default-value’ (default: ‘&no-default-value’) The default value associated for instances of this service type. This allows users to use the ‘service’ form without its second argument: (service TYPE) The returned service in this case has the default value specified by TYPE. *Note Tipos de Service e Serviços::, for examples. -- Scheme Procedure: service-extension TARGET-TYPE COMPUTE Return a new extension for services of type TARGET-TYPE. COMPUTE must be a one-argument procedure: ‘fold-services’ calls it, passing it the value associated with the service that provides the extension; it must return a valid value for the target service. -- Scheme Procedure: service-extension? OBJ Return true if OBJ is a service extension. Occasionally, you might want to simply extend an existing service. This involves creating a new service type and specifying the extension of interest, which can be verbose; the ‘simple-service’ procedure provides a shorthand for this. -- Scheme Procedure: simple-service NAME TARGET VALUE Return a service that extends TARGET with VALUE. This works by creating a singleton service type NAME, of which the returned service is an instance. For example, this extends mcron (*note Execução de trabalho agendado::) with an additional job: (simple-service 'my-mcron-job mcron-service-type #~(job '(next-hour (3)) "guix gc -F 2G")) At the core of the service abstraction lies the ‘fold-services’ procedure, which is responsible for “compiling” a list of services down to a single directory that contains everything needed to boot and run the system—the directory shown by the ‘guix system build’ command (*note Invocando guix system::). In essence, it propagates service extensions down the service graph, updating each node parameters on the way, until it reaches the root node. -- Scheme Procedure: fold-services SERVICES [#:target-type SYSTEM-SERVICE-TYPE] Fold SERVICES by propagating their extensions down to the root of type TARGET-TYPE; return the root service adjusted accordingly. Lastly, the ‘(gnu services)’ module also defines several essential service types, some of which are listed below. -- Scheme Variable: system-service-type This is the root of the service graph. It produces the system directory as returned by the ‘guix system build’ command. -- Scheme Variable: boot-service-type The type of the “boot service”, which produces the “boot script”. The boot script is what the initial RAM disk runs when booting. -- Scheme Variable: etc-service-type The type of the ‘/etc’ service. This service is used to create files under ‘/etc’ and can be extended by passing it name/file tuples such as: (list `("issue" ,(plain-file "issue" "Welcome!\n"))) In this example, the effect would be to add an ‘/etc/issue’ file pointing to the given file. -- Scheme Variable: setuid-program-service-type Type for the “setuid-program service”. This service collects lists of executable file names, passed as gexps, and adds them to the set of setuid and setgid programs on the system (*note Programas setuid::). -- Scheme Variable: profile-service-type Type of the service that populates the “system profile”—i.e., the programs under ‘/run/current-system/profile’. Other services can extend it by passing it lists of packages to add to the system profile. -- Scheme Variable: provenance-service-type This is the type of the service that records “provenance meta-data” in the system itself. It creates several files under ‘/run/current-system’: ‘channels.scm’ This is a “channel file” that can be passed to ‘guix pull -C’ or ‘guix time-machine -C’, and which describes the channels used to build the system, if that information was available (*note Canais::). ‘configuration.scm’ This is the file that was passed as the value for this ‘provenance-service-type’ service. By default, ‘guix system reconfigure’ automatically passes the OS configuration file it received on the command line. ‘provenance’ This contains the same information as the two other files but in a format that is more readily processable. In general, these two pieces of information (channels and configuration file) are enough to reproduce the operating system “from source”. Caveats: This information is necessary to rebuild your operating system, but it is not always sufficient. In particular, ‘configuration.scm’ itself is insufficient if it is not self-contained—if it refers to external Guile modules or to extra files. If you want ‘configuration.scm’ to be self-contained, we recommend that modules or files it refers to be part of a channel. Besides, provenance meta-data is “silent” in the sense that it does not change the bits contained in your system, _except for the meta-data bits themselves_. Two different OS configurations or sets of channels can lead to the same system, bit-for-bit; when ‘provenance-service-type’ is used, these two systems will have different meta-data and thus different store file names, which makes comparison less trivial. This service is automatically added to your operating system configuration when you use ‘guix system reconfigure’, ‘guix system init’, or ‘guix deploy’. -- Scheme Variable: linux-loadable-module-service-type Type of the service that collects lists of packages containing kernel-loadable modules, and adds them to the set of kernel-loadable modules. This service type is intended to be extended by other service types, such as below: (simple-service 'installing-module linux-loadable-module-service-type (list module-to-install-1 module-to-install-2)) This does not actually load modules at bootup, only adds it to the kernel profile so that it _can_ be loaded by other means.  File: guix.pt_BR.info, Node: Serviços de Shepherd, Next: Complex Configurations, Prev: Referência de Service, Up: Definindo serviços 12.18.4 Serviços de Shepherd ---------------------------- The ‘(gnu services shepherd)’ module provides a way to define services managed by the GNU Shepherd, which is the initialization system—the first process that is started when the system boots, also known as PID 1 (*note (shepherd)Introdução::). Services in the Shepherd can depend on each other. For instance, the SSH daemon may need to be started after the syslog daemon has been started, which in turn can only happen once all the file systems have been mounted. The simple operating system defined earlier (*note Usando o sistema de configuração::) results in a service graph like this: [image src="images/shepherd-graph.png" alt="Typical shepherd service graph."] You can actually generate such a graph for any operating system definition using the ‘guix system shepherd-graph’ command (*note ‘guix system shepherd-graph’: system-shepherd-graph.). The ‘%shepherd-root-service’ is a service object representing PID 1, of type ‘shepherd-root-service-type’; it can be extended by passing it lists of ‘’ objects. -- Data Type: shepherd-service The data type representing a service managed by the Shepherd. ‘provision’ This is a list of symbols denoting what the service provides. These are the names that may be passed to ‘herd start’, ‘herd status’, and similar commands (*note (shepherd)Invoking herd::). *Note the ‘provides’ slot: (shepherd)Slots of services, for details. ‘requirement’ (default: ‘'()’) List of symbols denoting the Shepherd services this one depends on. ‘one-shot?’ (default: ‘#f’) Whether this service is “one-shot”. One-shot services stop immediately after their ‘start’ action has completed. *Note (shepherd)Slots of services::, for more info. ‘respawn?’ (padrão: ‘#t’) Whether to restart the service when it stops, for instance when the underlying process dies. ‘iniciar’ ‘stop’ (default: ‘#~(const #f)’) The ‘start’ and ‘stop’ fields refer to the Shepherd’s facilities to start and stop processes (*note (shepherd)Service De- and Constructors::). They are given as G-expressions that get expanded in the Shepherd configuration file (*note Expressões-G::). ‘actions’ (default: ‘'()’) This is a list of ‘shepherd-action’ objects (see below) defining “actions” supported by the service, in addition to the standard ‘start’ and ‘stop’ actions. Actions listed here become available as ‘herd’ sub-commands: herd ACTION SERVICE [ARGUMENTS...] ‘auto-start?’ (default: ‘#t’) Whether this service should be started automatically by the Shepherd. If it is ‘#f’ the service has to be started manually with ‘herd start’. ‘documentation’ A documentation string, as shown when running: herd doc SERVICE-NAME where SERVICE-NAME is one of the symbols in ‘provision’ (*note (shepherd)Invoking herd::). ‘modules’ (default: ‘%default-modules’) This is the list of modules that must be in scope when ‘start’ and ‘stop’ are evaluated. The example below defines a Shepherd service that spawns ‘syslogd’, the system logger from the GNU Networking Utilities (*note ‘syslogd’: (inetutils)syslogd invocation.): (let ((config (plain-file "syslogd.conf" "..."))) (shepherd-service (documentation "Run the syslog daemon (syslogd).") (provision '(syslogd)) (requirement '(user-processes)) (start #~(make-forkexec-constructor (list #$(file-append inetutils "/libexec/syslogd") "--rcfile" #$config) #:pid-file "/var/run/syslog.pid")) (stop #~(make-kill-destructor)))) Key elements in this example are the ‘start’ and ‘stop’ fields: they are “staged” code snippets that use the ‘make-forkexec-constructor’ procedure provided by the Shepherd and its dual, ‘make-kill-destructor’ (*note (shepherd)Service De- and Constructors::). The ‘start’ field will have ‘shepherd’ spawn ‘syslogd’ with the given option; note that we pass ‘config’ after ‘--rcfile’, which is a configuration file declared above (contents of this file are omitted). Likewise, the ‘stop’ field tells how this service is to be stopped; in this case, it is stopped by making the ‘kill’ system call on its PID. Code staging is achieved using G-expressions: ‘#~’ stages code, while ‘#$’ “escapes” back to host code (*note Expressões-G::). -- Data Type: shepherd-action This is the data type that defines additional actions implemented by a Shepherd service (see above). ‘name’ Symbol naming the action. ‘documentation’ This is a documentation string for the action. It can be viewed by running: herd doc SERVICE action ACTION ‘procedure’ This should be a gexp that evaluates to a procedure of at least one argument, which is the “running value” of the service (*note (shepherd)Slots of services::). The following example defines an action called ‘say-hello’ that kindly greets the user: (shepherd-action (name 'say-hello) (documentation "Say hi!") (procedure #~(lambda (running . args) (format #t "Hello, friend! arguments: ~s\n" args) #t))) Assuming this action is added to the ‘example’ service, then you can do: # herd say-hello example Hello, friend! arguments: () # herd say-hello example a b c Hello, friend! arguments: ("a" "b" "c") This, as you can see, is a fairly sophisticated way to say hello. *Note (shepherd)Service Convenience::, for more info on actions. -- Scheme Procedure: shepherd-configuration-action Return a ‘configuration’ action to display FILE, which should be the name of the service’s configuration file. It can be useful to equip services with that action. For example, the service for the Tor anonymous router (*note ‘tor-service-type’: Serviços de Rede.) is defined roughly like this: (let ((torrc (plain-file "torrc" ...))) (shepherd-service (provision '(tor)) (requirement '(user-processes loopback syslogd)) (start #~(make-forkexec-constructor (list #$(file-append tor "/bin/tor") "-f" #$torrc) #:user "tor" #:group "tor")) (stop #~(make-kill-destructor)) (actions (list (shepherd-configuration-action torrc))) (documentation "Run the Tor anonymous network overlay."))) Thanks to this action, administrators can inspect the configuration file passed to ‘tor’ with this shell command: cat $(herd configuration tor) This can come in as a handy debugging tool! -- Scheme Variable: shepherd-root-service-type The service type for the Shepherd “root service”—i.e., PID 1. This is the service type that extensions target when they want to create shepherd services (*note Tipos de Service e Serviços::, for an example). Each extension must pass a list of ‘’. Its value must be a ‘shepherd-configuration’, as described below. -- Data Type: shepherd-configuration This data type represents the Shepherd’s configuration. ‘shepherd (default: shepherd)’ The Shepherd package to use. ‘services (default: '())’ A list of ‘’ to start. You should probably use the service extension mechanism instead (*note Serviços de Shepherd::). The following example specifies the Shepherd package for the operating system: (operating-system ;; ... (services (append (list openssh-service-type)) ;; ... %desktop-services) ;; ... ;; Use own Shepherd package. (essential-services (modify-services (operating-system-default-essential-services this-operating-system) (shepherd-root-service-type config => (shepherd-configuration (inherit config) (shepherd my-shepherd)))))) -- Scheme Variable: %shepherd-root-service This service represents PID 1.  File: guix.pt_BR.info, Node: Complex Configurations, Prev: Serviços de Shepherd, Up: Definindo serviços 12.18.5 Complex Configurations ------------------------------ Some programs might have rather complex configuration files or formats, and to make it easier to create Scheme bindings for these configuration files, you can use the utilities defined in the ‘(gnu services configuration)’ module. The main utility is the ‘define-configuration’ macro, which you will use to define a Scheme record type (*note (guile)Record Overview::). The Scheme record will be serialized to a configuration file by using “serializers”, which are procedures that take some kind of Scheme value and returns a G-expression (*note Expressões-G::), which should, once serialized to the disk, return a string. More details are listed below. -- Scheme Syntax: define-configuration NAME CLAUSE1 CLAUSE2 ... Create a record type named ‘NAME’ that contains the fields found in the clauses. A clause can have one of the following forms: (FIELD-NAME (TYPE DEFAULT-VALUE) DOCUMENTATION) (FIELD-NAME (TYPE DEFAULT-VALUE) DOCUMENTATION SERIALIZER) (FIELD-NAME (TYPE) DOCUMENTATION) (FIELD-NAME (TYPE) DOCUMENTATION SERIALIZER) FIELD-NAME is an identifier that denotes the name of the field in the generated record. TYPE is the type of the value corresponding to FIELD-NAME; since Guile is untyped, a predicate procedure—‘TYPE?’—will be called on the value corresponding to the field to ensure that the value is of the correct type. This means that if say, TYPE is ‘package’, then a procedure named ‘package?’ will be applied on the value to make sure that it is indeed a ‘’ object. DEFAULT-VALUE is the default value corresponding to the field; if none is specified, the user is forced to provide a value when creating an object of the record type. DOCUMENTATION is a string formatted with Texinfo syntax which should provide a description of what setting this field does. SERIALIZER is the name of a procedure which takes two arguments, the first is the name of the field, and the second is the value corresponding to the field. The procedure should return a string or G-expression (*note Expressões-G::) that represents the content that will be serialized to the configuration file. If none is specified, a procedure of the name ‘serialize-TYPE’ will be used. A simple serializer procedure could look like this: (define (serialize-boolean field-name value) (let ((value (if value "true" "false"))) #~(string-append #$field-name #$value))) In some cases multiple different configuration records might be defined in the same file, but their serializers for the same type might have to be different, because they have different configuration formats. For example, the ‘serialize-boolean’ procedure for the Getmail service would have to be different from the one for the Transmission service. To make it easier to deal with this situation, one can specify a serializer prefix by using the ‘prefix’ literal in the ‘define-configuration’ form. This means that one doesn’t have to manually specify a custom SERIALIZER for every field. (define (foo-serialize-string field-name value) ...) (define (bar-serialize-string field-name value) ...) (define-configuration foo-configuration (label (string) "The name of label.") (prefix foo-)) (define-configuration bar-configuration (ip-address (string) "The IPv4 address for this device.") (prefix bar-)) However, in some cases you might not want to serialize any of the values of the record, to do this, you can use the ‘no-serialization’ literal. There is also the ‘define-configuration/no-serialization’ macro which is a shorthand of this. ;; Nothing will be serialized to disk. (define-configuration foo-configuration (field (string "test") "Some documentation.") (no-serialization)) ;; The same thing as above. (define-configuration/no-serialization bar-configuration (field (string "test") "Some documentation.")) -- Scheme Syntax: define-maybe TYPE Sometimes a field should not be serialized if the user doesn’t specify a value. To achieve this, you can use the ‘define-maybe’ macro to define a “maybe type”; if the value of a maybe type is left unset, or is set to the ‘%unset-value’ value, then it will not be serialized. When defining a “maybe type”, the corresponding serializer for the regular type will be used by default. For example, a field of type ‘maybe-string’ will be serialized using the ‘serialize-string’ procedure by default, you can of course change this by specifying a custom serializer procedure. Likewise, the type of the value would have to be a string, or left unspecified. (define-maybe string) (define (serialize-string field-name value) ...) (define-configuration baz-configuration (name ;; If set to a string, the `serialize-string' procedure will be used ;; to serialize the string. Otherwise this field is not serialized. maybe-string "The name of this module.")) Like with ‘define-configuration’, one can set a prefix for the serializer name by using the ‘prefix’ literal. (define-maybe integer (prefix baz-)) (define (baz-serialize-integer field-name value) ...) There is also the ‘no-serialization’ literal, which when set means that no serializer will be defined for the “maybe type”, regardless of whether its value is set or not. ‘define-maybe/no-serialization’ is a shorthand for specifying the ‘no-serialization’ literal. (define-maybe/no-serialization symbol) (define-configuration/no-serialization test-configuration (mode maybe-symbol "Docstring.")) -- (Scheme: Procedure) maybe-value-set? VALUE Predicate to check whether a user explicitly specified the value of a maybe field. -- Scheme Procedure: serialize-configuration CONFIGURATION FIELDS Return a G-expression that contains the values corresponding to the FIELDS of CONFIGURATION, a record that has been generated by ‘define-configuration’. The G-expression can then be serialized to disk by using something like ‘mixed-text-file’. -- Scheme Procedure: empty-serializer FIELD-NAME VALUE A serializer that just returns an empty string. The ‘serialize-package’ procedure is an alias for this. Once you have defined a configuration record, you will most likely also want to document it so that other people know to use it. To help with that, there are two procedures, both of which are documented below. -- Scheme Procedure: generate-documentation DOCUMENTATION DOCUMENTATION-NAME Generate a Texinfo fragment from the docstrings in DOCUMENTATION, a list of ‘(LABEL FIELDS SUB-DOCUMENTATION ...)’. LABEL should be a symbol and should be the name of the configuration record. FIELDS should be a list of all the fields available for the configuration record. SUB-DOCUMENTATION is a ‘(FIELD-NAME CONFIGURATION-NAME)’ tuple. FIELD-NAME is the name of the field which takes another configuration record as its value, and CONFIGURATION-NAME is the name of that configuration record. SUB-DOCUMENTATION is only needed if there are nested configuration records. For example, the ‘getmail-configuration’ record (*note Serviços de correio::) accepts a ‘getmail-configuration-file’ record in one of its ‘rcfile’ field, therefore documentation for ‘getmail-configuration-file’ is nested in ‘getmail-configuration’. (generate-documentation `((getmail-configuration ,getmail-configuration-fields (rcfile getmail-configuration-file)) ...) 'getmail-configuration) DOCUMENTATION-NAME should be a symbol and should be the name of the configuration record. -- Scheme Procedure: configuration->documentation CONFIGURATION-SYMBOL Take CONFIGURATION-SYMBOL, the symbol corresponding to the name used when defining a configuration record with ‘define-configuration’, and print the Texinfo documentation of its fields. This is useful if there aren’t any nested configuration records since it only prints the documentation for the top-level fields. As of right now, there is no automated way to generate documentation for configuration records and put them in the manual. Instead, every time you make a change to the docstrings of a configuration record, you have to manually call ‘generate-documentation’ or ‘configuration->documentation’, and paste the output into the ‘doc/guix.texi’ file. Below is an example of a record type created using ‘define-configuration’ and friends. (use-modules (gnu services) (guix gexp) (gnu services configuration) (srfi srfi-26) (srfi srfi-1)) ;; Turn field names, which are Scheme symbols into strings (define (uglify-field-name field-name) (let ((str (symbol->string field-name))) ;; field? -> is-field (if (string-suffix? "?" str) (string-append "is-" (string-drop-right str 1)) str))) (define (serialize-string field-name value) #~(string-append #$(uglify-field-name field-name) " = " #$value "\n")) (define (serialize-integer field-name value) (serialize-string field-name (number->string value))) (define (serialize-boolean field-name value) (serialize-string field-name (if value "true" "false"))) (define (serialize-contact-name field-name value) #~(string-append "\n[" #$value "]\n")) (define (list-of-contact-configurations? lst) (every contact-configuration? lst)) (define (serialize-list-of-contact-configurations field-name value) #~(string-append #$@(map (cut serialize-configuration <> contact-configuration-fields) value))) (define (serialize-contacts-list-configuration configuration) (mixed-text-file "contactrc" #~(string-append "[Owner]\n" #$(serialize-configuration configuration contacts-list-configuration-fields)))) (define-maybe integer) (define-maybe string) (define-configuration contact-configuration (name (string) "The name of the contact." serialize-contact-name) (phone-number maybe-integer "The person's phone number.") (email maybe-string "The person's email address.") (married? (boolean) "Whether the person is married.")) (define-configuration contacts-list-configuration (name (string) "The name of the owner of this contact list.") (email (string) "The owner's email address.") (contacts (list-of-contact-configurations '()) "A list of @code{contact-configuation} records which contain information about all your contacts.")) A contacts list configuration could then be created like this: (define my-contacts (contacts-list-configuration (name "Alice") (email "alice@example.org") (contacts (list (contact-configuration (name "Bob") (phone-number 1234) (email "bob@gnu.org") (married? #f)) (contact-configuration (name "Charlie") (phone-number 0000) (married? #t)))))) After serializing the configuration to disk, the resulting file would look like this: [owner] name = Alice email = alice@example.org [Bob] phone-number = 1234 email = bob@gnu.org is-married = false [Charlie] phone-number = 0 is-married = true  File: guix.pt_BR.info, Node: Home Configuration, Next: Documentação, Prev: Configuração do sistema, Up: Top 13 Home Configuration ********************* Guix supports declarative configuration of “home environments” by utilizing the configuration mechanism described in the previous chapter (*note Definindo serviços::), but for user’s dotfiles and packages. It works both on Guix System and foreign distros and allows users to declare all the packages and services that should be installed and configured for the user. Once a user has written a file containing ‘home-environment’ record, such a configuration can be “instantiated” by an unprivileged user with the ‘guix home’ command (*note Invoking guix home::). Nota: The functionality described in this section is still under development and is subject to change. Get in touch with us on ! The user’s home environment usually consists of three basic parts: software, configuration, and state. Software in mainstream distros are usually installed system-wide, but with GNU Guix most software packages can be installed on a per-user basis without needing root privileges, and are thus considered part of the user’s “home environment”. Packages on their own are not very useful in many cases, because often they require some additional configuration, usually config files that reside in ‘XDG_CONFIG_HOME’ (‘~/.config’ by default) or other directories. Everything else can be considered state, like media files, application databases, and logs. Using Guix for managing home environments provides a number of advantages: • All software can be configured in one language (Guile Scheme), this gives users the ability to share values between configurations of different programs. • A well-defined home environment is self-contained and can be created in a declarative and reproducible way—there is no need to grab external binaries or manually edit some configuration file. • After every ‘guix home reconfigure’ invocation, a new home environment generation will be created. This means that users can rollback to a previous home environment generation so they don’t have to worry about breaking their configuration. • It is possible to manage stateful data with Guix Home, this includes the ability to automatically clone Git repositories on the initial setup of the machine, and periodically running commands like ‘rsync’ to sync data with another host. This functionality is still in an experimental stage, though. * Menu: * Declaring the Home Environment:: Customizing your Home. * Configurando o "Shell":: Enabling home environment. * Home Services:: Specifying home services. * Invoking guix home:: Instantiating a home configuration.  File: guix.pt_BR.info, Node: Declaring the Home Environment, Next: Configurando o "Shell", Up: Home Configuration 13.1 Declaring the Home Environment =================================== The home environment is configured by providing a ‘home-environment’ declaration in a file that can be passed to the ‘guix home’ command (*note Invoking guix home::). The easiest way to get started is by generating an initial configuration with ‘guix home import’: guix home import ~/src/guix-config The ‘guix home import’ command reads some of the “dot files” such as ‘~/.bashrc’ found in your home directory and copies them to the given directory, ‘~/src/guix-config’ in this case; it also reads the contents of your profile, ‘~/.guix-profile’, and, based on that, it populates ‘~/src/guix-config/home-configuration.scm’ with a Home configuration that resembles your current configuration. A simple setup can include Bash and a custom text configuration, like in the example below. Don’t be afraid to declare home environment parts, which overlaps with your current dot files: before installing any configuration files, Guix Home will back up existing config files to a separate place in the home directory. Nota: It is highly recommended that you manage your shell or shells with Guix Home, because it will make sure that all the necessary scripts are sourced by the shell configuration file. Otherwise you will need to do it manually. (*note Configurando o "Shell"::). (use-modules (gnu home) (gnu home services) (gnu home services shells) (gnu services) (gnu packages admin) (guix gexp)) (home-environment (packages (list htop)) (services (list (service home-bash-service-type (home-bash-configuration (guix-defaults? #t) (bash-profile (list (plain-file "bash-profile" "\ export HISTFILE=$XDG_CACHE_HOME/.bash_history"))))) (simple-service 'test-config home-xdg-configuration-files-service-type (list `("test.conf" ,(plain-file "tmp-file.txt" "the content of ~/.config/test.conf"))))))) The ‘packages’ field should be self-explanatory, it will install the list of packages into the user’s profile. The most important field is ‘services’, it contains a list of “home services”, which are the basic building blocks of a home environment. There is no daemon (at least not necessarily) related to a home service, a home service is just an element that is used to declare part of home environment and extend other parts of it. The extension mechanism discussed in the previous chapter (*note Definindo serviços::) should not be confused with Shepherd services (*note Serviços de Shepherd::). Using this extension mechanism and some Scheme code that glues things together gives the user the freedom to declare their own, very custom, home environments. Once the configuration looks good, you can first test it in a throw-away “container”: guix home container config.scm The command above spawns a shell where your home environment is running. The shell runs in a container, meaning it’s isolated from the rest of the system, so it’s a good way to try out your configuration—you can see if configuration bits are missing or misbehaving, if daemons get started, and so on. Once you exit that shell, you’re back to the prompt of your original shell “in the real world”. Once you have a configuration file that suits your needs, you can reconfigure your home by running: guix home reconfigure config.scm This “builds” your home environment and creates ‘~/.guix-home’ pointing to it. Voilà! Nota: Make sure the operating system has elogind, systemd, or a similar mechanism to create the XDG run-time directory and has the ‘XDG_RUNTIME_DIR’ variable set. Failing that, the ‘on-first-login’ script will not execute anything, and processes like user Shepherd and its descendants will not start.  File: guix.pt_BR.info, Node: Configurando o "Shell", Next: Home Services, Prev: Declaring the Home Environment, Up: Home Configuration 13.2 Configurando o "Shell" =========================== This section is safe to skip if your shell or shells are managed by Guix Home. Otherwise, read it carefully. There are a few scripts that must be evaluated by a login shell to activate the home environment. The shell startup files only read by login shells often have ‘profile’ suffix. For more information about login shells see *note (bash)Invoking Bash:: and see *note (bash)Bash Startup Files::. The first script that needs to be sourced is ‘setup-environment’, which sets all the necessary environment variables (including variables declared by the user) and the second one is ‘on-first-login’, which starts Shepherd for the current user and performs actions declared by other home services that extends ‘home-run-on-first-login-service-type’. Guix Home will always create ‘~/.profile’, which contains the following lines: HOME_ENVIRONMENT=$HOME/.guix-home . $HOME_ENVIRONMENT/setup-environment $HOME_ENVIRONMENT/on-first-login This makes POSIX compliant login shells activate the home environment. However, in most cases this file won’t be read by most modern shells, because they are run in non POSIX mode by default and have their own ‘*profile’ startup files. For example Bash will prefer ‘~/.bash_profile’ in case it exists and only if it doesn’t will it fallback to ‘~/.profile’. Zsh (if no additional options are specified) will ignore ‘~/.profile’, even if ‘~/.zprofile’ doesn’t exist. To make your shell respect ‘~/.profile’, add ‘. ~/.profile’ or ‘source ~/.profile’ to the startup file for the login shell. In case of Bash, it is ‘~/.bash_profile’, and in case of Zsh, it is ‘~/.zprofile’. Nota: This step is only required if your shell is _not_ managed by Guix Home. Otherwise, everything will be done automatically.  File: guix.pt_BR.info, Node: Home Services, Next: Invoking guix home, Prev: Configurando o "Shell", Up: Home Configuration 13.3 Home Services ================== A “home service” is not necessarily something that has a daemon and is managed by Shepherd (*note (shepherd)Jump Start::), in most cases it doesn’t. It’s a simple building block of the home environment, often declaring a set of packages to be installed in the home environment profile, a set of config files to be symlinked into ‘XDG_CONFIG_HOME’ (‘~/.config’ by default), and environment variables to be set by a login shell. There is a service extension mechanism (*note Composição de serviço::) which allows home services to extend other home services and utilize capabilities they provide; for example: declare mcron jobs (*note (mcron)Top::) by extending *note Mcron Home Service::; declare daemons by extending *note Shepherd Home Service::; add commands, which will be invoked on by the Bash by extending *note ‘home-bash-service-type’: Shells Home Services. A good way to discover available home services is using the ‘guix home search’ command (*note Invoking guix home::). After the required home services are found, include its module with the ‘use-modules’ form (*note Using Guile Modules: (guile)use-modules.), or the ‘#:use-modules’ directive (*note Creating Guile Modules: (guile)define-module.) and declare a home service using the ‘service’ function, or extend a service type by declaring a new service with the ‘simple-service’ procedure from ‘(gnu services)’. * Menu: * Serviços essenciais domésticos:: Environment variables, packages, on-* scripts. * Shells: Shells Home Services. POSIX shells, Bash, Zsh. * Mcron: Mcron Home Service. Execução de trabalho do Usuário agendado. * Power Management: Power Management Home Services. Services for battery power. * Shepherd: Shepherd Home Service. Managing User’s Daemons. * SSH: Secure Shell. Setting up the secure shell client. * Desktop: Desktop Home Services. Services for graphical environments. * Guix: Guix Home Services. Services for Guix.  File: guix.pt_BR.info, Node: Serviços essenciais domésticos, Next: Shells Home Services, Up: Home Services 13.3.1 Serviços essenciais domésticos ------------------------------------- There are a few essential home services defined in ‘(gnu services)’, they are mostly for internal use and are required to build a home environment, but some of them will be useful for the end user. -- Scheme Variable: home-environment-variables-service-type The service of this type will be instantiated by every home environment automatically by default, there is no need to define it, but someone may want to extend it with a list of pairs to set some environment variables. (list ("ENV_VAR1" . "value1") ("ENV_VAR2" . "value2")) The easiest way to extend a service type, without defining a new service type is to use the ‘simple-service’ helper from ‘(gnu services)’. (simple-service 'some-useful-env-vars-service home-environment-variables-service-type `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst") ("SHELL" . ,(file-append zsh "/bin/zsh")) ("USELESS_VAR" . #f) ("_JAVA_AWT_WM_NONREPARENTING" . #t))) If you include such a service in you home environment definition, it will add the following content to the ‘setup-environment’ script (which is expected to be sourced by the login shell): export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh export _JAVA_AWT_WM_NONREPARENTING Nota: Make sure that module ‘(gnu packages shells)’ is imported with ‘use-modules’ or any other way, this namespace contains the definition of the ‘zsh’ package, which is used in the example above. The association list (*note alists: (guile)Association Lists.) is a data structure containing key-value pairs, for ‘home-environment-variables-service-type’ the key is always a string, the value can be a string, string-valued gexp (*note Expressões-G::), file-like object (*note file-like object: Expressões-G.) or boolean. For gexps, the variable will be set to the value of the gexp; for file-like objects, it will be set to the path of the file in the store (*note O armazém::); for ‘#t’, it will export the variable without any value; and for ‘#f’, it will omit variable. -- Scheme Variable: home-profile-service-type The service of this type will be instantiated by every home environment automatically, there is no need to define it, but you may want to extend it with a list of packages if you want to install additional packages into your profile. Other services, which need to make some programs available to the user will also extend this service type. The extension value is just a list of packages: (list htop vim emacs) The same approach as ‘simple-service’ (*note simple-service: Referência de Service.) for ‘home-environment-variables-service-type’ can be used here, too. Make sure that modules containing the specified packages are imported with ‘use-modules’. To find a package or information about its module use ‘guix search’ (*note Invocando guix package::). Alternatively, ‘specification->package’ can be used to get the package record from string without importing related module. There are few more essential services, but users are not expected to extend them. -- Scheme Variable: home-service-type The root of home services DAG, it generates a folder, which later will be symlinked to ‘~/.guix-home’, it contains configurations, profile with binaries and libraries, and some necessary scripts to glue things together. -- Scheme Variable: home-run-on-first-login-service-type The service of this type generates a Guile script, which is expected to be executed by the login shell. It is only executed if the special flag file inside ‘XDG_RUNTIME_DIR’ hasn’t been created, this prevents redundant executions of the script if multiple login shells are spawned. It can be extended with a gexp. However, to autostart an application, users _should not_ use this service, in most cases it’s better to extend ‘home-shepherd-service-type’ with a Shepherd service (*note Serviços de Shepherd::), or extend the shell’s startup file with the required command using the appropriate service type. -- Scheme Variable: home-files-service-type The service of this type allows to specify a list of files, which will go to ‘~/.guix-home/files’, usually this directory contains configuration files (to be more precise it contains symlinks to files in ‘/gnu/store’), which should be placed in ‘$XDG_CONFIG_DIR’ or in rare cases in ‘$HOME’. It accepts extension values in the following format: `((".sway/config" ,sway-file-like-object) (".tmux.conf" ,(local-file "./tmux.conf"))) Each nested list contains two values: a subdirectory and file-like object. After building a home environment ‘~/.guix-home/files’ will be populated with apropiate content and all nested directories will be created accordingly, however, those files won’t go any further until some other service will do it. By default a ‘home-symlink-manager-service-type’, which creates necessary symlinks in home folder to files from ‘~/.guix-home/files’ and backs up already existing, but clashing configs and other things, is a part of essential home services (enabled by default), but it’s possible to use alternative services to implement more advanced use cases like read-only home. Feel free to experiment and share your results. -- Scheme Variable: home-xdg-configuration-files-service-type The service is very similiar to ‘home-files-service-type’ (and actually extends it), but used for defining files, which will go to ‘~/.guix-home/files/.config’, which will be symlinked to ‘$XDG_CONFIG_DIR’ by ‘home-symlink-manager-service-type’ (for example) during activation. It accepts extension values in the following format: `(("sway/config" ,sway-file-like-object) ;; -> ~/.guix-home/files/.config/sway/config ;; -> $XDG_CONFIG_DIR/sway/config (by symlink-manager) ("tmux/tmux.conf" ,(local-file "./tmux.conf"))) -- Scheme Variable: home-activation-service-type The service of this type generates a guile script, which runs on every ‘guix home reconfigure’ invocation or any other action, which leads to the activation of the home environment. -- Scheme Variable: home-symlink-manager-service-type The service of this type generates a guile script, which will be executed during activation of home environment, and do a few following steps: 1. Reads the content of ‘files/’ directory of current and pending home environments. 2. Cleans up all symlinks created by symlink-manager on previous activation. Also, sub-directories, which become empty also will be cleaned up. 3. Creates new symlinks the following way: It looks ‘files/’ directory (usually defined with ‘home-files-service-type’, ‘home-xdg-configuration-files-service-type’ and maybe some others), takes the files from ‘files/.config/’ subdirectory and put respective links in ‘XDG_CONFIG_DIR’. For example symlink for ‘files/.config/sway/config’ will end up in ‘$XDG_CONFIG_DIR/sway/config’. The rest files in ‘files/’ outside of ‘files/.config/’ subdirectory will be treated slightly different: symlink will just go to ‘$HOME’. ‘files/.some-program/config’ will end up in ‘$HOME/.some-program/config’. 4. If some sub-directories are missing, they will be created. 5. If there is a clashing files on the way, they will be backed up. symlink-manager is a part of essential home services and is enabled and used by default.  File: guix.pt_BR.info, Node: Shells Home Services, Next: Mcron Home Service, Prev: Serviços essenciais domésticos, Up: Home Services 13.3.2 Shells ------------- Shells play a quite important role in the environment initialization process, you can configure them manually as described in section *note Configurando o "Shell"::, but the recommended way is to use home services listed below. It’s both easier and more reliable. Each home environment instantiates ‘home-shell-profile-service-type’, which creates a ‘~/.profile’ startup file for all POSIX-compatible shells. This file contains all the necessary steps to properly initialize the environment, but many modern shells like Bash or Zsh prefer their own startup files, that’s why the respective home services (‘home-bash-service-type’ and ‘home-zsh-service-type’) ensure that ‘~/.profile’ is sourced by ‘~/.bash_profile’ and ‘~/.zprofile’, respectively. Shell Profile Service ..................... -- Data Type: home-shell-profile-configuration Available ‘home-shell-profile-configuration’ fields are: ‘profile’ (default: ‘()’) (type: text-config) ‘home-shell-profile’ is instantiated automatically by ‘home-environment’, DO NOT create this service manually, it can only be extended. ‘profile’ is a list of file-like objects, which will go to ‘~/.profile’. By default ‘~/.profile’ contains the initialization code which must be evaluated by the login shell to make home-environment’s profile available to the user, but other commands can be added to the file if it is really necessary. In most cases shell’s configuration files are preferred places for user’s customizations. Extend home-shell-profile service only if you really know what you do. Bash Home Service ................. -- Data Type: home-bash-configuration Available ‘home-bash-configuration’ fields are: ‘package’ (default: ‘bash’) (type: package) The Bash package to use. ‘guix-defaults?’ (default: ‘#t’) (type: boolean) Add sane defaults like reading ‘/etc/bashrc’ and coloring the output of ‘ls’ to the top of the ‘.bashrc’ file. ‘environment-variables’ (default: ‘()’) (type: alist) Association list of environment variables to set for the Bash session. The rules for the ‘home-environment-variables-service-type’ apply here (*note Serviços essenciais domésticos::). The contents of this field will be added after the contents of the ‘bash-profile’ field. ‘aliases’ (default: ‘()’) (type: alist) Association list of aliases to set for the Bash session. The aliases will be defined after the contents of the ‘bashrc’ field has been put in the ‘.bashrc’ file. The alias will automatically be quoted, so something like this: '(("ls" . "ls -alF")) turns into alias ls="ls -alF" ‘bash-profile’ (default: ‘()’) (type: text-config) List of file-like objects, which will be added to ‘.bash_profile’. Used for executing user’s commands at start of login shell (In most cases the shell started on tty just after login). ‘.bash_login’ won’t be ever read, because ‘.bash_profile’ always present. ‘bashrc’ (default: ‘()’) (type: text-config) List of file-like objects, which will be added to ‘.bashrc’. Used for executing user’s commands at start of interactive shell (The shell for interactive usage started by typing ‘bash’ or by terminal app or any other program). ‘bash-logout’ (default: ‘()’) (type: text-config) List of file-like objects, which will be added to ‘.bash_logout’. Used for executing user’s commands at the exit of login shell. It won’t be read in some cases (if the shell terminates by exec’ing another process for example). You can extend the Bash service by using the ‘home-bash-extension’ configuration record, whose fields must mirror that of ‘home-bash-configuration’ (*note home-bash-configuration::). The contents of the extensions will be added to the end of the corresponding Bash configuration files (*note (bash)Bash Startup Files::. For example, here is how you would define a service that extends the Bash service such that ‘~/.bash_profile’ defines an additional environment variable, ‘PS1’: (define bash-fancy-prompt-service (simple-service 'bash-fancy-prompt home-bash-service-type (home-bash-extension (environment-variables '(("PS1" . "\\u \\wλ ")))))) You would then add ‘bash-fancy-prompt-service’ to the list in the ‘services’ field of your ‘home-environment’. The reference of ‘home-bash-extension’ follows. -- Data Type: home-bash-extension Available ‘home-bash-extension’ fields are: ‘environment-variables’ (default: ‘()’) (type: alist) Additional environment variables to set. These will be combined with the environment variables from other extensions and the base service to form one coherent block of environment variables. ‘aliases’ (default: ‘()’) (type: alist) Additional aliases to set. These will be combined with the aliases from other extensions and the base service. ‘bash-profile’ (default: ‘()’) (type: text-config) Additional text blocks to add to ‘.bash_profile’, which will be combined with text blocks from other extensions and the base service. ‘bashrc’ (default: ‘()’) (type: text-config) Additional text blocks to add to ‘.bashrc’, which will be combined with text blocks from other extensions and the base service. ‘bash-logout’ (default: ‘()’) (type: text-config) Additional text blocks to add to ‘.bash_logout’, which will be combined with text blocks from other extensions and the base service. Zsh Home Service ................ -- Data Type: home-zsh-configuration Available ‘home-zsh-configuration’ fields are: ‘package’ (default: ‘zsh’) (type: package) The Zsh package to use. ‘xdg-flavor?’ (default: ‘#t’) (type: boolean) Place all the configs to ‘$XDG_CONFIG_HOME/zsh’. Makes ‘~/.zshenv’ to set ‘ZDOTDIR’ to ‘$XDG_CONFIG_HOME/zsh’. Shell startup process will continue with ‘$XDG_CONFIG_HOME/zsh/.zshenv’. ‘environment-variables’ (default: ‘()’) (type: alist) Association list of environment variables to set for the Zsh session. ‘zshenv’ (default: ‘()’) (type: text-config) List of file-like objects, which will be added to ‘.zshenv’. Used for setting user’s shell environment variables. Must not contain commands assuming the presence of tty or producing output. Will be read always. Will be read before any other file in ‘ZDOTDIR’. ‘zprofile’ (default: ‘()’) (type: text-config) List of file-like objects, which will be added to ‘.zprofile’. Used for executing user’s commands at start of login shell (In most cases the shell started on tty just after login). Will be read before ‘.zlogin’. ‘zshrc’ (default: ‘()’) (type: text-config) List of file-like objects, which will be added to ‘.zshrc’. Used for executing user’s commands at start of interactive shell (The shell for interactive usage started by typing ‘zsh’ or by terminal app or any other program). ‘zlogin’ (default: ‘()’) (type: text-config) List of file-like objects, which will be added to ‘.zlogin’. Used for executing user’s commands at the end of starting process of login shell. ‘zlogout’ (default: ‘()’) (type: text-config) List of file-like objects, which will be added to ‘.zlogout’. Used for executing user’s commands at the exit of login shell. It won’t be read in some cases (if the shell terminates by exec’ing another process for example).  File: guix.pt_BR.info, Node: Mcron Home Service, Next: Power Management Home Services, Prev: Shells Home Services, Up: Home Services 13.3.3 Scheduled User’s Job Execution ------------------------------------- The ‘(gnu home services mcron)’ module provides an interface to GNU mcron, a daemon to run jobs at scheduled times (*note (mcron)Top::). The information about system’s mcron is applicable here (*note Execução de trabalho agendado::), the only difference for home services is that they have to be declared in a ‘home-environment’ record instead of an ‘operating-system’ record. -- Scheme Variable: home-mcron-service-type This is the type of the ‘mcron’ home service, whose value is an ‘home-mcron-configuration’ object. It allows to manage scheduled tasks. This service type can be the target of a service extension that provides additional job specifications (*note Composição de serviço::). In other words, it is possible to define services that provide additional mcron jobs to run. -- Data Type: home-mcron-configuration Available ‘home-mcron-configuration’ fields are: ‘mcron’ (default: ‘mcron’) (type: file-like) The mcron package to use. ‘jobs’ (default: ‘()’) (type: list-of-gexps) This is a list of gexps (*note Expressões-G::), where each gexp corresponds to an mcron job specification (*note mcron job specifications: (mcron)Syntax.). ‘log?’ (default: ‘#t’) (type: boolean) Log messages to standard output. ‘log-format’ (default: ‘"~1@*~a ~a: ~a~%"’) (type: string) ‘(ice-9 format)’ format string for log messages. The default value produces messages like "‘PID NAME: MESSAGE"’ (*note Invoking: (mcron)Invoking mcron.). Each message is also prefixed by a timestamp by GNU Shepherd.  File: guix.pt_BR.info, Node: Power Management Home Services, Next: Shepherd Home Service, Prev: Mcron Home Service, Up: Home Services 13.3.4 Power Management Home Services ------------------------------------- The ‘(gnu home services pm)’ module provides home services pertaining to battery power. -- Scheme Variable: home-batsignal-service-type Service for ‘batsignal’, a program that monitors battery levels and warns the user through desktop notifications when their battery is getting low. You can also configure a command to be run when the battery level passes a point deemed “dangerous”. This service is configured with the ‘home-batsignal-configuration’ record. -- Data Type: home-batsignal-configuration Data type representing the configuration for batsignal. ‘warning-level’ (default: ‘15’) The battery level to send a warning message at. ‘warning-message’ (default: ‘#f’) The message to send as a notification when the battery level reaches the ‘warning-level’. Setting to ‘#f’ uses the default message. ‘critical-level’ (default: ‘5’) The battery level to send a critical message at. ‘critical-message’ (default: ‘#f’) The message to send as a notification when the battery level reaches the ‘critical-level’. Setting to ‘#f’ uses the default message. ‘danger-level’ (default: ‘2’) The battery level to run the ‘danger-command’ at. ‘danger-command’ (default: ‘#f’) The command to run when the battery level reaches the ‘danger-level’. Setting to ‘#f’ disables running the command entirely. ‘full-level’ (default: ‘#f’) The battery level to send a full message at. Setting to ‘#f’ disables sending the full message entirely. ‘full-message’ (default: ‘#f’) The message to send as a notification when the battery level reaches the ‘full-level’. Setting to ‘#f’ uses the default message. ‘batteries’ (default: ‘'()’) The batteries to monitor. Setting to ‘'()’ tries to find batteries automatically. ‘poll-delay’ (default: ‘60’) The time in seconds to wait before checking the batteries again. ‘icon’ (default: ‘#f’) A file-like object to use as the icon for battery notifications. Setting to ‘#f’ disables notification icons entirely. ‘notifications?’ (default: ‘#t’) Whether to send any notifications. ‘notifications-expire?’ (default: ‘#f’) Whether notifications sent expire after a time. ‘notification-command’ (default: ‘#f’) Command to use to send messages. Setting to ‘#f’ sends a notification through ‘libnotify’. ‘ignore-missing?’ (default: ‘#f’) Whether to ignore missing battery errors.  File: guix.pt_BR.info, Node: Shepherd Home Service, Next: Secure Shell, Prev: Power Management Home Services, Up: Home Services 13.3.5 Managing User Daemons ---------------------------- The ‘(gnu home services shepherd)’ module supports the definitions of per-user Shepherd services (*note (shepherd)Introdução::). You extend ‘home-shepherd-service-type’ with new services; Guix Home then takes care of starting the ‘shepherd’ daemon for you when you log in, which in turns starts the services you asked for. -- Scheme Variable: home-shepherd-service-type The service type for the userland Shepherd, which allows one to manage long-running processes or one-shot tasks. User’s Shepherd is not an init process (PID 1), but almost all other information described in (*note Serviços de Shepherd::) is applicable here too. This is the service type that extensions target when they want to create shepherd services (*note Tipos de Service e Serviços::, for an example). Each extension must pass a list of ‘’. Its value must be a ‘home-shepherd-configuration’, as described below. -- Data Type: home-shepherd-configuration This data type represents the Shepherd’s configuration. ‘shepherd (default: shepherd)’ The Shepherd package to use. ‘auto-start? (default: #t)’ Whether or not to start Shepherd on first login. ‘services (default: '())’ A list of ‘’ to start. You should probably use the service extension mechanism instead (*note Serviços de Shepherd::).  File: guix.pt_BR.info, Node: Secure Shell, Next: Desktop Home Services, Prev: Shepherd Home Service, Up: Home Services 13.3.6 Secure Shell ------------------- The OpenSSH package (https://www.openssh.com) includes a client, the ‘ssh’ command, that allows you to connect to remote machines using the SSH (secure shell) protocol. With the ‘(gnu home services ssh)’ module, you can set up OpenSSH so that it works in a predictable fashion, almost independently of state on the local machine. To do that, you instantiate ‘home-openssh-service-type’ in your Home configuration, as explained below. -- Scheme Variable: home-openssh-service-type This is the type of the service to set up the OpenSSH client. It takes care of several things: • providing a ‘~/.ssh/config’ file based on your configuration so that ‘ssh’ knows about hosts you regularly connect to and their associated parameters; • providing a ‘~/.ssh/authorized_keys’, which lists public keys that the local SSH server, ‘sshd’, may accept to connect to this user account; • optionally providing a ‘~/.ssh/known_hosts’ file so that ‘ssh’ can authenticate hosts you connect to. Here is an example of a service and its configuration that you could add to the ‘services’ field of your ‘home-environment’: (service home-openssh-service-type (home-openssh-configuration (hosts (list (openssh-host (name "ci.guix.gnu.org") (user "charlie")) (openssh-host (name "chbouib") (host-name "chbouib.example.org") (user "supercharlie") (port 10022)))) (authorized-keys (list (local-file "alice.pub"))))) The example above lists two hosts and their parameters. For instance, running ‘ssh chbouib’ will automatically connect to ‘chbouib.example.org’ on port 10022, logging in as user ‘supercharlie’. Further, it marks the public key in ‘alice.pub’ as authorized for incoming connections. The value associated with a ‘home-openssh-service-type’ instance must be a ‘home-openssh-configuration’ record, as describe below. -- Data Type: home-openssh-configuration This is the datatype representing the OpenSSH client and server configuration in one’s home environment. It contains the following fields: ‘hosts’ (default: ‘'()’) A list of ‘openssh-host’ records specifying host names and associated connection parameters (see below). This host list goes into ‘~/.ssh/config’, which ‘ssh’ reads at startup. ‘known-hosts’ (default: ‘*unspecified*’) This must be either: • ‘*unspecified*’, in which case ‘home-openssh-service-type’ leaves it up to ‘ssh’ and to the user to maintain the list of known hosts at ‘~/.ssh/known_hosts’, or • a list of file-like objects, in which case those are concatenated and emitted as ‘~/.ssh/known_hosts’. The ‘~/.ssh/known_hosts’ contains a list of host name/host key pairs that allow ‘ssh’ to authenticate hosts you connect to and to detect possible impersonation attacks. By default, ‘ssh’ updates it in a “TOFU, trust-on-first-use” fashion, meaning that it records the host’s key in that file the first time you connect to it. This behavior is preserved when ‘known-hosts’ is set to ‘*unspecified*’. If you instead provide a list of host keys upfront in the ‘known-hosts’ field, your configuration becomes self-contained and stateless: it can be replicated elsewhere or at another point in time. Preparing this list can be relatively tedious though, which is why ‘*unspecified*’ is kept as a default. ‘authorized-keys’ (default: ‘'()’) This must be a list of file-like objects, each of which containing an SSH public key that should be authorized to connect to this machine. Concretely, these files are concatenated and made available as ‘~/.ssh/authorized_keys’. If an OpenSSH server, ‘sshd’, is running on this machine, then it _may_ take this file into account: this is what ‘sshd’ does by default, but be aware that it can also be configured to ignore it. -- Data Type: openssh-host Available ‘openssh-host’ fields are: ‘name’ (type: string) Name of this host declaration. ‘host-name’ (type: maybe-string) Host name—e.g., ‘"foo.example.org"’ or ‘"192.168.1.2"’. ‘address-family’ (type: address-family) Address family to use when connecting to this host: one of ‘AF_INET’ (for IPv4 only), ‘AF_INET6’ (for IPv6 only), or ‘*unspecified*’ (allowing any address family). ‘identity-file’ (type: maybe-string) The identity file to use—e.g., ‘"/home/charlie/.ssh/id_ed25519"’. ‘port’ (type: maybe-natural-number) TCP port number to connect to. ‘user’ (type: maybe-string) User name on the remote host. ‘forward-x11?’ (default: ‘#f’) (type: boolean) Whether to forward remote client connections to the local X11 graphical display. ‘forward-x11-trusted?’ (default: ‘#f’) (type: boolean) Whether remote X11 clients have full access to the original X11 graphical display. ‘forward-agent?’ (default: ‘#f’) (type: boolean) Whether the authentication agent (if any) is forwarded to the remote machine. ‘compression?’ (default: ‘#f’) (type: boolean) Whether to compress data in transit. ‘proxy-command’ (type: maybe-string) The command to use to connect to the server. As an example, a command to connect via an HTTP proxy at 192.0.2.0 would be: ‘"nc -X connect -x 192.0.2.0:8080 %h %p"’. ‘host-key-algorithms’ (type: maybe-string-list) The list of accepted host key algorithms—e.g., ‘'("ssh-ed25519")’. ‘accepted-key-types’ (type: maybe-string-list) The list of accepted user public key types. ‘extra-content’ (default: ‘""’) (type: raw-configuration-string) Extra content appended as-is to this ‘Host’ block in ‘~/.ssh/config’.  File: guix.pt_BR.info, Node: Desktop Home Services, Next: Guix Home Services, Prev: Secure Shell, Up: Home Services 13.3.7 Desktop Home Services ---------------------------- The ‘(gnu home services desktop)’ module provides services that you may find useful on “desktop” systems running a graphical user environment such as Xorg. -- Scheme Variable: home-redshift-service-type This is the service type for Redshift (https://github.com/jonls/redshift), a program that adjusts the display color temperature according to the time of day. Its associated value must be a ‘home-redshift-configuration’ record, as shown below. A typical configuration, where we manually specify the latitude and longitude, might look like this: (service home-redshift-service-type (home-redshift-configuration (location-provider 'manual) (latitude 35.81) ;northern hemisphere (longitude -0.80))) ;west of Greenwich -- Data Type: home-redshift-configuration Available ‘home-redshift-configuration’ fields are: ‘redshift’ (default: ‘redshift’) (type: file-like) Redshift package to use. ‘location-provider’ (default: ‘geoclue2’) (type: symbol) Geolocation provider—‘'manual’ or ‘'geoclue2’. In the former case, you must also specify the ‘latitude’ and ‘longitude’ fields so Redshift can determine daytime at your place. In the latter case, the Geoclue system service must be running; it will be queried for location information. ‘adjustment-method’ (default: ‘randr’) (type: symbol) Color adjustment method. ‘daytime-temperature’ (default: ‘6500’) (type: integer) Daytime color temperature (kelvins). ‘nighttime-temperature’ (default: ‘4500’) (type: integer) Nighttime color temperature (kelvins). ‘daytime-brightness’ (type: maybe-inexact-number) Daytime screen brightness, between 0.1 and 1.0, or left unspecified. ‘nighttime-brightness’ (type: maybe-inexact-number) Nighttime screen brightness, between 0.1 and 1.0, or left unspecified. ‘latitude’ (type: maybe-inexact-number) Latitude, when ‘location-provider’ is ‘'manual’. ‘longitude’ (type: maybe-inexact-number) Longitude, when ‘location-provider’ is ‘'manual’. ‘dawn-time’ (type: maybe-string) Custom time for the transition from night to day in the morning—‘"HH:MM"’ format. When specified, solar elevation is not used to determine the daytime/nighttime period. ‘dusk-time’ (type: maybe-string) Likewise, custom time for the transition from day to night in the evening. ‘extra-content’ (default: ‘""’) (type: raw-configuration-string) Extra content appended as-is to the Redshift configuration file. Run ‘man redshift’ for more information about the configuration file format. -- Scheme Variable: home-dbus-service-type This is the service type for running a session-specific D-Bus, for unprivileged applications that require D-Bus to be running. -- Data Type: home-dbus-configuration The configuration record for ‘home-dbus-service-type’. ‘dbus’ (default: ‘dbus’) The package providing the ‘/bin/dbus-daemon’ command.  File: guix.pt_BR.info, Node: Guix Home Services, Prev: Desktop Home Services, Up: Home Services 13.3.8 Guix Home Services ------------------------- The ‘(gnu home services guix)’ module provides services for user-specific Guix configuration. -- Scheme Variable: home-channels-service-type This is the service type for managing ‘$XDG_CONFIG_HOME/guix/channels.scm’, the file that controls the channels received on ‘guix pull’ (*note Canais::). Its associated value is a list of ‘channel’ records, defined in the ‘(guix channels)’ module. Generally, it is better to extend this service than to directly configure it, as its default value is the default guix channel(s) defined by ‘%default-channels’. If you configure this service directly, be sure to include a guix channel. *Note Specifying Additional Channels:: and *note Using a Custom Guix Channel:: for more details. A typical extension for adding a channel might look like this: (simple-service 'variant-packages-service home-channels-service-type (list (channel (name 'variant-packages) (url "https://example.org/variant-packages.git"))))  File: guix.pt_BR.info, Node: Invoking guix home, Prev: Home Services, Up: Home Configuration 13.4 Invoking ‘guix home’ ========================= Once you have written a home environment declaration (*note Declaring the Home Environment::, it can be “instantiated” using the ‘guix home’ command. The synopsis is: guix home OPTIONS... ACTION FILE FILE must be the name of a file containing a ‘home-environment’ declaration. ACTION specifies how the home environment is instantiated, but there are few auxiliary actions which don’t instantiate it. Currently the following values are supported: ‘pesquisa’ Display available home service type definitions that match the given regular expressions, sorted by relevance: $ 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 (*note GNU recutils databases: (recutils)Top.). ‘recipiente’ 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=FONTE[=ALVO]’ ‘--share=FONTE[=ALVO]’ 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’ (*note ‘--expose’ and ‘--share’: Invoking guix shell.). 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. Nota: It is highly recommended to run ‘guix pull’ once before you run ‘guix home reconfigure’ for the first time (*note Invocando 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’). This command creates a new generation whose number is one greater than the current generation (as reported by ‘guix home list-generations’). If that generation already exists, it will be overwritten. This behavior mirrors that of ‘guix package’ (*note Invocando guix package::). Upon completion, the new home is deployed under ‘~/.guix-home’. This directory contains “provenance meta-data”: the list of channels in use (*note Canais::) and FILE itself, when available. You can view the provenance information by running: guix home describe This information is useful should you later want to inspect how this particular generation was built. In fact, assuming FILE is self-contained, you can later rebuild generation N of your home environment with: 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 You can think of it as some sort of built-in version control! Your home is not just a binary artifact: _it carries its own source_. ‘switch-generation’ Switch to an existing home generation. This action atomically switches the home profile to the specified home generation. The target generation can be specified explicitly by its generation number. For example, the following invocation would switch to home generation 7: guix home switch-generation 7 The target generation can also be specified relative to the current generation with the form ‘+N’ or ‘-N’, where ‘+3’ means “3 generations ahead of the current generation,” and ‘-1’ means “1 generation prior to the current generation.” When specifying a negative value such as ‘-1’, you must precede it with ‘--’ to prevent it from being parsed as an option. For example: guix home switch-generation -- -1 This action will fail if the specified generation does not exist. ‘roll-back’ Switch to the preceding home generation. This is the inverse of ‘reconfigure’, and it is exactly the same as invoking ‘switch-generation’ with an argument of ‘-1’. ‘delete-generations’ Delete home generations, making them candidates for garbage collection (*note Invocando guix gc::, for information on how to run the “garbage collector”). This works in the same way as ‘guix package --delete-generations’ (*note ‘--delete-generations’: Invocando guix package.). With no arguments, all home generations but the current one are deleted: guix home delete-generations You can also select the generations you want to delete. The example below deletes all the home generations that are more than two months old: guix home delete-generations 2m ‘build’ Build the derivation of the home environment, which includes all the configuration files and programs needed. This action does not actually install anything. ‘describe’ Describe the current home generation: its file name, as well as provenance information when available. To show installed packages in the current home generation’s profile, the ‘--list-installed’ flag is provided, with the same syntax that is used in ‘guix package --list-installed’ (*note Invocando guix package::). For instance, the following command shows a table of all the packages with “emacs” in their name that are installed in the current home generation’s profile: guix home describe --list-installed=emacs ‘list-generations’ List a summary of each generation of the home environment available on disk, in a human-readable way. This is similar to the ‘--list-generations’ option of ‘guix package’ (*note Invocando guix package::). Optionally, one can specify a pattern, with the same syntax that is used in ‘guix package --list-generations’, to restrict the list of generations displayed. For instance, the following command displays generations that are up to 10 days old: guix home list-generations 10d The ‘--list-installed’ flag may also be specified, with the same syntax that is used in ‘guix home describe’. This may be helpful if trying to determine when a package was added to the home profile. ‘import’ Generate a “home environment” from the packages in the default profile and configuration files found in the user’s home directory. The configuration files will be copied to the specified directory, and a ‘home-configuration.scm’ will be populated with the home environment. Note that not every home service that exists is supported (*note Home Services::). $ guix home import ~/guix-config guix home: '/home/alice/guix-config' populated with all the Home configuration files 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 (*note Composição de serviço::, 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’ (*note ‘--backend’: Invocando guix graph.): O comando: guix home extension-graph FILE | xdot - shows the extension relations among services. ‘shepherd-graph’ Emit to standard output the “dependency graph” of shepherd services of the home environment defined in FILE. *Note Serviços de Shepherd::, for more information and for an example graph. Again, the default output format is Dot/Graphviz, but you can pass ‘--graph-backend’ to select a different one. OPTIONS can contain any of the common build options (*note Opções de compilação comum::). In addition, OPTIONS can contain one of the following: ‘--expression=EXPR’ ‘-e EXPR’ Consider the home-environment EXPR evaluates to. This is an alternative to specifying a file which evaluates to a home environment. ‘--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!  File: guix.pt_BR.info, Node: Documentação, Next: Platforms, Prev: Home Configuration, Up: Top 14 Documentação *************** In most cases packages installed with Guix come with documentation. There are two main documentation formats: “Info”, a browsable hypertext format used for GNU software, and “manual pages” (or “man pages”), the linear documentation format traditionally found on Unix. Info manuals are accessed with the ‘info’ command or with Emacs, and man pages are accessed using ‘man’. You can look for documentation of software installed on your system by keyword. For example, the following command searches for information about “TLS” in Info manuals: $ info -k TLS "(emacs)Network Security" -- STARTTLS "(emacs)Network Security" -- TLS "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function ... The command below searches for the same keyword in man pages(1): $ man -k TLS SSL (7) - OpenSSL SSL/TLS library certtool (1) - GnuTLS certificate tool ... These searches are purely local to your computer so you have the guarantee that documentation you find corresponds to what you have actually installed, you can access it off-line, and your privacy is respected. Once you have these results, you can view the relevant documentation by running, say: $ info "(gnutls)Core TLS API" or: $ man certtool Info manuals contain sections and indices as well as hyperlinks like those found in Web pages. The ‘info’ reader (*note Info reader: (info-stnd)Top.) and its Emacs counterpart (*note (emacs)Misc Help::) provide intuitive key bindings to navigate manuals. *Note (info)Primeiros passos::, for an introduction to Info navigation. ---------- Footnotes ---------- (1) The database searched by ‘man -k’ is only created in profiles that contain the ‘man-db’ package.  File: guix.pt_BR.info, Node: Platforms, Next: System Images, Prev: Documentação, Up: Top 15 Platforms ************ The packages and systems built by Guix are intended, like most computer programs, to run on a CPU with a specific instruction set, and under a specific operating system. Those programs are often also targeting a specific kernel and system library. Those constraints are captured by Guix in ‘platform’ records. * Menu: * platform Reference:: Detail of platform declarations. * Supported Platforms:: Description of the supported platforms.  File: guix.pt_BR.info, Node: platform Reference, Next: Supported Platforms, Up: Platforms 15.1 ‘platform’ Reference ========================= The ‘platform’ data type describes a “platform”: an ISA (instruction set architecture), combined with an operating system and possibly additional system-wide settings such as the ABI (application binary interface). -- Data Type: platform This is the data type representing a platform. ‘target’ This field specifies the platform’s GNU triplet as a string (*note GNU configuration triplets: (autoconf)Specifying Target Triplets.). ‘system’ This string is the system type as it is known to Guix and passed, for instance, to the ‘--system’ option of most commands. It usually has the form ‘"CPU-KERNEL"’, where CPU is the target CPU and KERNEL the target operating system kernel. It can be for instance ‘"aarch64-linux"’ or ‘"armhf-linux"’. You will encounter system types when you perform native builds (*note Native Builds::). ‘linux-architecture’ (default: ‘#false’) This optional string field is only relevant if the kernel is Linux. In that case, it corresponds to the ARCH variable used when building Linux, ‘"mips"’ for instance. ‘glibc-dynamic-linker’ This field is the name of the GNU C Library dynamic linker for the corresponding system, as a string. It can be ‘"/lib/ld-linux-armhf.so.3"’.  File: guix.pt_BR.info, Node: Supported Platforms, Prev: platform Reference, Up: Platforms 15.2 Supported Platforms ======================== The ‘(guix platforms ...)’ modules export the following variables, each of which is bound to a ‘platform’ record. -- Scheme Variable: armv7-linux Platform targeting ARM v7 CPU running GNU/Linux. -- Scheme Variable: aarch64-linux Platform targeting ARM v8 CPU running GNU/Linux. -- Scheme Variable: mips64-linux Platform targeting MIPS little-endian 64-bit CPU running GNU/Linux. -- Scheme Variable: powerpc-linux Platform targeting PowerPC big-endian 32-bit CPU running GNU/Linux. -- Scheme Variable: powerpc64le-linux Platform targeting PowerPC little-endian 64-bit CPU running GNU/Linux. -- Scheme Variable: riscv64-linux Platform targeting RISC-V 64-bit CPU running GNU/Linux. -- Scheme Variable: i686-linux Platform targeting x86 CPU running GNU/Linux. -- Scheme Variable: x86_64-linux Platform targeting x86 64-bit CPU running GNU/Linux. -- Scheme Variable: i686-mingw Platform targeting x86 CPU running Windows, with run-time support from MinGW. -- Scheme Variable: x86_64-mingw Platform targeting x86 64-bit CPU running Windows, with run-time support from MinGW. -- Scheme Variable: i586-gnu Platform targeting x86 CPU running GNU/Hurd (also referred to as “GNU”).  File: guix.pt_BR.info, Node: System Images, Next: Instalando arquivos de depuração, Prev: Platforms, Up: Top 16 Creating System Images ************************* When it comes to installing Guix System for the first time on a new machine, you can basically proceed in three different ways. The first one is to use an existing operating system on the machine to run the ‘guix system init’ command (*note Invocando guix system::). The second one, is to produce an installation image (*note Compilando a imagem de instalação::). This is a bootable system which role is to eventually run ‘guix system init’. Finally, the third option would be to produce an image that is a direct instantiation of the system you wish to run. That image can then be copied on a bootable device such as an USB drive or a memory card. The target machine would then directly boot from it, without any kind of installation procedure. The ‘guix system image’ command is able to turn an operating system definition into a bootable image. This command supports different image types, such as ‘efi-raw’, ‘iso9660’ and ‘docker’. Any modern ‘x86_64’ machine will probably be able to boot from an ‘iso9660’ image. However, there are a few machines out there that require specific image types. Those machines, in general using ‘ARM’ processors, may expect specific partitions at specific offsets. This chapter explains how to define customized system images and how to turn them into actual bootable images. * Menu: * image Reference:: Detail of image declarations. * Instantiate an Image:: How to instantiate an image record. * image-type Reference:: Detail of image types declaration. * Image Modules:: Definition of image modules.  File: guix.pt_BR.info, Node: image Reference, Next: Instantiate an Image, Up: System Images 16.1 ‘image’ Reference ====================== The ‘image’ record, described right after, allows you to define a customized bootable system image. -- Data Type: image This is the data type representing a system image. ‘name’ (default: ‘#false’) The image name as a symbol, ‘'my-iso9660’ for instance. The name is optional and it defaults to ‘#false’. ‘format’ The image format as a symbol. The following formats are supported: • ‘disk-image’, a raw disk image composed of one or multiple partitions. • ‘compressed-qcow2’, a compressed qcow2 image composed of one or multiple partitions. • ‘docker’, a Docker image. • ‘iso9660’, an ISO-9660 image. • ‘tarball’, a tar.gz image archive. • ‘wsl2’, a WSL2 image. ‘platform’ (default: ‘#false’) The ‘platform’ record the image is targeting (*note Platforms::), ‘aarch64-linux’ for instance. By default, this field is set to ‘#false’ and the image will target the host platform. ‘size’ (default: ‘'guess’) The image size in bytes or ‘'guess’. The ‘'guess’ symbol, which is the default, means that the image size will be inferred based on the image content. ‘sistema operacional’ The image’s ‘operating-system’ record that is instanciated. ‘partition-table-type’ (default: ‘'mbr’) The image partition table type as a symbol. Possible values are ‘'mbr’ and ‘'gpt’. It default to ‘'mbr’. ‘partitions’ (default: ‘'()’) The image partitions as a list of ‘partition’ records (*note partition Reference::). ‘compression?’ (default: ‘#true’) Whether the image content should be compressed, as a boolean. It defaults to ‘#true’ and only applies to ‘'iso9660’ image formats. ‘volatile-root?’ (default: ‘#true’) Whether the image root partition should be made volatile, as a boolean. This is achieved by using a RAM backed file system (overlayfs) that is mounted on top of the root partition by the initrd. It defaults to ‘#true’. When set to ‘#false’, the image root partition is mounted as read-write partition by the initrd. ‘shared-store?’ (default: ‘#false’) Whether the image’s store should be shared with the host system, as a boolean. This can be useful when creating images dedicated to virtual machines. When set to ‘#false’, which is the default, the image’s ‘operating-system’ closure is copied to the image. Otherwise, when set to ‘#true’, it is assumed that the host store will be made available at boot, using a ‘9p’ mount for instance. ‘shared-network?’ (default: ‘#false’) Whether to use the host network interfaces within the image, as a boolean. This is only used for the ‘'docker’ image format. It defaults to ‘#false’. ‘substitutable?’ (default: ‘#true’) Whether the image derivation should be substitutable, as a boolean. It defaults to ‘true’. * Menu: * partition Reference::  File: guix.pt_BR.info, Node: partition Reference, Up: image Reference 16.1.1 ‘partition’ Reference ---------------------------- In ‘image’ record may contain some partitions. -- Data Type: partition This is the data type representing an image partition. ‘size’ (default: ‘'guess’) The partition size in bytes or ‘'guess’. The ‘'guess’ symbol, which is the default, means that the partition size will be inferred based on the partition content. ‘offset’ (default: ‘0’) The partition’s start offset in bytes, relative to the image start or the previous partition end. It defaults to ‘0’ which means that there is no offset applied. ‘file-system’ (default: ‘"ext4"’) The partition file system as a string, defaulting to ‘"ext4"’. The supported values are ‘"vfat"’, ‘"fat16"’, ‘"fat32"’ and ‘"ext4"’. ‘file-system-options’ (default: ‘'()’) The partition file system creation options that should be passed to the partition creation tool, as a list of strings. This is only supported when creating ‘"ext4"’ partitions. See the ‘"extended-options"’ man page section of the ‘"mke2fs"’ tool for a more complete reference. ‘rótulo’ The partition label as a mandatory string, ‘"my-root"’ for instance. ‘uuid’ (default: ‘#false’) The partition UUID as an ‘uuid’ record (*note Sistemas de arquivos::). By default it is ‘#false’, which means that the partition creation tool will attribute a random UUID to the partition. ‘flags’ (default: ‘'()’) The partition flags as a list of symbols. Possible values are ‘'boot’ and ‘'esp’. The ‘'boot’ flags should be set if you want to boot from this partition. Exactly one partition should have this flag set, usually the root one. The ‘'esp’ flag identifies a UEFI System Partition. ‘initializer’ (default: ‘#false’) The partition initializer procedure as a gexp. This procedure is called to populate a partition. If no initializer is passed, the ‘initialize-root-partition’ procedure from the ‘(gnu build image)’ module is used.  File: guix.pt_BR.info, Node: Instantiate an Image, Next: image-type Reference, Prev: image Reference, Up: System Images 16.2 Instantiate an Image ========================= Let’s say you would like to create an MBR image with three distinct partitions: • The ESP (EFI System Partition), a partition of 40 MiB at offset 1024 KiB with a vfat file system. • an ext4 partition of 50 MiB data file, and labeled “data”. • an ext4 bootable partition containing the ‘%simple-os’ operating-system. You would then write the following image definition in a ‘my-image.scm’ file for instance. (use-modules (gnu) (gnu image) (gnu tests) (gnu system image) (guix gexp)) (define MiB (expt 2 20)) (image (format 'disk-image) (operating-system %simple-os) (partitions (list (partition (size (* 40 MiB)) (offset (* 1024 1024)) (label "GNU-ESP") (file-system "vfat") (flags '(esp)) (initializer (gexp initialize-efi-partition))) (partition (size (* 50 MiB)) (label "DATA") (file-system "ext4") (initializer #~(lambda* (root . rest) (mkdir root) (call-with-output-file (string-append root "/data") (lambda (port) (format port "my-data")))))) (partition (size 'guess) (label root-label) (file-system "ext4") (flags '(boot)) (initializer (gexp initialize-root-partition)))))) Note that the first and third partitions use generic initializers procedures, initialize-efi-partition and initialize-root-partition respectively. The initialize-efi-partition installs a GRUB EFI loader that is loading the GRUB bootloader located in the root partition. The initialize-root-partition instantiates a complete system as defined by the ‘%simple-os’ operating-system. You can now run: guix system image my-image.scm to instantiate the ‘image’ definition. That produces a disk image which has the expected structure: $ parted $(guix system image my-image.scm) print ... Model: (file) Disk /gnu/store/yhylv1bp5b2ypb97pd3bbhz6jk5nbhxw-disk-image: 1714MB Sector size (logical/physical): 512B/512B Partition Table: msdos Disk Flags: Number Start End Size Type File system Flags 1 1049kB 43.0MB 41.9MB primary fat16 esp 2 43.0MB 95.4MB 52.4MB primary ext4 3 95.4MB 1714MB 1619MB primary ext4 boot The size of the ‘boot’ partition has been inferred to ‘1619MB’ so that it is large enough to host the ‘%simple-os’ operating-system. You can also use existing ‘image’ record definitions and inherit from them to simplify the ‘image’ definition. The ‘(gnu system image)’ module provides the following ‘image’ definition variables. -- Scheme Variable: efi-disk-image A MBR disk-image composed of two partitions: a 64 bits ESP partition and a ROOT boot partition. This image can be used on most ‘x86_64’ and ‘i686’ machines, supporting BIOS or UEFI booting. -- Scheme Variable: efi32-disk-image Same as ‘efi-disk-image’ but with a 32 bits EFI partition. -- Scheme Variable: iso9660-image An ISO-9660 image composed of a single bootable partition. This image can also be used on most ‘x86_64’ and ‘i686’ machines. -- Scheme Variable: docker-image A Docker image that can be used to spawn a Docker container. Using the ‘efi-disk-image’ we can simplify our previous ‘image’ declaration this way: (use-modules (gnu) (gnu image) (gnu tests) (gnu system image) (guix gexp) (ice-9 match)) (define MiB (expt 2 20)) (define data (partition (size (* 50 MiB)) (label "DATA") (file-system "ext4") (initializer #~(lambda* (root . rest) (mkdir root) (call-with-output-file (string-append root "/data") (lambda (port) (format port "my-data"))))))) (image (inherit efi-disk-image) (operating-system %simple-os) (partitions (match (image-partitions efi-disk-image) ((esp root) (list esp data root))))) This will give the exact same ‘image’ instantiation but the ‘image’ declaration is simpler.  File: guix.pt_BR.info, Node: image-type Reference, Next: Image Modules, Prev: Instantiate an Image, Up: System Images 16.3 image-type Reference ========================= The ‘guix system image’ command can, as we saw above, take a file containing an ‘image’ declaration as argument and produce an actual disk image from it. The same command can also handle a file containing an ‘operating-system’ declaration as argument. In that case, how is the ‘operating-system’ turned into an image? That’s where the ‘image-type’ record intervenes. This record defines how to transform an ‘operating-system’ record into an ‘image’ record. -- Data Type: image-type This is the data type representing an image-type. ‘name’ The image-type name as a mandatory symbol, ‘'efi32-raw’ for instance. ‘constructor’ The image-type constructor, as a mandatory procedure that takes an ‘operating-system’ record as argument and returns an ‘image’ record. There are several ‘image-type’ records provided by the ‘(gnu system image)’ and the ‘(gnu system images ...)’ modules. -- Scheme Variable: efi-raw-image-type Build an image based on the ‘efi-disk-image’ image. -- Scheme Variable: efi32-raw-image-type Build an image based on the ‘efi32-disk-image’ image. -- Scheme Variable: qcow2-image-type Build an image based on the ‘efi-disk-image’ image but with the ‘compressed-qcow2’ image format. -- Scheme Variable: iso-image-type Build a compressed image based on the ‘iso9660-image’ image. -- Scheme Variable: uncompressed-iso-image-type Build an image based on the ‘iso9660-image’ image but with the ‘compression?’ field set to ‘#false’. -- Scheme Variable: docker-image-type Build an image based on the ‘docker-image’ image. -- Scheme Variable: raw-with-offset-image-type Build an MBR image with a single partition starting at a ‘1024KiB’ offset. This is useful to leave some room to install a bootloader in the post-MBR gap. -- Scheme Variable: pinebook-pro-image-type Build an image that is targeting the Pinebook Pro machine. The MBR image contains a single partition starting at a ‘9MiB’ offset. The ‘u-boot-pinebook-pro-rk3399-bootloader’ bootloader will be installed in this gap. -- Scheme Variable: rock64-image-type Build an image that is targeting the Rock64 machine. The MBR image contains a single partition starting at a ‘16MiB’ offset. The ‘u-boot-rock64-rk3328-bootloader’ bootloader will be installed in this gap. -- Scheme Variable: novena-image-type Build an image that is targeting the Novena machine. It has the same characteristics as ‘raw-with-offset-image-type’. -- Scheme Variable: pine64-image-type Build an image that is targeting the Pine64 machine. It has the same characteristics as ‘raw-with-offset-image-type’. -- Scheme Variable: hurd-image-type Build an image that is targeting a ‘i386’ machine running the Hurd kernel. The MBR image contains a single ext2 partitions with specific ‘file-system-options’ flags. -- Scheme Variable: hurd-qcow2-image-type Build an image similar to the one built by the ‘hurd-image-type’ but with the ‘format’ set to ‘'compressed-qcow2’. -- Scheme Variable: wsl2-image-type Build an image for the WSL2 (Windows Subsystem for Linux 2). It can be imported by running: wsl --import Guix ./guix ./wsl2-image.tar.gz wsl -d Guix So, if we get back to the ‘guix system image’ command taking an ‘operating-system’ declaration as argument. By default, the ‘efi-raw-image-type’ is used to turn the provided ‘operating-system’ into an actual bootable image. To use a different ‘image-type’, the ‘--image-type’ option can be used. The ‘--list-image-types’ option will list all the supported image types. It turns out to be a textual listing of all the ‘image-types’ variables described just above (*note Invocando guix system::).  File: guix.pt_BR.info, Node: Image Modules, Prev: image-type Reference, Up: System Images 16.4 Image Modules ================== Let’s take the example of the Pine64, an ARM based machine. To be able to produce an image targeting this board, we need the following elements: • An ‘operating-system’ record containing at least an appropriate kernel (‘linux-libre-arm64-generic’) and bootloader ‘u-boot-pine64-lts-bootloader’) for the Pine64. • Possibly, an ‘image-type’ record providing a way to turn an ‘operating-system’ record to an ‘image’ record suitable for the Pine64. • An actual ‘image’ that can be instantiated with the ‘guix system image’ command. The ‘(gnu system images pine64)’ module provides all those elements: ‘pine64-barebones-os’, ‘pine64-image-type’ and ‘pine64-barebones-raw-image’ respectively. The module returns the ‘pine64-barebones-raw-image’ in order for users to be able to run: guix system image gnu/system/images/pine64.scm Now, thanks to the ‘pine64-image-type’ record declaring the ‘'pine64-raw’ ‘image-type’, one could also prepare a ‘my-pine.scm’ file with the following content: (use-modules (gnu system images pine64)) (operating-system (inherit pine64-barebones-os) (timezone "Europe/Athens")) to customize the ‘pine64-barebones-os’, and run: $ guix system image --image-type=pine64-raw my-pine.scm Note that there are other modules in the ‘gnu/system/images’ directory targeting ‘Novena’, ‘Pine64’, ‘PinebookPro’ and ‘Rock64’ machines.  File: guix.pt_BR.info, Node: Instalando arquivos de depuração, Next: Using TeX and LaTeX, Prev: System Images, Up: Top 17 Instalando arquivos de depuração *********************************** Program binaries, as produced by the GCC compilers for instance, are typically written in the ELF format, with a section containing “debugging information”. Debugging information is what allows the debugger, GDB, to map binary code to source code; it is required to debug a compiled program in good conditions. This chapter explains how to use separate debug info when packages provide it, and how to rebuild packages with debug info when it’s missing. * Menu: * Separate Debug Info:: Installing ’debug’ outputs. * Rebuilding Debug Info:: Building missing debug info.  File: guix.pt_BR.info, Node: Separate Debug Info, Next: Rebuilding Debug Info, Up: Instalando arquivos de depuração 17.1 Separate Debug Info ======================== The problem with debugging information is that is takes up a fair amount of disk space. For example, debugging information for the GNU C Library weighs in at more than 60 MiB. Thus, as a user, keeping all the debugging info of all the installed programs is usually not an option. Yet, space savings should not come at the cost of an impediment to debugging—especially in the GNU system, which should make it easier for users to exert their computing freedom (*note Distribuição GNU::). Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a mechanism that allows users to get the best of both worlds: debugging information can be stripped from the binaries and stored in separate files. GDB is then able to load debugging information from those files, when they are available (*note (gdb)Separate Debug Files::). The GNU distribution takes advantage of this by storing debugging information in the ‘lib/debug’ sub-directory of a separate package output unimaginatively called ‘debug’ (*note Pacotes com múltiplas saídas::). Users can choose to install the ‘debug’ output of a package when they need it. For instance, the following command installs the debugging information for the GNU C Library and for GNU Guile: guix install glibc:debug guile:debug GDB must then be told to look for debug files in the user’s profile, by setting the ‘debug-file-directory’ variable (consider setting it from the ‘~/.gdbinit’ file, *note (gdb)Startup::): (gdb) set debug-file-directory ~/.guix-profile/lib/debug From there on, GDB will pick up debugging information from the ‘.debug’ files under ‘~/.guix-profile/lib/debug’. Below is an alternative GDB script which is useful when working with other profiles. It takes advantage of the optional Guile integration in GDB. This snippet is included by default on Guix System in the ‘~/.gdbinit’ file. guile (use-modules (gdb)) (execute (string-append "set debug-file-directory " (or (getenv "GDB_DEBUG_FILE_DIRECTORY") "~/.guix-profile/lib/debug"))) end In addition, you will most likely want GDB to be able to show the source code being debugged. To do that, you will have to unpack the source code of the package of interest (obtained with ‘guix build --source’, *note Invocando guix build::), and to point GDB to that source directory using the ‘directory’ command (*note ‘directory’: (gdb)Source Path.). The ‘debug’ output mechanism in Guix is implemented by the ‘gnu-build-system’ (*note Sistemas de compilação::). Currently, it is opt-in—debugging information is available only for the packages with definitions explicitly declaring a ‘debug’ output. To check whether a package has a ‘debug’ output, use ‘guix package --list-available’ (*note Invocando guix package::). Read on for how to deal with packages lacking a ‘debug’ output.  File: guix.pt_BR.info, Node: Rebuilding Debug Info, Prev: Separate Debug Info, Up: Instalando arquivos de depuração 17.2 Rebuilding Debug Info ========================== As we saw above, some packages, but not all, provide debugging info in a ‘debug’ output. What can you do when debugging info is missing? The ‘--with-debug-info’ option provides a solution to that: it allows you to rebuild the package(s) for which debugging info is missing—and only those—and to graft those onto the application you’re debugging. Thus, while it’s not as fast as installing a ‘debug’ output, it is relatively inexpensive. Let’s illustrate that. Suppose you’re experiencing a bug in Inkscape and would like to see what’s going on in GLib, a library that’s deep down in its dependency graph. As it turns out, GLib does not have a ‘debug’ output and the backtrace GDB shows is all sadness: (gdb) bt #0 0x00007ffff5f92190 in g_getenv () from /gnu/store/...-glib-2.62.6/lib/libglib-2.0.so.0 #1 0x00007ffff608a7d6 in gobject_init_ctor () from /gnu/store/...-glib-2.62.6/lib/libgobject-2.0.so.0 #2 0x00007ffff7fe275a in call_init (l=, argc=argc@entry=1, argv=argv@entry=0x7fffffffcfd8, env=env@entry=0x7fffffffcfe8) at dl-init.c:72 #3 0x00007ffff7fe2866 in call_init (env=0x7fffffffcfe8, argv=0x7fffffffcfd8, argc=1, l=) at dl-init.c:118 To address that, you install Inkscape linked against a variant GLib that contains debug info: guix install inkscape --with-debug-info=glib This time, debugging will be a whole lot nicer: $ gdb --args sh -c 'exec inkscape' ... (gdb) b g_getenv Function "g_getenv" not defined. Make breakpoint pending on future shared library load? (y or [n]) y Breakpoint 1 (g_getenv) pending. (gdb) r Starting program: /gnu/store/...-profile/bin/sh -c exec\ inkscape ... (gdb) bt #0 g_getenv (variable=variable@entry=0x7ffff60c7a2e "GOBJECT_DEBUG") at ../glib-2.62.6/glib/genviron.c:252 #1 0x00007ffff608a7d6 in gobject_init () at ../glib-2.62.6/gobject/gtype.c:4380 #2 gobject_init_ctor () at ../glib-2.62.6/gobject/gtype.c:4493 #3 0x00007ffff7fe275a in call_init (l=, argc=argc@entry=3, argv=argv@entry=0x7fffffffd088, env=env@entry=0x7fffffffd0a8) at dl-init.c:72 ... Much better! Note that there can be packages for which ‘--with-debug-info’ will not have the desired effect. *Note ‘--with-debug-info’: Opções de transformação de pacote, for more information.  File: guix.pt_BR.info, Node: Using TeX and LaTeX, Next: Atualizações de segurança, Prev: Instalando arquivos de depuração, Up: Top 18 Using TeX and LaTeX ********************** Guix provides packages for the TeX, LaTeX, ConTeXt, LuaTeX, and related typesetting systems, taken from the TeX Live distribution (https://www.tug.org/texlive/). However, because TeX Live is so huge and because finding your way in this maze is tricky, we thought that you, dear user, would welcome guidance on how to deploy the relevant packages so you can compile your TeX and LaTeX documents. TeX Live currently comes in two flavors in Guix: • The “monolithic” ‘texlive’ package: it comes with _every single TeX Live package_ (more than 7,000 of them), but it is huge (more than 4 GiB for a single package!). • The “modular” ‘texlive-’ packages: you install ‘texlive-base’, which provides core functionality and the main commands—‘pdflatex’, ‘dvips’, ‘luatex’, ‘mf’, etc.—together with individual packages that provide just the features you need—‘texlive-listings’ for the ‘listings’ package, ‘texlive-hyperref’ for ‘hyperref’, ‘texlive-beamer’ for Beamer, ‘texlive-pgf’ for PGF/TikZ, and so on. We recommend using the modular package set because it is much less resource-hungry. To build your documents, you would use commands such as: guix shell texlive-base texlive-wrapfig \ texlive-hyperref texlive-cm-super -- pdflatex doc.tex You can quickly end up with unreasonably long command lines though. The solution is to instead write a manifest, for example like this one: (specifications->manifest '("rubber" "texlive-base" "texlive-wrapfig" "texlive-microtype" "texlive-listings" "texlive-hyperref" ;; PGF/TikZ "texlive-pgf" ;; Additional fonts. "texlive-cm-super" "texlive-amsfonts" "texlive-times" "texlive-helvetic" "texlive-courier")) You can then pass it to any command with the ‘-m’ option: guix shell -m manifest.scm -- pdflatex doc.tex *Note Writing Manifests::, for more on manifests. In the future, we plan to provide packages for TeX Live “collections”—“meta-packages” such as ‘fontsrecommended’, ‘humanities’, or ‘langarabic’ that provide the set of packages needed in this particular domain. That will allow you to list fewer packages. The main difficulty here is that using the modular package set forces you to select precisely the packages that you need. You can use ‘guix search’, but finding the right package can prove to be tedious. When a package is missing, ‘pdflatex’ and similar commands fail with an obscure message along the lines of: doc.tex: File `tikz.sty' not found. doc.tex:7: Emergency stop. or, for a missing font: kpathsea: Running mktexmf phvr7t ! I can't find file `phvr7t'. How do you determine what the missing package is? In the first case, you’ll find the answer by running: $ guix search texlive tikz name: texlive-pgf version: 59745 ... In the second case, ‘guix search’ turns up nothing. Instead, you can search the TeX Live package database using the ‘tlmgr’ command: $ guix shell texlive-base -- tlmgr info phvr7t tlmgr: cannot find package phvr7t, searching for other matches: Packages containing `phvr7t' in their title/description: Packages containing files matching `phvr7t': helvetic: texmf-dist/fonts/tfm/adobe/helvetic/phvr7t.tfm texmf-dist/fonts/tfm/adobe/helvetic/phvr7tn.tfm texmf-dist/fonts/vf/adobe/helvetic/phvr7t.vf texmf-dist/fonts/vf/adobe/helvetic/phvr7tn.vf tex4ht: texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf The file is available in the TeX Live ‘helvetic’ package, which is known in Guix as ‘texlive-helvetic’. Quite a ride, but we found it! There is one important limitation though: Guix currently provides a subset of the TeX Live packages. If you stumble upon a missing package, you can try and import it (*note Invocando guix import::): guix import texlive PACKAGE Additional options include: ‘--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. Nota: TeX Live packaging is still very much work in progress, but you can help! *Note Contribuindo::, for more information.  File: guix.pt_BR.info, Node: Atualizações de segurança, Next: Inicializando, Prev: Using TeX and LaTeX, Up: Top 19 Atualizações de segurança **************************** Occasionally, important security vulnerabilities are discovered in software packages and must be patched. Guix developers try hard to keep track of known vulnerabilities and to apply fixes as soon as possible in the ‘master’ branch of Guix (we do not yet provide a “stable” branch containing only security updates). The ‘guix lint’ tool helps developers find out about vulnerable versions of software packages in the distribution: $ guix lint -c cve gnu/packages/base.scm:652:2: glibc@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547 gnu/packages/gcc.scm:334:2: gcc@4.9.3: probably vulnerable to CVE-2015-5276 gnu/packages/image.scm:312:2: openjpeg@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924 ... *Note Invocando guix lint::, for more information. Guix follows a functional package management discipline (*note Introdução::), which implies that, when a package is changed, _every package that depends on it_ must be rebuilt. This can significantly slow down the deployment of fixes in core packages such as libc or Bash, since basically the whole distribution would need to be rebuilt. Using pre-built binaries helps (*note Substitutos::), but deployment may still take more time than desired. To address this, Guix implements “grafts”, a mechanism that allows for fast deployment of critical updates without the costs associated with a whole-distribution rebuild. The idea is to rebuild only the package that needs to be patched, and then to “graft” it onto packages explicitly installed by the user and that were previously referring to the original package. The cost of grafting is typically very low, and order of magnitudes lower than a full rebuild of the dependency chain. For instance, suppose a security update needs to be applied to Bash. Guix developers will provide a package definition for the “fixed” Bash, say ‘bash-fixed’, in the usual way (*note Definindo pacotes::). Then, the original package definition is augmented with a ‘replacement’ field pointing to the package containing the bug fix: (define bash (package (name "bash") ;; ... (replacement bash-fixed))) From there on, any package depending directly or indirectly on Bash—as reported by ‘guix gc --requisites’ (*note Invocando guix gc::)—that is installed is automatically “rewritten” to refer to ‘bash-fixed’ instead of ‘bash’. This grafting process takes time proportional to the size of the package, usually less than a minute for an “average” package on a recent machine. Grafting is recursive: when an indirect dependency requires grafting, then grafting “propagates” up to the package that the user is installing. Currently, the length of the name and version of the graft and that of the package it replaces (‘bash-fixed’ and ‘bash’ in the example above) must be equal. This restriction mostly comes from the fact that grafting works by patching files, including binary files, directly. Other restrictions may apply: for instance, when adding a graft to a package providing a shared library, the original shared library and its replacement must have the same ‘SONAME’ and be binary-compatible. The ‘--no-grafts’ command-line option allows you to forcefully avoid grafting (*note ‘--no-grafts’: Opções de compilação comum.). Thus, the command: guix build bash --no-grafts returns the store file name of the original Bash, whereas: guix build bash returns the store file name of the “fixed”, replacement Bash. This allows you to distinguish between the two variants of Bash. To verify which Bash your whole profile refers to, you can run (*note Invocando guix gc::): guix gc -R $(readlink -f ~/.guix-profile) | grep bash ... and compare the store file names that you get with those above. Likewise for a complete Guix system generation: guix gc -R $(guix system build my-config.scm) | grep bash Lastly, to check which Bash running processes are using, you can use the ‘lsof’ command: lsof | grep /gnu/store/.*bash  File: guix.pt_BR.info, Node: Inicializando, Next: Portando, Prev: Atualizações de segurança, Up: Top 20 Inicializando **************** Bootstrapping in our context refers to how the distribution gets built “from nothing”. Remember that the build environment of a derivation contains nothing but its declared inputs (*note Introdução::). So there’s an obvious chicken-and-egg problem: how does the first package get built? How does the first compiler get compiled? It is tempting to think of this question as one that only die-hard hackers may care about. However, while the answer to that question is technical in nature, its implications are wide-ranging. How the distribution is bootstrapped defines the extent to which we, as individuals and as a collective of users and hackers, can trust the software we run. It is a central concern from the standpoint of _security_ and from a _user freedom_ viewpoint. The GNU system is primarily made of C code, with libc at its core. The GNU build system itself assumes the availability of a Bourne shell and command-line tools provided by GNU Coreutils, Awk, Findutils, ‘sed’, and ‘grep’. Furthermore, build programs—programs that run ‘./configure’, ‘make’, etc.—are written in Guile Scheme (*note Derivações::). Consequently, to be able to build anything at all, from scratch, Guix relies on pre-built binaries of Guile, GCC, Binutils, libc, and the other packages mentioned above—the “bootstrap binaries”. These bootstrap binaries are “taken for granted”, though we can also re-create them if needed (*note Preparing to Use the Bootstrap Binaries::). * Menu: * Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU. * Preparing to Use the Bootstrap Binaries:: Building that what matters most.  File: guix.pt_BR.info, Node: Reduced Binary Seed Bootstrap, Next: Preparing to Use the Bootstrap Binaries, Up: Inicializando 20.1 The Reduced Binary Seed Bootstrap ====================================== Guix—like other GNU/Linux distributions—is traditionally bootstrapped from a set of bootstrap binaries: Bourne shell, command-line tools provided by GNU Coreutils, Awk, Findutils, ‘sed’, and ‘grep’ and Guile, GCC, Binutils, and the GNU C Library (*note Inicializando::). Usually, these bootstrap binaries are “taken for granted.” Taking the bootstrap binaries for granted means that we consider them to be a correct and trustworthy “seed” for building the complete system. Therein lies a problem: the combined size of these bootstrap binaries is about 250MB (*note (mes)Bootstrappable Builds::). Auditing or even inspecting these is next to impossible. For ‘i686-linux’ and ‘x86_64-linux’, Guix now features a “Reduced Binary Seed” bootstrap (1). The Reduced Binary Seed bootstrap removes the most critical tools—from a trust perspective—from the bootstrap binaries: GCC, Binutils and the GNU C Library are replaced by: ‘bootstrap-mescc-tools’ (a tiny assembler and linker) and ‘bootstrap-mes’ (a small Scheme Interpreter and a C compiler written in Scheme and the Mes C Library, built for TinyCC and for GCC). Using these new binary seeds the “missing” Binutils, GCC, and the GNU C Library are built from source. From here on the more traditional bootstrap process resumes. This approach has reduced the bootstrap binaries in size to about 145MB in Guix v1.1. The next step that Guix has taken is to replace the shell and all its utilities with implementations in Guile Scheme, the _Scheme-only bootstrap_. Gash (*note (gash)Gash::) is a POSIX-compatible shell that replaces Bash, and it comes with Gash Utils which has minimalist replacements for Awk, the GNU Core Utilities, Grep, Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were removed are now built from source. Building the GNU System from source is currently only possible by adding some historical GNU packages as intermediate steps(2). As Gash and Gash Utils mature, and GNU packages become more bootstrappable again (e.g., new releases of GNU Sed will also ship as gzipped tarballs again, as alternative to the hard to bootstrap ‘xz’-compression), this set of added packages can hopefully be reduced again. The graph below shows the resulting dependency graph for ‘gcc-core-mesboot0’, the bootstrap compiler used for the traditional bootstrap of the rest of the Guix System. [image src="images/gcc-core-mesboot0-graph.png" alt="Dependency graph of gcc-core-mesboot0"] The only significant binary bootstrap seeds that remain(3) are a Scheme interpreter and a Scheme compiler: GNU Mes and GNU Guile(4). This further reduction has brought down the size of the binary seed to about 60MB for ‘i686-linux’ and ‘x86_64-linux’. Work is ongoing to remove all binary blobs from our free software bootstrap stack, working towards a Full Source Bootstrap. Also ongoing is work to bring these bootstraps to the ‘arm-linux’ and ‘aarch64-linux’ architectures and to the Hurd. If you are interested, join us on ‘#bootstrappable’ on the Freenode IRC network or discuss on or . ---------- Footnotes ---------- (1) We would like to say: “Full Source Bootstrap” and while we are working towards that goal it would be hyperbole to use that term for what we do now. (2) Packages such as ‘gcc-2.95.3’, ‘binutils-2.14’, ‘glibc-2.2.5’, ‘gzip-1.2.4’, ‘tar-1.22’, and some others. For details, see ‘gnu/packages/commencement.scm’. (3) Ignoring the 68KB ‘mescc-tools’; that will be removed later, together with ‘mes’. (4) Not shown in this graph are the static binaries for ‘bash’, ‘tar’, and ‘xz’ that are used to get Guile running.  File: guix.pt_BR.info, Node: Preparing to Use the Bootstrap Binaries, Prev: Reduced Binary Seed Bootstrap, Up: Inicializando 20.2 Preparing to Use the Bootstrap Binaries ============================================ [image src="images/bootstrap-graph.png" alt="Dependency graph of the early bootstrap derivations"] The figure above shows the very beginning of the dependency graph of the distribution, corresponding to the package definitions of the ‘(gnu packages bootstrap)’ module. A similar figure can be generated with ‘guix graph’ (*note Invocando guix graph::), along the lines of: guix graph -t derivation \ -e '(@@ (gnu packages bootstrap) %bootstrap-gcc)' \ | dot -Tps > gcc.ps or, for the further Reduced Binary Seed bootstrap guix graph -t derivation \ -e '(@@ (gnu packages bootstrap) %bootstrap-mes)' \ | dot -Tps > mes.ps At this level of detail, things are slightly complex. First, Guile itself consists of an ELF executable, along with many source and compiled Scheme files that are dynamically loaded when it runs. This gets stored in the ‘guile-2.0.7.tar.xz’ tarball shown in this graph. This tarball is part of Guix’s “source” distribution, and gets inserted into the store with ‘add-to-store’ (*note O armazém::). But how do we write a derivation that unpacks this tarball and adds it to the store? To solve this problem, the ‘guile-bootstrap-2.0.drv’ derivation—the first one that gets built—uses ‘bash’ as its builder, which runs ‘build-bootstrap-guile.sh’, which in turn calls ‘tar’ to unpack the tarball. Thus, ‘bash’, ‘tar’, ‘xz’, and ‘mkdir’ are statically-linked binaries, also part of the Guix source distribution, whose sole purpose is to allow the Guile tarball to be unpacked. Once ‘guile-bootstrap-2.0.drv’ is built, we have a functioning Guile that can be used to run subsequent build programs. Its first task is to download tarballs containing the other pre-built binaries—this is what the ‘.tar.xz.drv’ derivations do. Guix modules such as ‘ftp-client.scm’ are used for this purpose. The ‘module-import.drv’ derivations import those modules in a directory in the store, using the original layout. The ‘module-import-compiled.drv’ derivations compile those modules, and write them in an output directory with the right layout. This corresponds to the ‘#:modules’ argument of ‘build-expression->derivation’ (*note Derivações::). Finally, the various tarballs are unpacked by the derivations ‘gcc-bootstrap-0.drv’, ‘glibc-bootstrap-0.drv’, or ‘bootstrap-mes-0.drv’ and ‘bootstrap-mescc-tools-0.drv’, at which point we have a working C tool chain. Building the Build Tools ======================== Bootstrapping is complete when we have a full tool chain that does not depend on the pre-built bootstrap tools discussed above. This no-dependency requirement is verified by checking whether the files of the final tool chain contain references to the ‘/gnu/store’ directories of the bootstrap inputs. The process that leads to this “final” tool chain is described by the package definitions found in the ‘(gnu packages commencement)’ module. The ‘guix graph’ command allows us to “zoom out” compared to the graph above, by looking at the level of package objects instead of individual derivations—remember that a package may translate to several derivations, typically one derivation to download its source, one to build the Guile modules it needs, and one to actually build the package from source. The command: guix graph -t bag \ -e '(@@ (gnu packages commencement) glibc-final-with-bootstrap-bash)' | xdot - displays the dependency graph leading to the “final” C library(1), depicted below. [image src="images/bootstrap-packages.png" alt="Dependency graph of the early packages"] The first tool that gets built with the bootstrap binaries is GNU Make—noted ‘make-boot0’ above—which is a prerequisite for all the following packages. From there Findutils and Diffutils get built. Then come the first-stage Binutils and GCC, built as pseudo cross tools—i.e., with ‘--target’ equal to ‘--host’. They are used to build libc. Thanks to this cross-build trick, this libc is guaranteed not to hold any reference to the initial tool chain. From there the final Binutils and GCC (not shown above) are built. GCC uses ‘ld’ from the final Binutils, and links programs against the just-built libc. This tool chain is used to build the other packages used by Guix and by the GNU Build System: Guile, Bash, Coreutils, etc. And voilà! At this point we have the complete set of build tools that the GNU Build System expects. These are in the ‘%final-inputs’ variable of the ‘(gnu packages commencement)’ module, and are implicitly used by any package that uses ‘gnu-build-system’ (*note ‘gnu-build-system’: Sistemas de compilação.). Building the Bootstrap Binaries =============================== Because the final tool chain does not depend on the bootstrap binaries, those rarely need to be updated. Nevertheless, it is useful to have an automated way to produce them, should an update occur, and this is what the ‘(gnu packages make-bootstrap)’ module provides. The following command builds the tarballs containing the bootstrap binaries (Binutils, GCC, glibc, for the traditional bootstrap and linux-libre-headers, bootstrap-mescc-tools, bootstrap-mes for the Reduced Binary Seed bootstrap, and Guile, and a tarball containing a mixture of Coreutils and other basic command-line tools): guix build bootstrap-tarballs The generated tarballs are those that should be referred to in the ‘(gnu packages bootstrap)’ module mentioned at the beginning of this section. Still here? Then perhaps by now you’ve started to wonder: when do we reach a fixed point? That is an interesting question! The answer is unknown, but if you would like to investigate further (and have significant computational and storage resources to do so), then let us know. Reducing the Set of Bootstrap Binaries ====================================== Our traditional bootstrap includes GCC, GNU Libc, Guile, etc. That’s a lot of binary code! Why is that a problem? It’s a problem because these big chunks of binary code are practically non-auditable, which makes it hard to establish what source code produced them. Every unauditable binary also leaves us vulnerable to compiler backdoors as described by Ken Thompson in the 1984 paper _Reflections on Trusting Trust_. This is mitigated by the fact that our bootstrap binaries were generated from an earlier Guix revision. Nevertheless it lacks the level of transparency that we get in the rest of the package dependency graph, where Guix always gives us a source-to-binary mapping. Thus, our goal is to reduce the set of bootstrap binaries to the bare minimum. The Bootstrappable.org web site (https://bootstrappable.org) lists on-going projects to do that. One of these is about replacing the bootstrap GCC with a sequence of assemblers, interpreters, and compilers of increasing complexity, which could be built from source starting from a simple and auditable assembler. Our first major achievement is the replacement of of GCC, the GNU C Library and Binutils by MesCC-Tools (a simple hex linker and macro assembler) and Mes (*note GNU Mes Reference Manual: (mes)Top, a Scheme interpreter and C compiler in Scheme). Neither MesCC-Tools nor Mes can be fully bootstrapped yet and thus we inject them as binary seeds. We call this the Reduced Binary Seed bootstrap, as it has halved the size of our bootstrap binaries! Also, it has eliminated the C compiler binary; i686-linux and x86_64-linux Guix packages are now bootstrapped without any binary C compiler. Work is ongoing to make MesCC-Tools and Mes fully bootstrappable and we are also looking at any other bootstrap binaries. Your help is welcome! ---------- Footnotes ---------- (1) You may notice the ‘glibc-intermediate’ label, suggesting that it is not _quite_ final, but as a good approximation, we will consider it final.  File: guix.pt_BR.info, Node: Portando, Next: Contribuindo, Prev: Inicializando, Up: Top 21 Portando para uma nova plataforma ************************************ As discussed above, the GNU distribution is self-contained, and self-containment is achieved by relying on pre-built “bootstrap binaries” (*note Inicializando::). These binaries are specific to an operating system kernel, CPU architecture, and application binary interface (ABI). Thus, to port the distribution to a platform that is not yet supported, one must build those bootstrap binaries, and update the ‘(gnu packages bootstrap)’ module to use them on that platform. Fortunately, Guix can _cross compile_ those bootstrap binaries. When everything goes well, and assuming the GNU tool chain supports the target platform, this can be as simple as running a command like this one: guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs For this to work, it is first required to register a new platform as defined in the ‘(guix platform)’ module. A platform is making the connection between a GNU triplet (*note GNU configuration triplets: (autoconf)Specifying Target Triplets.), the equivalent SYSTEM in Nix notation, the name of the GLIBC-DYNAMIC-LINKER, and the corresponding Linux architecture name if applicable (*note Platforms::). Once the bootstrap tarball are built, the ‘(gnu packages bootstrap)’ module needs to be updated to refer to these binaries on the target platform. That is, the hashes and URLs of the bootstrap tarballs for the new platform must be added alongside those of the currently supported platforms. The bootstrap Guile tarball is treated specially: it is expected to be available locally, and ‘gnu/local.mk’ has rules to download it for the supported architectures; a rule for the new platform must be added as well. In practice, there may be some complications. First, it may be that the extended GNU triplet that specifies an ABI (like the ‘eabi’ suffix above) is not recognized by all the GNU tools. Typically, glibc recognizes some of these, whereas GCC uses an extra ‘--with-abi’ configure flag (see ‘gcc.scm’ for examples of how to handle this). Second, some of the required packages could fail to build for that platform. Lastly, the generated binaries could be broken for some reason.  File: guix.pt_BR.info, Node: Contribuindo, Next: Agradecimentos, Prev: Portando, Up: Top 22 Contribuindo *************** This project is a cooperative effort, and we need your help to make it grow! Please get in touch with us on and ‘#guix’ on the Libera Chat IRC network. We welcome ideas, bug reports, patches, and anything that may be helpful to the project. We particularly welcome help on packaging (*note Diretrizes de empacotamento::). Queremos oferecer um ambiente acolhedor, amigável e sem assédio, para que todos possam contribuir com o melhor de suas habilidades. Para este fim, nosso projeto usa um “Acordo de contribuição“, que foi adaptado de . Você pode encontrar uma versão local no arquivo ‘CODE-OF-CONDUCT’ na árvore de fontes. Os contribuidores não são obrigados a usar seu nome legal em patches e comunicação on-line; eles podem usar qualquer nome ou pseudônimo de sua escolha. * Menu: * Compilando do git:: A mais recente e melhor. * Executando guix antes dele ser instalado:: Truques de hacker. * A configuração perfeita:: As ferramentas certas. * Diretrizes de empacotamento:: Crescendo a distribuição. * Estilo de código:: Limpeza do contribuidor. * Enviando patches:: Compartilhe seu trabalho. * Tracking Bugs and Patches:: Keeping it all organized. * Commit Access:: Pushing to the official repository. * Updating the Guix Package:: Updating the Guix package definition. * Writing Documentation:: Improving documentation in GNU Guix. * Traduzindo o Guix:: Make Guix speak your native language.  File: guix.pt_BR.info, Node: Compilando do git, Next: Executando guix antes dele ser instalado, Up: Contribuindo 22.1 Compilando do git ====================== Se você quiser hackear o próprio Guix, é recomendado usar a versão mais recente do repositório Git: git clone https://git.savannah.gnu.org/git/guix.git How do you ensure that you obtained a genuine copy of the repository? To do that, run ‘guix git authenticate’, passing it the commit and OpenPGP fingerprint of the “channel introduction” (*note Invoking guix git authenticate::): git fetch origin keyring:keyring guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \ "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA" This command completes with exit code zero on success; it prints an error message and exits with a non-zero code otherwise. As you can see, there is a chicken-and-egg problem: you first need to have Guix installed. Typically you would install Guix System (*note Instalação do sistema::) or Guix on top of another distro (*note Instalação de binários::); in either case, you would verify the OpenPGP signature on the installation medium. This “bootstraps” the trust chain. A maneira mais fácil de configurar um ambiente de desenvolvimento para o Guix é, obviamente, usando o Guix! O comando a seguir inicia um novo shell no qual todas as dependências e variáveis de ambiente apropriadas são configuradas para hackear o Guix: guix shell -D guix --pure *Note Invoking guix shell::, for more information on that command. If you are unable to use Guix when building Guix from a checkout, the following are the required packages in addition to those mentioned in the installation instructions (*note Requisitos::). • GNU Autoconf (https://gnu.org/software/autoconf/); • GNU Automake (https://gnu.org/software/automake/); • GNU Gettext (https://gnu.org/software/gettext/); • GNU Texinfo (https://gnu.org/software/texinfo/); • Graphviz (https://www.graphviz.org/); • GNU Help2man (optional) (https://www.gnu.org/software/help2man/). On Guix, extra dependencies can be added by instead running ‘guix shell’: guix shell -D guix help2man git strace --pure From there you can generate the build system infrastructure using Autoconf and Automake: ./bootstrap If you get an error like this one: configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES provavelmente significa que o Autoconf não conseguiu encontrar o ‘pkg.m4’, que é fornecido pelo pkg-config. Certifique-se de que ‘pkg.m4’ esteja disponível. O mesmo vale para o conjunto de macros ‘guile.m4’ fornecido pelo Guile. Por exemplo, se você instalou o Automake em ‘/usr/local’, ele não procuraria arquivos ‘.m4’ em ‘/usr/share’. Nesse caso, você tem que invocar o seguinte comando: export ACLOCAL_PATH=/usr/share/aclocal *Note (automake)Macro Search Path::, para mais informações. Then, run: ./configure --localstatedir=/var ... where ‘/var’ is the normal ‘localstatedir’ value (*note O armazém::, for information about this). Note that you will probably not run ‘make install’ at the end (you don’t have to) but it’s still important to pass the right ‘localstatedir’. Finally, you can build Guix and, if you feel so inclined, run the tests (*note Executando a suíte de testes::): make make check If anything fails, take a look at installation instructions (*note Instalação::) or send a message to the mailing list . From there on, you can authenticate all the commits included in your checkout by running: make authenticate The first run takes a couple of minutes, but subsequent runs are faster. Or, when your configuration for your local Git repository doesn’t match the default one, you can provide the reference for the ‘keyring’ branch through the variable ‘GUIX_GIT_KEYRING’. The following example assumes that you have a Git remote called ‘myremote’ pointing to the official repository: make authenticate GUIX_GIT_KEYRING=myremote/keyring Nota: You are advised to run ‘make authenticate’ after every ‘git pull’ invocation. This ensures you keep receiving valid changes to the repository. After updating the repository, ‘make’ might fail with an error similar to the following example: error: failed to load 'gnu/packages/dunst.scm': ice-9/eval.scm:293:34: In procedure abi-check: #>: record ABI mismatch; recompilation needed This means that one of the record types that Guix defines (in this example, the ‘origin’ record) has changed, and all of guix needs to be recompiled to take that change into account. To do so, run ‘make clean-go’ followed by ‘make’.  File: guix.pt_BR.info, Node: Executando guix antes dele ser instalado, Next: A configuração perfeita, Prev: Compilando do git, Up: Contribuindo 22.2 Executando guix antes dele ser instalado ============================================= Para manter um ambiente de trabalho saudável, você achará útil testar as alterações feitas na árvore local de fontes sem realmente instalá-las. Para que você possa distinguir entre o seu chapéude ”usuário final” e sua fantasia ”misturada”. To that end, all the command-line tools can be used even if you have not run ‘make install’. To do that, you first need to have an environment with all the dependencies available (*note Compilando do git::), and then simply prefix each command with ‘./pre-inst-env’ (the ‘pre-inst-env’ script lives in the top build tree of Guix; it is generated by running ‘./bootstrap’ followed by ‘./configure’). As an example, here is how you would build the ‘hello’ package as defined in your working tree (this assumes ‘guix-daemon’ is already running on your system; it’s OK if it’s a different version): $ ./pre-inst-env guix build hello Similarly, an example for a Guile session using the Guix modules: $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' ;;; ("x86_64-linux") ... and for a REPL (*note Using Guix Interactively::): $ ./pre-inst-env guile scheme@(guile-user)> ,use(guix) scheme@(guile-user)> ,use(gnu) scheme@(guile-user)> (define snakes (fold-packages (lambda (package lst) (if (string-prefix? "python" (package-name package)) (cons package lst) lst)) '())) scheme@(guile-user)> (length snakes) $1 = 361 If you are hacking on the daemon and its supporting code or if ‘guix-daemon’ is not already running on your system, you can launch it straight from the build tree(1): $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild O script ‘pre-inst-env’ configura todas as variáveis de ambiente necessárias para prover suporte a isso, incluindo ‘PATH’ e ‘GUILE_LOAD_PATH’. Observe que ‘./pre-inst-env guix pull’ _não_ atualiza a área de fontes local; ele simplesmente atualiza o link simbólico ‘~/.config/guix/current’ (*note Invocando guix pull::). Execute ‘git pull’ em vez disso, se você quiser atualizar sua árvore de fontes local. Sometimes, especially if you have recently updated your repository, running ‘./pre-inst-env’ will print a message similar to the following example: ;;; note: source file /home/user/projects/guix/guix/progress.scm ;;; newer than compiled /home/user/projects/guix/guix/progress.go This is only a note and you can safely ignore it. You can get rid of the message by running ‘make -j4’. Until you do, Guile will run slightly slower because it will interpret the code instead of using prepared Guile object (‘.go’) files. You can run ‘make’ automatically as you work using ‘watchexec’ from the ‘watchexec’ package. For example, to build again each time you update a package file, run ‘watchexec -w gnu/packages -- make -j4’. ---------- Footnotes ---------- (1) The ‘-E’ flag to ‘sudo’ guarantees that ‘GUILE_LOAD_PATH’ is correctly set such that ‘guix-daemon’ and the tools it uses can find the Guile modules they need.  File: guix.pt_BR.info, Node: A configuração perfeita, Next: Diretrizes de empacotamento, Prev: Executando guix antes dele ser instalado, Up: Contribuindo 22.3 A configuração perfeita ============================ The Perfect Setup to hack on Guix is basically the perfect setup used for Guile hacking (*note (guile)Using Guile in Emacs::). First, you need more than an editor, you need Emacs (https://www.gnu.org/software/emacs), empowered by the wonderful Geiser (https://nongnu.org/geiser/). To set that up, run: guix install emacs guile emacs-geiser emacs-geiser-guile O Geiser permite um desenvolvimento interativo e incremental de dentro do Emacs: compilação e avaliação de código de dentro dos buffers, acesso à documentação on-line (docstrings), completação sensível ao contexto, ‘M-.’ para pular para uma definição de objeto, um REPL para tentar seu código e muito mais (*note (geiser)Introdução::). Para um desenvolvimento prático do Guix, certifique-se de aumentar o caminho de carregamento do Guile para que ele encontre os arquivos de origem do seu checkout: ;; Presumindo que o checkout do Guix está em ~/src/guix. (with-eval-after-load 'geiser-guile (add-to-list 'geiser-guile-load-path "~/src/guix")) To actually edit the code, Emacs already has a neat Scheme mode. But in addition to that, you must not miss Paredit (https://www.emacswiki.org/emacs/ParEdit). It provides facilities to directly operate on the syntax tree, such as raising an s-expression or wrapping it, swallowing or rejecting the following s-expression, etc. We also provide templates for common git commit messages and package definitions in the ‘etc/snippets’ directory. These templates can be used to expand short trigger strings to interactive text snippets. If you use YASnippet (https://joaotavora.github.io/yasnippet/), you may want to add the ‘etc/snippets/yas’ snippets directory to the YAS-SNIPPET-DIRS variable. If you use Tempel (https://github.com/minad/tempel/), you may want to add the ‘etc/snippets/tempel/*’ path to the TEMPEL-PATH variable in Emacs. ;; Assuming the Guix checkout is in ~/src/guix. ;; Yasnippet configuration (with-eval-after-load 'yasnippet (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas")) ;; Tempel configuration (with-eval-after-load 'tempel ;; Ensure tempel-path is a list -- it may also be a string. (unless (listp 'tempel-path) (setq tempel-path (list tempel-path))) (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*")) Os trechos de mensagens de commit dependem de Magit (https://magit.vc/) para exibir arquivos "staged". Ao editar uma mensagem de commit, digite ‘add’ seguido por ‘TAB’ para inserir um modelo de mensagem de commit para adicionar um pacote; digite ‘update’ seguido por ‘TAB’ para inserir um modelo para atualizar um pacote; digite ‘https’ seguido por ‘TAB’ para inserir um modelo para alterar a URI da página inicial de um pacote para HTTPS. O trecho principal para ‘scheme-mode’ é acionado digitando ‘package ...’ seguido de ‘TAB’. Esse trecho também insere a string de acionamento ‘origin...’, que pode ser expandida ainda mais. O trecho ‘origin’, por sua vez, pode inserir outras strings acionadoras que terminam em ‘...’, que também podem ser expandidas. We additionally provide insertion and automatic update of a copyright in ‘etc/copyright.el’. You may want to set your full name, mail, and load a file. (setq user-full-name "Alice Doe") (setq user-mail-address "alice@mail.org") ;; Assuming the Guix checkout is in ~/src/guix. (load-file "~/src/guix/etc/copyright.el") To insert a copyright at the current line invoke ‘M-x guix-copyright’. To update a copyright you need to specify a ‘copyright-names-regexp’. (setq copyright-names-regexp (format "%s <%s>" user-full-name user-mail-address)) You can check if your copyright is up to date by evaluating ‘M-x copyright-update’. If you want to do it automatically after each buffer save then add ‘(add-hook 'after-save-hook 'copyright-update)’ in Emacs.  File: guix.pt_BR.info, Node: Diretrizes de empacotamento, Next: Estilo de código, Prev: A configuração perfeita, Up: Contribuindo 22.4 Diretrizes de empacotamento ================================ A distribuição do GNU é incipiente e pode muito bem não ter alguns dos seus pacotes favoritos. Esta seção descreve como você pode ajudar a fazer a distribuição crescer. Pacotes de software livre geralmente são distribuídos na forma de “tarballs de código-fonte” – geralmente arquivos ‘tar.gz’ que contêm todos os arquivos fonte. Adicionar um pacote à distribuição significa essencialmente duas coisas: adicionar uma “receita” que descreve como criar o pacote, incluindo uma lista de outros pacotes necessários para compilá-lo e adicionar “metadados de pacote” junto com essa receita, como uma descrição e informações de licenciamento. No Guix, todas essas informações estão incorporadas em “configurações de pacote”. As definições de pacote fornecem uma visão de alto nível do pacote. Elas são escritas usando a sintaxe da linguagem de programação Scheme; de fato, para cada pacote, definimos uma variável vinculada à definição do pacote e exportamos essa variável de um módulo (*note Módulos de pacote::). No entanto, o conhecimento profundo de Scheme _não_ é um pré-requisito para a criação de pacotes. Para mais informações sobre definições de pacotes, *note Definindo pacotes::. Quando uma definição de pacote está em vigor, armazenada em um arquivo na árvore de fontes do Guix, ela pode ser testada usando o comando ‘guix build’ (*note Invocando guix build::). Por exemplo, supondo que o novo pacote seja chamado ‘gnew’, você pode executar este comando na árvore de construção do Guix (*note Executando guix antes dele ser instalado::): ./pre-inst-env guix build gnew --keep-failed O uso de ‘--keep-failed’ facilita a depuração de falhas de compilação, pois fornece acesso à árvore de compilação com falha. Outra opção útil da linha de comando ao depurar é ‘--log-file’, para acessar o log de compilação. Se o pacote for desconhecido para o comando ‘guix’, pode ser que o arquivo fonte contenha um erro de sintaxe ou não tenha uma cláusula ‘define-public’ para exportar a variável do pacote. Para descobrir isso, você pode carregar o módulo do Guile para obter mais informações sobre o erro real: ./pre-inst-env guile -c '(use-modules (gnu packages gnew))' Once your package builds correctly, please send us a patch (*note Enviando patches::). Well, if you need help, we will be happy to help you too. Once the patch is committed in the Guix repository, the new package automatically gets built on the supported platforms by our continuous integration system (https://ci.guix.gnu.org). Users can obtain the new package definition simply by running ‘guix pull’ (*note Invocando guix pull::). When ‘ci.guix.gnu.org’ is done building the package, installing the package automatically downloads binaries from there (*note Substitutos::). The only place where human intervention is needed is to review and apply the patch. * Menu: * Liberdade de software:: O que pode ir na distribuição. * Nomeando um pacote:: Que há em um nome? * Números de versão:: Quando o nome não é suficiente. * Sinopses e descrições:: Ajudando usuários a localizar o pacote certo. * Snippets versus Phases:: Whether to use a snippet, or a build phase. * Emacs Packages:: Your Elisp fix. * Módulos Python:: Um toque de comédia britânica. * Módulos Perl:: Pequenas pérolas. * Pacotes Java:: Parada para o café. * Rust Crates:: Beware of oxidation. * Elm Packages:: Trees of browser code * Fontes:: Vício em fontes.  File: guix.pt_BR.info, Node: Liberdade de software, Next: Nomeando um pacote, Up: Diretrizes de empacotamento 22.4.1 Liberdade de software ---------------------------- The GNU operating system has been developed so that users can have freedom in their computing. GNU is “free software”, meaning that users have the four essential freedoms (https://www.gnu.org/philosophy/free-sw.html): to run the program, to study and change the program in source code form, to redistribute exact copies, and to distribute modified versions. Packages found in the GNU distribution provide only software that conveys these four freedoms. In addition, the GNU distribution follow the free software distribution guidelines (https://www.gnu.org/distros/free-system-distribution-guidelines.html). Among other things, these guidelines reject non-free firmware, recommendations of non-free software, and discuss ways to deal with trademarks and patents. Algumas fontes de pacotes upstream livres de outra forma contêm um subconjunto pequeno e opcional que viola as diretrizes acima, por exemplo, porque esse subconjunto é ele próprio um código não livre. Quando isso acontece, os itens incorretos são removidos com patches ou trechos de código apropriados no formato ‘origin’ do pacote (*note Definindo pacotes::). Dessa forma, o ‘guix build --source’ retorna a fonte “lançada” em vez da fonte upstream não modificada.  File: guix.pt_BR.info, Node: Nomeando um pacote, Next: Números de versão, Prev: Liberdade de software, Up: Diretrizes de empacotamento 22.4.2 Nomeando um pacote ------------------------- A package actually has two names associated with it. First, there is the name of the _Scheme variable_, the one following ‘define-public’. By this name, the package can be made known in the Scheme code, for instance as input to another package. Second, there is the string in the ‘name’ field of a package definition. This name is used by package management commands such as ‘guix package’ and ‘guix build’. Ambos são geralmente iguais e correspondem à conversão em minúscula do nome do projeto escolhido a montante, com os sublinhados substituídos por hífenes. Por exemplo, o GNUnet está disponível como ‘gnunet’ e SDL_net como ‘sdl-net’. A noteworthy exception to this rule is when the project name is only a single character, or if an older maintained project with the same name already exists—regardless of whether it has already been packaged for Guix. Use common sense to make such names unambiguous and meaningful. For example, Guix’s package for the shell called “s” upstream is ‘s-shell’ and _not_ ‘s’. Feel free to ask your fellow hackers for inspiration. Não adicionamos prefixos ‘lib’ para pacotes de bibliotecas, a menos que eles já façam parte do nome oficial do projeto. Mas *note Módulos Python:: e *note Módulos Perl:: para regras especiais relativas a módulos para as linguagens Python e Perl. Nomes de pacote de fontes são lidados de forma diferente. *Note Fontes::.  File: guix.pt_BR.info, Node: Números de versão, Next: Sinopses e descrições, Prev: Nomeando um pacote, Up: Diretrizes de empacotamento 22.4.3 Números de versão ------------------------ Geralmente, empacotamos apenas a versão mais recente de um determinado projeto de software livre. Mas, às vezes, por exemplo, para versões incompatíveis de bibliotecas, são necessárias duas (ou mais) versões do mesmo pacote. Isso requer nomes de variáveis Scheme diferentes. Usamos o nome como definido em *note Nomeando um pacote:: para a versão mais recente; as versões anteriores usam o mesmo nome, com o sufixo ‘-’ e o menor prefixo do número da versão que pode distinguir as duas versões. O nome dentro da definição do pacote é o mesmo para todas as versões de um pacote e não contém nenhum número de versão. Por exemplo, as versões 2.24.20 e 3.9.12 do GTK podem ser empacotados da seguinte forma: (define-public gtk+ (package (name "gtk+") (version "3.9.12") ...)) (define-public gtk+-2 (package (name "gtk+") (version "2.24.20") ...)) Se também quiséssemos GTK 3.8.2, este seria empacotado como (define-public gtk+-3.8 (package (name "gtk+") (version "3.8.2") ...)) Ocasionalmente, empacotamos snapshots do sistema de controle de versão (VCS) do upstream em vez de lançamentos formais. Isso deve permanecer excepcional, porque cabe aos desenvolvedores upstream esclarecer qual é a versão estável. No entanto, às vezes é necessário. Então, o que devemos colocar no campo ‘version’? Claramente, precisamos tornar o identificador de commit do snapshot VCS visível na string de versão, mas também precisamos garantir que a string de versão esteja aumentando monotonicamente para que o ‘pacote guix --upgrade’ possa determinar qual versão é mais recente. Como os identificadores de commit, principalmente com o Git, não estão aumentando monotonicamente, adicionamos um número de revisão que aumentamos cada vez que atualizamos para um snapshot mais recente. A sequência da versão resultante é assim: 2.0.11-3.cabba9e ^ ^ ^ | | `-- ID do commit do upstream | | | `--- revisão do pacote do Guix | versão mais recente do upstream It is a good idea to strip commit identifiers in the ‘version’ field to, say, 7 digits. It avoids an aesthetic annoyance (assuming aesthetics have a role to play here) as well as problems related to OS limits such as the maximum shebang length (127 bytes for the Linux kernel). There are helper functions for doing this for packages using ‘git-fetch’ or ‘hg-fetch’ (see below). It is best to use the full commit identifiers in ‘origin’s, though, to avoid ambiguities. A typical package definition may look like this: (define meu-pacote (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") (revision "1")) ;revisão do pacote do Guix (package (version (git-version "0.9" revision commit)) (source (origin (method git-fetch) (uri (git-reference (url "git://example.org/meu-pacote.git") (commit commit))) (sha256 (base32 "1mbikn...")) (file-name (git-file-name name version)))) ;; ... ))) -- Scheme Procedure: git-version VERSION REVISION COMMIT Return the version string for packages using ‘git-fetch’. (git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05") ⇒ "0.2.3-0.93818c9" -- Scheme Procedure: hg-version VERSION REVISION CHANGESET Return the version string for packages using ‘hg-fetch’. It works in the same way as ‘git-version’.  File: guix.pt_BR.info, Node: Sinopses e descrições, Next: Snippets versus Phases, Prev: Números de versão, Up: Diretrizes de empacotamento 22.4.4 Sinopses e descrições ---------------------------- Como vimos anteriormente, cada pacote no GNU Guix inclui uma sinopse e uma descrição (*note Definindo pacotes::). Sinopses e descrições são importantes: são o que o ‘guix package --search’ pesquisa e uma informação crucial para ajudar os usuários a determinar se um determinado pacote atende às suas necessidades. Consequentemente, os empacotadores devem prestar atenção ao que entra neles. As sinopses devem começar com uma letra maiúscula e não devem terminar com um ponto. Elas não devem começar com “a” ou “the”, que geralmente não traz nada; por exemplo, prefira “Tool-frobbing tool” em vez de “A tool that frobs files”. A sinopse deve dizer o que é o pacote – por exemplo, “Core GNU utilities (file, text, shell)” – ou para que é usado – por exemplo, a sinopse do GNU grep é “Print lines matching a pattern”. Lembre-se de que a sinopse deve ser significativa para um público muito amplo. Por exemplo, “Manipulate alignments in the SAM format” pode fazer sentido para um pesquisador experiente em bioinformática, mas pode ser bastante inútil ou até enganoso para um público não especializado. É uma boa ideia apresentar uma sinopse que dê uma ideia do domínio do aplicativo do pacote. Neste exemplo, isso pode fornecer algo como “Manipulate nucleotide sequence alignments”, o que, esperançosamente, dá ao usuário uma melhor ideia de se é isso que eles estão procurando. Descrições devem levar entre cinco e dez linhas. Use sentenças completas e evite usar acrônimos sem primeiro apresentá-los. Por favor, evite frases de marketing como “inovação mundial”, “força industrial” e “próxima geração”, e evite superlativos como “a mais avançada” – eles não ajudam o usuário procurando por um pacote e podem atém parece suspeito. Em vez idsso, tente se ater aos fatos, mencionando casos de uso e recursos. Descriptions can include Texinfo markup, which is useful to introduce ornaments such as ‘@code’ or ‘@dfn’, bullet lists, or hyperlinks (*note (texinfo)Overview::). However you should be careful when using some characters for example ‘@’ and curly braces which are the basic special characters in Texinfo (*note (texinfo)Special Characters::). User interfaces such as ‘guix show’ take care of rendering it appropriately. Synopses and descriptions are translated by volunteers at Weblate (https://translate.fedoraproject.org/projects/guix/packages) so that as many users as possible can read them in their native language. User interfaces search them and display them in the language specified by the current locale. Para permitir que ‘xgettext’ extrai-as com strings traduzíveis, as sinopses e descrições _devem ser strings literais_. Isso significa que você não pode usar ‘string-append’ ou ‘format’ para construir essas strings: (package ;; ... (synopsis "Isso é traduzível") (description (string-append "Isso " "*não*" " é traduzível."))) Tradução é muito trabalhoso, então, como empacotador, por favor, tenha ainda mais atenção às suas sinopses e descrições, pois cada alteração pode implicar em trabalho adicional para tradutores. Para ajudá-loas, é possível tornar recomendações ou instruções visíveis inserindo comentários especiais como esse (*note (gettext)xgettext Invocation::): ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. (description "ARandR is designed to provide a simple visual front end for the X11 resize-and-rotate (RandR) extension. ...")  File: guix.pt_BR.info, Node: Snippets versus Phases, Next: Emacs Packages, Prev: Sinopses e descrições, Up: Diretrizes de empacotamento 22.4.5 Snippets versus Phases ----------------------------- The boundary between using an origin snippet versus a build phase to modify the sources of a package can be elusive. Origin snippets are typically used to remove unwanted files such as bundled libraries, nonfree sources, or to apply simple substitutions. The source derived from an origin should produce a source that can be used to build the package on any system that the upstream package supports (i.e., act as the corresponding source). In particular, origin snippets must not embed store items in the sources; such patching should rather be done using build phases. Refer to the ‘origin’ record documentation for more information (*note Referência do origin::).  File: guix.pt_BR.info, Node: Emacs Packages, Next: Módulos Python, Prev: Snippets versus Phases, Up: Diretrizes de empacotamento 22.4.6 Emacs Packages --------------------- Emacs packages should preferably use the Emacs build system (*note emacs-build-system::), for uniformity and the benefits provided by its build phases, such as the auto-generation of the autoloads file and the byte compilation of the sources. Because there is no standardized way to run a test suite for Emacs packages, tests are disabled by default. When a test suite is available, it should be enabled by setting the ‘#:tests?’ argument to ‘#true’. By default, the command to run the test is ‘make check’, but any command can be specified via the ‘#:test-command’ argument. The ‘#:test-command’ argument expects a list containing a command and its arguments, to be invoked during the ‘check’ phase. The Elisp dependencies of Emacs packages are typically provided as ‘propagated-inputs’ when required at run time. As for other packages, build or test dependencies should be specified as ‘native-inputs’. Emacs packages sometimes depend on resources directories that should be installed along the Elisp files. The ‘#:include’ argument can be used for that purpose, by specifying a list of regexps to match. The best practice when using the ‘#:include’ argument is to extend rather than override its default value (accessible via the ‘%default-include’ variable). As an example, a yasnippet extension package typically include a ‘snippets’ directory, which could be copied to the installation directory using: #:include (cons "^snippets/" %default-include) When encountering problems, it is wise to check for the presence of the ‘Package-Requires’ extension header in the package main source file, and whether any dependencies and their versions listed therein are satisfied.  File: guix.pt_BR.info, Node: Módulos Python, Next: Módulos Perl, Prev: Emacs Packages, Up: Diretrizes de empacotamento 22.4.7 Módulos Python --------------------- Atualmente empacotamos Python 2 e Python 3, sob os nomes de variável Scheme ‘python-2’ e ‘python’ conforme explicado em *note Números de versão::. Para evitar confusão e conflitos de nomes com outras linguagens de programação, parece desejável que o nome de um pacote para um módulo Python contenha a palavra ‘python’. Some modules are compatible with only one version of Python, others with both. If the package Foo is compiled with Python 3, we name it ‘python-foo’. If it is compiled with Python 2, we name it ‘python2-foo’. Packages should be added when they are necessary; we don’t add Python 2 variants of the package unless we are going to use them. Se um projeto já contém a palavra ‘python’, nós a descartamos; por exemplo, o módulo python-dateutil é empacotado sob os nomes ‘python-dateutil’ e ‘python2-dateutil’. Se o nome do projeto começa com ‘py’ (p.ex., ‘pytz’), nós o mantemos e o prefixamos conforme descrito acima. Nota: Currently there are two different build systems for Python packages in Guix: PYTHON-BUILD-SYSTEM and PYPROJECT-BUILD-SYSTEM. For the longest time, Python packages were built from an informally specified ‘setup.py’ file. That worked amazingly well, considering Python’s success, but was difficult to build tooling around. As a result, a host of alternative build systems emerged and the community eventually settled on a formal standard (https://peps.python.org/pep-0517/) for specifying build requirements. PYPROJECT-BUILD-SYSTEM is Guix’s implementation of this standard. It is considered “experimental” in that it does not yet support all the various PEP-517 _build backends_, but you are encouraged to try it for new Python packages and report any problems. It will eventually be deprecated and merged into PYTHON-BUILD-SYSTEM. 22.4.7.1 Especificando dependências ................................... Dependency information for Python packages is usually available in the package source tree, with varying degrees of accuracy: in the ‘pyproject.toml’ file, the ‘setup.py’ file, in ‘requirements.txt’, or in ‘tox.ini’ (the latter mostly for test dependencies). Sua missão, ao escrever uma receita para um pacote Python, é mapear essas dependências para o tipo apropriado de “entrada” (*note inputs: Referência do package.). Apesar do importador do ‘pypi’ normalmente fazer um bom trabalho (*note Invocando guix import::), você pode se interessar em verificar a lista de verificação a seguir para determinar qual dependência vai onde. • We currently package Python with ‘setuptools’ and ‘pip’ installed per default. This is about to change, and users are encouraged to use ‘python-toolchain’ if they want a build environment for Python. ‘guix lint’ will warn if ‘setuptools’ or ‘pip’ are added as native-inputs because they are generally not necessary. • Dependências de Python necessárias em tempo de execução vão em ‘propagated-inputs’. Elas geralmente são definidas com a palavra-chave ‘install_requires’ em ‘setup.py’ ou no arquivo ‘requirements.txt’. • Python packages required only at build time—e.g., those listed under ‘build-system.requires’ in ‘pyproject.toml’ or with the ‘setup_requires’ keyword in ‘setup.py’—or dependencies only for testing—e.g., those in ‘tests_require’ or ‘tox.ini’—go into ‘native-inputs’. The rationale is that (1) they do not need to be propagated because they are not needed at run time, and (2) in a cross-compilation context, it’s the “native” input that we’d want. Exemplos são os frameworks de teste ‘pytest’, ‘mock’ e ‘nose’. É claro, se qualquer um desses pacotes também for necessário em tempo de compilação, ele precisa ir para ‘propagated-inputs’. • Qualquer coisa que não encaixar nas categorias anteriores vai para ‘inputs’. Por exemplo, programas ou bibliotecas C necessárias para compilar pacotes Python contendo extensões C. • Se um pacote Python tem dependências opcionais (‘extras_require’), fica a seu critério adicioná-las ou não, com base na sua proporção de utilidade/sobrecarga (*note ‘guix size’: Enviando patches.).  File: guix.pt_BR.info, Node: Módulos Perl, Next: Pacotes Java, Prev: Módulos Python, Up: Diretrizes de empacotamento 22.4.8 Módulos Perl ------------------- Os programas Perl próprios são nomeados como qualquer outro pacote, usando o nome upstream em letras minúsculas. Para pacotes Perl que contêm uma única classe, usamos o nome da classe em letras minúsculas, substituímos todas as ocorrências de ‘::’ por traços e precede o prefixo ‘perl-’. Portanto, a classe ‘XML::Parser’ se torna ‘perl-xml-parser’. Módulos contendo várias classes mantêm seu nome upstream em minúsculas e também são precedidos por ‘perl-’. Esses módulos tendem a ter a palavra ‘perl’ em algum lugar do nome, que é descartada em favor do prefixo. Por exemplo, ‘libwww-perl’ se torna ‘perl-libwww’.  File: guix.pt_BR.info, Node: Pacotes Java, Next: Rust Crates, Prev: Módulos Perl, Up: Diretrizes de empacotamento 22.4.9 Pacotes Java ------------------- Os programas Java próprios são nomeados como qualquer outro pacote, usando o nome do upstream em letras minúsculas. Para evitar confusão e conflitos de nomes com outras linguagens de programação, é desejável que o nome de um pacote para um pacote Java seja prefixado com ‘java-’. Se um projeto já contém a palavra ‘java’, descartamos isso; por exemplo, o pacote ‘ngsjava’ é empacotado com o nome ‘java-ngs’. Para pacotes Java que contêm uma única classe ou uma pequena hierarquia de classes, usamos o nome da classe em letras minúsculas, substitua todas as ocorrências de ‘.’ por traços e acrescente o prefixo ‘java-’. Assim, a classe ‘apache.commons.cli’ se torna o pacote ‘java-apache-commons-cli’.  File: guix.pt_BR.info, Node: Rust Crates, Next: Elm Packages, Prev: Pacotes Java, Up: Diretrizes de empacotamento 22.4.10 Rust Crates ------------------- Rust programs standing for themselves are named as any other package, using the lowercase upstream name. To prevent namespace collisions we prefix all other Rust packages with the ‘rust-’ prefix. The name should be changed to lowercase as appropriate and dashes should remain in place. In the rust ecosystem it is common for multiple incompatible versions of a package to be used at any given time, so all package definitions should have a versioned suffix. The versioned suffix is the left-most non-zero digit (and any leading zeros, of course). This follows the “caret” version scheme intended by Cargo. Examples ‘rust-clap-2’, ‘rust-rand-0.6’. Because of the difficulty in reusing rust packages as pre-compiled inputs for other packages the Cargo build system (*note ‘cargo-build-system’: Sistemas de compilação.) presents the ‘#:cargo-inputs’ and ‘cargo-development-inputs’ keywords as build system arguments. It would be helpful to think of these as similar to ‘propagated-inputs’ and ‘native-inputs’. Rust ‘dependencies’ and ‘build-dependencies’ should go in ‘#:cargo-inputs’, and ‘dev-dependencies’ should go in ‘#:cargo-development-inputs’. If a Rust package links to other libraries then the standard placement in ‘inputs’ and the like should be used. Care should be taken to ensure the correct version of dependencies are used; to this end we try to refrain from skipping the tests or using ‘#:skip-build?’ when possible. Of course this is not always possible, as the package may be developed for a different Operating System, depend on features from the Nightly Rust compiler, or the test suite may have atrophied since it was released.  File: guix.pt_BR.info, Node: Elm Packages, Next: Fontes, Prev: Rust Crates, Up: Diretrizes de empacotamento 22.4.11 Elm Packages -------------------- Elm applications can be named like other software: their names need not mention Elm. Packages in the Elm sense (see ‘elm-build-system’ under *note Sistemas de compilação::) are required use names of the format AUTHOR‘/’PROJECT, where both the AUTHOR and the PROJECT may contain hyphens internally, and the AUTHOR sometimes contains uppercase letters. To form the Guix package name from the upstream name, we follow a convention similar to Python packages (*note Módulos Python::), adding an ‘elm-’ prefix unless the name would already begin with ‘elm-’. In many cases we can reconstruct an Elm package’s upstream name heuristically, but, since conversion to a Guix-style name involves a loss of information, this is not always possible. Care should be taken to add the ‘'upstream-name’ property when necessary so that ‘guix import elm’ will work correctly (*note Invocando guix import::). The most notable scenarios when explicitly specifying the upstream name is necessary are: 1. When the AUTHOR is ‘elm’ and the PROJECT contains one or more hyphens, as with ‘elm/virtual-dom’; and 2. When the AUTHOR contains hyphens or uppercase letters, as with ‘Elm-Canvas/raster-shapes’—unless the AUTHOR is ‘elm-explorations’, which is handled as a special case, so packages like ‘elm-explorations/markdown’ do _not_ need to use the ‘'upstream-name’ property. The module ‘(guix build-system elm)’ provides the following utilities for working with names and related conventions: -- Scheme procedure: elm-package-origin ELM-NAME VERSION HASH Returns a Git origin using the repository naming and tagging regime required for a published Elm package with the upstream name ELM-NAME at version VERSION with sha256 checksum HASH. For example: (package (name "elm-html") (version "1.0.0") (source (elm-package-origin "elm/html" version (base32 "15k1679ja57vvlpinpv06znmrxy09lbhzfkzdc89i01qa8c4gb4a"))) ...) -- Scheme procedure: elm->package-name ELM-NAME Returns the Guix-style package name for an Elm package with upstream name ELM-NAME. Note that there is more than one possible ELM-NAME for which ‘elm->package-name’ will produce a given result. -- Scheme procedure: guix-package->elm-name PACKAGE Given an Elm PACKAGE, returns the possibly-inferred upstream name, or ‘#f’ the upstream name is not specified via the ‘'upstream-name’ property and can not be inferred by ‘infer-elm-package-name’. -- Scheme procedure: infer-elm-package-name GUIX-NAME Given the GUIX-NAME of an Elm package, returns the inferred upstream name, or ‘#f’ if the upstream name can’t be inferred. If the result is not ‘#f’, supplying it to ‘elm->package-name’ would produce GUIX-NAME.  File: guix.pt_BR.info, Node: Fontes, Prev: Elm Packages, Up: Diretrizes de empacotamento 22.4.12 Fontes -------------- Para fontes que geralmente não são instaladas por um usuário para fins de digitação ou que são distribuídas como parte de um pacote de software maior, contamos com as regras gerais de empacotamento de software; por exemplo, isso se aplica às fontes entregues como parte do sistema X.Org ou às fontes que fazem parte do TeX Live. Para facilitar a busca de fontes por um usuário, os nomes de outros pacotes contendo apenas fontes são compilados da seguinte maneira, independentemente do nome do pacote upstream. O nome de um pacote que contém apenas uma família de fontes começa com ‘font-’; é seguido pelo nome da fundição e um traço ‘-’ se a fundição for conhecida e o nome da família da fonte, em que os espaços são substituídos por hífenes (e, como sempre, todas as letras maiúsculas são transformadas em minúsculas). Por exemplo, a família de fontes Gentium da SIL é empacotada com o nome ‘font-sil-gentium’. Para um pacote que contém várias famílias de fontes, o nome da coleção é usado no lugar do nome da família de fontes. Por exemplo, as fontes Liberation consistem em três famílias, Liberation Sans, Liberation Serif e Liberation Mono. Eles podem ser empacotados separadamente com os nomes ‘font-liberation-sans’ e assim por diante; mas como eles são distribuídos juntos com um nome comum, preferimos agrupá-los como ‘font-liberation’. No caso de vários formatos da mesma família ou coleção de fontes serem empacotados separadamente, um formato abreviado do formato, precedido por um traço, é adicionado ao nome do pacote. Usamos ‘-ttf’ para fontes TrueType, ‘-otf’ para fontes OpenType e ‘-type1’ para fontes PostScript Type 1.  File: guix.pt_BR.info, Node: Estilo de código, Next: Enviando patches, Prev: Diretrizes de empacotamento, Up: Contribuindo 22.5 Estilo de código ===================== Em geral, nosso código segue os Padrões de Codificação GNU (*note (standards)Top::). No entanto, eles não dizem muito sobre Scheme, então aqui estão algumas regras adicionais. * Menu: * Paradigma de programação:: Como compor seus elementos. * Módulos:: Onde armazenar seu código? * Tipos de dados e correspondência de padrão:: Implementação de estruturas de dados. * Formatação de código:: Convenções de escrita.  File: guix.pt_BR.info, Node: Paradigma de programação, Next: Módulos, Up: Estilo de código 22.5.1 Paradigma de programação ------------------------------- O código Scheme no Guix é escrito em um estilo puramente funcional. Uma exceção é o código que envolve entrada/saída e procedimentos que implementam conceitos de baixo nível, como o procedimento ‘memoize’.  File: guix.pt_BR.info, Node: Módulos, Next: Tipos de dados e correspondência de padrão, Prev: Paradigma de programação, Up: Estilo de código 22.5.2 Módulos -------------- Os módulos de Guile que devem ser usados no lado do compilador devem residir no espaço de nomes ‘(guix build ...)’. Eles não devem fazer referência a outros módulos Guix ou GNU. No entanto, é aceitável que um módulo no lado do “hospedeiro” use um módulo do lado do compilador. Módulos que lidam com o sistema GNU mais amplo devem estar no espaço de nome ‘(gnu ...)’ em vez de ‘(guix ...)’.  File: guix.pt_BR.info, Node: Tipos de dados e correspondência de padrão, Next: Formatação de código, Prev: Módulos, Up: Estilo de código 22.5.3 Tipos de dados e correspondência de padrão ------------------------------------------------- A tendência no Lisp clássico é usar listas para representar tudo e, em seguida, pesquisá-las “à mão” usando ‘car’, ‘cdr’, ‘cadr’ e co. Existem vários problemas com esse estilo, notadamente o fato de que é difícil de ler, propenso a erros e um obstáculo para os relatórios de erros de tipos adequados. Guix code should define appropriate data types (for instance, using ‘define-record-type*’) rather than abuse lists. In addition, it should use pattern matching, via Guile’s ‘(ice-9 match)’ module, especially when matching lists (*note (guile)Pattern Matching::); pattern matching for records is better done using ‘match-record’ from ‘(guix records)’, which, unlike ‘match’, verifies field names at macro-expansion time.  File: guix.pt_BR.info, Node: Formatação de código, Prev: Tipos de dados e correspondência de padrão, Up: Estilo de código 22.5.4 Formatação de código --------------------------- When writing Scheme code, we follow common wisdom among Scheme programmers. In general, we follow the Riastradh’s Lisp Style Rules (https://mumble.net/~campbell/scheme/style.txt). This document happens to describe the conventions mostly used in Guile’s code too. It is very thoughtful and well written, so please do read it. Alguns formulários especiais introduzidos no Guix, como a macro ‘substitute*’, possuem regras especiais de recuo. Estes são definidos no arquivo ‘.dir-locals.el’, que o Emacs usa automaticamente. Observe também que o Emacs-Guix fornece o modo ‘guix-devel-mode’ que recua e destaca o código Guix corretamente (*note (emacs-guix)Development::). Se você não usa o Emacs, por favor, certifique-se que o seu editor conhece estas regras. Para recuar automaticamente uma definição de pacote, você também pode executar: ./pre-inst-env guix style PACKAGE *Note Invoking guix style::, for more information. Se você estiver editando código com o Vim, recomendamos que execute ‘:set autoindent’ para que seu código seja automaticamente recuado na medida em que você digita. Além disso, o ‘paredit.vim’ (https://www.vim.org/scripts/script.php?script_id=3998) pode ajudá-lo a lidar com todos esses parênteses. Nós exigimos que todos os procedimentos de nível superior carreguem uma docstring. Porém, este requisito pode ser relaxado para procedimentos privados simples no espaço de nomes ‘(guix build ...)’. Os procedimentos não devem ter mais de quatro parâmetros posicionais. Use os parâmetros de palavra-chave para procedimentos que levam mais de quatro parâmetros.  File: guix.pt_BR.info, Node: Enviando patches, Next: Tracking Bugs and Patches, Prev: Estilo de código, Up: Contribuindo 22.6 Enviando patches ===================== Development is done using the Git distributed version control system. Thus, access to the repository is not strictly necessary. We welcome contributions in the form of patches as produced by ‘git format-patch’ sent to the mailing list (*note (git)Submitting patches to a project::). Contributors are encouraged to take a moment to set some Git repository options (*note Configurando o Git::) first, which can improve the readability of patches. Seasoned Guix developers may also want to look at the section on commit access (*note Commit Access::). This mailing list is backed by a Debbugs instance, which allows us to keep track of submissions (*note Tracking Bugs and Patches::). Each message sent to that mailing list gets a new tracking number assigned; people can then follow up on the submission by sending email to ‘ISSUE_NUMBER@debbugs.gnu.org’, where ISSUE_NUMBER is the tracking number (*note Enviando uma série de patches::). Por favor, escreva os logs de commit no formato de ChangeLog (*note (standards)Change Logs::); você pode verificar o histórico de commit para exemplos. Antes de enviar um patch que adicione ou modifique uma definição de pacote, execute esta lista de verificação: 1. Se os autores do software empacotado fornecerem uma assinatura criptográfica para o tarball de lançamento, faça um esforço para verificar a autenticidade do arquivo. Para um arquivo de assinatura GPG separado, isso seria feito com o comando ‘gpg --verify’. 2. Reserve algum tempo para fornecer uma sinopse e descrição adequadas para o pacote. *Note Sinopses e descrições::, para algumas diretrizes. 3. Execute ‘guix lint PACOTE’, sendo PACOTE o nome do pacote novo ou modificado e corrija quaisquer erros que forem relatados (*note Invocando guix lint::). 4. Run ‘guix style PACKAGE’ to format the new package definition according to the project’s conventions (*note Invoking guix style::). 5. Certifique-se de que o pacote compila em sua plataforma, usando ‘guix build PACOTE’. 6. We recommend you also try building the package on other supported platforms. As you may not have access to actual hardware platforms, we recommend using the ‘qemu-binfmt-service-type’ to emulate them. In order to enable it, add the ‘virtualization’ service module and the following service to the list of services in your ‘operating-system’ configuration: (service qemu-binfmt-service-type (qemu-binfmt-configuration (platforms (lookup-qemu-platforms "arm" "aarch64")))) Então, reconfigure seu sistema. You can then build packages for different platforms by specifying the ‘--system’ option. For example, to build the "hello" package for the armhf or aarch64 architectures, you would run the following commands, respectively: guix build --system=armhf-linux --rounds=2 hello guix build --system=aarch64-linux --rounds=2 hello 7. Verifique se o pacote não usa cópias de software já disponíveis como pacotes separados. Às vezes, os pacotes incluem cópias do código-fonte de suas dependências como uma conveniência para os usuários. No entanto, como uma distribuição, queremos garantir que esses pacotes acabem usando a cópia que já temos na distribuição, se houver. Isso melhora o uso de recursos (a dependência é criada e armazenada apenas uma vez) e permite que a distribuição faça alterações transversais, como aplicar atualizações de segurança para um determinado pacote de software em um único local e fazê-las afetar todo o sistema – algo que cópias incluídas impedem. 8. Take a look at the profile reported by ‘guix size’ (*note Invocando guix size::). This will allow you to notice references to other packages unwillingly retained. It may also help determine whether to split the package (*note Pacotes com múltiplas saídas::), and which optional dependencies should be used. In particular, avoid adding ‘texlive’ as a dependency: because of its extreme size, use the ‘texlive-tiny’ package or ‘texlive-union’ procedure instead. 9. For important changes, check that dependent packages (if applicable) are not affected by the change; ‘guix refresh --list-dependent PACKAGE’ will help you do that (*note Invocando guix refresh::). Dependendo do número de pacotes dependentes e, portanto, da quantidade de recompilação induzida, os commits vão para diferentes ramos, ao longo das seguintes linhas: 300 pacotes dependentes ou menos Ramo ‘master’ (alterações não disruptivas). between 300 and 1,800 dependent packages ‘staging’ branch (non-disruptive changes). This branch is intended to be merged in ‘master’ every 6 weeks or so. Topical changes (e.g., an update of the GNOME stack) can instead go to a specific branch (say, ‘gnome-updates’). This branch is not expected to be buildable or usable until late in its development process. more than 1,800 dependent packages ‘core-updates’ branch (may include major and potentially disruptive changes). This branch is intended to be merged in ‘master’ every 6 months or so. This branch is not expected to be buildable or usable until late in its development process. All these branches are tracked by our build farm (https://ci.guix.gnu.org) and merged into ‘master’ once everything has been successfully built. This allows us to fix issues before they hit users, and to reduce the window during which pre-built binaries are not available. When we decide to start building the ‘staging’ or ‘core-updates’ branches, they will be forked and renamed with the suffix ‘-frozen’, at which time only bug fixes may be pushed to the frozen branches. The ‘core-updates’ and ‘staging’ branches will remain open to accept patches for the next cycle. Please ask on the mailing list or IRC if unsure where to place a patch. 10. Verifique se o processo de compilação do pacote é determinístico. Isso normalmente significa verificar se uma compilação independente do pacote produz o mesmo resultado que você obteve, bit por bit. Uma maneira simples de fazer isso é compilar o mesmo pacote várias vezes seguidas em sua máquina (*note Invocando guix build::): guix build --rounds=2 meu-pacote Isso é suficiente para capturar uma classe de problemas comuns de não-determinismo, como registros de data e hora ou saída gerada aleatoriamente no resultado da compilação. Another option is to use ‘guix challenge’ (*note Invocando guix challenge::). You may run it once the package has been committed and built by ‘ci.guix.gnu.org’ to check whether it obtains the same result as you did. Better yet: Find another machine that can build it and run ‘guix publish’. Since the remote build machine is likely different from yours, this can catch non-determinism issues related to the hardware—e.g., use of different instruction set extensions—or to the operating system kernel—e.g., reliance on ‘uname’ or ‘/proc’ files. 11. Ao escrever documentação, por favor, use palavras de gênero neutras ao se referir a pessoas, como singular “they”, “their” , “them” (https://en.wikipedia.org/wiki/Singular_they), e assim por diante. 12. Verifique se o seu patch contém apenas um conjunto de alterações relacionadas. Agrupar mudanças não relacionadas juntas torna a revisão mais difícil e lenta. Exemplos de alterações não relacionadas incluem a adição de vários pacotes ou uma atualização de pacote juntamente com correções para esse pacote. 13. Please follow our code formatting rules, possibly running ‘guix style’ script to do that automatically for you (*note Formatação de código::). 14. Quando possível, use espelhos no URL fonte (*note Invocando guix download::). Use URLs confiáveis, não os gerados. Por exemplo, os arquivos do GitHub não são necessariamente idênticos de uma geração para a seguinte, portanto, nesse caso, geralmente é melhor clonar o repositório. Não use o campo ‘name’ no URL: não é muito útil e se o nome mudar, o URL provavelmente estará errado. 15. Check if Guix builds (*note Compilando do git::) and address the warnings, especially those about use of undefined symbols. 16. Make sure your changes do not break Guix and simulate a ‘guix pull’ with: guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master When posting a patch to the mailing list, use ‘[PATCH] ...’ as a subject, if your patch is to be applied on a branch other than ‘master’, say ‘core-updates’, specify it in the subject like ‘[PATCH core-updates] ...’. You may use your email client or the ‘git send-email’ command (*note Enviando uma série de patches::). We prefer to get patches in plain text messages, either inline or as MIME attachments. You are advised to pay attention if your email client changes anything like line breaks or indentation which could potentially break the patches. Expect some delay when you submit your very first patch to . You have to wait until you get an acknowledgement with the assigned tracking number. Future acknowledgements should not be delayed. When a bug is resolved, please close the thread by sending an email to . * Menu: * Configurando o Git:: * Enviando uma série de patches:: * Teams::  File: guix.pt_BR.info, Node: Configurando o Git, Next: Enviando uma série de patches, Up: Enviando patches 22.6.1 Configurando o Git ------------------------- If you have not done so already, you may wish to set a name and email that will be associated with your commits (*note Telling Git your name: (git)telling git your name.). If you wish to use a different name or email just for commits in this repository, you can use ‘git config --local’, or edit ‘.git/config’ in the repository instead of ‘~/.gitconfig’. We provide some default settings in ‘etc/git/gitconfig’ which modify how patches are generated, making them easier to read and apply. These settings can be applied by manually copying them to ‘.git/config’ in your checkout, or by telling Git to include the whole file: git config --local include.path ../etc/git/gitconfig From then on, any changes to ‘etc/git/gitconfig’ would automatically take effect. Since the first patch in a series must be sent separately (*note Enviando uma série de patches::), it can also be helpful to tell ‘git format-patch’ to handle the e-mail threading instead of ‘git send-email’: git config --local format.thread shallow git config --local sendemail.thread no  File: guix.pt_BR.info, Node: Enviando uma série de patches, Next: Teams, Prev: Configurando o Git, Up: Enviando patches 22.6.2 Enviando uma série de patches ------------------------------------ Single Patches .............. The ‘git send-email’ command is the best way to send both single patches and patch series (*note Multiple Patches::) to the Guix mailing list. Sending patches as email attachments may make them difficult to review in some mail clients, and ‘git diff’ does not store commit metadata. Nota: The ‘git send-email’ command is provided by the ‘send-email’ output of the ‘git’ package, i.e. ‘git:send-email’. The following command will create a patch email from the latest commit, open it in your EDITOR or VISUAL for editing, and send it to the Guix mailing list to be reviewed and merged: $ git send-email -1 -a --base=auto --to=guix-patches@gnu.org Tip: To add a prefix to the subject of your patch, you may use the ‘--subject-prefix’ option. The Guix project uses this to specify that the patch is intended for a branch or repository other than the ‘master’ branch of . git send-email -1 -a --base=auto \ --subject-prefix='PATCH core-updates' \ --to=guix-patches@gnu.org The patch email contains a three-dash separator line after the commit message. You may “annotate” the patch with explanatory text by adding it under this line. If you do not wish to annotate the email, you may drop the ‘-a’ flag (which is short for ‘--annotate’). The ‘--base=auto’ flag automatically adds a note at the bottom of the patch of the commit it was based on, making it easier for maintainers to rebase and merge your patch. If you need to send a revised patch, don’t resend it like this or send a “fix” patch to be applied on top of the last one; instead, use ‘git commit -a’ or ‘git rebase’ (https://git-rebase.io) to modify the commit, and use the address and the ‘-v’ flag with ‘git send-email’. $ git commit -a $ git send-email -1 -a --base=auto -v REVISION \ --to=ISSUE_NUMBER@debbugs.gnu.org You can find out ISSUE_NUMBER either by searching on the mumi interface at for the name of your patch or reading the acknowledgement email sent automatically by Debbugs in reply to incoming bugs and patches, which contains the bug number. Notifying Teams ............... The ‘etc/teams.scm’ script may be used to notify all those who may be interested in your patch of its existence (*note Teams::). Use ‘etc/teams.scm list-teams’ to display all the teams, decide which team(s) your patch relates to, and use ‘etc/teams.scm cc’ to output various ‘git send-email’ flags which will notify the appropriate team members, or use ‘etc/teams.scm cc-members’ to detect the appropriate teams automatically. Multiple Patches ................ While ‘git send-email’ alone will suffice for a single patch, an unfortunate flaw in Debbugs means you need to be more careful when sending multiple patches: if you send them all to the address, a new issue will be created for each patch! When sending a series of patches, it’s best to send a Git “cover letter” first, to give reviewers an overview of the patch series. We can create a directory called ‘outgoing’ containing both our patch series and a cover letter called ‘0000-cover-letter.patch’ with ‘git format-patch’. $ git format-patch -NUMBER_COMMITS -o outgoing \ --cover-letter --base=auto We can now send _just_ the cover letter to the address, which will create an issue that we can send the rest of the patches to. $ git send-email outgoing/0000-cover-letter.patch -a \ --to=guix-patches@debbugs.gnu.org \ $(etc/teams.scm cc-members ...) $ rm outgoing/0000-cover-letter.patch # we don't want to resend it! Ensure you edit the email to add an appropriate subject line and blurb before sending it. Note the automatically generated shortlog and diffstat below the blurb. Once the Debbugs mailer has replied to your cover letter email, you can send the actual patches to the newly-created issue address. $ git send-email outgoing/*.patch \ --to=ISSUE_NUMBER@debbugs.gnu.org \ $(etc/teams.scm cc-members ...) $ rm -rf outgoing # we don't need these anymore Thankfully, this ‘git format-patch’ dance is not necessary to send an amended patch series, since an issue already exists for the patchset. $ git send-email -NUMBER_COMMITS \ -vREVISION --base=auto \ --to ISSUE_NUMBER@debbugs.gnu.org If need be, you may use ‘--cover-letter -a’ to send another cover letter, e.g. for explaining what’s changed since the last revision, and these changes are necessary.  File: guix.pt_BR.info, Node: Teams, Prev: Enviando uma série de patches, Up: Enviando patches 22.6.3 Teams ------------ There are several teams mentoring different parts of the Guix source code. To list all those teams, you can run from a Guix checkout: $ ./etc/teams.scm list-teams id: mentors name: Mentors description: A group of mentors who chaperone contributions by newcomers. members: + Christopher Baines + Ricardo Wurmus + Mathieu Othacehe + jgart + Ludovic Courtès ... You can run the following command to have the ‘Mentors’ team put in CC of a patch series: $ git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch The appropriate team or teams can also be inferred from the modified files. For instance, if you want to send the two latest commits of the current Git repository to review, you can run: $ guix shell -D guix [env]$ git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc-members HEAD~2 HEAD) *.patch  File: guix.pt_BR.info, Node: Tracking Bugs and Patches, Next: Commit Access, Prev: Enviando patches, Up: Contribuindo 22.7 Tracking Bugs and Patches ============================== This section describes how the Guix project tracks its bug reports and patch submissions. * Menu: * The Issue Tracker:: The official bug and patch tracker. * Debbugs User Interfaces:: Ways to interact with Debbugs. * Debbugs Usertags:: Tag reports with custom labels.  File: guix.pt_BR.info, Node: The Issue Tracker, Next: Debbugs User Interfaces, Up: Tracking Bugs and Patches 22.7.1 The Issue Tracker ------------------------ Bug reports and patch submissions are currently tracked using the Debbugs instance at . Bug reports are filed against the ‘guix’ “package” (in Debbugs parlance), by sending email to , while patch submissions are filed against the ‘guix-patches’ package by sending email to (*note Enviando patches::).  File: guix.pt_BR.info, Node: Debbugs User Interfaces, Next: Debbugs Usertags, Prev: The Issue Tracker, Up: Tracking Bugs and Patches 22.7.2 Debbugs User Interfaces ------------------------------ A web interface (actually _two_ web interfaces!) are available to browse issues: • provides a pleasant interface(1) to browse bug reports and patches, and to participate in discussions; • lists bug reports; • lists patch submissions. To view discussions related to issue number N, go to ‘https://issues.guix.gnu.org/N’ or ‘https://bugs.gnu.org/N’. If you use Emacs, you may find it more convenient to interact with issues using ‘debbugs.el’, which you can install with: guix install emacs-debbugs For example, to list all open issues on ‘guix-patches’, hit: C-u M-x debbugs-gnu RET RET guix-patches RET n y *Note (debbugs-ug)Top::, for more information on this nifty tool! ---------- Footnotes ---------- (1) The web interface at is powered by Mumi, a nice piece of software written in Guile, and you can help! See .  File: guix.pt_BR.info, Node: Debbugs Usertags, Prev: Debbugs User Interfaces, Up: Tracking Bugs and Patches 22.7.3 Debbugs Usertags ----------------------- Debbugs provides a feature called “usertags” that allows any user to tag any bug with an arbitrary label. Bugs can be searched by usertag, so this is a handy way to organize bugs(1). For example, to view all the bug reports (or patches, in the case of ‘guix-patches’) tagged with the usertag ‘powerpc64le-linux’ for the user ‘guix’, open a URL like the following in a web browser: . For more information on how to use usertags, please refer to the documentation for Debbugs or the documentation for whatever tool you use to interact with Debbugs. In Guix, we are experimenting with usertags to keep track of architecture-specific issues. To facilitate collaboration, all our usertags are associated with the single user ‘guix’. The following usertags currently exist for that user: ‘powerpc64le-linux’ The purpose of this usertag is to make it easy to find the issues that matter most for the ‘powerpc64le-linux’ system type. Please assign this usertag to bugs or patches that affect ‘powerpc64le-linux’ but not other system types. In addition, you may use it to identify issues that for some reason are particularly important for the ‘powerpc64le-linux’ system type, even if the issue affects other system types, too. ‘reproducibility’ For issues related to reproducibility. For example, it would be appropriate to assign this usertag to a bug report for a package that fails to build reproducibly. If you’re a committer and you want to add a usertag, just start using it with the ‘guix’ user. If the usertag proves useful to you, consider updating this section of the manual so that others will know what your usertag means. ---------- Footnotes ---------- (1) The list of usertags is public information, and anyone can modify any user’s list of usertags, so keep that in mind if you choose to use this feature.  File: guix.pt_BR.info, Node: Commit Access, Next: Updating the Guix Package, Prev: Tracking Bugs and Patches, Up: Contribuindo 22.8 Commit Access ================== Everyone can contribute to Guix without having commit access (*note Enviando patches::). However, for frequent contributors, having write access to the repository can be convenient. As a rule of thumb, a contributor should have accumulated fifty (50) reviewed commits to be considered as a committer and have sustained their activity in the project for at least 6 months. This ensures enough interactions with the contributor, which is essential for mentoring and assessing whether they are ready to become a committer. Commit access should not be thought of as a “badge of honor” but rather as a responsibility a contributor is willing to take to help the project. The following sections explain how to get commit access, how to be ready to push commits, and the policies and community expectations for commits pushed upstream. 22.8.1 Applying for Commit Access --------------------------------- When you deem it necessary, consider applying for commit access by following these steps: 1. Find three committers who would vouch for you. You can view the list of committers at . Each of them should email a statement to (a private alias for the collective of maintainers), signed with their OpenPGP key. Committers are expected to have had some interactions with you as a contributor and to be able to judge whether you are sufficiently familiar with the project’s practices. It is _not_ a judgment on the value of your work, so a refusal should rather be interpreted as “let’s try again later”. 2. Send a message stating your intent, listing the three committers who support your application, signed with the OpenPGP key you will use to sign commits, and giving its fingerprint (see below). See , for an introduction to public-key cryptography with GnuPG. Set up GnuPG such that it never uses the SHA1 hash algorithm for digital signatures, which is known to be unsafe since 2019, for instance by adding the following line to ‘~/.gnupg/gpg.conf’ (*note (gnupg)GPG Esoteric Options::): digest-algo sha512 3. Maintainers ultimately decide whether to grant you commit access, usually following your referrals’ recommendation. 4. If and once you’ve been given access, please send a message to to say so, again signed with the OpenPGP key you will use to sign commits (do that before pushing your first commit). That way, everyone can notice and ensure you control that OpenPGP key. Importante: Before you can push for the first time, maintainers must: 1. add your OpenPGP key to the ‘keyring’ branch; 2. add your OpenPGP fingerprint to the ‘.guix-authorizations’ file of the branch(es) you will commit to. 5. Make sure to read the rest of this section and... profit! Nota: Maintainers are happy to give commit access to people who have been contributing for some time and have a track record—don’t be shy and don’t underestimate your work! However, note that the project is working towards a more automated patch review and merging system, which, as a consequence, may lead us to have fewer people with commit access to the main repository. Stay tuned! All commits that are pushed to the central repository on Savannah must be signed with an OpenPGP key, and the public key should be uploaded to your user account on Savannah and to public key servers, such as ‘keys.openpgp.org’. To configure Git to automatically sign commits, run: git config commit.gpgsign true # Substitute the fingerprint of your public PGP key. git config user.signingkey CABBA6EA1DC0FF33 To check that commits are signed with correct key, use: make authenticate You can prevent yourself from accidentally pushing unsigned or signed with the wrong key commits to Savannah by using the pre-push Git hook located at ‘etc/git/pre-push’: cp etc/git/pre-push .git/hooks/pre-push It additionally calls ‘make check-channel-news’ to be sure ‘news.scm’ file is correct. 22.8.2 Commit Policy -------------------- If you get commit access, please make sure to follow the policy below (discussions of the policy can take place on ). Non-trivial patches should always be posted to (trivial patches include fixing typos, etc.). This mailing list fills the patch-tracking database (*note Tracking Bugs and Patches::). For patches that just add a new package, and a simple one, it’s OK to commit, if you’re confident (which means you successfully built it in a chroot setup, and have done a reasonable copyright and license auditing). Likewise for package upgrades, except upgrades that trigger a lot of rebuilds (for example, upgrading GnuTLS or GLib). We have a mailing list for commit notifications (), so people can notice. Before pushing your changes, make sure to run ‘git pull --rebase’. When pushing a commit on behalf of somebody else, please add a ‘Signed-off-by’ line at the end of the commit log message—e.g., with ‘git am --signoff’. This improves tracking of who did what. When adding channel news entries (*note Writing Channel News: Canais.), make sure they are well-formed by running the following command right before pushing: make check-channel-news For anything else, please post to and leave time for a review, without committing anything (*note Enviando patches::). If you didn’t receive any reply after two weeks, and if you’re confident, it’s OK to commit. That last part is subject to being adjusted, allowing individuals to commit directly on non-controversial changes on parts they’re familiar with. 22.8.3 Addressing Issues ------------------------ Peer review (*note Enviando patches::) and tools such as ‘guix lint’ (*note Invocando guix lint::) and the test suite (*note Executando a suíte de testes::) should catch issues before they are pushed. Yet, commits that “break” functionality might occasionally go through. When that happens, there are two priorities: mitigating the impact, and understanding what happened to reduce the chance of similar incidents in the future. The responsibility for both these things primarily lies with those involved, but like everything this is a group effort. Some issues can directly affect all users—for instance because they make ‘guix pull’ fail or break core functionality, because they break major packages (at build time or run time), or because they introduce known security vulnerabilities. The people involved in authoring, reviewing, and pushing such commit(s) should be at the forefront to mitigate their impact in a timely fashion: by pushing a followup commit to fix it (if possible), or by reverting it to leave time to come up with a proper fix, and by communicating with other developers about the problem. If these persons are unavailable to address the issue in time, other committers are entitled to revert the commit(s), explaining in the commit log and on the mailing list what the problem was, with the goal of leaving time to the original committer, reviewer(s), and author(s) to propose a way forward. Once the problem has been dealt with, it is the responsibility of those involved to make sure the situation is understood. If you are working to understand what happened, focus on gathering information and avoid assigning any blame. Do ask those involved to describe what happened, do not ask them to explain the situation—this would implicitly blame them, which is unhelpful. Accountability comes from a consensus about the problem, learning from it and improving processes so that it’s less likely to reoccur. 22.8.4 Commit Revocation ------------------------ In order to reduce the possibility of mistakes, committers will have their Savannah account removed from the Guix Savannah project and their key removed from ‘.guix-authorizations’ after 12 months of inactivity; they can ask to regain commit access by emailing the maintainers, without going through the vouching process. Maintainers(1) may also revoke an individual’s commit rights, as a last resort, if cooperation with the rest of the community has caused too much friction—even within the bounds of the project’s code of conduct (*note Contribuindo::). They would only do so after public or private discussion with the individual and a clear notice. Examples of behavior that hinders cooperation and could lead to such a decision include: • repeated violation of the commit policy stated above; • repeated failure to take peer criticism into account; • breaching trust through a series of grave incidents. When maintainers resort to such a decision, they notify developers on ; inquiries may be sent to . Depending on the situation, the individual may still be welcome to contribute. 22.8.5 Helping Out ------------------ One last thing: the project keeps moving forward because committers not only push their own awesome changes, but also offer some of their time _reviewing_ and pushing other people’s changes. As a committer, you’re welcome to use your expertise and commit rights to help other contributors, too! ---------- Footnotes ---------- (1) See for the current list of maintainers. You can email them privately at .  File: guix.pt_BR.info, Node: Updating the Guix Package, Next: Writing Documentation, Prev: Commit Access, Up: Contribuindo 22.9 Updating the Guix Package ============================== It is sometimes desirable to update the ‘guix’ package itself (the package defined in ‘(gnu packages package-management)’), for example to make new daemon features available for use by the ‘guix-service-type’ service type. In order to simplify this task, the following command can be used: make update-guix-package The ‘update-guix-package’ make target will use the last known _commit_ corresponding to ‘HEAD’ in your Guix checkout, compute the hash of the Guix sources corresponding to that commit and update the ‘commit’, ‘revision’ and hash of the ‘guix’ package definition. To validate that the updated ‘guix’ package hashes are correct and that it can be built successfully, the following command can be run from the directory of your Guix checkout: ./pre-inst-env guix build guix To guard against accidentally updating the ‘guix’ package to a commit that others can’t refer to, a check is made that the commit used has already been pushed to the Savannah-hosted Guix git repository. This check can be disabled, _at your own peril_, by setting the ‘GUIX_ALLOW_ME_TO_USE_PRIVATE_COMMIT’ environment variable. When this variable is set, the updated package source is also added to the store. This is used as part of the release process of Guix.  File: guix.pt_BR.info, Node: Writing Documentation, Next: Traduzindo o Guix, Prev: Updating the Guix Package, Up: Contribuindo 22.10 Writing Documentation =========================== Guix is documented using the Texinfo system. If you are not yet familiar with it, we accept contributions for documentation in most formats. That includes plain text, Markdown, Org, etc. Documentation contributions can be sent to . Prepend ‘[DOCUMENTATION]’ to the subject. When you need to make more than a simple addition to the documentation, we prefer that you send a proper patch as opposed to sending an email as described above. *Note Enviando patches:: for more information on how to send your patches. To modify the documentation, you need to edit ‘doc/guix.texi’ and ‘doc/contributing.texi’ (which contains this documentation section), or ‘doc/guix-cookbook.texi’ for the cookbook. If you compiled the Guix repository before, you will have many more ‘.texi’ files that are translations of these documents. Do not modify them, the translation is managed through Weblate (https://translate.fedoraproject.org/projects/guix). *Note Traduzindo o Guix:: for more information. To render documentation, you must first make sure that you ran ‘./configure’ in your source tree (*note Executando guix antes dele ser instalado::). After that you can run one of the following commands: • ‘make doc/guix.info’ to compile the Info manual. You can check it with ‘info doc/guix.info’. • ‘make doc/guix.html’ to compile the HTML version. You can point your browser to the relevant file in the ‘doc/guix.html’ directory. • ‘make doc/guix-cookbook.info’ for the cookbook Info manual. • ‘make doc/guix-cookbook.html’ for the cookbook HTML version.  File: guix.pt_BR.info, Node: Traduzindo o Guix, Prev: Writing Documentation, Up: Contribuindo 22.11 Traduzindo o Guix ======================= Writing code and packages is not the only way to provide a meaningful contribution to Guix. Translating to a language you speak is another example of a valuable contribution you can make. This section is designed to describe the translation process. It gives you advice on how you can get involved, what can be translated, what mistakes you should avoid and what we can do to help you! Guix is a big project that has multiple components that can be translated. We coordinate the translation effort on a Weblate instance (https://translate.fedoraproject.org/projects/guix/) hosted by our friends at Fedora. You will need an account to submit translations. Some of the software packaged in Guix also contain translations. We do not host a translation platform for them. If you want to translate a package provided by Guix, you should contact their developers or find the information on their website. As an example, you can find the homepage of the ‘hello’ package by typing ‘guix show hello’. On the “homepage” line, you will see as the homepage. Many GNU and non-GNU packages can be translated on the Translation Project (https://translationproject.org). Some projects with multiple components have their own platform. For instance, GNOME has its own platform, Damned Lies (https://l10n.gnome.org/). Guix has five components hosted on Weblate. • ‘guix’ contains all the strings from the Guix software (the guided system installer, the package manager, etc), excluding packages. • ‘packages’ contains the synopsis (single-sentence description of a package) and description (longer description) of packages in Guix. • ‘website’ contains the official Guix website, except for blog posts and multimedia content. • ‘documentation-manual’ corresponds to this manual. • ‘documentation-cookbook’ is the component for the cookbook. General Directions .................. Once you get an account, you should be able to select a component from the guix project (https://translate.fedoraproject.org/projects/guix/), and select a language. If your language does not appear in the list, go to the bottom and click on the “Start new translation” button. Select the language you want to translate to from the list, to start your new translation. Like lots of other free software packages, Guix uses GNU Gettext (https://www.gnu.org/software/gettext) for its translations, with which translatable strings are extracted from the source code to so-called PO files. Even though PO files are text files, changes should not be made with a text editor but with PO editing software. Weblate integrates PO editing functionality. Alternatively, translators can use any of various free-software tools for filling in translations, of which Poedit (https://poedit.net/) is one example, and (after logging in) upload (https://docs.weblate.org/en/latest/user/files.html) the changed file. There is also a special PO editing mode (https://www.emacswiki.org/emacs/PoMode) for users of GNU Emacs. Over time translators find out what software they are happy with and what features they need. On Weblate, you will find various links to the editor, that will show various subsets (or all) of the strings. Have a look around and at the documentation (https://docs.weblate.org/en/latest/) to familiarize yourself with the platform. Translation Components ...................... In this section, we provide more detailed guidance on the translation process, as well as details on what you should or should not do. When in doubt, please contact us, we will be happy to help! guix Guix is written in the Guile programming language, and some strings contain special formatting that is interpreted by Guile. These special formatting should be highlighted by Weblate. They start with ‘~’ followed by one or more characters. When printing the string, Guile replaces the special formatting symbols with actual values. For instance, the string ‘ambiguous package specification `~a'’ would be substituted to contain said package specification instead of ‘~a’. To properly translate this string, you must keep the formatting code in your translation, although you can place it where it makes sense in your language. For instance, the French translation says ‘spécification du paquet « ~a » ambiguë’ because the adjective needs to be placed in the end of the sentence. If there are multiple formatting symbols, make sure to respect the order. Guile does not know in which order you intended the string to be read, so it will substitute the symbols in the same order as the English sentence. As an example, you cannot translate ‘package '~a' has been superseded by '~a'’ by ‘'~a' superseeds package '~a'’, because the meaning would be reversed. If FOO is superseded by BAR, the translation would read ‘'foo' superseeds package 'bar'’. To work around this problem, it is possible to use more advanced formatting to select a given piece of data, instead of following the default English order. *Note (guile)Formatted Output::, for more information on formatting in Guile. pacotes Package descriptions occasionally contain Texinfo markup (*note Sinopses e descrições::). Texinfo markup looks like ‘@code{rm -rf}’, ‘@emph{important}’, etc. When translating, please leave markup as is. The characters after “@” form the name of the markup, and the text between “{” and “}” is its content. In general, you should not translate the content of markup like ‘@code’, as it contains literal code that do not change with language. You can translate the content of formatting markup such as ‘@emph’, ‘@i’, ‘@itemize’, ‘@item’. However, do not translate the name of the markup, or it will not be recognized. Do not translate the word after ‘@end’, it is the name of the markup that is closed at this position (e.g. ‘@itemize ... @end itemize’). documentation-manual and documentation-cookbook The first step to ensure a successful translation of the manual is to find and translate the following strings _first_: • ‘version.texi’: Translate this string as ‘version-xx.texi’, where ‘xx’ is your language code (the one shown in the URL on weblate). • ‘contributing.texi’: Translate this string as ‘contributing.xx.texi’, where ‘xx’ is the same language code. • ‘Top’: Do not translate this string, it is important for Texinfo. If you translate it, the document will be empty (missing a Top node). Please look for it, and register ‘Top’ as its translation. Translating these strings first ensure we can include your translation in the guix repository without breaking the make process or the ‘guix pull’ machinery. The manual and the cookbook both use Texinfo. As for ‘packages’, please keep Texinfo markup as is. There are more possible markup types in the manual than in the package descriptions. In general, do not translate the content of ‘@code’, ‘@file’, ‘@var’, ‘@value’, etc. You should translate the content of formatting markup such as ‘@emph’, ‘@i’, etc. The manual contains sections that can be referred to by name by ‘@ref’, ‘@xref’ and ‘@pxref’. We have a mechanism in place so you do not have to translate their content. If you keep the English title, we will automatically replace it with your translation of that title. This ensures that Texinfo will always be able to find the node. If you decide to change the translation of the title, the references will automatically be updated and you will not have to update them all yourself. When translating references from the cookbook to the manual, you need to replace the name of the manual and the name of the section. For instance, to translate ‘@pxref{Defining Packages,,, guix, GNU Guix Reference Manual}’, you would replace ‘Defining Packages’ with the title of that section in the translated manual _only_ if that title is translated. If the title is not translated in your language yet, do not translate it here, or the link will be broken. Replace ‘guix’ with ‘guix.xx’ where ‘xx’ is your language code. ‘GNU Guix Reference Manual’ is the text of the link. You can translate it however you wish. website The website pages are written using SXML, an s-expression version of HTML, the basic language of the web. We have a process to extract translatable strings from the source, and replace complex s-expressions with a more familiar XML markup, where each markup is numbered. Translators can arbitrarily change the ordering, as in the following example. #. TRANSLATORS: Defining Packages is a section name #. in the English (en) manual. #: apps/base/templates/about.scm:64 msgid "Packages are <1>defined<1.1>en<1.2>Defining-Packages.html as native <2>Guile modules." msgstr "Pakete werden als reine <2>Guile-Module <1>definiert<1.1>de<1.2>Pakete-definieren.html." Note that you need to include the same markups. You cannot skip any. In case you make a mistake, the component might fail to build properly with your language, or even make guix pull fail. To prevent that, we have a process in place to check the content of the files before pushing to our repository. We will not be able to update the translation for your language in Guix, so we will notify you (through weblate and/or by email) so you get a chance to fix the issue. Outside of Weblate .................. Currently, some parts of Guix cannot be translated on Weblate, help wanted! • ‘guix pull’ news can be translated in ‘news.scm’, but is not available from Weblate. If you want to provide a translation, you can prepare a patch as described above, or simply send us your translation with the name of the news entry you translated and your language. *Note Writing Channel News::, for more information about channel news. • Guix blog posts cannot currently be translated. • The installer script (for foreign distributions) is entirely in English. • Some of the libraries Guix uses cannot be translated or are translated outside of the Guix project. Guile itself is not internationalized. • Other manuals linked from this manual or the cookbook might not be translated. Conditions for Inclusion ........................ There are no conditions for adding new translations of the ‘guix’ and ‘guix-packages’ components, other than they need at least one translated string. New languages will be added to Guix as soon as possible. The files may be removed if they fall out of sync and have no more translated strings. Given that the web site is dedicated to new users, we want its translation to be as complete as possible before we include it in the language menu. For a new language to be included, it needs to reach at least 80% completion. When a language is included, it may be removed in the future if it stays out of sync and falls below 60% completion. The manual and cookbook are automatically added in the default compilation target. Every time we synchronize translations, developers need to recompile all the translated manuals and cookbooks. This is useless for what is essentially the English manual or cookbook. Therefore, we will only include a new language when it reaches 10% completion in the component. When a language is included, it may be removed in the future if it stays out of sync and falls below 5% completion. Translation Infrastructure .......................... Weblate is backed by a git repository from which it discovers new strings to translate and pushes new and updated translations. Normally, it would be enough to give it commit access to our repositories. However, we decided to use a separate repository for two reasons. First, we would have to give Weblate commit access and authorize its signing key, but we do not trust it in the same way we trust guix developers, especially since we do not manage the instance ourselves. Second, if translators mess something up, it can break the generation of the website and/or guix pull for all our users, independently of their language. For these reasons, we use a dedicated repository to host translations, and we synchronize it with our guix and artworks repositories after checking no issue was introduced in the translation. Developers can download the latest PO files from weblate in the Guix repository by running the ‘make download-po’ command. It will automatically download the latest files from weblate, reformat them to a canonical form, and check they do not contain issues. The manual needs to be built again to check for additional issues that might crash Texinfo. Before pushing new translation files, developers should add them to the make machinery so the translations are actually available. The process differs for the various components. • New po files for the ‘guix’ and ‘packages’ components must be registered by adding the new language to ‘po/guix/LINGUAS’ or ‘po/packages/LINGUAS’. • New po files for the ‘documentation-manual’ component must be registered by adding the file name to ‘DOC_PO_FILES’ in ‘po/doc/local.mk’, the generated ‘%D%/guix.xx.texi’ manual to ‘info_TEXINFOS’ in ‘doc/local.mk’ and the generated ‘%D%/guix.xx.texi’ and ‘%D%/contributing.xx.texi’ to ‘TRANSLATED_INFO’ also in ‘doc/local.mk’. • New po files for the ‘documentation-cookbook’ component must be registered by adding the file name to ‘DOC_COOKBOOK_PO_FILES’ in ‘po/doc/local.mk’, the generated ‘%D%/guix-cookbook.xx.texi’ manual to ‘info_TEXINFOS’ in ‘doc/local.mk’ and the generated ‘%D%/guix-cookbook.xx.texi’ to ‘TRANSLATED_INFO’ also in ‘doc/local.mk’. • New po files for the ‘website’ component must be added to the ‘guix-artwork’ repository, in ‘website/po/’. ‘website/po/LINGUAS’ and ‘website/po/ietf-tags.scm’ must be updated accordingly (see ‘website/i18n-howto.txt’ for more information on the process).  File: guix.pt_BR.info, Node: Agradecimentos, Next: Licença de Documentação Livre GNU, Prev: Contribuindo, Up: Top 23 Agradecimentos ***************** Guix is based on the Nix package manager (https://nixos.org/nix/), which was designed and implemented by Eelco Dolstra, with contributions from other people (see the ‘nix/AUTHORS’ file in Guix). Nix pioneered functional package management, and promoted unprecedented features, such as transactional package upgrades and rollbacks, per-user profiles, and referentially transparent build processes. Without this work, Guix would not exist. As distribuições de software baseadas em Nix, Nixpkgs e NixOS, também foram uma inspiração para o Guix. O GNU Guix em si é um trabalho coletivo com contribuições de várias pessoas. Veja o arquivo ‘AUTHORS’ no Guix para obter mais informações sobre essas pessoas legais. O arquivo ‘THANKS’ lista as pessoas que ajudaram a relatar erros, cuidar da infraestrutura, fornecer ilustrações e temas, fazer sugestões e muito mais – obrigado!  File: guix.pt_BR.info, Node: Licença de Documentação Livre GNU, Next: Índice de conceitos, Prev: Agradecimentos, Up: Top Appendix A Licença de Documentação Livre GNU ******************************************** Version 1.3, 3 November 2008 Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”. Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text. The “publisher” means any person or entity that distributes copies of the Document to the public. A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles. You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.” 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License. However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See . Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document. 11. RELICENSING “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site. “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization. “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document. An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008. The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing. ADDENDUM: How to use this License for your documents ==================================================== To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (C) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this: with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.