@item
Installing
@url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
-allow you to use the @command{guix import pypi} command; it is of
+allow you to use the @command{guix import pypi} command (@pxref{Invoking
+guix import}). It is of
interest primarily for developers and not for casual users.
@item
Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
@end example
@noindent
-For details on how to set it up, @ref{Setting Up the Daemon}.
+For details on how to set it up, @pxref{Setting Up the Daemon}.
@cindex chroot
@cindex container, build environment
own directory---something that resembles
@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
(note that Guix comes with an Emacs extension to shorten those file
-names, @ref{Emacs Prettify}.)
+names, @pxref{Emacs Prettify}.)
Instead of referring to these directories, users have their own
@dfn{profile}, which points to the packages that they actually want to
otherwise, it builds the package from source, locally
(@pxref{Substitutes}).
+Control over the build environment is a feature that is also useful for
+developers. The @command{guix environment} command allows developers of
+a package to quickly set up the right development environment for their
+package, without having to manually install the package's dependencies
+in their profile (@pxref{Invoking guix environment}).
+
@node Invoking guix package
@section Invoking @command{guix package}
@code{(guix packages)} module; for instance, @code{(package-name hello)}
returns---surprise!---@code{"hello"}.
+With luck, you may be able to import part or all of the definition of
+the package you are interested in from another repository, using the
+@code{guix import} command (@pxref{Invoking guix import}).
+
In the example above, @var{hello} is defined into a module of its own,
@code{(gnu packages hello)}. Technically, this is not strictly
necessary, but it is convenient to do so: all the packages defined in
unavailable to the build process, possibly leading to a build failure.
@end itemize
-Once a package definition is in place@footnote{Simple package
-definitions like the one above may be automatically converted from the
-Nixpkgs distribution using the @command{guix import} command.}, the
+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
more information on how to test package definitions, and
@ref{Invoking guix lint}, for information on how to check a definition
for style conformance.
-
Eventually, updating the package definition to a new upstream version
can be partly automated by the @command{guix refresh} command
(@pxref{Invoking guix refresh}).
create and manipulate them is provided by the @code{(guix build-system)}
module, and actual build systems are exported by specific modules.
+@cindex bag (low-level package representation)
Under the hood, build systems first compile package objects to
@dfn{bags}. A @dfn{bag} is like a package, but with less
ornamentation---in other words, a bag is a lower-level representation of
* Invoking guix build:: Building packages from the command line.
* Invoking guix download:: Downloading a file and printing its hash.
* Invoking guix hash:: Computing the cryptographic hash of a file.
+* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix environment:: Setting up development environments.
@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}. For more
-information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
+information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
@end table
@node Invoking guix hash
@end table
+@node Invoking guix import
+@section Invoking @command{guix import}
+
+@cindex importing packages
+@cindex package import
+@cindex package conversion
+The @command{guix import} command is useful for people willing to add a
+package to the distribution but who'd rather do as little work as
+possible to get there---a legitimate demand. The command knows of a few
+repositories from which it can ``import'' package meta-data. The result
+is a package definition, or a template thereof, in the format we know
+(@pxref{Defining Packages}).
+
+The general syntax is:
+
+@example
+guix import @var{importer} @var{options}@dots{}
+@end example
+
+@var{importer} specifies the source from which to import package
+meta-data, and @var{options} specifies a package identifier and other
+options specific to @var{importer}. Currently, the available
+``importers'' are:
+
+@table @code
+@item gnu
+Import meta-data for the given GNU package. This provides a template
+for the latest version of that GNU package, including the hash of its
+source tarball, and its canonical synopsis and description.
+
+Additional information such as the package's dependencies and its
+license needs to be figured out manually.
+
+For example, the following command returns a package definition for
+GNU@tie{}Hello:
+
+@example
+guix import gnu hello
+@end example
+
+Specific command-line options are:
+
+@table @code
+@item --key-download=@var{policy}
+As for @code{guix refresh}, specify the policy to handle missing OpenPGP
+keys when verifying the package's signature. @xref{Invoking guix
+refresh, @code{--key-download}}.
+@end table
+
+@item pypi
+@cindex pypi
+Import meta-data from the @uref{https://pypi.python.org/, Python Package
+Index}@footnote{This functionality requires Guile-JSON to be installed.
+@xref{Requirements}.}. Information is taken from the JSON-formatted
+description available at @code{pypi.python.org} and usually includes all
+the relevant information, including package dependencies.
+
+The command below imports meta-data for the @code{itsdangerous} Python
+package:
+
+@example
+guix import pypi itsdangerous
+@end example
+
+@item nix
+Import meta-data from a local copy of the source of the
+@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
+relies on the @command{nix-instantiate} command of
+@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
+typically written in a mixture of Nix-language and Bash code. This
+command only imports the high-level package structure that is written in
+the Nix language. It normally includes all the basic fields of a
+package definition.
+
+When importing a GNU package, the synopsis and descriptions are replaced
+by their canonical upstream variant.
+
+As an example, the command below imports the package definition of
+LibreOffice (more precisely, it imports the definition of the package
+bound to the @code{libreoffice} top-level attribute):
+
+@example
+guix import nix ~/path/to/nixpkgs libreoffice
+@end example
+@end table
+
+The structure of the @command{guix import} code is modular. It would be
+useful to have more importers for other package formats, and your help
+is welcome here (@pxref{Contributing}).
+
@node Invoking guix refresh
@section Invoking @command{guix refresh}
@item --update
@itemx -u
Update distribution source files (package recipes) in place.
-@ref{Defining Packages}, for more information on package definitions.
+@xref{Defining Packages}, for more information on package definitions.
@item --select=[@var{subset}]
@itemx -s @var{subset}
@table @code
-@item --key-server=@var{host}
-Use @var{host} as the OpenPGP key server when importing a public key.
-
@item --gpg=@var{command}
Use @var{command} as the GnuPG 2.x command. @var{command} is searched
for in @code{$PATH}.
+@item --key-download=@var{policy}
+Handle missing OpenPGP keys according to @var{policy}, which may be one
+of:
+
+@table @code
+@item always
+Always download missing OpenPGP keys from the key server, and add them
+to the user's GnuPG keyring.
+
+@item never
+Never try to download missing OpenPGP keys. Instead just bail out.
+
+@item interactive
+When a package signed with an unknown OpenPGP key is encountered, ask
+the user whether to download it or not. This is the default behavior.
+@end table
+
+@item --key-server=@var{host}
+Use @var{host} as the OpenPGP key server when importing a public key.
+
@end table
@node Invoking guix lint
@node Invoking guix environment
@section Invoking @command{guix environment}
+@cindex reproducible build environments
The purpose of @command{guix environment} is to assist hackers in
creating reproducible development environments without polluting their
package profile. The @command{guix environment} tool takes one or more
@end menu
Building this distribution is a cooperative effort, and you are invited
-to join! @ref{Contributing}, for information about how you can help.
+to join! @xref{Contributing}, for information about how you can help.
@node System Installation
@section System Installation
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
* Initial RAM Disk:: Linux-Libre bootstrapping.
+* GRUB Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
* Defining Services:: Adding new service definitions.
@end menu
%base-file-systems))
(users (list (user-account
(name "alice")
- (password "")
(uid 1000) (group 100)
(comment "Bob's sister")
(home-directory "/home/alice"))))
possible to use the GNU@tie{}Hurd.}.
@item @code{bootloader}
-The system bootloader configuration object.
-@c FIXME: Add xref to bootloader section.
+The system bootloader configuration object. @xref{GRUB Configuration}.
@item @code{initrd} (default: @code{base-initrd})
A two-argument monadic procedure that returns an initial RAM disk for
the Linux kernel. @xref{Initial RAM Disk}.
+@item @code{firmware} (default: @var{%base-firmware})
+@cindex firmware
+List of firmware packages loadable by the operating system kernel.
+
+The default includes firmware needed for Atheros-based WiFi devices
+(Linux-libre module @code{ath9k}.)
+
@item @code{host-name}
The host name.
graphical login managers do not list them.
@item @code{password} (default: @code{#f})
-Unless @code{#f}, this is the password to be used for the account.
+You would normally leave this field to @code{#f}, initialize user
+passwords as @code{root} with the @command{passwd} command, and then let
+users change it with @command{passwd}.
+
+If you @emph{do} want to have a preset password for an account, then
+this field must contain the encrypted password, as a string.
+@xref{crypt,,, The GNU C Library Reference Manual}, for more information
+on password encryption, and @ref{Encryption,,, GNU Guile Reference
+Manual}, for information on Guile's @code{crypt} procedure.
@end table
@end deftp
started by the @dfn{login manager}, currently SLiM.
@deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
- [#:auto-login? #f] [#:default-user ""] [#:startx]
+ [#:auto-login? #f] [#:default-user ""] [#:startx] @
+ [#:theme @var{%default-slim-theme}] @
+ [#:theme-name @var{%default-slim-theme-name}]
Return a service that spawns the SLiM graphical login manager, which in
turn starts the X display server with @var{startx}, a command as returned by
@code{xorg-start-command}.
When @var{allow-empty-passwords?} is true, allow logins with an empty
password. When @var{auto-login?} is true, log in automatically as
@var{default-user}.
+
+If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
+@var{theme} must be a gexp denoting the name of a directory containing the
+theme to use. In that case, @var{theme-name} specifies the name of the
+theme.
@end deffn
+@defvr {Scheme Variable} %default-theme
+@defvrx {Scheme Variable} %default-theme-name
+The G-Expression denoting the default SLiM theme and its name.
+@end defvr
+
@deffn {Monadic Procedure} xorg-start-command [#:guile] @
[#:drivers '()] [#:resolutions '()] [#:xorg-server @var{xorg-server}]
Return a derivation that builds a @var{guile} script to start the X server
initrd.
@end deffn
+@node GRUB Configuration
+@subsection GRUB Configuration
+
+@cindex GRUB
+@cindex boot loader
+
+The operating system uses GNU@tie{}GRUB as its boot loader
+(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
+configured using @code{grub-configuration} declarations. This data type
+is exported by the @code{(gnu system grub)} module, and described below.
+
+@deftp {Data Type} grub-configuration
+The type of a GRUB configuration declaration.
+
+@table @asis
+
+@item @code{device}
+This is a string denoting the boot device. It must be a device name
+understood by the @command{grub-install} command, such as
+@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
+GNU GRUB Manual}).
+
+@item @code{menu-entries} (default: @code{()})
+A possibly empty list of @code{menu-entry} objects (see below), denoting
+entries to appear in the GRUB boot menu, in addition to the current
+system entry and the entry pointing to previous system generations.
+
+@item @code{default-entry} (default: @code{0})
+The index of the default boot menu entry. Index 0 is for the current
+system's entry.
+
+@item @code{timeout} (default: @code{5})
+The number of seconds to wait for keyboard input before booting. Set to
+0 to boot immediately, and to -1 to wait indefinitely.
+
+@item @code{theme} (default: @var{%default-theme})
+The @code{grub-theme} object describing the theme to use.
+@end table
+
+@end deftp
+
+Should you want to list additional boot menu entries @i{via} the
+@code{menu-entries} field above, you will need to create them with the
+@code{menu-entry} form:
+
+@deftp {Data Type} menu-entry
+The type of an entry in the GRUB boot menu.
+
+@table @asis
+
+@item @code{label}
+The label to show in the menu---e.g., @code{"GNU System"}.
+
+@item @code{linux}
+The Linux kernel to boot.
+
+@item @code{linux-arguments} (default: @code{()})
+The list of extra Linux kernel command-line arguments---e.g.,
+@code{("console=ttyS0")}.
+
+@item @code{initrd}
+A G-Expression or string denoting the file name of the initial RAM disk
+to use (@pxref{G-Expressions}).
+
+@end table
+@end deftp
+
+@c FIXME: Write documentation once it's stable.
+Themes are created using the @code{grub-theme} form, which is not
+documented yet.
+
+@defvr {Scheme Variable} %default-theme
+This is the default GRUB theme used by the operating system, with a
+fancy background image displaying the GNU and Guix logos.
+@end defvr
+
+
@node Invoking guix system
@subsection Invoking @code{guix system}
entries for older configurations to a submenu---unless
@option{--no-grub} is passed.
+@c The paragraph below refers to the problem discussed at
+@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
+It is highly recommended to run @command{guix pull} once before you run
+@command{guix system reconfigure} for the first time (@pxref{Invoking
+guix pull}). Failing to do that you would see an older version of Guix
+once @command{reconfigure} has completed.
+
@item build
Build the operating system's derivation, which includes all the
configuration files and programs needed to boot and run the system.
distribution. The root of this dependency graph is a small set of
@dfn{bootstrap binaries}, provided by the @code{(gnu packages
bootstrap)} module. For more information on bootstrapping,
-@ref{Bootstrapping}.
+@pxref{Bootstrapping}.
@node Packaging Guidelines
@section Packaging Guidelines
and export that variable from a module (@pxref{Package Modules}).
However, in-depth Scheme knowledge is @emph{not} a prerequisite for
creating packages. For more information on package definitions,
-@ref{Defining Packages}.
+@pxref{Defining Packages}.
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{Contributing}). Well, if you need help, we will be happy to
help you too. Once the patch is committed in the Guix repository, the
new package automatically gets built on the supported platforms by
-@url{http://hydra.gnu.org/gnu/master, our continuous integration
+@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
system}.
@cindex substituter
SDL_net as @code{sdl-net}.
We do not add @code{lib} prefixes for library packages, unless these are
-already part of the official project name. But see @pxref{Python
+already part of the official project name. But @pxref{Python
Modules} and @ref{Perl Modules} for special rules concerning modules for
the Python and Perl languages.
@chapter Acknowledgments
Guix is based on the Nix package manager, which was designed and
-implemented by Eelco Dolstra. Nix pioneered functional package
+implemented by Eelco Dolstra, with contributions from other people (see
+the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
management, and promoted unprecedented features, such as transactional
package upgrades and rollbacks, per-user profiles, and referentially
transparent build processes. Without this work, Guix would not exist.
The Nix-based software distributions, Nixpkgs and NixOS, have also been
an inspiration for Guix.
+GNU@tie{}Guix itself is a collective work with contributions from a
+number of people. See the @file{AUTHORS} file in Guix for more
+information on these fine people. The @file{THANKS} file lists people
+who have helped by reporting bugs, taking care of the infrastructure,
+providing artwork and themes, making suggestions, and more---thank you!
+
+
@c *********************************************************************
@node GNU Free Documentation License
@appendix GNU Free Documentation License
HCoop / jackhill / guix / guix.git / blobdiff