diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 80 |
1 files changed, 56 insertions, 24 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 5b91bc2982..90016a4496 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -659,9 +659,9 @@ version: 7.2alpha6 @item --list-installed[=@var{regexp}] @itemx -I [@var{regexp}] -List currently installed packages in the specified profile. When -@var{regexp} is specified, list only installed packages whose name -matches @var{regexp}. +List the currently installed packages in the specified profile, with the +most recently installed packages shown last. When @var{regexp} is +specified, list only installed packages whose name matches @var{regexp}. For each installed package, print the following items, separated by tabs: the package name, its version string, the part of the package that @@ -679,6 +679,41 @@ For each package, print the following items separated by tabs: its name, its version string, the parts of the package (@pxref{Packages with Multiple Outputs}), and the source location of its definition. +@item --list-generations[=@var{pattern}] +@itemx -l [@var{pattern}] +Return a list of generations along with their creation dates; for each +generation, show the installed packages, with the most recently +installed packages shown last. + +For each installed package, print the following items, separated by +tabs: the name of a package, its version string, the part of the package +that is installed (@pxref{Packages with Multiple Outputs}), and the +location of this package in the store. + +When @var{pattern} is used, the command returns only matching +generations. Valid patterns include: + +@itemize +@item @emph{Integers and comma-separated integers}. Both patterns denote +generation numbers. For instance, @code{--list-generations=1} returns +the first one. + +And @code{--list-generations=1,8,2} outputs three generations in the +specified order. Neither spaces nor trailing commas are allowed. + +@item @emph{Ranges}. @code{--list-generations=2..9} prints the +specified generations and everything in between. Note that the start of +a range must be lesser than its end. + +It is also possible to omit the endpoint. For example, +@code{--list-generations=2..}, returns all generations starting from the +second one. + +@item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks, +or months by passing an integer along with the first letter of the +duration, e.g., @code{--list-generations=20d}. +@end itemize + @end table @node Packages with Multiple Outputs @@ -987,8 +1022,8 @@ The build actions it prescribes may then be realized by using the @code{build-derivations} procedure (@pxref{The Store}). @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}] -Return the derivation path and corresponding @code{<derivation>} object -of @var{package} for @var{system} (@pxref{Derivations}). +Return the @code{<derivation>} object of @var{package} for @var{system} +(@pxref{Derivations}). @var{package} must be a valid @code{<package>} object, and @var{system} must be a string denoting the target system type---e.g., @@ -1004,8 +1039,8 @@ package for some other system: @deffn {Scheme Procedure} package-cross-derivation @var{store} @ @var{package} @var{target} [@var{system}] -Return the derivation path and corresponding @code{<derivation>} object -of @var{package} cross-built from @var{system} to @var{target}. +Return the @code{<derivation>} object of @var{package} cross-built from +@var{system} to @var{target}. @var{target} must be a valid GNU triplet denoting the target hardware and operating system, such as @code{"mips64el-linux-gnu"} @@ -1061,15 +1096,16 @@ argument. Return @code{#t} when @var{path} is a valid store path. @end deffn -@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references} +@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}] Add @var{text} under file @var{name} in the store, and return its store path. @var{references} is the list of store paths referred to by the resulting store path. @end deffn @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations} -Build @var{derivations} (a list of derivation paths), and return when -the worker is done building them. Return @code{#t} on success. +Build @var{derivations} (a list of @code{<derivation>} objects or +derivation paths), and return when the worker is done building them. +Return @code{#t} on success. @end deffn @c FIXME @@ -1119,8 +1155,8 @@ otherwise manipulate derivations. The lowest-level primitive to create a derivation is the @code{derivation} procedure: @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] [#:references-graphs #f] -Build a derivation with the given arguments. Return the resulting store -path and @code{<derivation>} object. +Build a derivation with the given arguments, and return the resulting +@code{<derivation>} object. When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a @dfn{fixed-output derivation} is created---i.e., one whose result is @@ -1142,16 +1178,13 @@ to a Bash executable in the store: (guix store) (guix derivations)) -(call-with-values - (lambda () - (let ((builder ; add the Bash script to the store - (add-text-to-store store "my-builder.sh" - "echo hello world > $out\n" '()))) - (derivation store "foo" - bash `("-e" ,builder) - #:env-vars '(("HOME" . "/homeless"))))) - list) -@result{} ("/nix/store/@dots{}-foo.drv" #<<derivation> @dots{}>) +(let ((builder ; add the Bash script to the store + (add-text-to-store store "my-builder.sh" + "echo hello world > $out\n" '()))) + (derivation store "foo" + bash `("-e" ,builder) + #:env-vars '(("HOME" . "/homeless")))) +@result{} #<derivation /nix/store/@dots{}-foo.drv => /nix/store/@dots{}-foo> @end lisp As can be guessed, this primitive is cumbersome to use directly. An @@ -1196,8 +1229,7 @@ containing one file: (build-expression->derivation store "goo" (%current-system) builder '())) -@result{} "/nix/store/@dots{}-goo.drv" -@result{} #<<derivation> @dots{}> +@result{} #<derivation /nix/store/@dots{}-goo.drv => @dots{}> @end lisp @cindex strata of code |