diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 128 |
1 files changed, 101 insertions, 27 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 652db050cb..a32bdd824f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -5832,6 +5832,7 @@ Voilà! @c What follows stems from discussions at @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as @c earlier discussions on guix-devel@gnu.org. +@c Updated in 2025 to refer to the Deprecation Policy. @quotation Warning Before you publish your channel, we would like to share a few words of caution: @@ -5846,10 +5847,10 @@ process. @item Package modules and package definitions are Scheme code that uses -various programming interfaces (APIs). We, Guix developers, never -change APIs gratuitously, but we do @emph{not} commit to freezing APIs -either. When you maintain package definitions outside Guix, we consider -that @emph{the compatibility burden is on you}. +various programming interfaces (APIs). Those may occasionally change, +in accordance with our deprecation policy (@pxref{Deprecation Policy}), +and it is your responsibility as a channel author to adjust your code +accordingly. @item Corollary: if you're using an external channel and that channel breaks, please @@ -15800,6 +15801,49 @@ Note that changes made by the @code{arguments} rule do not entail a rebuild of the affected packages. Furthermore, if a package definition happens to be using G-expressions already, @command{guix style} leaves it unchanged. + +@item git-source +If the @code{home-page} is a Git repository (as per +@code{git-repository-url?}), and the actual Git repository is tagged +with @code{version} or @code{(string-append ``v'' version)}, change the +package origin to the @code{git-fetch} method +(@pxref{origin Reference}). Consider this example: + +@lisp +(define-public guile-json-4 + (package + (inherit guile-json-3) + (name "guile-json") + (version "4.7.3") + (source (origin + (method url-fetch) + (uri (string-append "mirror://savannah/guile-json/guile-json-" + version ".tar.gz")) + (sha256 + (base32 + "127k2xc07w1gnyqs40z4865l8p3ra5xgpcn569dz04lxsa709fiq")))))) +@end lisp + +@noindent +Running @command{guix style -S git-source} on this package would rewrite +its @code{source} field like to: + +@lisp +(define-public guile-json-4 + (package + (inherit guile-json-3) + (name "guile-json") + (version "4.7.3") + (source (origin + (method git-fetch) + (uri (git-reference (url + "https://github.com/aconchillo/guile-json") + (commit version))) + (file-name (git-file-name name version)) + (sha256 (base32 + "0akhm8xjv8fl55fyq0w6c9c6hi5j7mifjx01w07np7qg1cjl9f06")))))) +@end lisp + @end table @item --list-stylings @@ -38164,6 +38208,9 @@ as its configuration and access token. @item @code{run-directory} (default: @code{"/var/run/forgejo-runner"}) Directory where @command{forgejo-runner} stores cached data. +@item @code{log-file} (default: @code{"/var/log/forgejo-runner.log"}) +Name of the @command{forgejo-runner} log file. + @end table @end deftp @@ -43491,6 +43538,12 @@ The port to bind the server to. @item @code{host} (default: @code{"127.0.0.1"}) The host to bind the server to. +@item @code{control-port} (default: @code{8734}) +The port to bind the control server to. + +@item @code{control-host} (default: @code{"127.0.0.1"}) +The host to bind the control server to. + @item @code{mirror} (default: @code{#f}) Optional URL of the other Nar Herder instance which should be mirrored. This means that this Nar Herder instance will download it's database, @@ -50312,6 +50365,8 @@ Extend home-shell-profile service only if you really know what you do. @subsubheading Bash Home Service @anchor{home-bash-configuration} +@c %start of fragment + @deftp {Data Type} home-bash-configuration Available @code{home-bash-configuration} fields are: @@ -50326,13 +50381,19 @@ use Guix System, is it safe to set this to @code{#f}, as in this case this is already taken care of by the globally installed @file{/etc/bashrc}. -@item @code{environment-variables} (default: @code{'()}) (type: alist) -Association list of environment variables to set for the Bash session. The -rules for the @code{home-environment-variables-service-type} apply -here (@pxref{Essential Home Services}). The contents of this field will be -added after the contents of the @code{bash-profile} field. +@item @code{environment-variables} (default: @code{()}) (type: alist) +Association list of environment variables to set for the Bash session. +The rules for the @code{home-environment-variables-service-type} apply +here (@pxref{Essential Home Services}). The contents of this field will +be added after the contents of the @code{bash-profile} field. + +@item @code{variables} (default: @code{()}) (type: alist) +Bash variables (not to be confused with environment variables) to be set +in @file{.bashrc} for use by interactive shells. A typical example of +such variables is @code{HISTSIZE} and related history variables +(@pxref{Bash Variables,,, bash,Bash Reference Manual}). -@item @code{aliases} (default: @code{%default-bash-aliases}) (type: alist) +@item @code{aliases} (type: alist) Association list of aliases to set for the Bash session. The aliases will be defined after the contents of the @code{bashrc} field has been put in the @file{.bashrc} file. The alias will automatically be quoted, @@ -50348,27 +50409,31 @@ turns into alias ls="ls -alF" @end example -@item @code{bash-profile} (default: @code{'()}) (type: text-config) +@item @code{bash-profile} (default: @code{()}) (type: text-config) List of file-like objects, which will be added to @file{.bash_profile}. Used for executing user's commands at start of login shell (In most cases the shell started on tty just after login). @file{.bash_login} won't be ever read, because @file{.bash_profile} always present. -@item @code{bashrc} (default: @code{'()}) (type: text-config) +@item @code{bashrc} (default: @code{()}) (type: text-config) List of file-like objects, which will be added to @file{.bashrc}. Used for executing user's commands at start of interactive shell (The shell for interactive usage started by typing @code{bash} or by terminal app or any other program). -@item @code{bash-logout} (default: @code{'()}) (type: text-config) +@item @code{bash-logout} (default: @code{()}) (type: text-config) List of file-like objects, which will be added to @file{.bash_logout}. Used for executing user's commands at the exit of login shell. It won't be read in some cases (if the shell terminates by exec'ing another process for example). @end table + @end deftp + +@c %end of fragment + You can extend the Bash service by using the @code{home-bash-extension} configuration record, whose fields must mirror that of @code{home-bash-configuration} (@pxref{home-bash-configuration}). The @@ -50378,14 +50443,14 @@ Bash Reference Manual}. For example, here is how you would define a service that extends the Bash service such that @file{~/.bash_profile} defines an additional -environment variable, @env{PS1}: +shell variable, @env{PS1}: @lisp (define bash-fancy-prompt-service (simple-service 'bash-fancy-prompt home-bash-service-type (home-bash-extension - (environment-variables + (variables '(("PS1" . "\\u \\wλ ")))))) @end lisp @@ -50393,34 +50458,43 @@ You would then add @code{bash-fancy-prompt-service} to the list in the @code{services} field of your @code{home-environment}. The reference of @code{home-bash-extension} follows. +@c %start of fragment + @deftp {Data Type} home-bash-extension Available @code{home-bash-extension} fields are: @table @asis -@item @code{environment-variables} (default: @code{'()}) (type: alist) -Additional environment variables to set. These will be combined with the -environment variables from other extensions and the base service to form one -coherent block of environment variables. +@item @code{environment-variables} (default: @code{()}) (type: alist) +Additional environment variables to set. These will be combined with +the environment variables from other extensions and the base service to +form one coherent block of environment variables. -@item @code{aliases} (default: @code{'()}) (type: alist) +@item @code{variables} (default: @code{()}) (type: alist) +Extra Bash variables (not to be confused with environment variables) to +be set in @file{.bashrc} for use by interactive shells. + +@item @code{aliases} (default: @code{()}) (type: alist) Additional aliases to set. These will be combined with the aliases from other extensions and the base service. -@item @code{bash-profile} (default: @code{'()}) (type: text-config) -Additional text blocks to add to @file{.bash_profile}, which will be combined -with text blocks from other extensions and the base service. +@item @code{bash-profile} (default: @code{()}) (type: text-config) +Additional text blocks to add to @file{.bash_profile}, which will be +combined with text blocks from other extensions and the base service. -@item @code{bashrc} (default: @code{'()}) (type: text-config) +@item @code{bashrc} (default: @code{()}) (type: text-config) Additional text blocks to add to @file{.bashrc}, which will be combined with text blocks from other extensions and the base service. -@item @code{bash-logout} (default: @code{'()}) (type: text-config) -Additional text blocks to add to @file{.bash_logout}, which will be combined -with text blocks from other extensions and the base service. +@item @code{bash-logout} (default: @code{()}) (type: text-config) +Additional text blocks to add to @file{.bash_logout}, which will be +combined with text blocks from other extensions and the base service. @end table + @end deftp +@c %end of fragment + @subsubheading Zsh Home Service @deftp {Data Type} home-zsh-configuration |