From 1120efe3759908c84817f45d317d8704769371d3 Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Sun, 23 Jun 2024 11:13:18 +0200 Subject: [PATCH] Fix race in check-guile to make needless guile-procedures symlink * check-guile.in (top_srcdir): Don't try to make guile-procedures.tx, as this races with multiple checkers, and it's gross. * meta/uninstalled-env.in (GUILE_DOCSTRINGS_PATH): Instead when uninstalled, use this variable. * module/ice-9/documentation.scm (documentation-files): Remove the current directory from the search path for documentation files; this was always a hack. Instead allow GUILE_DOCSTRINGS_PATH to override the built-in search path. --- check-guile.in | 5 - meta/uninstalled-env.in | 5 +- module/ice-9/documentation.scm | 175 +++++++++++++++++---------------- 3 files changed, 94 insertions(+), 91 deletions(-) diff --git a/check-guile.in b/check-guile.in index 8e5b526a5..7fc0e9897 100644 --- a/check-guile.in +++ b/check-guile.in @@ -31,11 +31,6 @@ if ! [ -f "$guile" -a -x "$guile" ] ; then exit 2 fi -# documentation searching ignores GUILE_LOAD_PATH. -if [ ! -f guile-procedures.txt ] ; then - @LN_S@ libguile/guile-procedures.txt . -fi - exec "$guile" \ --debug \ -L "$TEST_SUITE_DIR" \ diff --git a/meta/uninstalled-env.in b/meta/uninstalled-env.in index 2531e25cb..8b3bea11d 100644 --- a/meta/uninstalled-env.in +++ b/meta/uninstalled-env.in @@ -1,6 +1,6 @@ #!/bin/sh -# Copyright (C) 2003, 2006, 2008, 2009, 2010, 2011, 2012, 2015, 2017, 2022 Free Software Foundation +# Copyright (C) 2003, 2006, 2008, 2009, 2010, 2011, 2012, 2015, 2017, 2022, 2024 Free Software Foundation # # This file is part of GUILE. # @@ -46,6 +46,9 @@ top_builddir="@top_builddir_absolute@" exit 1 } +GUILE_DOCSTRINGS_PATH="@top_builddir_absolute@/libguile${GUILE_DOCSTRINGS_PATH:+:$GUILE_DOCSTRINGS_PATH}" +export GUILE_DOCSTRINGS_PATH + # When cross-compiling, let $GUILE_FOR_BUILD use its own .go files since # the ones that are being built may be incompatible ($GUILE_FOR_BUILD is # typically used to run `guild compile --target=$host'.) Likewise, diff --git a/module/ice-9/documentation.scm b/module/ice-9/documentation.scm index 9b0a121cc..5698bd653 100644 --- a/module/ice-9/documentation.scm +++ b/module/ice-9/documentation.scm @@ -1,90 +1,90 @@ -;;;; Copyright (C) 2000,2001, 2002, 2003, 2006, 2009, 2010 Free Software Foundation, Inc. -;;;; -;;;; This library is free software; you can redistribute it and/or -;;;; modify it under the terms of the GNU Lesser General Public -;;;; License as published by the Free Software Foundation; either -;;;; version 3 of the License, or (at your option) any later version. -;;;; -;;;; This library is distributed in the hope that it will be useful, -;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -;;;; Lesser General Public License for more details. -;;;; -;;;; You should have received a copy of the GNU Lesser General Public -;;;; License along with this library; if not, write to the Free Software -;;;; Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -;;;; +;;; documentation.scm --- Run-time documentation facility +;;; Copyright (C) 2000-2003,2006,2009,2010,2024 Free Software Foundation, Inc. +;;; +;;; This library is free software: you can redistribute it and/or modify +;;; it under the terms of the GNU Lesser General Public License as +;;; published by the Free Software Foundation, either version 3 of the +;;; License, or (at your option) any later version. +;;; +;;; This library is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +;;; Lesser General Public License for more details. +;;; +;;; You should have received a copy of the GNU Lesser General Public +;;; License along with this program. If not, see +;;; . ;;; Commentary: -;; * This module exports: -;; -;; file-commentary -- a procedure that returns a file's "commentary" -;; -;; documentation-files -- a search-list of files using the Guile -;; Documentation Format Version 2. -;; -;; search-documentation-files -- a procedure that takes NAME (a symbol) -;; and searches `documentation-files' for -;; associated documentation. optional -;; arg FILES is a list of filenames to use -;; instead of `documentation-files'. -;; -;; object-documentation -- a procedure that returns its arg's docstring -;; -;; * Guile Documentation Format -;; -;; Here is the complete and authoritative documentation for the Guile -;; Documentation Format Version 2: -;; -;; HEADER -;; ^LPROC1 -;; DOCUMENTATION1 -;; -;; ^LPROC2 -;; DOCUMENTATION2 -;; -;; ^L... -;; -;; The HEADER is completely ignored. The "^L" are formfeeds. PROC1, PROC2 -;; and so on are symbols that name the element documented. DOCUMENTATION1, -;; DOCUMENTATION2 and so on are the related documentation, w/o any further -;; formatting. Note that there are two newlines before the next formfeed; -;; these are discarded when the documentation is read in. -;; -;; (Version 1, corresponding to guile-1.4 and prior, is documented as being -;; not documented anywhere except by this embarrassingly circular comment.) -;; -;; * File Commentary -;; -;; A file's commentary is the body of text found between comments -;; ;;; Commentary: -;; and -;; ;;; Code: -;; both of which must be at the beginning of the line. In the result string, -;; semicolons at the beginning of each line are discarded. -;; -;; You can specify to `file-commentary' alternate begin and end strings, and -;; scrub procedure. Use #t to get default values. For example: -;; -;; (file-commentary "documentation.scm") -;; You should see this text! -;; -;; (file-commentary "documentation.scm" "^;;; Code:" "ends here$") -;; You should see the rest of this file. -;; -;; (file-commentary "documentation.scm" #t #t string-upcase) -;; You should see this text very loudly (note semicolons untouched). +;;; * This module exports: +;;; +;;; file-commentary -- a procedure that returns a file's "commentary" +;;; +;;; documentation-files -- a search-list of files using the Guile +;;; Documentation Format Version 2. +;;; +;;; search-documentation-files -- a procedure that takes NAME (a symbol) +;;; and searches `documentation-files' for +;;; associated documentation. optional +;;; arg FILES is a list of filenames to use +;;; instead of `documentation-files'. +;;; +;;; object-documentation -- a procedure that returns its arg's docstring +;;; +;;; * Guile Documentation Format +;;; +;;; Here is the complete and authoritative documentation for the Guile +;;; Documentation Format Version 2: +;;; +;;; HEADER +;;; ^LPROC1 +;;; DOCUMENTATION1 +;;; +;;; ^LPROC2 +;;; DOCUMENTATION2 +;;; +;;; ^L... +;;; +;;; The HEADER is completely ignored. The "^L" are formfeeds. PROC1, PROC2 +;;; and so on are symbols that name the element documented. DOCUMENTATION1, +;;; DOCUMENTATION2 and so on are the related documentation, w/o any further +;;; formatting. Note that there are two newlines before the next formfeed; +;;; these are discarded when the documentation is read in. +;;; +;;; (Version 1, corresponding to guile-1.4 and prior, is documented as being +;;; not documented anywhere except by this embarrassingly circular comment.) +;;; +;;; * File Commentary +;;; +;;; A file's commentary is the body of text found between comments +;;; ;;; Commentary: +;;; and +;;; ;;; Code: +;;; both of which must be at the beginning of the line. In the result string, +;;; semicolons at the beginning of each line are discarded. +;;; +;;; You can specify to `file-commentary' alternate begin and end strings, and +;;; scrub procedure. Use #t to get default values. For example: +;;; +;;; (file-commentary "documentation.scm") +;;; You should see this text! +;;; +;;; (file-commentary "documentation.scm" "^;;; Code:" "ends here$") +;;; You should see the rest of this file. +;;; +;;; (file-commentary "documentation.scm" #t #t string-upcase) +;;; You should see this text very loudly (note semicolons untouched). ;;; Code: (define-module (ice-9 documentation) - :use-module (ice-9 rdelim) - :export (file-commentary - documentation-files search-documentation-files - object-documentation) - :autoload (ice-9 regex) (match:suffix) - :no-backtrace) + #:use-module (ice-9 rdelim) + #:use-module (ice-9 regex) + #:use-module (ice-9 match) + #:export (file-commentary + documentation-files search-documentation-files + object-documentation)) ;; @@ -144,16 +144,21 @@ +(define (parse-path var) + (match (getenv var) + (#f #f) + ;; Ignore e.g. "export GUILE_SYSTEM_EXTENSIONS_PATH=". + ("" '()) + (val (string-split val #\:)))) + ;; ;; documentation-files is the list of places to look for documentation ;; (define documentation-files (map (lambda (vicinity) - (in-vicinity (vicinity) "guile-procedures.txt")) - (list %library-dir - %package-data-dir - %site-dir - (lambda () ".")))) + (in-vicinity vicinity "guile-procedures.txt")) + (or (parse-path "GUILE_DOCSTRINGS_PATH") + (list (%library-dir) (%package-data-dir) (%site-dir))))) (define entry-delimiter "\f")