@copying
Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014 Andreas Enge@*
-Copyright @copyright{} 2013 Nikita Karetnikov
+Copyright @copyright{} 2013 Nikita Karetnikov@*
+Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
Installation
+* Binary Installation:: Getting Guix running in no time!
* Requirements:: Software needed to build and run Guix.
* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
+* Running Guix Before It Is Installed:: Hacker tricks.
Setting Up the Daemon
* The Store Monad:: Purely functional interface to the store.
* G-Expressions:: Manipulating build expressions.
+Defining Packages
+
+* package Reference:: The package data type.
+* origin Reference:: The origin data type.
+
Utilities
* Invoking guix build:: Building packages from the command line.
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
+* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
* Base Services:: Essential system services.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
+* Desktop Services:: D-Bus and desktop services.
+* Database Services:: SQL databases.
* Various Services:: Other services.
Packaging Guidelines
* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
+* Running Guix Before It Is Installed:: Hacker tricks.
@end menu
@node Binary Installation
would overwrite its own essential files.
@item
-Create the group and user accounts for build users as explained below
-(@pxref{Build Environment Setup}), and run the daemon:
+Run the daemon:
@example
-# /root/.guix-profile/bin/guix-daemon --build-users-group=guix-builder
+# /root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
@end example
@item
@example
# mkdir -p /usr/local/bin
# cd /usr/local/bin
-# ln -s /root/.guix-profile/bin/guix
+# ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
@end example
@item
following packages are also needed:
@itemize
-@item @url{http://sqlite.org, SQLite 3}
-@item @url{http://www.bzip.org, libbz2}
-@item @url{http://gcc.gnu.org, GCC's g++}
+@item @url{http://sqlite.org, SQLite 3};
+@item @url{http://www.bzip.org, libbz2};
+@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
+C++11 standard.
@end itemize
When a working installation of @url{http://nixos.org/nix/, the Nix package
@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
@example
-# groupadd --system guix-builder
-# for i in `seq 1 10`;
+# groupadd --system guixbuild
+# for i in `seq -w 1 10`;
do
- useradd -g guix-builder -G guix-builder \
- -d /var/empty -s `which nologin` \
- -c "Guix build user $i" --system \
- guix-builder$i;
+ useradd -g guixbuild -G guixbuild \
+ -d /var/empty -s `which nologin` \
+ -c "Guix build user $i" --system \
+ guixbuilder$i;
done
@end example
The @code{guix-daemon} program may then be run as @code{root} with:
@example
-# guix-daemon --build-users-group=guix-builder
+# guix-daemon --build-users-group=guixbuild
@end example
@cindex chroot
@noindent
This way, the daemon starts build processes in a chroot, under one of
-the @code{guix-builder} users. On GNU/Linux, by default, the chroot
+the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
environment contains nothing but:
@c Keep this list in sync with libstore/build.cc! -----------------------
a writable @file{/tmp} directory.
@end itemize
-If you are installing Guix as an unprivileged user, it is still
-possible to run @command{guix-daemon}. However, build processes will
-not be isolated from one another, and not from the rest of the system.
-Thus, build processes may interfere with each other, and may access
-programs, libraries, and other files available on the system---making it
-much harder to view them as @emph{pure} functions.
+If you are installing Guix as an unprivileged user, it is still possible
+to run @command{guix-daemon} provided you pass @code{--disable-chroot}.
+However, build processes will not be isolated from one another, and not
+from the rest of the system. Thus, build processes may interfere with
+each other, and may access programs, libraries, and other files
+available on the system---making it much harder to view them as
+@emph{pure} functions.
@node Daemon Offload Setup
is normally run as @code{root} like this:
@example
-# guix-daemon --build-users-group=guix-builder
+# guix-daemon --build-users-group=guixbuild
@end example
@noindent
Disable chroot builds.
Using this option is not recommended since, again, it would allow build
-processes to gain access to undeclared dependencies.
+processes to gain access to undeclared dependencies. It is necessary,
+though, when @command{guix-daemon} is running under an unprivileged user
+account.
@item --disable-log-compression
Disable compression of the build logs.
daemons on the same machine.
@end table
+@node Running Guix Before It Is Installed
+@section Running Guix Before It Is Installed
+
+If you are hacking Guix itself---which is a good idea!---you will find
+it useful to test the changes made in your local source tree checkout
+without actually installing them.
+
+To that end, all the command-line tools can be used even if you have not
+run @command{make install}. To do that, prefix each command with
+@command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
+top build tree of Guix), as in:
+
+@example
+$ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
+$ ./pre-inst-env guix build hello
+@end example
+
+@noindent
+Similarly, for a Guile session using the Guix modules:
+
+@example
+$ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
+@end example
+
+The @command{pre-inst-env} script sets up all the environment variables
+necessary to support this, including @code{PATH} and
+@code{GUILE_LOAD_PATH}.
+
+If you are hacking Guix from Emacs using the wonderful Geiser
+(@pxref{Introduction,,, geiser, Geiser User Manual}), make sure to
+augment Guile's load path so that it finds source files from your
+checkout:
+
+@lisp
+;; Assuming the Guix checkout is in ~/src/guix.
+(add-to-list 'geiser-guile-load-path "~/src/guix")
+@end lisp
+
@c *********************************************************************
@node Package Management
Primarily, @var{options} specifies the operations to be performed during
the transaction. Upon completion, a new profile is created, but
-previous generations of the profile remain available, should the user
+previous @dfn{generations} of the profile remain available, should the user
want to roll back.
For example, to remove @code{lua} and install @code{guile} and
guix package -r lua -i guile guile-cairo
@end example
+@command{guix package} also supports a @dfn{declarative approach}
+whereby the user specifies the exact set of packages to be available and
+passes it @i{via} the @option{--manifest} option
+(@pxref{profile-manifest, @option{--manifest}}).
+
For each user, a symlink to the user's default profile is automatically
created in @file{$HOME/.guix-profile}. This symlink always points to the
current generation of the user's default profile. Thus, users can add
@cindex propagated inputs
Sometimes packages have @dfn{propagated inputs}: these are dependencies
-that automatically get installed along with the required package.
+that automatically get installed along with the required package
+(@pxref{package-propagated-inputs, @code{propagated-inputs} in
+@code{package} objects}, for information about propagated inputs in
+package definitions).
+@anchor{package-cmd-propagated-inputs}
An example is the GNU MPC library: its C header files refer to those of
the GNU MPFR library, which in turn refer to those of the GMP library.
Thus, when installing MPC, the MPFR and GMP libraries also get installed
$ guix package --upgrade . --do-not-upgrade emacs
@end example
+@item @anchor{profile-manifest}--manifest=@var{file}
+@itemx -m @var{file}
+@cindex profile declaration
+@cindex profile manifest
+Create a new generation of the profile from the manifest object
+returned by the Scheme code in @var{file}.
+
+This allows you to @emph{declare} the profile's contents rather than
+constructing it through a sequence of @code{--install} and similar
+commands. The advantage is that @var{file} can be put under version
+control, copied to different machines to reproduce the same profile, and
+so on.
+
+@c FIXME: Add reference to (guix profile) documentation when available.
+@var{file} must return a @dfn{manifest} object, which is roughly a list
+of packages:
+
+@findex packages->manifest
+@example
+(use-package-modules guile emacs)
+
+(packages->manifest
+ (list emacs
+ guile-2.0
+ ;; Use a specific package output.
+ (list guile-2.0 "debug")))
+@end example
+
@item --roll-back
Roll back to the previous @dfn{generation} of the profile---i.e., undo
the last transaction.
not make a zeroth generation, so if a specified generation does not
exist, the current generation will not be changed.
-@item --search-paths
+@item --search-paths[=@var{kind}]
@cindex search paths
Report environment variable definitions, in Bash syntax, that may be
needed in order to use the set of installed packages. These environment
suggest setting these variables to @code{@var{profile}/include} and
@code{@var{profile}/lib}, respectively.
+The typical use case is to define these environment variables in the
+shell:
+
+@example
+$ eval `guix package --search-paths`
+@end example
+
+@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
+meaning that the returned environment variable definitions will either
+be exact settings, or prefixes or suffixes of the current value of these
+variables. When omitted, @var{kind} defaults to @code{exact}.
+
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
arguments. This fails if some of the files are not in the store, or if
they are still live.
+@item --optimize
+@cindex deduplication
+Optimize the store by hard-linking identical files---this is
+@dfn{deduplication}.
+
+The daemon performs deduplication after each successful build or archive
+import, unless it was started with @code{--disable-deduplication}
+(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
+this option is primarily useful when the daemon was running with
+@code{--disable-deduplication}.
+
@item --list-dead
Show the list of dead files and directories still present in the
store---i.e., files and directories no longer reachable from any root.
@itemize
@item
-The @code{source} field of the package is an @code{<origin>} object.
+The @code{source} field of the package is an @code{<origin>} object
+(@pxref{origin Reference}, for the complete reference).
Here, the @code{url-fetch} method from @code{(guix download)} is used,
meaning that the source is a file to be downloaded over FTP or HTTP.
unavailable to the build process, possibly leading to a build failure.
@end itemize
+@xref{package Reference}, for a full description of possible fields.
+
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}). @xref{Packaging Guidelines}, for
Configure and Build System}).
@end deffn
+@menu
+* package Reference :: The package data type.
+* origin Reference:: The origin data type.
+@end menu
+
+
+@node package Reference
+@subsection @code{package} Reference
+
+This section summarizes all the options available in @code{package}
+declarations (@pxref{Defining Packages}).
+
+@deftp {Data Type} package
+This is the data type representing a package recipe.
+
+@table @asis
+@item @code{name}
+The name of the package, as a string.
+
+@item @code{version}
+The version of the package, as a string.
+
+@item @code{source}
+An origin object telling how the source code for the package should be
+acquired (@pxref{origin Reference}).
+
+@item @code{build-system}
+The build system that should be used to build the package (@pxref{Build
+Systems}).
+
+@item @code{arguments} (default: @code{'()})
+The arguments that should be passed to the build system. This is a
+list, typically containing sequential keyword-value pairs.
+
+@item @code{inputs} (default: @code{'()})
+Package or derivation inputs to the build. This is a list of lists,
+where each list has the name of the input (a string) as its first
+element, a package or derivation object as its second element, and
+optionally the name of the output of the package or derivation that
+should be used, which defaults to @code{"out"}.
+
+@item @anchor{package-propagated-inputs}@code{propagated-inputs} (default: @code{'()})
+@cindex propagated inputs
+This field is like @code{inputs}, but the specified packages will be
+force-installed alongside the package they belong to
+(@pxref{package-cmd-propagated-inputs, @command{guix package}}, for
+information on how @command{guix package} deals with propagated inputs.)
+
+For example this is necessary when a library needs headers of another
+library to compile, or needs another shared library to be linked
+alongside itself when a program wants to link to it.
+
+@item @code{native-inputs} (default: @code{'()})
+This field is like @code{inputs}, but in case of a cross-compilation it
+will be ensured that packages for the architecture of the build machine
+are present, such that executables from them can be used during the
+build.
+
+This is typically where you would list tools needed at build time but
+not at run time, such as Autoconf, Automake, pkg-config, Gettext, or
+Bison. @command{guix lint} can report likely mistakes in this area
+(@pxref{Invoking guix lint}).
+
+@item @code{self-native-input?} (default: @code{#f})
+This is a Boolean field telling whether the package should use itself as
+a native input when cross-compiling.
+
+@item @code{outputs} (default: @code{'("out")})
+The list of output names of the package. @xref{Packages with Multiple
+Outputs}, for typical uses of additional outputs.
+
+@item @code{native-search-paths} (default: @code{'()})
+@itemx @code{search-paths} (default: @code{'()})
+A list of @code{search-path-specification} objects describing
+search-path environment variables honored by the package.
+
+@item @code{replacement} (default: @code{#f})
+This must either @code{#f} or a package object that will be used as a
+@dfn{replacement} for this package. @xref{Security Updates, grafts},
+for details.
+
+@item @code{synopsis}
+A one-line description of the package.
+
+@item @code{description}
+A more elaborate description of the package.
+
+@item @code{license}
+The license of the package; a value from @code{(guix licenses)}.
+
+@item @code{home-page}
+The URL to the home-page of the package, as a string.
+
+@item @code{supported-systems} (default: @var{%supported-systems})
+The list of systems supported by the package, as strings of the form
+@code{architecture-kernel}, for example @code{"x86_64-linux"}.
+
+@item @code{maintainers} (default: @code{'()})
+The list of maintainers of the package, as @code{maintainer} objects.
+
+@item @code{location} (default: source location of the @code{package} form)
+The source location of the package. It's useful to override this when
+inheriting from another package, in which case this field is not
+automatically corrected.
+@end table
+@end deftp
+
+
+@node origin Reference
+@subsection @code{origin} Reference
+
+This section summarizes all the options available in @code{origin}
+declarations (@pxref{Defining Packages}).
+
+@deftp {Data Type} origin
+This is the data type representing a source code origin.
+
+@table @asis
+@item @code{uri}
+An object containing the URI of the source. The object type depends on
+the @code{method} (see below). For example, when using the
+@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
+values are: a URL represented as a string, or a list thereof.
+
+@item @code{method}
+A procedure that will handle the URI.
+
+Examples include:
+
+@table @asis
+@item @var{url-fetch} from @code{(guix download)}
+download a file the HTTP, HTTPS, or FTP URL specified in the
+@code{uri} field;
+
+@item @var{git-fetch} from @code{(guix git-download)}
+clone the Git version control repository, and check out the revision
+specified in the @code{uri} field as a @code{git-reference} object; a
+@code{git-reference} looks like this:
+
+@example
+(git-reference
+ (url "git://git.debian.org/git/pkg-shadow/shadow")
+ (commit "v4.1.5.1"))
+@end example
+@end table
+
+@item @code{sha256}
+A bytevector containing the SHA-256 hash of the source. Typically the
+@code{base32} form is used here to generate the bytevector from a
+base-32 string.
+
+@item @code{file-name} (default: @code{#f})
+The file name under which the source code should be saved. When this is
+@code{#f}, a sensible default value will be used in most cases. In case
+the source is fetched from a URL, the file name from the URL will be
+used. For version control checkouts, it's recommended to provide the
+file name explicitly because the default is not very descriptive.
+
+@item @code{patches} (default: @code{'()})
+A list of file names containing patches to be applied to the source.
+
+@item @code{snippet} (default: @code{#f})
+A quoted piece of code that will be run in the source directory to make
+any modifications, which is sometimes more convenient than a patch.
+
+@item @code{patch-flags} (default: @code{'("-p1")})
+A list of command-line flags that should be passed to the @code{patch}
+command.
+
+@item @code{patch-inputs} (default: @code{#f})
+Input packages or derivations to the patching process. When this is
+@code{#f}, the usual set of inputs necessary for patching are provided,
+such as GNU@tie{}Patch.
+
+@item @code{modules} (default: @code{'()})
+A list of Guile modules that should be loaded during the patching
+process and while running the code in the @code{snippet} field.
+
+@item @code{imported-modules} (default: @code{'()})
+The list of Guile modules to import in the patch derivation, for use by
+the @code{snippet}.
+
+@item @code{patch-guile} (default: @code{#f})
+The Guile package that should be used in the patching process. When
+this is @code{#f}, a sensible default is used.
+@end table
+@end deftp
+
@node Build Systems
@section Build Systems
not found, the build system looks for @code{Setup.lhs} instead.
Which Haskell compiler is used can be specified with the @code{#:haskell}
-parameter which defaults to @code{ghc}.
+parameter which defaults to @code{ghc}.
@end defvr
Lastly, for packages that do not need anything as sophisticated, a
processes that use them.
@end itemize
-Actually this mechanism is not limited to package and derivation
-objects; @dfn{compilers} able to ``lower'' other high-level objects to
+This mechanism is not limited to package and derivation
+objects: @dfn{compilers} able to ``lower'' other high-level objects to
derivations can be defined, such that these objects can also be inserted
-into gexps. Another useful type of high-level object that can be
-inserted in a gexp is @dfn{local files}, which allows files from the
-local file system to be added to the store and referred to by
-derivations and such (see @code{local-file} below.)
+into gexps. For example, a useful type of high-level object that can be
+inserted in a gexp is ``file-like objects'', which make it easy to
+add files to the store and refer to them in
+derivations and such (see @code{local-file} and @code{plain-file}
+below.)
To illustrate the idea, here is an example of a gexp:
The other arguments are as for @code{derivation} (@pxref{Derivations}).
@end deffn
+@cindex file-like objects
+The @code{local-file} and @code{plain-file} procedures below return
+@dfn{file-like objects}. That is, when unquoted in a G-expression,
+these objects lead to a file in the store. Consider this G-expression:
+
+@example
+#~(system* (string-append #$glibc "/sbin/nscd") "-f"
+ #$(local-file "/tmp/my-nscd.conf"))
+@end example
+
+The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
+to the store. Once expanded, for instance @i{via}
+@code{gexp->derivation}, the G-expression refers to that copy under
+@file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
+does not have any effect on what the G-expression does.
+@code{plain-file} can be used similarly; it differs in that the file
+content is directly passed as a string.
+
@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
[#:recursive? #t]
Return an object representing local file @var{file} to add to the store; this
procedure (@pxref{The Store Monad, @code{interned-file}}).
@end deffn
+@deffn {Scheme Procedure} plain-file @var{name} @var{content}
+Return an object representing a text file called @var{name} with the given
+@var{content} (a string) to be added to the store.
+
+This is the declarative counterpart of @code{text-file}.
+@end deffn
+
@deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
Return an executable script @var{name} that runs @var{exp} using
@var{guile} with @var{modules} in its search path.
@item -E @var{command}
Execute @var{command} in the new environment.
+@item --ad-hoc
+Include all specified packages in the resulting environment, as if an
+@i{ad hoc} package were defined with them as inputs. This option is
+useful for quickly creating an environment without having to write a
+package expression to contain the desired inputs.
+
+For instance, the command:
+
+@example
+guix environment --ad-hoc guile guile-sdl -E guile
+@end example
+
+runs @command{guile} in an environment where Guile and Guile-SDL are
+available.
+
@item --pure
Unset existing environment variables when building the new environment.
This has the effect of creating an environment in which search paths
@enumerate
@item
-Configure the network, by running @command{dhclient eno1} (to get an
-automatically assigned IP address from the wired network interface
-controller@footnote{
+Configure the network, by running @command{ifconfig eno1 up && dhclient
+eno1} (to get an automatically assigned IP address from the wired
+network interface controller@footnote{
@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
The name @code{eno1} is for the first on-board Ethernet controller. The
interface name for an Ethernet controller that is in the first slot of
@table @asis
@item @code{kernel} (default: @var{linux-libre})
-The package object of the operating system to use@footnote{Currently
+The package object of the operating system kernel to use@footnote{Currently
only the Linux-libre kernel is supported. In the future, it will be
possible to use the GNU@tie{}Hurd.}.
(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
For example, @code{'("/dev/sda3")}.
-@item @code{users} (default: @code{'()})
+@item @code{users} (default: @code{%base-user-accounts})
@itemx @code{groups} (default: @var{%base-groups})
List of user accounts and groups. @xref{User Accounts}.
@item @code{sudoers} (default: @var{%sudoers-specification})
@cindex sudoers
-The contents of the @file{/etc/sudoers} file as a string.
+The contents of the @file{/etc/sudoers} file as a file-like object
+(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
This file specifies which users can use the @command{sudo} command, what
they are allowed to do, and what privileges they may gain. The default
specific devices such as ``audio'', ``disk'', and ``cdrom''.
@end defvr
+@defvr {Scheme Variable} %base-user-accounts
+This is the list of basic system accounts that programs may expect to
+find on a GNU/Linux system, such as the ``nobody'' account.
+
+Note that the ``root'' account is not included here. It is a
+special-case and is automatically added whether or not it is specified.
+@end defvr
+
@node Locales
@subsection Locales
@end defvr
@deffn {Monadic Procedure} xorg-start-command [#:guile] @
- [#:drivers '()] [#:resolutions '()] [#:xorg-server @var{xorg-server}]
+ [#:configuration-file #f] [#:xorg-server @var{xorg-server}]
Return a derivation that builds a @var{guile} script to start the X server
-from @var{xorg-server}. Usually the X server is started by a login manager.
+from @var{xorg-server}. @var{configuration-file} is the server configuration
+file or a derivation that builds it; when omitted, the result of
+@code{xorg-configuration-file} is used.
+
+Usually the X server is started by a login manager.
+@end deffn
+
+@deffn {Monadic Procedure} xorg-configuration-file @
+ [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
+Return a configuration file for the Xorg server containing search paths for
+all the common drivers.
@var{drivers} must be either the empty list, in which case Xorg chooses a
graphics driver automatically, or a list of driver names that will be tried in
-this order---e.g., @code{("modesetting" "vesa")}.
+this order---e.g., @code{(\"modesetting\" \"vesa\")}.
Likewise, when @var{resolutions} is the empty list, Xorg chooses an
appropriate screen resolution; otherwise, it must be a list of
resolutions---e.g., @code{((1024 768) (640 480))}.
+
+Last, @var{extra-config} is a list of strings or objects appended to the
+@code{text-file*} argument list. It is used to pass extra text to be added
+verbatim to the configuration file.
@end deffn
@node Desktop Services
of the given @var{size}. @var{size} may be a number of bytes, or it may
include a unit as a suffix (@pxref{Block size, size specifications,,
coreutils, GNU Coreutils}).
+
+@item --on-error=@var{strategy}
+Apply @var{strategy} when an error occurs when reading @var{file}.
+@var{strategy} may be one of the following:
+
+@table @code
+@item nothing-special
+Report the error concisely and exit. This is the default strategy.
+
+@item backtrace
+Likewise, but also display a backtrace.
+
+@item debug
+Report the error and enter Guile's debugger. From there, you can run
+commands such as @code{,bt} to get a backtrace, @code{,locals} to
+display local variable values, and more generally inspect the program's
+state. @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for
+a list of available debugging commands.
+@end table
@end table
Note that all the actions above, except @code{build} and @code{init},
@cindex package module search path
Users can store package definitions in modules with different
names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
-name and module name must match. @xref{Modules and the File System,,,
-guile, GNU Guile Reference Manual}, for details.} These package definitions
+name and module name must match. For instance, the @code{(my-packages
+emacs)} module must be stored in a @file{my-packages/emacs.scm} file
+relative to the load path specified with @option{--load-path} or
+@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
+guile, GNU Guile Reference Manual}, for details.}. These package definitions
will not be visible by default. Thus, users can invoke commands such as
@command{guix package} and @command{guix build} have to be used with the
-@code{-e} option so that they know where to find the package, or use the
+@code{-e} option so that they know where to find the package. Better
+yet, they can use the
@code{-L} option of these commands to make those modules visible
(@pxref{Invoking guix build, @code{--load-path}}), or define the
@code{GUIX_PACKAGE_PATH} environment variable. This environment
Once a package definition is in place, stored in a file in the Guix
source tree, it can be tested using the @command{guix build} command
(@pxref{Invoking guix build}). For example, assuming the new package is
-called @code{gnew}, you may run this command from the Guix build tree:
+called @code{gnew}, you may run this command from the Guix build tree
+(@pxref{Running Guix Before It Is Installed}):
@example
./pre-inst-env guix build gnew --keep-failed
HCoop / jackhill / guix / guix.git / blobdiff