Updated docs to indicate FILE_ENCODING will affect Substfile() as well as TextFile(). Added blurb to RELEASE.txt. Updated test fixture to include new utf-8 text for test

5 files changed, 24 insertions, 13 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 27be9f83d..03061e9c6 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -46,6 +46,11 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Added JAVAPROCESSORPATH construction variable which populates -processorpath.
     - Updated JavaScanner to scan JAVAPROCESSORPATH.
 
+  From Nickolai Korshunov
+    - Added FILE_ENCODING, to allow explicitly setting the text encoding for files
+      written by the Textfile() and Substfile() builders. If not specified, Textfile() and Substfile() builders
+      will write files as UTF-8. Fixed Issue #4302.
+
   From Dan Mezhiborsky:
     - Add newline to end of compilation db (compile_commands.json).
 
@@ -60,7 +65,6 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       Now configure checks now clear node info for non conftest nodes, so they will be re-evaluated for
       the real taskmaster run when the build commences.
 
-
   From Andrew Morrow
     - Avoid returning UniqueList for `children` and other `Executor` APIs. This type
       iterates more slowly than the builtin types. Also simplify uniquer_hashables to
@@ -134,11 +138,6 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       or not if it is already in the $LIBS construction var in the
       configure context. (issue #2768).
 
-  From Nickolai Korshunov
-    - Added explicit file encoding in env.Textfile. All written files by default 
-      will have utf-8 encoding. User can specify encoding manually with 
-      $FILE_ENCODING env var.
-
 
 RELEASE 4.4.0 -  Sat, 30 Jul 2022 14:08:29 -0700
 
diff --git a/RELEASE.txt b/RELEASE.txt
index 6c1c5f281..381d1c792 100644
--- a/RELEASE.txt
+++ b/RELEASE.txt
@@ -26,6 +26,9 @@ NEW FUNCTIONALITY
   not be called until all AddOption() calls are completed. Resolves Issue #4187
 - Added --experimental=tm_v2, which enables Andrew Morrow's NewParallel Job implementation.
   This should scale much better for highly parallel builds.  You can also enable this via SetOption().
+- Added FILE_ENCODING, to allow explicitly setting the text encoding for files
+  written by the Textfile() and Substfile() builders. If not specified, Textfile() and Substfile() builders
+  will write files as UTF-8.
 
 
 DEPRECATED FUNCTIONALITY
diff --git a/SCons/Tool/textfile.py b/SCons/Tool/textfile.py
index c960e67cf..0ec31d8f7 100644
--- a/SCons/Tool/textfile.py
+++ b/SCons/Tool/textfile.py
@@ -117,10 +117,8 @@ def _action(target, source, env):
                 value = str(value)
             subs.append((k, value))
 
-    if 'FILE_ENCODING' not in env:
-        file_encoding = 'utf-8'
-    else:
-        file_encoding = env['FILE_ENCODING']
+    # Pull file encoding from the environment or default to UTF-8
+    file_encoding = env.get('FILE_ENCODING', 'utf-8')
 
     # write the file
     try:
@@ -191,6 +189,7 @@ def generate(env):
     env['BUILDERS']['Substfile'] = _subst_builder
     env['SUBSTFILEPREFIX'] = ''
     env['SUBSTFILESUFFIX'] = ''
+    env['FILE_ENCODING'] = env.get('FILE_ENCODING', 'utf-8')
 
 
 def exists(env):
diff --git a/SCons/Tool/textfile.xml b/SCons/Tool/textfile.xml
index a40fef295..b019c687d 100644
--- a/SCons/Tool/textfile.xml
+++ b/SCons/Tool/textfile.xml
@@ -35,6 +35,7 @@ Set &consvars; for the &b-Textfile; and &b-Substfile; builders.
 <item>SUBSTFILESUFFIX</item>
 <item>TEXTFILEPREFIX</item>
 <item>TEXTFILESUFFIX</item>
+<item>FILE_ENCODING</item>
 </sets>
 <uses>
 <item>SUBST_DICT</item>
@@ -64,7 +65,9 @@ The prefix and suffix specified by the &cv-link-TEXTFILEPREFIX;
 and &cv-link-TEXTFILESUFFIX; &consvars;
 (by default an empty string and <filename>.txt</filename>, respectively)
 are automatically added to the target if they are not already present.
-By default file encoding is "utf-8" and can be changed by &cv-link-FILE_ENCODING;
+</para>
+<para>
+By default the target file encoding is "utf-8" and can be changed by &cv-link-FILE_ENCODING;
 Examples:
 </para>
 
@@ -127,6 +130,11 @@ are flattened. See also &b-link-Textfile;.
 </para>
 
 <para>
+By default the target file encoding is "utf-8" and can be changed by &cv-link-FILE_ENCODING;
+Examples:
+</para>
+
+<para>
 If a single source file name is specified and has a <filename>.in</filename> suffix,
 the suffix is stripped and the remainder of the name is used as the default target name.
 </para>
@@ -263,7 +271,8 @@ The suffix used for &b-link-Textfile; file names;
 <cvar name="FILE_ENCODING">
 <summary>
 <para>
-File encoding. "utf-8" by default.
+File encoding used for files written by &b-link-Textfile; and &b-link-Substfile;.  Set to "utf-8" by default.
+<emphasis>Added in version  4.5.0.</emphasis>
 </para>
 </summary>
 </cvar>
diff --git a/test/textfile/fixture/SConstruct b/test/textfile/fixture/SConstruct
index 60e7225a0..b2466870f 100644
--- a/test/textfile/fixture/SConstruct
+++ b/test/textfile/fixture/SConstruct
@@ -2,7 +2,8 @@ DefaultEnvironment(tools=[])
 
 env = Environment(tools=['textfile'])
 data0 = ['Goethe', 'Schiller']
-data = ['lalala', 42, data0, 'tanteratei']
+data = ['lalala', 42, data0, 'tanteratei',
+        '×'] # <-- this is unicode /xd7 symbol
 
 env.Textfile('foo1', data)
 env.Textfile('foo2', data, LINESEPARATOR='|*')