Subject: [PATCH] Support XDG Base Directory specification for init file

From: offset---cyan <[email-masked]>
Date: Sun, 18 Feb 2024 06:31:37 +0000

Implements a small code change to load a `guilerc` file as an
alternative to the `~/.guile` init file, from directories following the
XDG Base Directory Specification, `$XDG_CONFIG_HOME` or `$HOME/.config`.
Prioritises existing behaviour to avoid causing anyone trouble.

* module/ice-9/boot-9.scm (load-user-init): Check XDG_CONFIG_HOME
environment variable and HOME/.config for guile initialisation file `guilerc`.
* doc/ref/api-evaluation.texi: Update references to init file.
* doc/ref/guile-invoke.texi: Update references to init file.
* doc/ref/scheme-using.texi: Update references to init file.
* doc/ref/tour.texi: Update references to init file.
* module/ice-9/boot-9.scm: Update references to init file.
---
doc/ref/api-evaluation.texi | 3 ++-
doc/ref/guile-invoke.texi | 12 ++++++------
doc/ref/scheme-using.texi | 15 +++++++++------
doc/ref/tour.texi | 4 ++--
module/ice-9/boot-9.scm | 17 +++++++++++++----
5 files changed, 32 insertions(+), 19 deletions(-)

diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index 7c08e2494..5f863c23d 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -830,7 +830,8 @@ explicitly.
@defvr {Scheme Variable} %auto-compilation-options
This variable contains the options passed to the @code{compile-file}
procedure when auto-compiling source files. By default, it enables
-useful compilation warnings. It can be customized from @file{~/.guile}.
+useful compilation warnings. It can be customized from one's
+@file{guilerc} (see @pxref{Init File}).
@end defvr

@node Loading
diff --git a/doc/ref/guile-invoke.texi b/doc/ref/guile-invoke.texi
index 856bce7b8..472db23f0 100644
--- a/doc/ref/guile-invoke.texi
+++ b/doc/ref/guile-invoke.texi
@@ -69,7 +69,7 @@ Add @var{directory} to the front of Guile's module load path. The given
directories are searched in the order given on the command line and
before any directories in the @env{GUILE_LOAD_PATH} environment
variable. Paths added here are @emph{not} in effect during execution of
-the user's @file{.guile} file.
+the user's @file{guilerc} file.

@item -C @var{directory}
Like @option{-L}, but adjusts the load path for @emph{compiled} files.
@@ -79,7 +79,7 @@ Add @var{extension} to the front of Guile's load extension list
(@pxref{Load Paths, @code{%load-extensions}}). The specified extensions
are tried in the order given on the command line, and before the default
load extensions. Extensions added here are @emph{not} in effect during
-execution of the user's @file{.guile} file.
+execution of the user's @file{guilerc} file.

@item -l @var{file}
Load Scheme source code from @var{file}, and continue processing the
@@ -173,10 +173,10 @@ build upon it (see above).

@item -q
@cindex init file, not loading
-@cindex @file{.guile} file, not loading
-Do not load the initialization file, @file{.guile}. This option only
+@cindex @file{guilerc} file, not loading
+Do not load the initialization file, @file{guilerc}. This option only
has an effect when running interactively; running scripts does not load
-the @file{.guile} file. @xref{Init File}.
+the @file{guilerc} file. @xref{Init File}.

@item --listen[=@var{p}]
While this program runs, listen on a local port or a path for REPL
@@ -421,7 +421,7 @@ messages describing the warning. @xref{Deprecation}.
@item HOME
@vindex HOME
Guile uses the environment variable @env{HOME}, the name of your home
-directory, to locate various files, such as @file{.guile} or
+directory, to locate various files, such as @file{guilerc} or
@file{.guile_history}.

@item GUILE_JIT_THRESHOLD
diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi
index b08c85cbc..7ec7b3863 100644
--- a/doc/ref/scheme-using.texi
+++ b/doc/ref/scheme-using.texi
@@ -45,12 +45,15 @@ support for languages other than Scheme.

@node Init File
-@subsection The Init File, @file{~/.guile}
+@subsection The Init File, @file{guilerc}/@file{~/.guile}

@cindex .guile
-When run interactively, Guile will load a local initialization file from
-@file{~/.guile}. This file should contain Scheme expressions for
-evaluation.
+When run interactively, Guile will attempt to load a local initialization
+file from either: @file{~/.guile}, @file{$XDG_CONFIG_HOME/guilerc} (if
+defined), or @file{~/.config/guilerc}, in that order. @file{~/.guile} is
+checked first for legacy reasons - if a the user wishes to create an init
+file, it is recommended they use either latter file. This file should
+contain Scheme expressions for evaluation.

This facility lets the user customize their interactive Guile
environment, pulling in extra modules or parameterizing the REPL
@@ -75,8 +78,8 @@ scheme@@(guile-user)> (activate-readline)
@end lisp

It's a good idea to put these two lines (without the
-@code{scheme@@(guile-user)>} prompts) in your @file{.guile} file.
-@xref{Init File}, for more on @file{.guile}.
+@code{scheme@@(guile-user)>} prompts) in your @file{guilerc} file.
+@xref{Init File}, for more on @file{guilerc}.

@node Value History
diff --git a/doc/ref/tour.texi b/doc/ref/tour.texi
index c0ecb1699..23383b289 100644
--- a/doc/ref/tour.texi
+++ b/doc/ref/tour.texi
@@ -325,9 +325,9 @@ to you even after re-reading the section, it is a bug.
@end itemize

Before reporting the bug, check whether any programs you have loaded
-into Guile, including your @file{.guile} file, set any variables that
+into Guile, including your @file{guilerc} file, set any variables that
may affect the functioning of Guile. Also, see whether the problem
-happens in a freshly started Guile without loading your @file{.guile}
+happens in a freshly started Guile without loading your @file{guilerc}
file (start Guile with the @code{-q} switch to prevent loading the init
file). If the problem does @emph{not} occur then, you must report the
precise contents of any programs that you must load into Guile in order
diff --git a/module/ice-9/boot-9.scm b/module/ice-9/boot-9.scm
index a5f2eea9b..d7374a7db 100644
--- a/module/ice-9/boot-9.scm
+++ b/module/ice-9/boot-9.scm
@@ -2187,15 +2187,24 @@ non-locally, that exit determines the continuation."
(define (command-line) (program-arguments))

;; This is mostly for the internal use of the code generated by
-;; scm_compile_shell_switches.
+;; scm_compile_shell_switches. The file, if found, configures a Guile REPL.
+;; Supports the XDG Base Directory standard with backwards compatibility
+;; for ~/.guile.

(define (load-user-init)
(let* ((home (or (getenv "HOME")
(false-if-exception (passwd:dir (getpwuid (getuid))))
file-name-separator-string)) ;; fallback for cygwin etc.
- (init-file (in-vicinity home ".guile")))
- (if (file-exists? init-file)
- (primitive-load init-file))))
+ (xdg (or (getenv "XDG_CONFIG_HOME")
+ (string-append home
+ file-name-separator-string
+ ".config")))
+ (home-init-file (in-vicinity home ".guile"))
+ (xdg-init-file (in-vicinity xdg "guilerc")))
+
+ (cond
+ ((file-exists? home-init-file) (primitive-load home-init-file))
+ ((file-exists? xdg-init-file) (primitive-load xdg-init-file)))))

--
2.42.0