summaryrefslogtreecommitdiff
path: root/doc/user/misc.xml
diff options
context:
space:
mode:
authorJörg Frings-Fürst <debian@jff-webhosting.net>2019-07-14 08:35:24 +0200
committerJörg Frings-Fürst <debian@jff-webhosting.net>2019-07-14 08:35:24 +0200
commit697e33ed224b539a42ff68121f7497f5bbf941b2 (patch)
tree44ae83ad6ad4a7f6762a6d1bfde3766a1993b5ec /doc/user/misc.xml
parentbaee03c569c91b745a1e025660b19a718db16e7d (diff)
New upstream version 3.0.5upstream/3.0.5
Diffstat (limited to 'doc/user/misc.xml')
-rw-r--r--doc/user/misc.xml57
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>