Merge branch 'release/debian/3.1.0+repack-1'debian/3.1.0+repack-1

1 files changed, 53 insertions, 4 deletions

diff --git a/doc/user/misc.xml b/doc/user/misc.xml
index ed96625..5ade6d3 100644
--- a/doc/user/misc.xml
+++ b/doc/user/misc.xml
@@ -21,7 +21,7 @@
 
 <!--
 
-  Copyright (c) 2001 - 2017 The SCons Foundation
+  Copyright (c) 2001 - 2019 The SCons Foundation
 
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
@@ -268,9 +268,9 @@ hello.c
     <scons_example name="misc_FindFile1a">
       <file name="SConstruct" printme="1">
 # one directory
-print(FindFile('missing', '.'))
+print("%s"%FindFile('missing', '.'))
 t = FindFile('exists', '.')
-print(t.__class__, t)
+print("%s %s"%(t.__class__, t))
       </file>
       <file name="exists">
  exists
@@ -287,7 +287,7 @@ print(t.__class__, t)
 includes = [ '.', 'include', 'src/include']
 headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h']
 for hdr in headers:
-    print('%-12s' % ('%s:' % hdr), FindFile(hdr, includes))
+    print('%-12s: %s'%(hdr, FindFile(hdr, includes)))
       </file>
       <file name="config.h">
 exists
@@ -625,4 +625,53 @@ env.Command('directory_build_info',
 
   </section>
 
+  <section>
+  <title>Virtual environments (virtualenvs)</title>
+
+    <para>
+
+      Virtualenv is a tool to create isolated Python environments.
+      A python application (such as SCons) may be executed within
+      an activated virtualenv. The activation of virtualenv modifies
+      current environment by defining some virtualenv-specific variables
+      and modifying search PATH, such that executables installed within
+      virtualenv's home directory are preferred over the ones installed
+      outside of it.
+
+    </para>
+
+    <para>
+
+      Normally, SCons uses hard-coded PATH when searching for external
+      executables, so it always picks-up executables from these pre-defined
+      locations. This applies also to python interpreter, which is invoked
+      by some custom SCons tools or test suites. This means, when running
+      SCons in a virtualenv, an eventual invocation of python interpreter from
+      SCons script will most probably jump out of virtualenv and execute
+      python executable found in hard-coded SCons PATH, not the one which is
+      executing SCons. Some users may consider this as an inconsistency.
+
+    </para>
+
+    <para>
+      This issue may be overcome by using <literal>--enable-virtualenv</literal>
+      option. The option automatically imports virtualenv-related environment
+      variables to all created construction environment <literal>env['ENV']</literal>,
+      and modifies SCons PATH appropriately to prefer virtualenv's executables.
+      Setting environment variable <literal>SCONS_ENABLE_VIRTUALENV=1</literal>
+      will have same effect. If virtualenv support is enabled system-vide
+      by the environment variable, it may be suppressed with
+      <literal>--ignore-virtualenv</literal> option.
+    </para>
+
+    <para>
+      Inside of SConscript, a global function <literal>Virtualenv</literal> is
+      available. It returns a path to virtualenv's home directory, or
+      <literal>None</literal> if SCons is not running from virtualenv. Note,
+      that this function returns a path even if SCons is run from an
+      unactivated virtualenv.
+    </para>
+
+  </section>
+
 </chapter>