summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/emacs.texi75
-rw-r--r--doc/guix.texi110
-rw-r--r--doc/local.mk157
3 files changed, 304 insertions, 38 deletions
diff --git a/doc/emacs.texi b/doc/emacs.texi
index c4fdfff272..ed8896ad43 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
@@ -565,6 +547,51 @@ guix-packages-by-license} would do (@pxref{Emacs Commands}).
@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 9b7a0cb455..ab07d1066e 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
@@ -6039,6 +6051,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 +6248,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 +6447,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 +6709,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 +7299,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 +9369,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 +10795,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 +11037,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 +11286,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
generated by cgit v1.2.3 (git 2.50.1) at 2025-09-05 04:46:37 +0000