Deprecate sconsign-per-directory mode

This was the default mode prior to SCons 1.0, has long been discouraged
but not yet formally marked deprecated.

Signed-off-by: Mats Wichmann <mats@linux.com>

Author: mwichmann

CHANGES.txt

@@ -59,6 +59,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       Google style.
     - Additional small tweaks to Environment.py type hints, fold some overly
       long function signature lines, and some linting-insipired cleanups.
+    - Deprecated using signature-file-per-directory (aka old-style SConsign)
+      via the SConsignFile(name=None) call.
 
 
 RELEASE 4.10.1 - Sun, 16 Nov 2025 10:51:57 -0700

RELEASE.txt

@@ -25,6 +25,9 @@ DEPRECATED FUNCTIONALITY
 
 - Deprecated Python 3.7 & 3.8 support.
 
+- Deprecated using signature-file-per-directory (aka old-style SConsign)
+  via the SConsignFile(name=None) call.
+
 CHANGED/ENHANCED EXISTING FUNCTIONALITY
 ---------------------------------------
 

SCons/Environment.py

@@ -2861,16 +2861,26 @@ def Scanner(self, *args, **kw) -> SCons.Scanner.ScannerBase:
     def SConsignFile(
         self, name: str | None = "", dbm_module: ModuleType | None = None,
     ) -> None:
-        """Specify the name of the signature database to use for this environment.
+        """Specify the base name of the signature database.
 
-        For historical reasons, if *name* is ``None``, the database is
-        stored as one file per directory, rather than a single database
-        for the project.
+        If *name* is not specified, ``.sconsign`` is used as the base name.
+        The actual name *may* also include an indicator of the hash algorithm
+        used to calculate the signatures, and a suffix indicating the
+        storage format. If the hash algorithm is set via
+        :meth:`~SCons.Script.Main.SetOption`, that setting must occur
+        before this function is called.
 
-        If *dbm_module* is specified, it is the database module to use
-        (you need to pass the module object, not a string name).
+        If *dbm_module* is specified, it gives the database module to use.
+        The parameter must be an actual module object, not a string name.
         The module must follow the Python Database API specification
-        described in PEP 249.
+        described in PEP 249. The defaut is :mod:`SCons.dblite`.
+
+        For historical reasons, if *name* is ``None``, the signatures are
+        stored as one file per directory, rather than in a single project-wide
+        database.
+
+        .. deprecated:: NEXT_RELEASE
+           The signature-file-per-directory mode is deprecated.
         """
         if name is not None:
             if not name:

SCons/Environment.xml

@@ -3247,10 +3247,16 @@ in a separate
 file in each directory,
 not in a single combined database file.
 This is a backwards-compatibility measure to support
-what was the default behavior
+the behavior that was the default
 prior to &SCons; 0.97 (i.e. before 2008).
-Use of this mode is discouraged and may be
-deprecated in a future &SCons; release.
+Use of this mode is deprecated and should
+not be used in new projects.
+</para>
+
+<para>
+<emphasis>Deprecated since version NEXT_RELEASE</emphasis>:
+the signature-file-per-directory mode is deprecated
+and will be removed in a future release.
 </para>
 
 <para>

doc/man/sconsign.xml

@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
 <!--
 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
 SPDX-License-Identifier: MIT
+SPDX-FileType: DOCUMENTATION
+
+This file is processed by the bin/SConsDoc.py module.
 -->
 
 <!DOCTYPE reference [
@@ -57,26 +59,24 @@ individual dependency entries are printed in the following format:</para>
 
 <screen>
 depfile: content-signature timestamp length
-        implicit-dependency-1: content-signature timestamp length
-        implicit-dependency-2: content-signature timestamp length
+        implicit-dependency-1: content-signature timestamp size
+        implicit-dependency-2: content-signature timestamp size
         ...
         build-signature [action-string]
 </screen>
 
 <para>
 <emphasis role="bold">content-signature</emphasis>
-is the hash of the file's contents (<firstterm>csig</firstterm>)
-and <emphasis role="bold">build-signature</emphasis>
+(displayed as <firstterm>csig</firstterm> in verbose mode)
+is the hash of the file's contents.
+<emphasis role="bold">build-signature</emphasis>
 is the hash of the command line or other build action
-used to build a target (<firstterm>bactsig</firstterm>).
+used to build a target.
 If provided,
 <emphasis role="bold">action-string</emphasis>
 is the unexpanded string action or the function called.
 <emphasis role="bold">None</emphasis>
-is printed in place of any missing timestamp,
-<emphasis role="bold">csig</emphasis>,
-or <emphasis role="bold">bactsig</emphasis>
-values for any entry or any of its dependencies.
+is printed in place of any missing timestamp or signature.
 If the entry has no implicit dependencies,
 or no build action,
 the corresponding lines are omitted.
@@ -126,6 +126,11 @@ arguments, the name
 is assumed by default.
 </para>
 
+<para>
+<emphasis>Deprecated since version NEXT_RELEASE</emphasis>:
+The old-style signature-file-per-directory mode is deprecated.
+</para>
+
 </refsect1>
 
 <refsect1 id='options'>