Browse Source

doc: cookbook: Use "@lisp" for Scheme snippets.

* doc/guix-cookbook.texi: Use @lisp for Scheme snippets instead of
"@example scheme".  This allows for syntax highlighting of the HTML
output.
wip-system-bootstrap
Ludovic Courtès 2 years ago
parent
commit
b1eecb5c46
No known key found for this signature in database GPG Key ID: 90B11993D9AEBB5
  1. 86
      doc/guix-cookbook.texi

86
doc/guix-cookbook.texi

@ -125,14 +125,14 @@ and @code{#f} stand for the booleans "true" and "false", respectively.
Examples of valid expressions:
@example scheme
@lisp
> "Hello World!"
"Hello World!"
> 17
17
> (display (string-append "Hello " "Guix" "\n"))
"Hello Guix!"
@end example
@end lisp
@item
This last example is a function call nested in another function call. When a
@ -143,66 +143,66 @@ last evaluated expression as its return value.
@item
Anonymous functions are declared with the @code{lambda} term:
@example scheme
@lisp
> (lambda (x) (* x x))
#<procedure 120e348 at <unknown port>:24:0 (x)>
@end example
@end lisp
The above procedure returns the square of its argument. Since everything is
an expression, the @code{lambda} expression returns an anonymous procedure,
which can in turn be applied to an argument:
@example scheme
@lisp
> ((lambda (x) (* x x)) 3)
9
@end example
@end lisp
@item
Anything can be assigned a global name with @code{define}:
@example scheme
@lisp
> (define a 3)
> (define square (lambda (x) (* x x)))
> (square a)
9
@end example
@end lisp
@item
Procedures can be defined more concisely with the following syntax:
@example scheme
@lisp
(define (square x) (* x x))
@end example
@end lisp
@item
A list structure can be created with the @code{list} procedure:
@example scheme
@lisp
> (list 2 a 5 7)
(2 3 5 7)
@end example
@end lisp
@item
The @emph{quote} disables evaluation of a parenthesized expression: the first
term is not called over the other terms. Thus it effectively returns a list
of terms.
@example scheme
@lisp
> '(display (string-append "Hello " "Guix" "\n"))
(display (string-append "Hello " "Guix" "\n"))
> '(2 a 5 7)
(2 a 5 7)
@end example
@end lisp
@item
The @emph{quasiquote} disables evaluation of a parenthesized expression until
a comma re-enables it. Thus it provides us with fine-grained control over
what is evaluated and what is not.
@example scheme
@lisp
> `(2 a 5 7 (2 ,a 5 ,(+ a 4)))
(2 a 5 7 (2 3 5 7))
@end example
@end lisp
Note that the above result is a list of mixed elements: numbers, symbols (here
@code{a}) and the last element is a list itself.
@ -210,7 +210,7 @@ Note that the above result is a list of mixed elements: numbers, symbols (here
@item
Multiple variables can be named locally with @code{let}:
@example scheme
@lisp
> (define x 10)
> (let ((x 2)
(y 3))
@ -220,17 +220,17 @@ Multiple variables can be named locally with @code{let}:
10
> y
ERROR: In procedure module-lookup: Unbound variable: y
@end example
@end lisp
Use @code{let*} to allow later variable declarations to refer to earlier
definitions.
@example scheme
@lisp
> (let* ((x 2)
(y (* x 3)))
(list x y))
(2 6)
@end example
@end lisp
@item
The keyword syntax is @code{#:}; it is used to create unique identifiers.
@ -244,12 +244,12 @@ Scheme treats @code{%} exactly the same as any other letter.
@item
Modules are created with @code{define-module}. For instance
@example scheme
@lisp
(define-module (guix build-system ruby)
#:use-module (guix store)
#:export (ruby-build
ruby-build-system))
@end example
@end lisp
defines the module @code{guix build-system ruby} which must be located in
@file{guix/build-system/ruby.scm} somewhere in the Guile load path. It
@ -343,7 +343,7 @@ install}). Guix already provides a package definition which is a perfect
example to start with. You can look up its declaration with @code{guix edit
hello} from the command line. Let's see how it looks:
@example scheme
@lisp
(define-public hello
(package
(name "hello")
@ -363,7 +363,7 @@ serves as an example of standard GNU coding practices. As such, it supports
command-line arguments, multiple languages, and so on.")
(home-page "https://www.gnu.org/software/hello/")
(license gpl3+)))
@end example
@end lisp
As you can see, most of it is rather straightforward. But let's review the
fields together:
@ -423,7 +423,7 @@ setup later; for now we will go the simplest route.
Save the following to a file @file{my-hello.scm}.
@example scheme
@lisp
(use-modules (guix packages)
(guix download)
(guix build-system gnu)
@ -447,7 +447,7 @@ serves as an example of standard GNU coding practices. As such, it supports
command-line arguments, multiple languages, and so on.")
(home-page "https://www.gnu.org/software/hello/")
(license gpl3+))
@end example
@end lisp
We will explain the extra code in a moment.
@ -564,7 +564,7 @@ nature of how the package definition is written.
The @code{linux-libre} kernel package definition is actually a procedure which
creates a package.
@example scheme
@lisp
(define* (make-linux-libre version hash supported-systems
#:key
;; A function that takes an arch and a variant.
@ -575,19 +575,19 @@ creates a package.
(extra-options %default-extra-linux-options)
(patches (list %boot-logo-patch)))
...)
@end example
@end lisp
The current @code{linux-libre} package is for the 5.1.x series, and is
declared like this:
@example scheme
@lisp
(define-public linux-libre
(make-linux-libre %linux-libre-version
%linux-libre-hash
'("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux")
#:patches %linux-libre-5.1-patches
#:configuration-file kernel-config))
@end example
@end lisp
Any keys which are not assigned values inherit their default value from the
@code{make-linux-libre} definition. When comparing the two snippets above,
@ -603,7 +603,7 @@ including an actual @file{.config} file as a native input to our custom
kernel. The following is a snippet from the custom @code{'configure} phase of
the @code{make-linux-libre} package definition:
@example scheme
@lisp
(let ((build (assoc-ref %standard-phases 'build))
(config (assoc-ref (or native-inputs inputs) "kconfig")))
@ -614,13 +614,13 @@ the @code{make-linux-libre} package definition:
(copy-file config ".config")
(chmod ".config" #o666))
(invoke "make" ,defconfig))
@end example
@end lisp
Below is a sample kernel package. The @code{linux-libre} package is nothing
special and can be inherited from and have its fields overridden like any
other package:
@example scheme
@lisp
(define-public linux-libre/E2140
(package
(inherit linux-libre)
@ -628,7 +628,7 @@ other package:
`(("kconfig" ,(local-file "E2140.config"))
,@@(alist-delete "kconfig"
(package-native-inputs linux-libre))))))
@end example
@end lisp
In the same directory as the file defining @code{linux-libre-E2140} is a file
named @file{E2140.config}, which is an actual kernel configuration file. The
@ -641,7 +641,7 @@ The second way to create a custom kernel is to pass a new value to the
@code{extra-options} keyword works with another function defined right below
it:
@example scheme
@lisp
(define %default-extra-linux-options
`(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html
("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #t)
@ -667,11 +667,11 @@ it:
(string-append option "=n")))
options)
"\n"))
@end example
@end lisp
And in the custom configure script from the `make-linux-libre` package:
@example scheme
@lisp
;; Appending works even when the option wasn't in the
;; file. The last one prevails if duplicated.
(let ((port (open-file ".config" "a"))
@ -680,13 +680,13 @@ And in the custom configure script from the `make-linux-libre` package:
(close-port port))
(invoke "make" "oldconfig"))))
@end example
@end lisp
So by not providing a configuration-file the @file{.config} starts blank, and
then we write into it the collection of flags that we want. Here's another
custom kernel:
@example scheme
@lisp
(define %macbook41-full-config
(append %macbook41-config-options
%filesystems
@ -703,7 +703,7 @@ custom kernel:
#:extra-version "macbook41"
#:patches (@@@@ (gnu packages linux) %linux-libre-5.1-patches)
#:extra-options %macbook41-config-options))
@end example
@end lisp
In the above example @code{%filesystems} is a collection of flags enabling
different filesystem support, @code{%efi-support} enables EFI support and
@ -876,7 +876,7 @@ Let's dive in the set up!
A Guix profile can be set up @emph{via} a so-called @emph{manifest specification} that looks like
this:
@example
@lisp
(specifications->manifest
'("package-1"
;; Version 1.3 of package-2.
@ -885,9 +885,9 @@ this:
"package-3:lib"
; ...
"package-N"))
@end example
@end lisp
See @pxref{Invoking guix package,,, guix, GNU Guix Reference Manual} for
@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}, for
the syntax details.
We can create a manifest specification per profile and install them this way:

Loading…
Cancel
Save