me/guix
Archived
1
0
Fork 0
Code Activity

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

Browse source 
* doc/guix-cookbook.texi: Use @lisp for Scheme snippets instead of
"@example scheme".  This allows for syntax highlighting of the HTML
output.
This commit is contained in:
Ludovic Courtès 2019-10-25 12:14:09 +02:00
parent b1b27f284f
commit b1eecb5c46
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5
1 changed files with 43 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

86
doc/guix-cookbook.texi
View file

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