05/05: doc: Document 'this-package' and 'this-operating-system'.

[guix-commits]

civodul pushed a commit to branch master
in repository guix.

commit cbd059d1017bc22723f1e5293cc8f20dea640fff
Author: Ludovic Courtès <address@hidden>
Date:   Mon Apr 15 12:23:30 2019 +0200

    doc: Document 'this-package' and 'this-operating-system'.
    
    * doc/guix.texi (package Reference): Document 'this-package'.
    (operating-system Reference): Document 'this-operating-system'.
---
 doc/guix.texi | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 1ae5711..4593d79 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -5409,6 +5409,27 @@ automatically corrected.
 @end table
 @end deftp
 
address@hidden {Scheme Syntax} this-package
+When used in the @emph{lexical scope} of a package field definition, this
+identifier resolves to the package being defined.
+
+The example below shows how to add a package as a native input of itself when
+cross-compiling:
+
address@hidden
+(package
+  (name "guile")
+  ;; ...
+
+  ;; When cross-compiled, Guile, for example, depends on
+  ;; a native version of itself.  Add it here.
+  (native-inputs (if (%current-target-system)
+                     `(("self" ,this-package))
+                     '())))
address@hidden example
+
+It is an error to refer to @code{this-package} outside a package definition.
address@hidden deffn
 
 @node origin Reference
 @subsection @code{origin} Reference
@@ -10592,6 +10613,27 @@ is that only @code{root} and members of the 
@code{wheel} group may use
 @code{sudo}.
 
 @end table
+
address@hidden {Scheme Syntax} this-operating-system
+When used in the @emph{lexical scope} of an operating system field definition,
+this identifier resolves to the operating system being defined.
+
+The example below shows how to refer to the operating system being defined in
+the definition of the @code{label} field:
+
address@hidden
+(use-modules (gnu) (guix))
+
+(operating-system
+  ;; ...
+  (label (package-full-name
+          (operating-system-kernel this-operating-system))))
address@hidden example
+
+It is an error to refer to @code{this-operating-system} outside an operating
+system definition.
address@hidden deffn
+
 @end deftp
 
 @node File Systems