diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 32 | ||||
| -rw-r--r-- | doc/guix.texi | 140 | ||||
| -rw-r--r-- | doc/htmlxref.cnf | 4 |
3 files changed, 151 insertions, 25 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index bbc93424b4..925c584e42 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -248,7 +248,10 @@ please do read it. Some special forms introduced in Guix, such as the @code{substitute*} macro, have special indentation rules. These are defined in the -@file{.dir-locals.el} file, which Emacs automatically uses. +@file{.dir-locals.el} file, which Emacs automatically uses. Also note +that Emacs-Guix provides @code{guix-devel-mode} mode that indents and +highlights Guix code properly (@pxref{Development,,, emacs-guix, The +Emacs-Guix Reference Manual}). @cindex indentation, of code @cindex formatting, of code @@ -342,9 +345,30 @@ For important changes, check that dependent package (if applicable) are not affected by the change; @code{guix refresh --list-dependent @var{package}} will help you do that (@pxref{Invoking guix refresh}). -Packages with roughly 100 dependents or more usually have to be -committed to a separate branch. That branch can then be built -separately by our build farm, and later merged into @code{master} once +@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. +@cindex branching strategy +@cindex rebuild scheduling strategy +Depending on the number of dependent packages and thus the amount of +rebuilding induced, commits go to different branches, along these lines: + +@table @asis +@item 300 dependent packages or less +@code{master} branch (non-disruptive changes). + +@item between 300 and 1,200 dependent packages +@code{staging} branch (non-disruptive changes). This branch is intended +to be merged in @code{master} every 3 weeks or so. Topical changes +(e.g., an update of the GNOME stack) can instead go to a specific branch +(say, @code{gnome-updates}). + +@item more than 1,200 dependent packages +@code{core-updates} branch (may include major and potentially disruptive +changes). This branch is intended to be merged in @code{master} every +2.5 months or so. +@end table + +All these branches are tracked by our build farm +and merged into @code{master} once everything has been successfully built. This allows us to fix issues before they hit users, and to reduce the window during which pre-built binaries are not available. diff --git a/doc/guix.texi b/doc/guix.texi index 957ce2bab3..5227ad4ba0 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -34,7 +34,8 @@ Copyright @copyright{} 2017 Clément Lassieur@* Copyright @copyright{} 2017 Mathieu Othacehe@* Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017 Carlo Zancanaro@* -Copyright @copyright{} 2017 Thomas Danckaert +Copyright @copyright{} 2017 Thomas Danckaert@* +Copyright @copyright{} 2017 humanitiesNerd Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -1429,11 +1430,13 @@ remove software packages, without having to know about their build procedures or dependencies. Guix also goes beyond this obvious set of features. -This chapter describes the main features of Guix, as well as the package -management tools it provides. Along with the command-line interface -described below (@pxref{Invoking guix package, @code{guix package}}), -you may also use Emacs Interface, after installing @code{emacs-guix} -package (run @kbd{M-x guix-help} command to start with it): +This chapter describes the main features of Guix, as well as the +package management tools it provides. Along with the command-line +interface described below (@pxref{Invoking guix package, @code{guix +package}}), you may also use Emacs Interface (@pxref{Top,,, +emacs-guix, The Emacs-Guix Reference Manual}), after installing +@code{emacs-guix} package (run @kbd{M-x guix-help} command to start +with it): @example guix package -i emacs-guix @@ -2387,13 +2390,13 @@ For example, to download and deploy version 0.12.0 of Guix from the canonical Git repo: @example -guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/v0.12.0.tar.gz +guix pull --url=https://git.savannah.gnu.org/cgit/guix.git/snapshot/v0.12.0.tar.gz @end example It can also be used to deploy arbitrary Git revisions: @example -guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/74d862e8a.tar.gz +guix pull --url=https://git.savannah.gnu.org/cgit/guix.git/snapshot/74d862e8a.tar.gz @end example @item --bootstrap @@ -2401,6 +2404,8 @@ Use the bootstrap Guile to build the latest Guix. This option is only useful to Guix developers. @end table +In addition, @command{guix pull} supports all the common build options +(@pxref{Common Build Options}). @node Invoking guix pack @section Invoking @command{guix pack} @@ -2879,7 +2884,8 @@ unavailable to the build process, possibly leading to a build failure. Once a package definition is in place, the package may actually be built using the @code{guix build} command-line -tool (@pxref{Invoking guix build}). You can easily jump back to the +tool (@pxref{Invoking guix build}), troubleshooting any build failures +you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the package definition using the @command{guix edit} command (@pxref{Invoking guix edit}). @xref{Packaging Guidelines}, for @@ -3321,7 +3327,8 @@ 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. +archive. In this case the parameter @code{#:source-dir} can be used to +specify the source sub-directory, defaulting to ``src''. 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 @@ -4832,6 +4839,7 @@ described in the subsections below. * Common Build Options:: Build options for most commands. * Package Transformation Options:: Creating variants of packages. * Additional Build Options:: Options specific to 'guix build'. +* Debugging Build Failures:: Real life packaging experience @end menu @node Common Build Options @@ -4857,6 +4865,8 @@ the command-line tools. Keep the build tree of failed builds. Thus, if a build fails, its build tree is kept under @file{/tmp}, in a directory whose name is shown at the end of the build log. This is useful when debugging build issues. +@xref{Debugging Build Failures}, for tips and tricks on how to debug +build issues. @item --keep-going @itemx -k @@ -5244,6 +5254,82 @@ https://hydra.gnu.org/log/@dots{}-gdb-7.10 You can freely access a huge library of build logs! @end table +@node Debugging Build Failures +@subsection Debugging Build Failures + +@cindex build failures, debugging +When defining a new package (@pxref{Defining Packages}), you will +probably find yourself spending some time debugging and tweaking the +build until it succeeds. To do that, you need to operate the build +commands yourself in an environment as close as possible to the one the +build daemon uses. + +To that end, the first thing to do is to use the @option{--keep-failed} +or @option{-K} option of @command{guix build}, which will keep the +failed build tree in @file{/tmp} or whatever directory you specified as +@code{TMPDIR} (@pxref{Invoking guix build, @code{--keep-failed}}). + +From there on, you can @command{cd} to the failed build tree and source +the @file{environment-variables} file, which contains all the +environment variable definitions that were in place when the build +failed. So let's say you're debugging a build failure in package +@code{foo}; a typical session would look like this: + +@example +$ guix build foo -K +@dots{} @i{build fails} +$ cd /tmp/guix-build-foo.drv-0 +$ source ./environment-variables +$ cd foo-1.2 +@end example + +Now, you can invoke commands as if you were the daemon (almost) and +troubleshoot your build process. + +Sometimes it happens that, for example, a package's tests pass when you +run them manually but they fail when the daemon runs them. This can +happen because the daemon runs builds in containers where, unlike in our +environment above, network access is missing, @file{/bin/sh} does not +exist, etc. (@pxref{Build Environment Setup}). + +In such cases, you may need to run inspect the build process from within +a container similar to the one the build daemon creates: + +@example +$ guix build -K foo +@dots{} +$ cd /tmp/guix-build-foo.drv-0 +$ guix environment -C foo --ad-hoc strace gdb +[env]# source ./environment-variables +[env]# cd foo-1.2 +@end example + +Here, @command{guix environment -C} creates a container and spawns a new +shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc +strace gdb} part adds the @command{strace} and @command{gdb} commands to +the container, which would may find handy while debugging. + +To get closer to a container like that used by the build daemon, we can +remove @file{/bin/sh}: + +@example +[env]# rm /bin/sh +@end example + +(Don't worry, this is harmless: this is all happening in the throw-away +container created by @command{guix environment}.) + +The @command{strace} command is probably not in the search path, but we +can run: + +@example +[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check +@end example + +In this way, not only you will have reproduced the environment variables +the daemon uses, you will also be running the build process in a container +similar to the one the daemon uses. + @node Invoking guix edit @section Invoking @command{guix edit} @@ -5852,7 +5938,7 @@ an upgrade. More rebuilds might be required under some circumstances. @example $ guix refresh --list-dependent flex Building the following 120 packages would ensure 213 dependent packages are rebuilt: -hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{} +hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{} @end example The command above lists a set of packages that could be built to check @@ -6111,7 +6197,9 @@ provides a visual representation of the DAG. By default, @uref{http://www.graphviz.org/, Graphviz}, so its output can be passed directly to the @command{dot} command of Graphviz. It can also emit an HTML page with embedded JavaScript code to display a ``chord diagram'' -in a Web browser, using the @uref{https://d3js.org/, d3.js} library. +in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or +emit Cypher queries to construct a graph in a graph database supporting +the @uref{http://www.opencypher.org/, openCypher} query language. The general syntax is: @example @@ -7118,15 +7206,15 @@ get a feel of what that means.) Support for the Logical Volume Manager (LVM) is missing. @item -Few system services are currently supported out-of-the-box -(@pxref{Services}). +More and more system services are provided (@pxref{Services}), but some +may be missing. @item -More than 5,000 packages are available, but you may +More than 5,300 packages are available, but you may occasionally find that a useful package is missing. @item -GNOME, Xfce, and Enlightenment are available (@pxref{Desktop Services}), +GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}), as well as a number of X11 window managers. However, some graphical applications may be missing, as well as KDE. @end itemize @@ -7678,7 +7766,19 @@ provides all the tools one would expect for basic user and administrator tasks---including the GNU Core Utilities, the GNU Networking Utilities, the GNU Zile lightweight text editor, @command{find}, @command{grep}, etc. The example above adds tcpdump to those, taken from the @code{(gnu -packages admin)} module (@pxref{Package Modules}). +packages admin)} module (@pxref{Package Modules}). The +@code{(list package output)} syntax can be used to add a specific output +of a package: + +@lisp +(use-modules (gnu packages)) +(use-modules (gnu packages dns)) + +(operating-system + ;; ... + (packages (cons (list bind "utils") + %base-packages))) +@end lisp @findex specification->package Referring to packages by variable name, like @var{tcpdump} above, has @@ -16281,9 +16381,9 @@ distribution: @smallexample $ guix lint -c cve -gnu/packages/base.scm:652:2: glibc-2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547 -gnu/packages/gcc.scm:334:2: gcc-4.9.3: probably vulnerable to CVE-2015-5276 -gnu/packages/image.scm:312:2: openjpeg-2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924 +gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547 +gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276 +gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924 @dots{} @end smallexample diff --git a/doc/htmlxref.cnf b/doc/htmlxref.cnf index 93e214fcc5..78f427bd07 100644 --- a/doc/htmlxref.cnf +++ b/doc/htmlxref.cnf @@ -219,7 +219,9 @@ emacs node ${EMACS}/html_node/emacs/ easejs mono ${GS}/easejs/manual/easejs.html easejs node ${GS}/easejs/manual/ -emacs-guix mono https://notabug.org/alezost/emacs-guix +EMACS_GUIX = https://alezost.github.io/guix.el/manual/latest +emacs-guix mono ${EMACS_GUIX}/emacs-guix.html +emacs-guix node ${EMACS_GUIX}/html_node/index.html emacs-muse node ${GS}/emacs-muse/manual/muse.html emacs-muse node ${GS}/emacs-muse/manual/html_node/ |