diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 175 |
1 files changed, 134 insertions, 41 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index f7deafa516..112c32939d 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -16,8 +16,9 @@ Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* -Copyright @copyright{} 2015, 2016 Leo Famulari -Copyright @copyright{} 2016 Ben Woodcroft +Copyright @copyright{} 2015, 2016 Leo Famulari@* +Copyright @copyright{} 2016 Ben Woodcroft@* +Copyright @copyright{} 2016 Chris Marusich Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -154,6 +155,12 @@ Utilities * Invoking guix challenge:: Challenging substitute servers. * Invoking guix container:: Process isolation. +Invoking @command{guix build} + +* Common Build Options:: Build options for most commands. +* Package Transformation Options:: Creating variants of packages. +* Additional Build Options:: Options specific to 'guix build'. + GNU Distribution * System Installation:: Installing the whole operating system. @@ -165,6 +172,15 @@ GNU Distribution * Bootstrapping:: GNU/Linux built from scratch. * Porting:: Targeting another platform or kernel. +System Installation + +* Limitations:: What you can expect. +* Hardware Considerations:: Supported hardware. +* USB Stick Installation:: Preparing the installation medium. +* Preparing for Installation:: Networking, partitioning, etc. +* Proceeding with the Installation:: The real thing. +* Building the Installation Image:: How this comes to be. + System Configuration * Using the Configuration System:: Customizing your GNU system. @@ -2720,6 +2736,27 @@ of @var{gnu-build-system}, and differ mainly in the set of inputs implicitly added to the build process, and in the list of phases executed. Some of these build systems are listed below. +@defvr {Scheme Variable} ant-build-system +This variable is exported by @code{(guix build-system ant)}. It +implements the build procedure for Java packages that can be built with +@url{http://ant.apache.org/, Ant build tool}. + +It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as +provided by the @code{icedtea} package to the set of inputs. Different +packages can be specified with the @code{#:ant} and @code{#:jdk} +parameters, respectively. + +When the original package does not provide a suitable Ant build file, +the parameter @code{#:jar-name} can be used to generate a minimal Ant +build file @file{build.xml} with tasks to build the specified jar +archive. + +The parameter @code{#:build-target} can be used to specify the Ant task +that should be run during the @code{build} phase. By default the +``jar'' task will be run. + +@end defvr + @defvr {Scheme Variable} cmake-build-system This variable is exported by @code{(guix build-system cmake)}. It implements the build procedure for packages using the @@ -5636,11 +5673,12 @@ link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit @end ifinfo @menu -* Limitations:: What you can expect. -* USB Stick Installation:: Preparing the installation medium. -* Preparing for Installation:: Networking, partitioning, etc. -* Proceeding with the Installation:: The real thing. -* Building the Installation Image:: How this comes to be. +* Limitations:: What you can expect. +* Hardware Considerations:: Supported hardware. +* USB Stick Installation:: Preparing the installation medium. +* Preparing for Installation:: Networking, partitioning, etc. +* Proceeding with the Installation:: The real thing. +* Building the Installation Image:: How this comes to be. @end menu @node Limitations @@ -5686,6 +5724,40 @@ You have been warned! But more than a disclaimer, this is an invitation to report issues (and success stories!), and to join us in improving it. @xref{Contributing}, for more info. + +@node Hardware Considerations +@subsection Hardware Considerations + +@cindex hardware support on GuixSD +GNU@tie{}GuixSD focuses on respecting the user's computing freedom. It +builds around the kernel Linux-libre, which means that only hardware for +which free software drivers and firmware exists is supported. Nowadays, +a wide range of off-the-shelf hardware is supported on +GNU/Linux-libre---from keyboards to graphics cards to scanners and +Ethernet controllers. Unfortunately, there are still areas where +hardware vendors deny users control over their own computing, and such +hardware is not supported on GuixSD. + +@cindex WiFi, hardware support +One of the main areas where free drivers or firmware is lacking is WiFi +devices. WiFi devices known to work include those using Atheros chips +(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre +driver, and for which free firmware exists and is available +out-of-the-box on GuixSD, as part of @var{%base-firmware} +(@pxref{operating-system Reference, @code{firmware}}). + +@cindex RYF, Respects Your Freedom +The @uref{https://www.fsf.org/, Free Software Foundation} runs +@uref{https://www.fsf.org/ryf, @dfn{Respect Your Freedom}} (RYF), a +certification program for hardware products that respect your freedom +and your privacy and ensure that you have control over your device. We +encourage you to check the list of RYF-certified hardware. + +Another useful resource is the @uref{https://www.h-node.org/, H-Node} +web site. It contains a catalog of hardware devices with information +about their support in GNU/Linux. + + @node USB Stick Installation @subsection USB Stick Installation @@ -5967,8 +6039,8 @@ system} command, specifically: guix system disk-image --image-size=850MiB gnu/system/install.scm @end example -@xref{Invoking guix system} and -@file{gnu/system/install.scm} in the source tree for more information +Have a look at @file{gnu/system/install.scm} in the source tree, +and see also @ref{Invoking guix system} for more information about the installation image. @node System Configuration @@ -6087,28 +6159,42 @@ generated as needed (@pxref{Defining Services}). @cindex customization, of services @findex modify-services Occasionally, instead of using the base services as is, you will want to -customize them. For instance, to change the configuration of -@code{guix-daemon} and Mingetty (the console log-in), you may write the -following instead of @var{%base-services}: +customize them. To do this, use @code{modify-services} (@pxref{Service +Reference, @code{modify-services}}) to modify the list. + +For example, suppose you want to modify @code{guix-daemon} and Mingetty +(the console log-in) in the @var{%base-services} list (@pxref{Base +Services, @code{%base-services}}). To do that, you can write the +following in your operating system declaration: @lisp -(modify-services %base-services - (guix-service-type config => - (guix-configuration - (inherit config) - (use-substitutes? #f) - (extra-options '("--gc-keep-outputs")))) - (mingetty-service-type config => - (mingetty-configuration - (inherit config) - (motd (plain-file "motd" "Hi there!"))))) +(define %my-services + ;; My very own list of services. + (modify-services %base-services + (guix-service-type config => + (guix-configuration + (inherit config) + (use-substitutes? #f) + (extra-options '("--gc-keep-derivations")))) + (mingetty-service-type config => + (mingetty-configuration + (inherit config) + (motd (plain-file "motd" "Howdy!")))))) + +(operating-system + ;; @dots{} + (services %my-services)) @end lisp -@noindent -The effect here is to change the options passed to @command{guix-daemon} -when it is started, as well as the ``message of the day'' that appears -when logging in at the console. @xref{Service Reference, -@code{modify-services}}, for more on that. +This changes the configuration---i.e., the service parameters---of the +@code{guix-service-type} instance, and that of all the +@code{mingetty-service-type} instances in the @var{%base-services} list. +Observe how this is accomplished: first, we arrange for the original +configuration to be bound to the identifier @code{config} in the +@var{body}, and then we write the @var{body} so that it evaluates to the +desired configuration. In particular, notice how we use @code{inherit} +to create a new configuration which has the same values as the old +configuration, but with a few modifications. The configuration for a typical ``desktop'' usage, with the X11 display server, a desktop environment, network management, power management, and @@ -6214,7 +6300,8 @@ the Linux kernel. @xref{Initial RAM Disk}. List of firmware packages loadable by the operating system kernel. The default includes firmware needed for Atheros-based WiFi devices -(Linux-libre module @code{ath9k}.) +(Linux-libre module @code{ath9k}). @xref{Hardware Considerations}, for +more info on supported hardware. @item @code{host-name} The host name. @@ -9963,11 +10050,12 @@ Here is an example of how a service is created and manipulated: The @code{modify-services} form provides a handy way to change the parameters of some of the services of a list such as -@var{%base-services} (@pxref{Base Services, @code{%base-services}}). Of -course, you could always use standard list combinators such as -@code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, -guile, GNU Guile Reference Manual}); @code{modify-services} simply -provides a more concise form for this common pattern. +@var{%base-services} (@pxref{Base Services, @code{%base-services}}). It +evalutes to a list of services. Of course, you could always use +standard list combinators such as @code{map} and @code{fold} to do that +(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual}); +@code{modify-services} simply provides a more concise form for this +common pattern. @deffn {Scheme Syntax} modify-services @var{services} @ (@var{type} @var{variable} => @var{body}) @dots{} @@ -9979,16 +10067,21 @@ clauses. Each clause has the form: (@var{type} @var{variable} => @var{body}) @end example -where @var{type} is a service type, such as @var{guix-service-type}, and -@var{variable} is an identifier that is bound within @var{body} to the -value of the service of that @var{type}. @xref{Using the Configuration -System}, for an example. +where @var{type} is a service type---e.g., +@code{guix-service-type}---and @var{variable} is an identifier that is +bound within the @var{body} to the service parameters---e.g., a +@code{guix-configuration} instance---of the original service of that +@var{type}. -This is a shorthand for: +The @var{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 @code{define-record-type*}, you can write a succint +@var{body} that evaluates to the new service parameters by using the +@code{inherit} feature that @code{define-record-type*} provides. + +@xref{Using the Configuration System} for example usage. -@example -(map (lambda (service) @dots{}) @var{services}) -@end example @end deffn Next comes the programming interface for service types. This is |