diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 8 | ||||
| -rw-r--r-- | doc/emacs.texi | 78 | ||||
| -rw-r--r-- | doc/guix.texi | 174 | ||||
| -rw-r--r-- | doc/local.mk | 157 |
4 files changed, 350 insertions, 67 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 91759b677a..208c6af5e8 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -78,9 +78,13 @@ export ACLOCAL_PATH=/usr/share/aclocal @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for more information. -Then, run @command{./configure} as usual. +Then, run @command{./configure} as usual. Make sure to pass +@code{--localstatedir=@var{directory}} where @var{directory} is the +@code{localstatedir} value used by your current installation (@pxref{The +Store}, for information about this). -Finally, you have to invoke @code{make check} to run tests. If anything +Finally, you have to invoke @code{make check} to run tests +(@pxref{Running the Test Suite}). If anything fails, take a look at installation instructions (@pxref{Installation}) or send a message to the @email{guix-devel@@gnu.org, mailing list}. diff --git a/doc/emacs.texi b/doc/emacs.texi index c4fdfff272..575e87c262 100644 --- a/doc/emacs.texi +++ b/doc/emacs.texi @@ -10,6 +10,7 @@ Guix convenient and fun. * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. * Package Management: Emacs Package Management. Managing packages and generations. * Licenses: Emacs Licenses. Interface for licenses of Guix packages. +* Package Source Locations: Emacs Package Locations. Interface for package location files. * Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. * Build Log Mode: Emacs Build Log. Highlighting Guix build logs. @@ -160,6 +161,11 @@ Display package(s) with the specified name. @item M-x guix-packages-by-license Display package(s) with the specified license. +@item M-x guix-packages-by-location +Display package(s) located in the specified file. These files usually +have the following form: @file{gnu/packages/emacs.scm}, but don't type +them manually! Press @key{TAB} to complete the file name. + @item M-x guix-search-by-regexp Search for packages by a specified regexp. By default ``name'', ``synopsis'' and ``description'' of the packages will be searched. This @@ -217,30 +223,6 @@ With @kbd{C-u}, make it verbose. Once @command{guix pull} has succeeded, the Guix REPL is restared. This allows you to keep using the Emacs interface with the updated Guix. -Finally, there is an Emacs variant of @command{guix edit} command -(@pxref{Invoking guix edit}): - -@table @kbd -@item M-x guix-edit -As with @kbd{M-x guix-packages-by-name}, you can press @key{TAB} to -complete a package name. -@end table - -If you are contributing to Guix, you may find it useful for @kbd{M-x -guix-edit} to open package files from your git directory. This can be -done by setting @code{guix-directory} variable. For example, after -this: - -@example -(setq guix-directory "~/src/guix") -@end example - -@kbd{M-x guix-edit guix} opens -@file{~/src/guix/gnu/packages/package-management.scm} file. - -Also you can use @kbd{C-u} prefix argument to specify a directory just -for the current @kbd{M-x guix-edit} command. - @node Emacs General info @subsection General information @@ -562,8 +544,56 @@ Display a list of available licenses. You can press @kbd{@key{RET}} there to display packages with this license in the same way as @kbd{M-x guix-packages-by-license} would do (@pxref{Emacs Commands}). +@item M-x guix-find-license-definition +Open @file{@dots{}/guix/licenses.scm} and move to the specified license. + +@end table + + +@node Emacs Package Locations +@section Package Source Locations + +As you know, package definitions are placed in Guile files, also known +as @dfn{package locations}. The following commands should help you not +get lost in these locations: + +@table @kbd + +@item M-x guix-locations +Display a list of package locations. You can press @key{RET} there to +display packages placed in the current location in the same way as +@kbd{M-x guix-packages-by-location} would do (@pxref{Emacs Commands}). +Note that when the point is on a location button, @key{RET} will open +this location file. + +@item M-x guix-find-location +Open the given package definition source file (press @key{TAB} to choose +a location from a completion list). + +@item M-x guix-edit +Find location of a specified package. This is an Emacs analog of +@command{guix edit} command (@pxref{Invoking guix edit}). As with +@kbd{M-x guix-packages-by-name}, you can press @key{TAB} to complete a +package name. + @end table +If you are contributing to Guix, you may find it useful for @kbd{M-x +guix-find-location} and @kbd{M-x guix-edit} to open locations from your +Git checkout. This can be done by setting @code{guix-directory} +variable. For example, after this: + +@example +(setq guix-directory "~/src/guix") +@end example + +@kbd{M-x guix-edit guix} opens +@file{~/src/guix/gnu/packages/package-management.scm} file. + +Also you can use @kbd{C-u} prefix argument to specify a directory just +for the current @kbd{M-x guix-find-location} or @kbd{M-x guix-edit} +command. + @node Emacs Popup Interface @section Popup Interface diff --git a/doc/guix.texi b/doc/guix.texi index a34d547f7c..0d72574619 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -118,6 +118,7 @@ Emacs Interface * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. * Package Management: Emacs Package Management. Managing packages and generations. * Licenses: Emacs Licenses. Interface for licenses of Guix packages. +* Package Source Locations: Emacs Package Locations. Interface for package location files. * Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. * Build Log Mode: Emacs Build Log. Highlighting Guix build logs. @@ -225,6 +226,7 @@ Packaging Guidelines * Synopses and Descriptions:: Helping users find the right package. * Python Modules:: Taming the snake. * Perl Modules:: Little pearls. +* Java Packages:: Coffee break. * Fonts:: Fond of fonts. Contributing @@ -1157,6 +1159,16 @@ for Chinese languages: guix package -i font-adobe-source-han-sans:cn @end example +@subsection X.509 Certificates + +The @code{nss-certs} package provides X.509 certificates, which allow +programs to authenticate Web servers accessed over HTTPS. + +When using Guix on a foreign distro, you can install this package and +define the relevant environment variables so that packages know where to +look for certificates. @pxref{X.509 Certificates}, for detailed +information. + @subsection Emacs Packages When you install Emacs packages with Guix, the elisp files may be placed @@ -1377,12 +1389,6 @@ variables for their search paths (see explanation of @code{--search-paths} below). Any missing or possibly incorrect environment variable definitions are reported here. -@c XXX: keep me up-to-date -Finally, when installing a GNU package, the tool reports the -availability of a newer upstream version. In the future, it may provide -the option of installing directly from the upstream version, even if -that version is not yet in the distribution. - @item --install-from-expression=@var{exp} @itemx -e @var{exp} Install the package @var{exp} evaluates to. @@ -1968,6 +1974,15 @@ suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes When @var{min} is omitted, collect all the garbage. +@item --free-space=@var{free} +@itemx -F @var{free} +Collect garbage until @var{free} space is available under +@file{/gnu/store}, if possible; @var{free} denotes storage space, such +as @code{500MiB}, as described above. + +When @var{free} or more is already available in @file{/gnu/store}, do +nothing and exit immediately. + @item --delete @itemx -d Attempt to delete all the store files and directories specified as @@ -4057,8 +4072,9 @@ binaries are genuine. @xref{Invoking guix challenge}, for more. Note that, currently, the differing build results are not kept around, so you will have to manually investigate in case of an error---e.g., by -stashing one of the build results with @code{guix archive --export}, -then rebuilding, and finally comparing the two results. +stashing one of the build results with @code{guix archive --export} +(@pxref{Invoking guix archive}), then rebuilding, and finally comparing +the two results. @item --no-build-hook Do not attempt to offload builds @i{via} the ``build hook'' of the daemon @@ -4365,12 +4381,12 @@ facilitates the life of packagers by pointing their editor at the source file containing the definition of the specified packages. For instance: @example -guix edit gcc-4.8 vim +guix edit gcc@@4.9 vim @end example @noindent launches the program specified in the @code{VISUAL} or in the -@code{EDITOR} environment variable to edit the recipe of GCC@tie{}4.8.4 +@code{EDITOR} environment variable to edit the recipe of GCC@tie{}4.9.3 and that of Vim. If you are using Emacs, note that the Emacs user interface provides the @@ -5511,21 +5527,21 @@ any given store item. The command output looks like this: @smallexample -$ guix challenge --substitute-urls="http://hydra.gnu.org http://guix.example.org" -updating list of substitutes from 'http://hydra.gnu.org'... 100.0% -updating list of substitutes from 'http://guix.example.org'... 100.0% +$ guix challenge --substitute-urls="https://hydra.gnu.org https://guix.example.org" +updating list of substitutes from 'https://hydra.gnu.org'... 100.0% +updating list of substitutes from 'https://guix.example.org'... 100.0% /gnu/store/@dots{}-openssl-1.0.2d contents differ: local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - http://hydra.gnu.org/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - http://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim + https://hydra.gnu.org/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q + https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim /gnu/store/@dots{}-git-2.5.0 contents differ: local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha - http://hydra.gnu.org/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f - http://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 + https://hydra.gnu.org/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f + https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 /gnu/store/@dots{}-pius-2.1.1 contents differ: local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax - http://hydra.gnu.org/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax - http://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs + https://hydra.gnu.org/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax + https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs @end smallexample @noindent @@ -5544,14 +5560,14 @@ various things that Guix does not fully control, in spite of building packages in isolated environments (@pxref{Features}). Most common sources of non-determinism include the addition of timestamps in build results, the inclusion of random numbers, and directory listings sorted -by inode number. See @uref{http://reproducible.debian.net/howto/}, for +by inode number. See @uref{https://reproducible-builds.org/docs/}, for more information. To find out what is wrong with this Git binary, we can do something along these lines (@pxref{Invoking guix archive}): @example -$ wget -q -O - http://hydra.gnu.org/nar/@dots{}-git-2.5.0 \ +$ wget -q -O - https://hydra.gnu.org/nar/@dots{}-git-2.5.0 \ | guix archive -x /tmp/git $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git @end example @@ -5561,7 +5577,7 @@ local build, and the files resulting from the build on @code{hydra.gnu.org} (@pxref{Overview, Comparing and Merging Files,, diffutils, Comparing and Merging Files}). The @command{diff} command works great for text files. When binary files differ, a better option -is @uref{http://diffoscope.org/, Diffoscope}, a tool that helps +is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps visualize differences for all kinds of files. Once you have done that work, you can tell whether the differences are due @@ -5582,7 +5598,7 @@ $ guix challenge @var{package} @noindent where @var{package} is a package specification such as -@code{guile-2.0} or @code{glibc:debug}. +@code{guile@@2.0} or @code{glibc:debug}. The general syntax is: @@ -5590,6 +5606,12 @@ The general syntax is: guix challenge @var{options} [@var{packages}@dots{}] @end example +When a difference is found between the hash of a locally-built item and +that of a server-provided substitute, or among substitutes provided by +different servers, the command displays it as in the example above and +its exit code is 2 (other non-zero exit codes denote other kinds of +errors.) + The one option that matters is: @table @code @@ -5809,7 +5831,7 @@ to report issues (and success stories!), and to join us in improving it. @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, +which free software drivers and firmware exist 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 @@ -5817,7 +5839,7 @@ 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 +One of the main areas where free drivers or firmware are 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 @@ -5826,10 +5848,10 @@ out-of-the-box on GuixSD, as part of @var{%base-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 +@uref{https://www.fsf.org/ryf, @dfn{Respects 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. +encourage you to check the list of RYF-certified devices. Another useful resource is the @uref{https://www.h-node.org/, H-Node} web site. It contains a catalog of hardware devices with information @@ -6039,6 +6061,15 @@ partition): mount /dev/sda1 /mnt @end example +Finally, if you plan to use one or more swap partitions (@pxref{Memory +Concepts, swap space,, libc, The GNU C Library Reference Manual}), make +sure to initialize them with @command{mkswap}. Assuming you have one +swap partition on @file{/dev/sda2}, you would run: + +@example +mkswap /dev/sda2 +@end example + @node Proceeding with the Installation @subsection Proceeding with the Installation @@ -6227,7 +6258,7 @@ version: (operating-system ;; ... (packages (append (map specification->package - '("tcpdump" "htop" "gnupg-2.0")) + '("tcpdump" "htop" "gnupg@@2.0")) %base-packages))) @end lisp @@ -6426,15 +6457,17 @@ For example, @code{'("/dev/sda3")}. List of user accounts and groups. @xref{User Accounts}. @item @code{skeletons} (default: @code{(default-skeletons)}) -A monadic list of pairs of target file name and files. These are the -files that will be used as skeletons as new accounts are created. +A list target file name/file-like object tuples (@pxref{G-Expressions, +file-like objects}). These are the skeleton files that will be added to +the home directory of newly-created user accounts. For instance, a valid value may look like this: @example -(mlet %store-monad ((bashrc (text-file "bashrc" "\ - export PATH=$HOME/.guix-profile/bin"))) - (return `((".bashrc" ,bashrc)))) +`((".bashrc" ,(plain-file "bashrc" "echo Hello\n")) + (".guile" ,(plain-file "guile" + "(use-modules (ice-9 readline)) + (activate-readline)"))) @end example @item @code{issue} (default: @var{%default-issue}) @@ -6686,13 +6719,29 @@ Mapped devices are declared using the @code{mapped-device} form: (type luks-device-mapping)) @end example -@noindent +Or, better yet, like this: + +@example +(mapped-device + (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44")) + (target "home") + (type luks-device-mapping)) +@end example + @cindex disk encryption @cindex LUKS This example specifies a mapping from @file{/dev/sda3} to @file{/dev/mapper/home} using LUKS---the @url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a -standard mechanism for disk encryption. The @file{/dev/mapper/home} +standard mechanism for disk encryption. In the second example, the UUID +(unique identifier) is the LUKS UUID returned for the device by a +command like: + +@example +cryptsetup luksUUID /dev/sdx9 +@end example + +The @file{/dev/mapper/home} device can then be used as the @code{device} of a @code{file-system} declaration (@pxref{File Systems}). The @code{mapped-device} form is detailed below. @@ -7260,10 +7309,25 @@ Return a service that runs the Guix build daemon according to Run @var{udev}, which populates the @file{/dev} directory dynamically. @end deffn -@deffn {Scheme Procedure} console-keymap-service @var{file} +@deffn {Scheme Procedure} console-keymap-service @var{files} ... @cindex keyboard layout -Return a service to load console keymap from @var{file} using -@command{loadkeys} command. +Return a service to load console keymaps from @var{files} using +@command{loadkeys} command. Most likely, you want to load some default +keymap, which can be done like this: + +@example +(console-keymap-service "dvorak") +@end example + +Or, for example, for a Swedish keyboard, you may need to combine +the following keymaps: +@example +(console-keymap-service "se-lat6" "se-fi-lat6") +@end example + +Also you can specify a full file name (or file names) of your keymap(s). +See @code{man loadkeys} for details. + @end deffn @deffn {Scheme Procedure} gpm-service-type [#:gpm @var{gpm}] @ @@ -9315,14 +9379,22 @@ explicitly add it. The @file{/etc/ssl/certs} directory, which is where most applications and libraries look for certificates by default, points to the certificates installed globally. -Unprivileged users can also install their own certificate package in +Unprivileged users, including users of Guix on a foreign distro, +can also install their own certificate package in their profile. A number of environment variables need to be defined so that applications and libraries know where to find them. Namely, the OpenSSL library honors the @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE} variables. Some applications add their own environment variables; for instance, the Git version control system honors the certificate bundle -pointed to by the @code{GIT_SSL_CAINFO} environment variable. +pointed to by the @code{GIT_SSL_CAINFO} environment variable. Thus, you +would typically run something like: +@example +$ guix package -i nss-certs +$ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs" +$ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" +$ export GIT_SSL_CAINFO="$SSL_CERT_FILE" +@end example @node Name Service Switch @subsection Name Service Switch @@ -10733,6 +10805,7 @@ needed is to review and apply the patch. * Synopses and Descriptions:: Helping users find the right package. * Python Modules:: Taming the snake. * Perl Modules:: Little pearls. +* Java Packages:: Coffee break. * Fonts:: Fond of fonts. @end menu @@ -10974,6 +11047,25 @@ are also prepended by @code{perl-}. Such modules tend to have the word prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}. +@node Java Packages +@subsection Java Packages + +Java programs standing for themselves are named as any other package, +using the lowercase upstream name. + +To avoid confusion and naming clashes with other programming languages, +it is desirable that the name of a package for a Java package is +prefixed with @code{java-}. If a project already contains the word +@code{java}, we drop this; for instance, the package @code{ngsjava} is +packaged under the name @code{java-ngs}. + +For Java packages containing a single class or a small class hierarchy, +we use the lowercase class name, replace all occurrences of @code{.} by +dashes and prepend the prefix @code{java-}. So the class +@code{apache.commons.cli} becomes package +@code{java-apache-commons-cli}. + + @node Fonts @subsection Fonts @@ -11204,7 +11296,7 @@ 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 @file{gnu-system.am} has rules do download it for +available locally, and @file{gnu/local.mk} has rules do download it for the supported architectures; a rule for the new platform must be added as well. diff --git a/doc/local.mk b/doc/local.mk new file mode 100644 index 0000000000..b9f07c3590 --- /dev/null +++ b/doc/local.mk @@ -0,0 +1,157 @@ +# GNU Guix --- Functional package management for GNU +# Copyright © 2016 Eric Bavier <bavier@member.fsf.org> +# Copyright © 2012, 2013, 2014, 2015, 2016 Ludovic Courtès <ludo@gnu.org> +# Copyright © 2013 Andreas Enge <andreas@enge.fr> +# Copyright © 2016 Taylan Ulrich Bayırlı/Kammer <taylanbayirli@gmail.com> +# Copyright © 2016 Mathieu Lirzin <mthl@gnu.org> +# +# This file is part of GNU Guix. +# +# GNU Guix is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 3 of the License, or (at +# your option) any later version. +# +# GNU Guix is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GNU Guix. If not, see <http://www.gnu.org/licenses/>. + +info_TEXINFOS = doc/guix.texi + +DOT_FILES = \ + doc/images/bootstrap-graph.dot \ + doc/images/bootstrap-packages.dot \ + doc/images/coreutils-graph.dot \ + doc/images/coreutils-bag-graph.dot \ + doc/images/service-graph.dot \ + doc/images/shepherd-graph.dot + +DOT_VECTOR_GRAPHICS = \ + $(DOT_FILES:%.dot=%.eps) \ + $(DOT_FILES:%.dot=%.pdf) + +EXTRA_DIST += \ + doc/htmlxref.cnf \ + doc/contributing.texi \ + doc/emacs.texi \ + doc/fdl-1.3.texi \ + $(DOT_FILES) \ + $(DOT_VECTOR_GRAPHICS) \ + doc/images/coreutils-size-map.eps \ + doc/environment-gdb.scm \ + doc/package-hello.scm + +OS_CONFIG_EXAMPLES_TEXI = \ + doc/os-config-bare-bones.texi \ + doc/os-config-desktop.texi \ + doc/os-config-lightweight-desktop.texi + +# Bundle this file so that makeinfo finds it in out-of-source-tree builds. +BUILT_SOURCES += $(OS_CONFIG_EXAMPLES_TEXI) +EXTRA_DIST += $(OS_CONFIG_EXAMPLES_TEXI) +MAINTAINERCLEANFILES = $(OS_CONFIG_EXAMPLES_TEXI) + +doc/os-config-%.texi: gnu/system/examples/%.tmpl + $(AM_V_GEN)$(MKDIR_P) "`dirname $@`"; \ + cp "$<" "$@" + +infoimagedir = $(infodir)/images +dist_infoimage_DATA = \ + $(DOT_FILES:%.dot=%.png) \ + doc/images/coreutils-size-map.png + +# Try hard to obtain an image size and aspect that's reasonable for inclusion +# in an Info or PDF document. +DOT_OPTIONS = \ + -Gratio=.9 -Gnodesep=.005 -Granksep=.00005 \ + -Nfontsize=9 -Nheight=.1 -Nwidth=.1 + +.dot.png: + $(AM_V_DOT)$(DOT) -Tpng $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \ + mv "$(srcdir)/$@.tmp" "$(srcdir)/$@" + +.dot.pdf: + $(AM_V_DOT)$(DOT) -Tpdf $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \ + mv "$(srcdir)/$@.tmp" "$(srcdir)/$@" + +.dot.eps: + $(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \ + mv "$(srcdir)/$@.tmp" "$(srcdir)/$@" + +.png.eps: + $(AM_V_GEN)convert "$<" "$@-tmp.eps"; \ + mv "$@-tmp.eps" "$@" + +# We cannot add new dependencies to `doc/guix.pdf' & co. (info "(automake) +# Extending"). Using the `-local' rules is imperfect, because they may be +# triggered after the main rule. Oh, well. +pdf-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.pdf) +info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png) +ps-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps) \ + $(top_srcdir)/doc/images/coreutils-size-map.eps +dvi-local: ps-local + +## ----------- ## +## Man pages. ## +## ----------- ## + +# The man pages are generated using GNU Help2man. In makefiles rules they +# depend not on the binary, but on the source files. This usage allows a +# manual page to be generated by the maintainer and included in the +# distribution without requiring the end-user to have 'help2man' installed. +# They are built in $(srcdir) like info manuals. + +sub_commands_mans = \ + $(srcdir)/doc/guix-archive.1 \ + $(srcdir)/doc/guix-build.1 \ + $(srcdir)/doc/guix-challenge.1 \ + $(srcdir)/doc/guix-download.1 \ + $(srcdir)/doc/guix-edit.1 \ + $(srcdir)/doc/guix-environment.1 \ + $(srcdir)/doc/guix-gc.1 \ + $(srcdir)/doc/guix-hash.1 \ + $(srcdir)/doc/guix-import.1 \ + $(srcdir)/doc/guix-lint.1 \ + $(srcdir)/doc/guix-package.1 \ + $(srcdir)/doc/guix-publish.1 \ + $(srcdir)/doc/guix-pull.1 \ + $(srcdir)/doc/guix-refresh.1 \ + $(srcdir)/doc/guix-size.1 \ + $(srcdir)/doc/guix-system.1 + +dist_man1_MANS = \ + $(srcdir)/doc/guix.1 \ + $(sub_commands_mans) + +gen_man = \ + LANGUAGE= $(top_builddir)/pre-inst-env $(HELP2MAN) \ + $(HELP2MANFLAGS) + +HELP2MANFLAGS = --source=GNU --info-page=$(PACKAGE_TARNAME) + +$(srcdir)/doc/guix.1: scripts/guix.in $(sub_commands_mans) + -$(AM_V_HELP2MAN)$(gen_man) --output="$@" `basename "$@" .1` + +# The 'case' ensures the man pages are only generated if the corresponding +# source script (the first prerequisite) has been changed. The $(GOBJECTS) +# prerequisite is solely meant to force these docs to be made only after all +# Guile modules have been compiled. +$(srcdir)/doc/guix-%.1: guix/scripts/%.scm $(GOBJECTS) + -@case '$?' in \ + *$<*) $(AM_V_P) && set -x || echo " HELP2MAN $@"; \ + $(gen_man) --output="$@" "guix $*";; \ + *) : ;; \ + esac + +if BUILD_DAEMON + +dist_man1_MANS += $(srcdir)/doc/guix-daemon.1 + +$(srcdir)/doc/guix-daemon.1: nix/nix-daemon/guix-daemon.cc + -$(AM_V_HELP2MAN)$(gen_man) --output="$@" `basename "$@" .1` + +endif |