diff options
| -rw-r--r-- | CHANGES.txt | 35 | ||||
| -rwxr-xr-x | README-SF.rst | 18 | ||||
| -rw-r--r-- | RELEASE.txt | 153 | ||||
| -rwxr-xr-x | ReleaseConfig | 4 | ||||
| -rw-r--r-- | SCons/Environment.py | 19 | ||||
| -rw-r--r-- | SCons/EnvironmentTests.py | 273 | ||||
| -rw-r--r-- | SCons/Script/Main.py | 2 | ||||
| -rw-r--r-- | SCons/Script/Main.xml | 6 | ||||
| -rw-r--r-- | SCons/Tool/qt.py | 351 | ||||
| -rw-r--r-- | SCons/Tool/qt.xml | 415 | ||||
| -rw-r--r-- | SCons/Tool/qt3.py | 371 | ||||
| -rw-r--r-- | SCons/Tool/qt3.xml | 527 | ||||
| -rw-r--r-- | SCons/Util/__init__.py | 5 | ||||
| -rw-r--r-- | SCons/Warnings.py | 2 | ||||
| -rw-r--r-- | SCons/__init__.py | 10 | ||||
| -rw-r--r-- | SConstruct | 2 | ||||
| -rw-r--r-- | doc/generated/builders.gen | 474 | ||||
| -rw-r--r-- | doc/generated/examples/caching_ex-random_1.xml | 4 | ||||
| -rw-r--r-- | doc/generated/examples/factories_Chmod_1.xml | 2 | ||||
| -rw-r--r-- | doc/generated/examples/separate_ex1_2.xml | 16 | ||||
| -rw-r--r-- | doc/generated/examples/troubleshoot_explain1_3.xml | 2 | ||||
| -rw-r--r-- | doc/generated/examples/troubleshoot_stacktrace_2.xml | 4 | ||||
| -rw-r--r-- | doc/generated/functions.gen | 540 | ||||
| -rw-r--r-- | doc/generated/tools.gen | 31 | ||||
| -rw-r--r-- | doc/generated/tools.mod | 2 | ||||
| -rw-r--r-- | doc/generated/variables.gen | 950 | ||||
| -rw-r--r-- | doc/generated/variables.mod | 116 | ||||
| -rw-r--r-- | doc/user/main.xml | 4 | ||||
| -rw-r--r-- | pyproject.toml | 2 | ||||
| -rw-r--r-- | test/ParseConfig.py | 31 | ||||
| -rw-r--r-- | test/QT/qt3/CPPPATH-appended.py (renamed from test/QT/CPPPATH-appended.py) | 0 | ||||
| -rw-r--r-- | test/QT/qt3/CPPPATH.py (renamed from test/QT/CPPPATH.py) | 0 | ||||
| -rw-r--r-- | test/QT/qt3/QTFLAGS.py (renamed from test/QT/QTFLAGS.py) | 76 | ||||
| -rw-r--r-- | test/QT/qt3/Tool.py (renamed from test/QT/Tool.py) | 12 | ||||
| -rw-r--r-- | test/QT/qt3/copied-env.py (renamed from test/QT/copied-env.py) | 4 | ||||
| -rw-r--r-- | test/QT/qt3/empty-env.py (renamed from test/QT/empty-env.py) | 13 | ||||
| -rw-r--r-- | test/QT/qt3/generated-ui.py (renamed from test/QT/generated-ui.py) | 5 | ||||
| -rw-r--r-- | test/QT/qt3/installed.py (renamed from test/QT/installed.py) | 18 | ||||
| -rw-r--r-- | test/QT/qt3/manual.py (renamed from test/QT/manual.py) | 8 | ||||
| -rw-r--r-- | test/QT/qt3/moc-from-cpp.py (renamed from test/QT/moc-from-cpp.py) | 0 | ||||
| -rw-r--r-- | test/QT/qt3/moc-from-header.py (renamed from test/QT/moc-from-header.py) | 0 | ||||
| -rw-r--r-- | test/QT/qt3/qt_warnings.py (renamed from test/QT/qt_warnings.py) | 10 | ||||
| -rw-r--r-- | test/QT/qt3/reentrant.py (renamed from test/QT/reentrant.py) | 2 | ||||
| -rw-r--r-- | test/QT/qt3/source-from-ui.py (renamed from test/QT/source-from-ui.py) | 32 | ||||
| -rw-r--r-- | test/QT/qt3/up-to-date.py (renamed from test/QT/up-to-date.py) | 2 | ||||
| -rw-r--r-- | test/import.py | 31 | ||||
| -rw-r--r-- | test/textfile/textfile.py | 3 | ||||
| -rw-r--r-- | testing/framework/TestSCons.py | 17 |
48 files changed, 2713 insertions, 1891 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 6052a21a3..8bb3c21f7 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -9,6 +9,36 @@ NOTE: 4.3.0 now requires Python 3.6.0 and above. Python 3.5.x is no longer suppo RELEASE VERSION/DATE TO BE FILLED IN LATER + From Michał Górny: + - Remove the redundant `wheel` dependency from `pyproject.toml`, + as it is added automatically by the setuptools PEP517 backend. + + From Mats Wichmann + - Fix a problem (#4321) in 4.5.0/4.5.1 where ParseConfig could cause an + exception in MergeFlags when the result would be to add preprocessor + defines to existing CPPDEFINES. The following code illustrates the + circumstances that could trigger this: + env=Environment(CPPDEFINES=['a']) + env.Append(CPPDEFINES=['b']) + env.MergeFlags({'CPPDEFINES': 'c'}) + + +RELEASE 4.5.1 - Mon, 06 Mar 2023 14:08:29 -0700 + + From Mats Wichmann + - Fix a problem in 4.5.0 where using something like the following code + will cause a Clone()'d environment to share the CPPDEFINES with the + original Environment() which was cloned. Causing leakage of changes + to CPPDEFINES when they should be completely independent after the Clone. + env=Environment(CPPDEFINES=['a']) + env.Append(CPPDEFINES=['b']) (or AppendUnique,Prepend,PrependUnique) + env1=env.Clone() + env1.Append(CPPDEFINES=['c']) (or any other modification, but not overwriting CPPDEFINES + Now env['CPPDEFINES'] will contain 'c' when it should not. + + +RELEASE 4.5.0 - Sun, 05 Mar 2023 14:08:29 -0700 + From Anatoli Babenia: - Do not initialize DefaultEnvironment when calling EnsureSConsVersion(), EnsurePythonVersion(), Exit(), GetLaunchDir() and SConscriptChdir(). @@ -41,6 +71,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - Fixed Issue #4275 - when outputting compilation db and TEMPFILE was in use, the compilation db would have command lines using the generated tempfile for long command lines, instead of the full command line for the compilation step for the source/target pair. + - Renamed the qt tools to qt3 since the logic in that tool is only for QT version 3. Renamed all env vars + which affect qt3 from QT_ to QT3_. If you are still using SCons to build QT 3 code, you'll need to update + your SConscripts. Note that using 'qt' tool has been deprecated for some time. From David H: - Added JAVAPROCESSORPATH construction variable which populates -processorpath. @@ -129,7 +162,7 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - Updated MSVC documentation - adds "version added" annotations on recently added construction variables and provides a version-mapping table. - Add Python 3.12 support, and indicate 3.11/3.12 support in package. - 3.12 is in alpha for this SCons release, the bytecode sequences + 3.12 is in alpha for this SCons release, the bytecode sequences embedded in SCons/ActionTests.py may need to change later, but based on what is known now, 3.12 itself should work with this release. - Add "append" keyword argument to Configure context's CheckLib and diff --git a/README-SF.rst b/README-SF.rst index 3d8910ad0..c59c7951c 100755 --- a/README-SF.rst +++ b/README-SF.rst @@ -136,7 +136,7 @@ By default, the above commands will do the following: - Install scripts named "scons" and "sconsign" scripts in the default system script directory (/usr/bin or C:\\Python\*\\Scripts, for example). -- Install "scons-3.1.2.exe" and "scons.exe" executables in the Python +- Install "scons-4.5.1.exe" and "scons.exe" executables in the Python prefix directory on Windows (C:\\Python\*, for example). - Install the SCons build engine (a Python module) in the standard Python library directory @@ -378,7 +378,7 @@ running all of "runtest.py -a". Building Packages ================= -We use SCons (version 3.1.2 or later) to build its own packages. If you +We use SCons to build its own packages. If you already have an appropriate version of SCons installed on your system, you can build everything by simply running it:: @@ -393,12 +393,12 @@ about `Executing SCons Without Installing`_):: Depending on the utilities installed on your system, any or all of the following packages will be built:: - SCons-4.2.0-py3-none-any.whl - SCons-4.3.0ayyyymmdd.tar.gz - SCons-4.3.0ayyyymmdd.zip - scons-doc-4.3.0ayyyymmdd.tar.gz - scons-local-4.3.0ayyyymmdd.tar.gz - scons-local-4.3.0ayyyymmdd.zip + SCons-4.5.1-py3-none-any.whl + SCons-4.7.0ayyyymmdd.tar.gz + SCons-4.7.0ayyyymmdd.zip + scons-doc-4.7.0ayyyymmdd.tar.gz + scons-local-4.7.0ayyyymmdd.tar.gz + scons-local-4.7.0ayyyymmdd.zip The SConstruct file is supposed to be smart enough to avoid trying to build packages for which you don't have the proper utilities installed. @@ -612,5 +612,5 @@ many contributors, including but not at all limited to: \... and many others. -Copyright (c) 2001 - 2021 The SCons Foundation +Copyright (c) 2001 - 2023 The SCons Foundation diff --git a/RELEASE.txt b/RELEASE.txt index 91dbb862c..4e25b9522 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -6,35 +6,17 @@ Past official release announcements appear at: ================================================================== -A new SCons release, 4.4.1, is now available on the SCons download page: +A new SCons release, 4.5.2, is now available on the SCons download page: https://scons.org/pages/download.html -Here is a summary of the changes since 4.4.0: - -NOTE: If you build with Python 3.10.0 and then rebuild with 3.10.1 (or higher), you may - see unexpected rebuilds. This is due to Python internals changing which changed - the signature of a Python Action Function. - -NOTE: If you use a dictionary to specify your CPPDEFINES, you may see an unexpected rebuild. - The insertion order of dictionary keys is now preserved when generating the command line. - Previously these were sorted alphabecially. This change to the command line, - while generating identical set of CPPDEFINES can change order and cause a rebuild. - +Here is a summary of the changes since 4.5.1: NEW FUNCTIONALITY ----------------- -- Added ValidateOptions() which will check that all command line options are in either - those specified by SCons itself, or by AddOption() in SConstruct/SConscript. It should - 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. - +- List new features (presumably why a checkpoint is being released) DEPRECATED FUNCTIONALITY ------------------------ @@ -44,144 +26,41 @@ DEPRECATED FUNCTIONALITY CHANGED/ENHANCED EXISTING FUNCTIONALITY --------------------------------------- -- Added -fsanitize support to ParseFlags(). This will propagate to CCFLAGS and LINKFLAGS. -- Calling EnsureSConsVersion() and EnsurePythonVersion() won't initialize - DefaultEnvironment anymore. -- The console message from the Chmod() action function now displays - octal modes using the modern Python syntax (0o755 rather than 0755). -- Migrated logging logic for --taskmastertrace to use Python's logging module. Added logging - to NewParallel Job class (Andrew Morrow's new parallel job implementation) -- Preliminary support for Python 3.12. -- Run LaTeX after biber/bibtex only if necessary -- Configure context methods CheckLib and CheckLibWithHeader now expose - two additional keyword arguments: 'append', which controls whether to append - (the default) or prepend discovered libraries to $LIBS, and 'unique', - which controls whether to add the library if it is already in the $LIBS - list. This brings the library-adding functionality in Configure in line - with the regular Append, AppendUnique, Prepend and PrependUnique methods. -- CPPDEFINES values added via a dictionary type are longer sorted by - key. This used to be required to maintain a consistent order of - commandline arguments between SCons runs, but meant macros were not - always emitted in the order entered. Sorting is no longer required - after Python interpreter improvements. There might be a one-time - rebuild of targets that involved such sorted keys in their actions. +- List modifications to existing features, where the previous behavior + wouldn't actually be considered a bug FIXES ----- -- Added missing newline to generated compilation database (compile_commands.json) -- A list argument as the source to the Copy() action function is now handled. - Both the implementation and the strfunction which prints the progress - message were adjusted. -- The Java Scanner processing of JAVACLASSPATH for dependencies (behavior - that was introduced in SCons 4.4.0) is adjusted to split on the system's - search path separator instead of on a space. The previous behavior meant - that a path containing spaces (e.g. r"C:\somepath\My Classes") would - lead to unexpected errors. If the split-on-space behavior is desired, - pre-split the value: instead of: env["JAVACLASSPATH"] = "foo bar baz" - use: env["JAVACLASSPATH"] = env.Split("foo bar baz") - There is no change in how JAVACLASSPATH gets turned into the -classpath - argument passed to the JDK tools. -- Ninja: Fix execution environment sanitation for launching ninja. Previously if you set an - execution environment variable set to a python list it would crash. Now it - will create a string joining the list with os.pathsep -- Fixed command line argument --diskcheck: previously a value of 'none' was ignored. - SetOption('diskcheck','none') is unaffected, as it did not have the problem. -- Fixed Issue #4275 - when outputting compilation db and TEMPFILE was in use, the compilation db would have - command lines using the generated tempfile for long command lines, instead of the full command line for - the compilation step for the source/target pair. -- A refactor in the caching logic for version 4.4.0 left Java inner classes - failing with an exception when a CacheDir was enabled. This is now corrected. -- When using the gfortran tool (the default on most platforms as long as a GNU - toolchain is installed), the user setting of the "dialect" compilers - (F77, F90, F03 and F09, as well as the shared-library equivalents SHF77, - SHF90, SHF03, SHF09) is now honored; previously the tool overwrote the - settings to 'gfortran', which made it difficult reference a cross-compile - version for dialects. -- Fix issue #2757, where Configure checks that perform a check which reads a modified source - (including program, source or header file(s)) would incorrectly mark that file "up to date" so the - actual build would not see the file as modified. Leading to incorrect incremental builds. - 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. -- Inconsistent behavior of adding values to the CPPDEFINES construction - variable has been cleaned up (described in issue #4254). Now a tuple, - whether provided by itself or as a member of a list, is consistently - interpreted as a macro with replacement value. When adding a list, - individual members are added in sequence without interpretation. - A string value containing spaces is split if it is the initial value or - added, but not if it is given as a member of an added list. Detection - of duplicate macros now works for both valued and unvalued forms. -- Handling of CPPDEFINES macros via Prepend and PrependUnique now works - (previously this was special-cased only for Append and AppendUnique). +- List fixes of outright bugs IMPROVEMENTS ------------ -- Changed the Taskmaster trace logic to use python's logging module. -- Add cache-debug messages for push failures. -- Added error message to handle the case when SCons attempts to retrieve all the targets - for a specified builder from the CacheDir, fails to do so, and then runs into an error - when deleting the files which were retrieved. Previously if this happened there were no - errors or warnings. +- List improvements that wouldn't be visible to the user in the + documentation: performance improvements (describe the circumstances + under which they would be observed), or major code cleanups PACKAGING --------- -- SCons now has three requirements files: requirements.txt describes - requirements to run scons; requirements-dev.txt requirements to - develop it - mainly things needed to run the testsuite; - requirements_pkg.txt are the requirements to do a full build - (including docs build) with an intent to create the packages. -- Moved rpm and debian directories under packaging -- Added logic to help packagers enable reproducible builds into packaging/etc/. - Please read packaging/etc/README.txt if you are interested. -- A zipapp of scons-local is now also built. - +- Remove the redundant `wheel` dependency from `pyproject.toml`, + as it is added automatically by the setuptools PEP517 backend. DOCUMENTATION ------------- -- Updated the --hash-format manpage entry. -- EnsureSConsVersion, EnsurePythonVersion, Exit, GetLaunchDir and - SConscriptChdir are now listed as Global functions only. -- Updated the docs for Glob. -- Updated SHELL_ENV_GENERATORS description and added versionadded indicator. -- JAVABOOTCLASSPATH, JAVACLASSPATH and JAVASOURCEPATH better document the - acceptable syntax for values, and how they will be interpreted, - including that JAVACLASSPATH will be scanned for dependencies. - Added note on the possibly surprising feature that SCons always passes - -sourcepath when calling javac, which affects how the class path is - used when finding sources. -- Updated the User Guide chapter on installation: modernized the notes - on Python installs, SCons installs, and having multiple SCons versions - present on a single system. -- Updated the User Guide chapter on variant directories with more - explanation, and the introduction of terms like "out of tree" that - may help in forming a mental model. -- Additional explanations for MSVSProject and MSVSSolution builders. -- Updated MSVC documentation - adds "version added" annotations on recently - added construction variables and provides a version-mapping table. -- Added further details in the documentation of Append and related methods - on the special handling of CPPDEFINES. +- List any significant changes to the documentation (not individual + typo fixes, even if they're mentioned in src/CHANGES.txt to give + the contributor credit) DEVELOPMENT ----------- -- Refactored SCons/Taskmaster into a package. Moved SCons/Jobs.py into that package. - NOTE: If you hook into SCons.Jobs, you'll have to change that to use SCons.Taskmaster.Jobs -- Refactored SCons.Util, which had grown quite large, to be a package, - not a single-file module. Change should be transparent: the same import - of SCons.Util and public symbols from it will continue to work, however - code which reaches directly in to grab private symbols (starting with - underscore) which moved to a submodule, that code will have to be adjusted, - as those are not imported to the package level (new SCons.Util.hashes has - some of these, which are used by existing unit tests). -- Added overrides argument to SCons.Subst.scons_subst(), subst_list(), subst(), and Action's process(), - strfunction(). This allows passing a dictionary of envvars to override when evaluating subst()'d strings/lists - +- List visible changes in the way SCons is developed Thanks to the following contributors listed below for their contributions to this release. ========================================================================================== .. code-block:: text - git shortlog --no-merges -ns 4.4.0..HEAD + git shortlog --no-merges -ns 4.0.1..HEAD diff --git a/ReleaseConfig b/ReleaseConfig index 98a3785d0..2b80306fb 100755 --- a/ReleaseConfig +++ b/ReleaseConfig @@ -31,7 +31,7 @@ # 'final', the patchlevel is set to the release date. This value is # mandatory and must be present in this file. #version_tuple = (2, 2, 0, 'final', 0) -version_tuple = (4, 4, 1, 'a', 0) +version_tuple = (4, 5, 2, 'a', 0) # Python versions prior to unsupported_python_version cause a fatal error # when that version is used. Python versions prior to deprecate_python_version @@ -50,7 +50,7 @@ deprecated_python_version = (3, 6, 0) #month_year = 'December 2012' # If copyright years is not given, the release year is used as the end. -copyright_years = '2001 - 2021' +copyright_years = '2001 - 2023' # Local Variables: # tab-width:4 diff --git a/SCons/Environment.py b/SCons/Environment.py index 9140d2726..bd94832a1 100644 --- a/SCons/Environment.py +++ b/SCons/Environment.py @@ -1043,6 +1043,12 @@ class SubstitutionEnvironment: flags distributed into appropriate construction variables. See :meth:`ParseFlags`. + As a side effect, if *unique* is true, a new object is created + for each modified construction variable by the loop at the end. + This is silently expected by the :meth:`Override` *parse_flags* + functionality, which does not want to share the list (or whatever) + with the environment being overridden. + Args: args: flags to merge unique: merge flags rather than appending (default: True). @@ -1077,6 +1083,16 @@ class SubstitutionEnvironment: try: orig = orig + value except (KeyError, TypeError): + # If CPPDEFINES is a deque, adding value (a list) + # results in TypeError, so we handle that case here. + # Just in case we got called from Override, make + # sure we make a copy, because we don't go through + # the cleanup loops at the end of the outer for loop, + # which implicitly gives us a new object. + if isinstance(orig, deque): + self[key] = self[key].copy() + self.AppendUnique(CPPDEFINES=value, delete_existing=True) + continue try: add_to_orig = orig.append except AttributeError: @@ -1095,6 +1111,7 @@ class SubstitutionEnvironment: for v in orig[::-1]: if v not in t: t.insert(0, v) + self[key] = t @@ -1419,7 +1436,7 @@ class Base(SubstitutionEnvironment): if key == 'CPPDEFINES': _add_cppdefines(self._dict, val) continue - + try: orig = self._dict[key] except KeyError: diff --git a/SCons/EnvironmentTests.py b/SCons/EnvironmentTests.py index a021794c9..81143d5c0 100644 --- a/SCons/EnvironmentTests.py +++ b/SCons/EnvironmentTests.py @@ -28,7 +28,7 @@ import io import os import sys import unittest -from collections import UserDict as UD, UserList as UL +from collections import UserDict as UD, UserList as UL, deque import TestCmd @@ -902,6 +902,11 @@ sys.exit(0) assert env['A'] == ['aaa'], env['A'] assert env['B'] == ['b', 'bb', 'bbb'], env['B'] + # issue #4231: CPPDEFINES can be a deque, tripped up merge logic + env = Environment(CPPDEFINES=deque(['aaa', 'bbb'])) + env.MergeFlags({'CPPDEFINES': 'ccc'}) + self.assertEqual(env['CPPDEFINES'], deque(['aaa', 'bbb', 'ccc'])) + # issue #3665: if merging dict which is a compound object # (i.e. value can be lists, etc.), the value object should not # be modified. per the issue, this happened if key not in env. @@ -1821,147 +1826,189 @@ def exists(env): updates and check that the original remains intact and the copy has the updated values. """ - env1 = self.TestEnvironment(XXX='x', YYY='y') - env2 = env1.Clone() - env1copy = env1.Clone() - assert env1copy == env1 - assert env2 == env1 - env2.Replace(YYY = 'yyy') - assert env1 != env2 - assert env1 == env1copy - - env3 = env1.Clone(XXX='x3', ZZZ='z3') - assert env3 != env1 - assert env3.Dictionary('XXX') == 'x3' - assert env1.Dictionary('XXX') == 'x' - assert env3.Dictionary('YYY') == 'y' - assert env3.Dictionary('ZZZ') == 'z3' - assert env1 == env1copy + with self.subTest(): + env1 = self.TestEnvironment(XXX='x', YYY='y') + env2 = env1.Clone() + env1copy = env1.Clone() + self.assertEqual(env1copy, env1) + self.assertEqual(env2, env1) + env2.Replace(YYY = 'yyy') + self.assertNotEqual(env1, env2) + self.assertEqual(env1, env1copy) + + env3 = env1.Clone(XXX='x3', ZZZ='z3') + self.assertNotEqual(env3, env1) + self.assertEqual(env3.Dictionary('XXX'), 'x3') + self.assertEqual(env1.Dictionary('XXX'), 'x') + self.assertEqual(env3.Dictionary('YYY'), 'y') + self.assertEqual(env3.Dictionary('ZZZ'), 'z3') + self.assertRaises(KeyError, env1.Dictionary, 'ZZZ') # leak test + self.assertEqual(env1, env1copy) # Ensure that lists and dictionaries are deep copied, but not instances - class TestA: - pass + with self.subTest(): + + class TestA: + pass - env1 = self.TestEnvironment(XXX=TestA(), YYY=[1, 2, 3], ZZZ={1: 2, 3: 4}) - env2 = env1.Clone() - env2.Dictionary('YYY').append(4) - env2.Dictionary('ZZZ')[5] = 6 - assert env1.Dictionary('XXX') is env2.Dictionary('XXX') - assert 4 in env2.Dictionary('YYY') - assert 4 not in env1.Dictionary('YYY') - assert 5 in env2.Dictionary('ZZZ') - assert 5 not in env1.Dictionary('ZZZ') - - # - env1 = self.TestEnvironment(BUILDERS={'b1': Builder()}) - assert hasattr(env1, 'b1'), "env1.b1 was not set" - assert env1.b1.object == env1, "b1.object doesn't point to env1" - env2 = env1.Clone(BUILDERS = {'b2' : Builder()}) - assert env2 != env1 - assert hasattr(env1, 'b1'), "b1 was mistakenly cleared from env1" - assert env1.b1.object == env1, "b1.object was changed" - assert not hasattr(env2, 'b1'), "b1 was not cleared from env2" - assert hasattr(env2, 'b2'), "env2.b2 was not set" - assert env2.b2.object == env2, "b2.object doesn't point to env2" + env1 = self.TestEnvironment( + XXX=TestA(), + YYY=[1, 2, 3], + ZZZ={1: 2, 3: 4} + ) + env2 = env1.Clone() + env2.Dictionary('YYY').append(4) + env2.Dictionary('ZZZ')[5] = 6 + self.assertIs(env1.Dictionary('XXX'), env2.Dictionary('XXX')) + self.assertIn(4, env2.Dictionary('YYY')) + self.assertNotIn(4, env1.Dictionary('YYY')) + self.assertIn(5, env2.Dictionary('ZZZ')) + self.assertNotIn(5, env1.Dictionary('ZZZ')) + + # We also need to look at the special cases in semi_deepcopy() + # used when cloning - these should not leak to the original either + with self.subTest(): + env1 = self.TestEnvironment( + XXX=deque([1, 2, 3]), + YYY=UL([1, 2, 3]), + ZZZ=UD({1: 2, 3: 4}), + ) + env2 = env1.Clone() + env2['XXX'].append(4) + env2['YYY'].append(4) + env2['ZZZ'][5] = 6 + self.assertIn(4, env2['XXX']) + self.assertNotIn(4, env1['XXX']) + self.assertIn(4, env2['YYY']) + self.assertNotIn(4, env1['YYY']) + self.assertIn(5, env2['ZZZ']) + self.assertNotIn(5, env1['ZZZ']) + + # BUILDERS is special... + with self.subTest(): + env1 = self.TestEnvironment(BUILDERS={'b1': Builder()}) + assert hasattr(env1, 'b1'), "env1.b1 was not set" + assert env1.b1.object == env1, "b1.object doesn't point to env1" + env2 = env1.Clone(BUILDERS = {'b2' : Builder()}) + assert env2 != env1 + assert hasattr(env1, 'b1'), "b1 was mistakenly cleared from env1" + assert env1.b1.object == env1, "b1.object was changed" + assert not hasattr(env2, 'b1'), "b1 was not cleared from env2" + assert hasattr(env2, 'b2'), "env2.b2 was not set" + assert env2.b2.object == env2, "b2.object doesn't point to env2" # Ensure that specifying new tools in a copied environment works. - def foo(env): env['FOO'] = 1 - def bar(env): env['BAR'] = 2 - def baz(env): env['BAZ'] = 3 - env1 = self.TestEnvironment(tools=[foo]) - env2 = env1.Clone() - env3 = env1.Clone(tools=[bar, baz]) - - assert env1.get('FOO') == 1 - assert env1.get('BAR') is None - assert env1.get('BAZ') is None - assert env2.get('FOO') == 1 - assert env2.get('BAR') is None - assert env2.get('BAZ') is None - assert env3.get('FOO') == 1 - assert env3.get('BAR') == 2 - assert env3.get('BAZ') == 3 + with self.subTest(): + + def foo(env): + env['FOO'] = 1 + + def bar(env): + env['BAR'] = 2 + + def baz(env): + env['BAZ'] = 3 + + env1 = self.TestEnvironment(tools=[foo]) + env2 = env1.Clone() + env3 = env1.Clone(tools=[bar, baz]) + + assert env1.get('FOO') == 1 + assert env1.get('BAR') is None + assert env1.get('BAZ') is None + assert env2.get('FOO') == 1 + assert env2.get('BAR') is None + assert env2.get('BAZ') is None + assert env3.get('FOO') == 1 + assert env3.get('BAR') == 2 + assert env3.get('BAZ') == 3 # Ensure that recursive variable substitution when copying # environments works properly. - env1 = self.TestEnvironment(CCFLAGS = '-DFOO', XYZ = '-DXYZ') - env2 = env1.Clone(CCFLAGS = '$CCFLAGS -DBAR', - XYZ = ['-DABC', 'x $XYZ y', '-DDEF']) - x = env2.get('CCFLAGS') - assert x == '-DFOO -DBAR', x - x = env2.get('XYZ') - assert x == ['-DABC', 'x -DXYZ y', '-DDEF'], x + with self.subTest(): + env1 = self.TestEnvironment(CCFLAGS='-DFOO', XYZ='-DXYZ') + env2 = env1.Clone( + CCFLAGS='$CCFLAGS -DBAR', XYZ=['-DABC', 'x $XYZ y', '-DDEF'] + ) + x = env2.get('CCFLAGS') + assert x == '-DFOO -DBAR', x + x = env2.get('XYZ') + assert x == ['-DABC', 'x -DXYZ y', '-DDEF'], x # Ensure that special properties of a class don't get # lost on copying. - env1 = self.TestEnvironment(FLAGS = CLVar('flag1 flag2')) - x = env1.get('FLAGS') - assert x == ['flag1', 'flag2'], x - env2 = env1.Clone() - env2.Append(FLAGS = 'flag3 flag4') - x = env2.get('FLAGS') - assert x == ['flag1', 'flag2', 'flag3', 'flag4'], x - x = env1.get('FLAGS') - assert x == ['flag1', 'flag2'], x + with self.subTest(): + env1 = self.TestEnvironment(FLAGS=CLVar('flag1 flag2')) + x = env1.get('FLAGS') + assert x == ['flag1', 'flag2'], x + env2 = env1.Clone() + env2.Append(FLAGS='flag3 flag4') + x = env2.get('FLAGS') + assert x == ['flag1', 'flag2', 'flag3', 'flag4'], x + x = env1.get('FLAGS') + assert x == ['flag1', 'flag2'], x # Ensure that appending directly to a copied CLVar # doesn't modify the original. - env1 = self.TestEnvironment(FLAGS = CLVar('flag1 flag2')) - x = env1.get('FLAGS') - assert x == ['flag1', 'flag2'], x - env2 = env1.Clone() - env2['FLAGS'] += ['flag3', 'flag4'] - x = env2.get('FLAGS') - assert x == ['flag1', 'flag2', 'flag3', 'flag4'], x - x = env1.get('FLAGS') - assert x == ['flag1', 'flag2'], x + with self.subTest(): + env1 = self.TestEnvironment(FLAGS=CLVar('flag1 flag2')) + x = env1.get('FLAGS') + assert x == ['flag1', 'flag2'], x + env2 = env1.Clone() + env2['FLAGS'] += ['flag3', 'flag4'] + x = env2.get('FLAGS') + assert x == ['flag1', 'flag2', 'flag3', 'flag4'], x + x = env1.get('FLAGS') + assert x == ['flag1', 'flag2'], x # Test that the environment stores the toolpath and # re-uses it for copies. - test = TestCmd.TestCmd(workdir = '') + with self.subTest(): + test = TestCmd.TestCmd(workdir='') - test.write('xxx.py', """\ + test.write('xxx.py', """\ def exists(env): return True def generate(env): env['XXX'] = 'one' """) - test.write('yyy.py', """\ + test.write('yyy.py', """\ def exists(env): return True def generate(env): env['YYY'] = 'two' """) - env = self.TestEnvironment(tools=['xxx'], toolpath=[test.workpath('')]) - assert env['XXX'] == 'one', env['XXX'] - env = env.Clone(tools=['yyy']) - assert env['YYY'] == 'two', env['YYY'] - + env = self.TestEnvironment(tools=['xxx'], toolpath=[test.workpath('')]) + assert env['XXX'] == 'one', env['XXX'] + env = env.Clone(tools=['yyy']) + assert env['YYY'] == 'two', env['YYY'] # Test that - real_value = [4] + with self.subTest(): + real_value = [4] - def my_tool(env, rv=real_value): - assert env['KEY_THAT_I_WANT'] == rv[0] - env['KEY_THAT_I_WANT'] = rv[0] + 1 + def my_tool(env, rv=real_value): + assert env['KEY_THAT_I_WANT'] == rv[0] + env['KEY_THAT_I_WANT'] = rv[0] + 1 - env = self.TestEnvironment() + env = self.TestEnvironment() - real_value[0] = 5 - env = env.Clone(KEY_THAT_I_WANT=5, tools=[my_tool]) - assert env['KEY_THAT_I_WANT'] == real_value[0], env['KEY_THAT_I_WANT'] + real_value[0] = 5 + env = env.Clone(KEY_THAT_I_WANT=5, tools=[my_tool]) + assert env['KEY_THAT_I_WANT'] == real_value[0], env['KEY_THAT_I_WANT'] - real_value[0] = 6 - env = env.Clone(KEY_THAT_I_WANT=6, tools=[my_tool]) - assert env['KEY_THAT_I_WANT'] == real_value[0], env['KEY_THAT_I_WANT'] + real_value[0] = 6 + env = env.Clone(KEY_THAT_I_WANT=6, tools=[my_tool]) + assert env['KEY_THAT_I_WANT'] == real_value[0], env['KEY_THAT_I_WANT'] # test for pull request #150 - env = self.TestEnvironment() - env._dict.pop('BUILDERS') - assert ('BUILDERS' in env) is False - env2 = env.Clone() + with self.subTest(): + env = self.TestEnvironment() + env._dict.pop('BUILDERS') + assert ('BUILDERS' in env) is False + env2 = env.Clone() def test_Detect(self): """Test Detect()ing tools""" @@ -2125,7 +2172,7 @@ def generate(env): ('-isystem', '/usr/include/foo2'), ('-idirafter', '/usr/include/foo3'), '+DD64'], env['CCFLAGS'] - assert env['CPPDEFINES'] == ['FOO', ['BAR', 'value']], env['CPPDEFINES'] + self.assertEqual(list(env['CPPDEFINES']), ['FOO', ['BAR', 'value']]) assert env['CPPFLAGS'] == ['', '-Wp,-cpp'], env['CPPFLAGS'] assert env['CPPPATH'] == ['string', '/usr/include/fum', 'bar'], env['CPPPATH'] assert env['FRAMEWORKPATH'] == ['fwd1', 'fwd2', 'fwd3'], env['FRAMEWORKPATH'] @@ -3620,10 +3667,10 @@ def generate(env): env = Environment(tools=[], CCFLAGS=None, parse_flags = '-Y') assert env['CCFLAGS'] == ['-Y'], env['CCFLAGS'] - env = Environment(tools=[], CPPDEFINES = 'FOO', parse_flags = '-std=c99 -X -DBAR') + env = Environment(tools=[], CPPDEFINES='FOO', parse_flags='-std=c99 -X -DBAR') assert env['CFLAGS'] == ['-std=c99'], env['CFLAGS'] assert env['CCFLAGS'] == ['-X'], env['CCFLAGS'] - assert env['CPPDEFINES'] == ['FOO', 'BAR'], env['CPPDEFINES'] + self.assertEqual(list(env['CPPDEFINES']), ['FOO', 'BAR']) def test_clone_parse_flags(self): """Test the env.Clone() parse_flags argument""" @@ -3645,8 +3692,7 @@ def generate(env): assert 'CCFLAGS' not in env assert env2['CCFLAGS'] == ['-X'], env2['CCFLAGS'] assert env['CPPDEFINES'] == 'FOO', env['CPPDEFINES'] - assert env2['CPPDEFINES'] == ['FOO','BAR'], env2['CPPDEFINES'] - + self.assertEqual(list(env2['CPPDEFINES']), ['FOO','BAR']) class OverrideEnvironmentTestCase(unittest.TestCase,TestEnvironmentFixture): @@ -3936,15 +3982,16 @@ class OverrideEnvironmentTestCase(unittest.TestCase,TestEnvironmentFixture): assert env['CCFLAGS'] is None, env['CCFLAGS'] assert env2['CCFLAGS'] == ['-Y'], env2['CCFLAGS'] - env = SubstitutionEnvironment(CPPDEFINES = 'FOO') - env2 = env.Override({'parse_flags' : '-std=c99 -X -DBAR'}) + env = SubstitutionEnvironment(CPPDEFINES='FOO') + env2 = env.Override({'parse_flags': '-std=c99 -X -DBAR'}) assert 'CFLAGS' not in env assert env2['CFLAGS'] == ['-std=c99'], env2['CFLAGS'] assert 'CCFLAGS' not in env assert env2['CCFLAGS'] == ['-X'], env2['CCFLAGS'] + # make sure they are independent + self.assertIsNot(env['CPPDEFINES'], env2['CPPDEFINES']) assert env['CPPDEFINES'] == 'FOO', env['CPPDEFINES'] - assert env2['CPPDEFINES'] == ['FOO','BAR'], env2['CPPDEFINES'] - + self.assertEqual(list(env2['CPPDEFINES']), ['FOO','BAR']) class NoSubstitutionProxyTestCase(unittest.TestCase,TestEnvironmentFixture): diff --git a/SCons/Script/Main.py b/SCons/Script/Main.py index b90284278..d4228facb 100644 --- a/SCons/Script/Main.py +++ b/SCons/Script/Main.py @@ -505,7 +505,7 @@ def ValidateOptions(throw_exception=False) -> None: :raises SConsBadOptionError: If throw_exception is True and there are invalid options on command line. - .. versionadded:: 4.4.1 + .. versionadded:: 4.5.0 """ OptionsParser.raise_exception_on_error = throw_exception diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml index fbb90fd07..2070c36b0 100644 --- a/SCons/Script/Main.xml +++ b/SCons/Script/Main.xml @@ -1000,9 +1000,9 @@ scons --compilers=mingw (the correct flag is --compiler) Could cause SCons to run configure steps with the incorrect compiler. Costing developer time trying to track down why the configure logic failed with a compiler which should work. </para> - - - + <para> + <emphasis>New in version 4.5.0</emphasis> + </para> </summary> </scons_function> diff --git a/SCons/Tool/qt.py b/SCons/Tool/qt.py index ff995657d..607b58d83 100644 --- a/SCons/Tool/qt.py +++ b/SCons/Tool/qt.py @@ -21,351 +21,18 @@ # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -"""Tool-specific initialization for Qt. - -There normally shouldn't be any need to import this module directly. -It will usually be imported through the generic SCons.Tool.Tool() -selection method. """ - -import os.path -import re - -import SCons.Action -import SCons.Builder -import SCons.Defaults -import SCons.Scanner -import SCons.Tool -import SCons.Util -import SCons.Tool.cxx -import SCons.Warnings -cplusplus = SCons.Tool.cxx - -class ToolQtWarning(SCons.Warnings.SConsWarning): - pass - -class GeneratedMocFileNotIncluded(ToolQtWarning): - pass - -class QtdirNotFound(ToolQtWarning): - pass - -SCons.Warnings.enableWarningClass(ToolQtWarning) - -header_extensions = [".h", ".hxx", ".hpp", ".hh"] -if SCons.Util.case_sensitive_suffixes('.h', '.H'): - header_extensions.append('.H') - -cxx_suffixes = cplusplus.CXXSuffixes - - -def find_platform_specific_qt_paths(): - """ - find non-standard QT paths - - If the platform does not put QT tools in standard search paths, - the path is expected to be set using QTDIR. SCons violates - the normal rule of not pulling from the user's environment - in this case. However, some test cases try to validate what - happens when QTDIR is unset, so we need to try to make a guess. - - :return: a guess at a path - """ - - # qt_bin_dirs = [] - qt_bin_dir = None - if os.path.isfile('/etc/redhat-release'): - with open('/etc/redhat-release','r') as rr: - lines = rr.readlines() - distro = lines[0].split()[0] - if distro == 'CentOS': - # Centos installs QT under /usr/{lib,lib64}/qt{4,5,-3.3}/bin - # so we need to handle this differently - # qt_bin_dirs = glob.glob('/usr/lib64/qt*/bin') - # TODO: all current Fedoras do the same, need to look deeper here. - qt_bin_dir = '/usr/lib64/qt-3.3/bin' - - return qt_bin_dir - - -QT_BIN_DIR = find_platform_specific_qt_paths() - -def checkMocIncluded(target, source, env): - moc = target[0] - cpp = source[0] - # looks like cpp.includes is cleared before the build stage :-( - # not really sure about the path transformations (moc.cwd? cpp.cwd?) :-/ - path = SCons.Defaults.CScan.path(env, moc.cwd) - includes = SCons.Defaults.CScan(cpp, env, path) - if moc not in includes: - SCons.Warnings.warn( - GeneratedMocFileNotIncluded, - "Generated moc file '%s' is not included by '%s'" % - (str(moc), str(cpp))) - -def find_file(filename, paths, node_factory): - for dir in paths: - node = node_factory(filename, dir) - if node.rexists(): - return node - return None - -class _Automoc: - """ - Callable class, which works as an emitter for Programs, SharedLibraries and - StaticLibraries. - """ - - def __init__(self, objBuilderName): - self.objBuilderName = objBuilderName - - def __call__(self, target, source, env): - """ - Smart autoscan function. Gets the list of objects for the Program - or Lib. Adds objects and builders for the special qt files. - """ - try: - if int(env.subst('$QT_AUTOSCAN')) == 0: - return target, source - except ValueError: - pass - try: - debug = int(env.subst('$QT_DEBUG')) - except ValueError: - debug = 0 - - # some shortcuts used in the scanner - splitext = SCons.Util.splitext - objBuilder = getattr(env, self.objBuilderName) - - # some regular expressions: - # Q_OBJECT detection - q_object_search = re.compile(r'[^A-Za-z0-9]Q_OBJECT[^A-Za-z0-9]') - # cxx and c comment 'eater' - #comment = re.compile(r'(//.*)|(/\*(([^*])|(\*[^/]))*\*/)') - # CW: something must be wrong with the regexp. See also bug #998222 - # CURRENTLY THERE IS NO TEST CASE FOR THAT - - # The following is kind of hacky to get builders working properly (FIXME) - objBuilderEnv = objBuilder.env - objBuilder.env = env - mocBuilderEnv = env.Moc.env - env.Moc.env = env - - # make a deep copy for the result; MocH objects will be appended - out_sources = source[:] - - for obj in source: - if not obj.has_builder(): - # binary obj file provided - if debug: - print("scons: qt: '%s' seems to be a binary. Discarded." % str(obj)) - continue - cpp = obj.sources[0] - if not splitext(str(cpp))[1] in cxx_suffixes: - if debug: - print("scons: qt: '%s' is no cxx file. Discarded." % str(cpp)) - # c or fortran source - continue - #cpp_contents = comment.sub('', cpp.get_text_contents()) - if debug: - print("scons: qt: Getting contents of %s" % cpp) - cpp_contents = cpp.get_text_contents() - h=None - for h_ext in header_extensions: - # try to find the header file in the corresponding source - # directory - hname = splitext(cpp.name)[0] + h_ext - h = find_file(hname, (cpp.get_dir(),), env.File) - if h: - if debug: - print("scons: qt: Scanning '%s' (header of '%s')" % (str(h), str(cpp))) - #h_contents = comment.sub('', h.get_text_contents()) - h_contents = h.get_text_contents() - break - if not h and debug: - print("scons: qt: no header for '%s'." % (str(cpp))) - if h and q_object_search.search(h_contents): - # h file with the Q_OBJECT macro found -> add moc_cpp - moc_cpp = env.Moc(h) - moc_o = objBuilder(moc_cpp) - out_sources.append(moc_o) - #moc_cpp.target_scanner = SCons.Defaults.CScan - if debug: - print("scons: qt: found Q_OBJECT macro in '%s', moc'ing to '%s'" % (str(h), str(moc_cpp))) - if cpp and q_object_search.search(cpp_contents): - # cpp file with Q_OBJECT macro found -> add moc - # (to be included in cpp) - moc = env.Moc(cpp) - env.Ignore(moc, moc) - if debug: - print("scons: qt: found Q_OBJECT macro in '%s', moc'ing to '%s'" % (str(cpp), str(moc))) - #moc.source_scanner = SCons.Defaults.CScan - # restore the original env attributes (FIXME) - objBuilder.env = objBuilderEnv - env.Moc.env = mocBuilderEnv - - return (target, out_sources) - -AutomocShared = _Automoc('SharedObject') -AutomocStatic = _Automoc('StaticObject') - -def _detect(env): - """Not really safe, but fast method to detect the QT library""" - - QTDIR = env.get('QTDIR',None) - if not QTDIR: - QTDIR = os.environ.get('QTDIR',None) - if not QTDIR: - moc = env.WhereIs('moc') or env.WhereIs('moc',QT_BIN_DIR) - if moc: - QTDIR = os.path.dirname(os.path.dirname(moc)) - SCons.Warnings.warn( - QtdirNotFound, - "Could not detect qt, using moc executable as a hint (QTDIR=%s)" % QTDIR) - else: - QTDIR = None - SCons.Warnings.warn( - QtdirNotFound, - "Could not detect qt, using empty QTDIR") - return QTDIR - -def uicEmitter(target, source, env): - adjustixes = SCons.Util.adjustixes - bs = SCons.Util.splitext(str(source[0].name))[0] - bs = os.path.join(str(target[0].get_dir()),bs) - # first target (header) is automatically added by builder - if len(target) < 2: - # second target is implementation - target.append(adjustixes(bs, - env.subst('$QT_UICIMPLPREFIX'), - env.subst('$QT_UICIMPLSUFFIX'))) - if len(target) < 3: - # third target is moc file - target.append(adjustixes(bs, - env.subst('$QT_MOCHPREFIX'), - env.subst('$QT_MOCHSUFFIX'))) - return target, source - -def uicScannerFunc(node, env, path): - lookout = [] - lookout.extend(env['CPPPATH']) - lookout.append(str(node.rfile().dir)) - includes = re.findall("<include.*?>(.*?)</include>", node.get_text_contents()) - result = [] - for incFile in includes: - dep = env.FindFile(incFile,lookout) - if dep: - result.append(dep) - return result - -uicScanner = SCons.Scanner.ScannerBase(uicScannerFunc, - name = "UicScanner", - node_class = SCons.Node.FS.File, - node_factory = SCons.Node.FS.File, - recursive = 0) +This is a fake tool to instruct any builds still referencing 'qt' instead +of the new 'qt3' or a newer QT builder how to fix their now broken build. +""" +import SCons.Errors def generate(env): - """Add Builders and construction variables for qt to an Environment.""" - CLVar = SCons.Util.CLVar - Action = SCons.Action.Action - Builder = SCons.Builder.Builder - - SCons.Warnings.warn( - SCons.Warnings.ToolQtDeprecatedWarning, "Tool module for Qt version 3 is deprecated" + raise SCons.Errors.UserError( + "Deprecated tool 'qt' renamed to 'qt3'. " + "Please update your build accordingly. " + "'qt3' will be removed entirely in a future release." ) - env.SetDefault(QTDIR = _detect(env), - QT_BINPATH = os.path.join('$QTDIR', 'bin'), - QT_CPPPATH = os.path.join('$QTDIR', 'include'), - QT_LIBPATH = os.path.join('$QTDIR', 'lib'), - QT_MOC = os.path.join('$QT_BINPATH','moc'), - QT_UIC = os.path.join('$QT_BINPATH','uic'), - QT_LIB = 'qt', # may be set to qt-mt - - QT_AUTOSCAN = 1, # scan for moc'able sources - - # Some QT specific flags. I don't expect someone wants to - # manipulate those ... - QT_UICIMPLFLAGS = CLVar(''), - QT_UICDECLFLAGS = CLVar(''), - QT_MOCFROMHFLAGS = CLVar(''), - QT_MOCFROMCXXFLAGS = CLVar('-i'), - - # suffixes/prefixes for the headers / sources to generate - QT_UICDECLPREFIX = '', - QT_UICDECLSUFFIX = '.h', - QT_UICIMPLPREFIX = 'uic_', - QT_UICIMPLSUFFIX = '$CXXFILESUFFIX', - QT_MOCHPREFIX = 'moc_', - QT_MOCHSUFFIX = '$CXXFILESUFFIX', - QT_MOCCXXPREFIX = '', - QT_MOCCXXSUFFIX = '.moc', - QT_UISUFFIX = '.ui', - - # Commands for the qt support ... - # command to generate header, implementation and moc-file - # from a .ui file - QT_UICCOM = [ - CLVar('$QT_UIC $QT_UICDECLFLAGS -o ${TARGETS[0]} $SOURCE'), - CLVar('$QT_UIC $QT_UICIMPLFLAGS -impl ${TARGETS[0].file} ' - '-o ${TARGETS[1]} $SOURCE'), - CLVar('$QT_MOC $QT_MOCFROMHFLAGS -o ${TARGETS[2]} ${TARGETS[0]}')], - # command to generate meta object information for a class - # declarated in a header - QT_MOCFROMHCOM = ( - '$QT_MOC $QT_MOCFROMHFLAGS -o ${TARGETS[0]} $SOURCE'), - # command to generate meta object information for a class - # declarated in a cpp file - QT_MOCFROMCXXCOM = [ - CLVar('$QT_MOC $QT_MOCFROMCXXFLAGS -o ${TARGETS[0]} $SOURCE'), - Action(checkMocIncluded,None)]) - - # ... and the corresponding builders - uicBld = Builder(action=SCons.Action.Action('$QT_UICCOM', '$QT_UICCOMSTR'), - emitter=uicEmitter, - src_suffix='$QT_UISUFFIX', - suffix='$QT_UICDECLSUFFIX', - prefix='$QT_UICDECLPREFIX', - source_scanner=uicScanner) - mocBld = Builder(action={}, prefix={}, suffix={}) - for h in header_extensions: - act = SCons.Action.Action('$QT_MOCFROMHCOM', '$QT_MOCFROMHCOMSTR') - mocBld.add_action(h, act) - mocBld.prefix[h] = '$QT_MOCHPREFIX' - mocBld.suffix[h] = '$QT_MOCHSUFFIX' - for cxx in cxx_suffixes: - act = SCons.Action.Action('$QT_MOCFROMCXXCOM', '$QT_MOCFROMCXXCOMSTR') - mocBld.add_action(cxx, act) - mocBld.prefix[cxx] = '$QT_MOCCXXPREFIX' - mocBld.suffix[cxx] = '$QT_MOCCXXSUFFIX' - - # register the builders - env['BUILDERS']['Uic'] = uicBld - env['BUILDERS']['Moc'] = mocBld - static_obj, shared_obj = SCons.Tool.createObjBuilders(env) - static_obj.add_src_builder('Uic') - shared_obj.add_src_builder('Uic') - - # We use the emitters of Program / StaticLibrary / SharedLibrary - # to scan for moc'able files - # We can't refer to the builders directly, we have to fetch them - # as Environment attributes because that sets them up to be called - # correctly later by our emitter. - env.AppendUnique(PROGEMITTER =[AutomocStatic], - SHLIBEMITTER=[AutomocShared], - LDMODULEEMITTER=[AutomocShared], - LIBEMITTER =[AutomocStatic], - # Of course, we need to link against the qt libraries - CPPPATH=["$QT_CPPPATH"], - LIBPATH=["$QT_LIBPATH"], - LIBS=['$QT_LIB']) - def exists(env): - return _detect(env) - -# Local Variables: -# tab-width:4 -# indent-tabs-mode:nil -# End: -# vim: set expandtab tabstop=4 shiftwidth=4: + return False diff --git a/SCons/Tool/qt.xml b/SCons/Tool/qt.xml index 5298a82c4..3ba71b92c 100644 --- a/SCons/Tool/qt.xml +++ b/SCons/Tool/qt.xml @@ -26,422 +26,9 @@ See its __doc__ string for a discussion of the format. <tool name="qt"> <summary> <para> -Sets &consvars; for building Qt3 applications. -</para> - -<note><para> -This tool is only suitable for building targeted to Qt3, -which is obsolete -(<emphasis>the tool is deprecated since 4.3</emphasis>). -There are contributed tools for Qt4 and Qt5, see -<ulink url="https://github.com/SCons/scons-contrib"> -https://github.com/SCons/scons-contrib</ulink>. -Qt4 has also passed end of life for standard support (in Dec 2015). -</para></note> - -<para> -Note paths for these &consvars; are assembled -using the <function>os.path.join</function> method -so they will have the appropriate separator at runtime, -but are listed here in the various -entries only with the <literal>'/'</literal> separator -for simplicity. -</para> - -<para> -In addition, the &consvars; -&cv-link-CPPPATH;, -&cv-link-LIBPATH; and -&cv-link-LIBS; may be modified -and the variables -&cv-link-PROGEMITTER;, &cv-link-SHLIBEMITTER; and &cv-link-LIBEMITTER; -are modified. Because the build-performance is affected when using this tool, -you have to explicitly specify it at Environment creation: -</para> - -<example_commands> -Environment(tools=['default','qt']) -</example_commands> - -<para> -The &t-qt; tool supports the following operations: -</para> - -<para> -<emphasis role="strong">Automatic moc file generation from header files.</emphasis> -You do not have to specify moc files explicitly, the tool does it for you. -However, there are a few preconditions to do so: Your header file must have -the same filebase as your implementation file and must stay in the same -directory. It must have one of the suffixes -<filename>.h</filename>, -<filename>.hpp</filename>, -<filename>.H</filename>, -<filename>.hxx</filename>, -<filename>.hh</filename>. -You can turn off automatic moc file generation by setting -&cv-link-QT_AUTOSCAN; to <constant>False</constant>. -See also the corresponding -&b-link-Moc; Builder. -</para> - -<para> -<emphasis role="strong">Automatic moc file generation from C++ files.</emphasis> -As described in the Qt documentation, include the moc file at the end of -the C++ file. Note that you have to include the file, which is generated -by the transformation -<literal>${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}</literal>, by default -<filename><basename>.mo</filename>. A warning is generated after building the moc file if you -do not include the correct file. If you are using &f-link-VariantDir;, you may -need to specify <parameter>duplicate=True</parameter>. -You can turn off automatic moc file generation by setting &cv-QT_AUTOSCAN; to -<literal>False</literal>. See also the corresponding -&b-link-Moc; Builder. -</para> - -<para> -<emphasis role="strong">Automatic handling of .ui files.</emphasis> -The implementation files generated from <filename>.ui</filename> -files are handled much the same as yacc or lex files. -Each <command>.ui</command> file given as a source of &b-link-Program;, -&b-link-Library; or &b-link-SharedLibrary; -will generate three files: the declaration file, the -implementation file and a moc file. Because there are also generated headers, -you may need to specify <parameter>duplicate=True</parameter> in calls to -&f-link-VariantDir;. -See also the corresponding -&b-link-Uic; Builder. +Placeholder tool to alert anyone still using qt tools to switch to qt3 or newer tool. </para> </summary> -<sets> -<item>QTDIR</item> -<item>QT_BINPATH</item> -<item>QT_CPPPATH</item> -<item>QT_LIBPATH</item> -<item>QT_MOC</item> -<item>QT_UIC</item> -<item>QT_LIB</item> -<item>QT_AUTOSCAN</item> -<item>QT_UICIMPLFLAGS</item> -<item>QT_UICDECLFLAGS</item> -<item>QT_MOCFROMHFLAGS</item> -<item>QT_MOCFROMCXXFLAGS</item> -<item>QT_UICDECLPREFIX</item> -<item>QT_UICDECLSUFFIX</item> -<item>QT_UICIMPLPREFIX</item> -<item>QT_UICIMPLSUFFIX</item> -<item>QT_MOCHPREFIX</item> -<item>QT_MOCHSUFFIX</item> -<item>QT_MOCCXXPREFIX</item> -<item>QT_MOCCXXSUFFIX</item> -<item>QT_UISUFFIX</item> -<item>QT_UICCOM</item> -<item>QT_MOCFROMHCOM</item> -<item>QT_MOCFROMCXXCOM</item> -</sets> -<uses> -<item>QTDIR</item> -</uses> </tool> -<builder name="Moc"> -<summary> -<para> -Builds an output file from a <command>moc</command> input file. -<command>moc</command> input files are either header files or C++ files. -This builder is only available after using the -tool &t-link-qt;. See the &cv-link-QTDIR; variable for more information. -Example: -</para> - -<example_commands> -env.Moc('foo.h') # generates moc_foo.cc -env.Moc('foo.cpp') # generates foo.moc -</example_commands> -</summary> -</builder> - -<builder name="Uic"> -<summary> -<para> -Builds a header file, an implementation file and a moc file from an ui file. -and returns the corresponding nodes in the that order. -This builder is only available after using the tool &t-link-qt;. -Note: you can specify <filename>.ui</filename> files directly as source -files to the &b-link-Program;, -&b-link-Library; and &b-link-SharedLibrary; builders -without using this builder. Using this builder lets you override the standard -naming conventions (be careful: prefixes are always prepended to names of -built files; if you don't want prefixes, you may set them to ``). -See the &cv-link-QTDIR; variable for more information. -Example: -</para> - -<example_commands> -env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] -env.Uic( - target=Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), - source='foo.ui' -) # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc'] -</example_commands> -</summary> -</builder> - -<cvar name="QTDIR"> -<summary> -<para> -The path to the Qt installation to build against. -If not already set, -&t-link-qt; tool tries to obtain this from -<varname>os.environ</varname>; -if not found there, it tries to make a guess. -</para> -</summary> -</cvar> - -<cvar name="QT_AUTOSCAN"> -<summary> -<para> -Turn off scanning for mocable files. Use the &b-link-Moc; Builder to explicitly -specify files to run <command>moc</command> on. -</para> -</summary> -</cvar> - -<cvar name="QT_BINPATH"> -<summary> -<para> -The path where the Qt binaries are installed. -The default value is '&cv-link-QTDIR;<filename>/bin</filename>'. -</para> -</summary> -</cvar> - -<cvar name="QT_CPPPATH"> -<summary> -<para> -The path where the Qt header files are installed. -The default value is '&cv-link-QTDIR;/include'. -Note: If you set this variable to <constant>None</constant>, -the tool won't change the &cv-link-CPPPATH; -construction variable. -</para> -</summary> -</cvar> - -<cvar name="QT_DEBUG"> -<summary> -<para> -Prints lots of debugging information while scanning for moc files. -</para> -</summary> -</cvar> - -<cvar name="QT_LIB"> -<summary> -<para> -Default value is <literal>'qt'</literal>. -You may want to set this to <literal>'qt-mt'</literal>. -Note: If you set this variable to <constant>None</constant>, -the tool won't change the &cv-link-LIBS; variable. -</para> -</summary> -</cvar> - -<cvar name="QT_LIBPATH"> -<summary> -<para> -The path where the Qt libraries are installed. -The default value is '&cv-link-QTDIR;<filename>/lib</filename>'. -Note: If you set this variable to <constant>None</constant>, -the tool won't change the &cv-link-LIBPATH; -construction variable. -</para> -</summary> -</cvar> - -<cvar name="QT_MOC"> -<summary> -<para> -Default value is '&cv-link-QT_BINPATH;<filename>/moc</filename>'. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCCXXPREFIX"> -<summary> -<para> -Default value is <literal>''</literal>. -Prefix for <command>moc</command> output files when source is a C++ file. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCCXXSUFFIX"> -<summary> -<para> -Default value is <literal>'.moc'</literal>. -Suffix for <command>moc</command> output files when source is a C++ file. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCFROMCXXFLAGS"> -<summary> -<para> -Default value is <literal>'-i'</literal>. -These flags are passed to <command>moc</command> when moccing a C++ file. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCFROMCXXCOM"> -<summary> -<para> -Command to generate a moc file from a C++ file. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCFROMCXXCOMSTR"> -<summary> -<para> -The string displayed when generating a moc file from a C++ file. -If this is not set, then &cv-link-QT_MOCFROMCXXCOM; (the command line) is displayed. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCFROMHCOM"> -<summary> -<para> -Command to generate a moc file from a header. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCFROMHCOMSTR"> -<summary> -<para> -The string displayed when generating a moc file from a C++ file. -If this is not set, then &cv-link-QT_MOCFROMHCOM; (the command line) is displayed. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCFROMHFLAGS"> -<summary> -<para> -Default value is <literal>''</literal>. These flags are passed to <command>moc</command> -when moccing a header file. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCHPREFIX"> -<summary> -<para> -Default value is <literal>'moc_'</literal>. -Prefix for <command>moc</command> output files when source is a header. -</para> -</summary> -</cvar> - -<cvar name="QT_MOCHSUFFIX"> -<summary> -<para> -Default value is '&cv-link-CXXFILESUFFIX;'. -Suffix for moc output files when source is a header. -</para> -</summary> -</cvar> - -<cvar name="QT_UIC"> -<summary> -<para> -Default value is '&cv-link-QT_BINPATH;<filename>/uic</filename>'. -</para> -</summary> -</cvar> - -<cvar name="QT_UICCOM"> -<summary> -<para> -Command to generate header files from <filename>.ui</filename> files. -</para> -</summary> -</cvar> - -<cvar name="QT_UICCOMSTR"> -<summary> -<para> -The string displayed when generating header files from <filename>.ui</filename> files. -If this is not set, then &cv-link-QT_UICCOM; (the command line) is displayed. -</para> -</summary> -</cvar> - -<cvar name="QT_UICDECLFLAGS"> -<summary> -<para> -Default value is ''. These flags are passed to <command>uic</command> -when creating a header file from a <filename>.ui</filename> file. -</para> -</summary> -</cvar> - -<cvar name="QT_UICDECLPREFIX"> -<summary> -<para> -Default value is <literal>''</literal>. -Prefix for <command>uic</command> generated header files. -</para> -</summary> -</cvar> - -<cvar name="QT_UICDECLSUFFIX"> -<summary> -<para> -Default value is <literal>'.h'</literal>. -Suffix for <command>uic</command> generated header files. -</para> -</summary> -</cvar> - -<cvar name="QT_UICIMPLFLAGS"> -<summary> -<para> -Default value is <literal>''</literal>. -These flags are passed to <command>uic</command> when creating a C++ -file from a <filename>.ui</filename> file. -</para> -</summary> -</cvar> - -<cvar name="QT_UICIMPLPREFIX"> -<summary> -<para> -Default value is <literal>'uic_'</literal>. -Prefix for uic generated implementation files. -</para> -</summary> -</cvar> - -<cvar name="QT_UICIMPLSUFFIX"> -<summary> -<para> -Default value is '&cv-link-CXXFILESUFFIX;'. Suffix for uic generated implementation -files. -</para> -</summary> -</cvar> - -<cvar name="QT_UISUFFIX"> -<summary> -<para> -Default value is <literal>'.ui'</literal>. -Suffix of designer input files. -</para> -</summary> -</cvar> - </sconsdoc> diff --git a/SCons/Tool/qt3.py b/SCons/Tool/qt3.py new file mode 100644 index 000000000..4e6975648 --- /dev/null +++ b/SCons/Tool/qt3.py @@ -0,0 +1,371 @@ +# MIT License +# +# Copyright The SCons Foundation +# +# Permission is hereby granted, free of charge, to any person obtaining +# a copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# without limitation the rights to use, copy, modify, merge, publish, +# distribute, sublicense, and/or sell copies of the Software, and to +# permit persons to whom the Software is furnished to do so, subject to +# the following conditions: +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY +# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +"""Tool-specific initialization for Qt. + +There normally shouldn't be any need to import this module directly. +It will usually be imported through the generic SCons.Tool.Tool() +selection method. +""" + +import os.path +import re + +import SCons.Action +import SCons.Builder +import SCons.Defaults +import SCons.Scanner +import SCons.Tool +import SCons.Util +import SCons.Tool.cxx +import SCons.Warnings +cplusplus = SCons.Tool.cxx + +class ToolQtWarning(SCons.Warnings.SConsWarning): + pass + +class GeneratedMocFileNotIncluded(ToolQtWarning): + pass + +class QtdirNotFound(ToolQtWarning): + pass + +SCons.Warnings.enableWarningClass(ToolQtWarning) + +header_extensions = [".h", ".hxx", ".hpp", ".hh"] +if SCons.Util.case_sensitive_suffixes('.h', '.H'): + header_extensions.append('.H') + +cxx_suffixes = cplusplus.CXXSuffixes + + +def find_platform_specific_qt3_paths(): + """ + find non-standard QT paths + + If the platform does not put QT tools in standard search paths, + the path is expected to be set using QT3DIR. SCons violates + the normal rule of not pulling from the user's environment + in this case. However, some test cases try to validate what + happens when QT3DIR is unset, so we need to try to make a guess. + + :return: a guess at a path + """ + + # qt3_bin_dirs = [] + qt3_bin_dir = None + if os.path.isfile('/etc/redhat-release'): + with open('/etc/redhat-release','r') as rr: + lines = rr.readlines() + distro = lines[0].split()[0] + if distro == 'CentOS': + # Centos installs QT under /usr/{lib,lib64}/qt{4,5,-3.3}/bin + # so we need to handle this differently + # qt3_bin_dirs = glob.glob('/usr/lib64/qt*/bin') + # TODO: all current Fedoras do the same, need to look deeper here. + qt3_bin_dir = '/usr/lib64/qt-3.3/bin' + + return qt3_bin_dir + + +QT3_BIN_DIR = find_platform_specific_qt3_paths() + +def checkMocIncluded(target, source, env): + moc = target[0] + cpp = source[0] + # looks like cpp.includes is cleared before the build stage :-( + # not really sure about the path transformations (moc.cwd? cpp.cwd?) :-/ + path = SCons.Defaults.CScan.path(env, moc.cwd) + includes = SCons.Defaults.CScan(cpp, env, path) + if moc not in includes: + SCons.Warnings.warn( + GeneratedMocFileNotIncluded, + "Generated moc file '%s' is not included by '%s'" % + (str(moc), str(cpp))) + +def find_file(filename, paths, node_factory): + for dir in paths: + node = node_factory(filename, dir) + if node.rexists(): + return node + return None + +class _Automoc: + """ + Callable class, which works as an emitter for Programs, SharedLibraries and + StaticLibraries. + """ + + def __init__(self, objBuilderName): + self.objBuilderName = objBuilderName + + def __call__(self, target, source, env): + """ + Smart autoscan function. Gets the list of objects for the Program + or Lib. Adds objects and builders for the special qt3 files. + """ + try: + if int(env.subst('$QT3_AUTOSCAN')) == 0: + return target, source + except ValueError: + pass + try: + debug = int(env.subst('$QT3_DEBUG')) + except ValueError: + debug = 0 + + # some shortcuts used in the scanner + splitext = SCons.Util.splitext + objBuilder = getattr(env, self.objBuilderName) + + # some regular expressions: + # Q_OBJECT detection + q_object_search = re.compile(r'[^A-Za-z0-9]Q_OBJECT[^A-Za-z0-9]') + # cxx and c comment 'eater' + #comment = re.compile(r'(//.*)|(/\*(([^*])|(\*[^/]))*\*/)') + # CW: something must be wrong with the regexp. See also bug #998222 + # CURRENTLY THERE IS NO TEST CASE FOR THAT + + # The following is kind of hacky to get builders working properly (FIXME) + objBuilderEnv = objBuilder.env + objBuilder.env = env + mocBuilderEnv = env.Moc.env + env.Moc.env = env + + # make a deep copy for the result; MocH objects will be appended + out_sources = source[:] + + for obj in source: + if not obj.has_builder(): + # binary obj file provided + if debug: + print("scons: qt3: '%s' seems to be a binary. Discarded." % str(obj)) + continue + cpp = obj.sources[0] + if not splitext(str(cpp))[1] in cxx_suffixes: + if debug: + print("scons: qt3: '%s' is no cxx file. Discarded." % str(cpp)) + # c or fortran source + continue + #cpp_contents = comment.sub('', cpp.get_text_contents()) + if debug: + print("scons: qt3: Getting contents of %s" % cpp) + cpp_contents = cpp.get_text_contents() + h=None + for h_ext in header_extensions: + # try to find the header file in the corresponding source + # directory + hname = splitext(cpp.name)[0] + h_ext + h = find_file(hname, (cpp.get_dir(),), env.File) + if h: + if debug: + print("scons: qt3: Scanning '%s' (header of '%s')" % (str(h), str(cpp))) + #h_contents = comment.sub('', h.get_text_contents()) + h_contents = h.get_text_contents() + break + if not h and debug: + print("scons: qt3: no header for '%s'." % (str(cpp))) + if h and q_object_search.search(h_contents): + # h file with the Q_OBJECT macro found -> add moc_cpp + moc_cpp = env.Moc(h) + moc_o = objBuilder(moc_cpp) + out_sources.append(moc_o) + #moc_cpp.target_scanner = SCons.Defaults.CScan + if debug: + print("scons: qt3: found Q_OBJECT macro in '%s', moc'ing to '%s'" % (str(h), str(moc_cpp))) + if cpp and q_object_search.search(cpp_contents): + # cpp file with Q_OBJECT macro found -> add moc + # (to be included in cpp) + moc = env.Moc(cpp) + env.Ignore(moc, moc) + if debug: + print("scons: qt3: found Q_OBJECT macro in '%s', moc'ing to '%s'" % (str(cpp), str(moc))) + #moc.source_scanner = SCons.Defaults.CScan + # restore the original env attributes (FIXME) + objBuilder.env = objBuilderEnv + env.Moc.env = mocBuilderEnv + + return (target, out_sources) + +AutomocShared = _Automoc('SharedObject') +AutomocStatic = _Automoc('StaticObject') + +def _detect_qt3(env): + """Not really safe, but fast method to detect the QT library""" + + QT3DIR = env.get('QT3DIR',None) + if not QT3DIR: + QT3DIR = os.environ.get('QTDIR',None) + if not QT3DIR: + moc = env.WhereIs('moc') or env.WhereIs('moc',QT3_BIN_DIR) + if moc: + QT3DIR = os.path.dirname(os.path.dirname(moc)) + SCons.Warnings.warn( + QtdirNotFound, + "Could not detect qt3, using moc executable as a hint (QT3DIR=%s)" % QT3DIR) + else: + QT3DIR = None + SCons.Warnings.warn( + QtdirNotFound, + "Could not detect qt3, using empty QT3DIR") + return QT3DIR + +def uicEmitter(target, source, env): + adjustixes = SCons.Util.adjustixes + bs = SCons.Util.splitext(str(source[0].name))[0] + bs = os.path.join(str(target[0].get_dir()),bs) + # first target (header) is automatically added by builder + if len(target) < 2: + # second target is implementation + target.append(adjustixes(bs, + env.subst('$QT3_UICIMPLPREFIX'), + env.subst('$QT3_UICIMPLSUFFIX'))) + if len(target) < 3: + # third target is moc file + target.append(adjustixes(bs, + env.subst('$QT3_MOCHPREFIX'), + env.subst('$QT3_MOCHSUFFIX'))) + return target, source + +def uicScannerFunc(node, env, path): + lookout = [] + lookout.extend(env['CPPPATH']) + lookout.append(str(node.rfile().dir)) + includes = re.findall("<include.*?>(.*?)</include>", node.get_text_contents()) + result = [] + for incFile in includes: + dep = env.FindFile(incFile,lookout) + if dep: + result.append(dep) + return result + +uicScanner = SCons.Scanner.ScannerBase(uicScannerFunc, + name = "UicScanner", + node_class = SCons.Node.FS.File, + node_factory = SCons.Node.FS.File, + recursive = 0) + +def generate(env): + """Add Builders and construction variables for qt3 to an Environment.""" + CLVar = SCons.Util.CLVar + Action = SCons.Action.Action + Builder = SCons.Builder.Builder + + qt3path = _detect_qt3(env) + if qt3path is None: + return None + + env.SetDefault(QT3DIR = qt3path, + QT3_BINPATH = os.path.join('$QT3DIR', 'bin'), + QT3_CPPPATH = os.path.join('$QT3DIR', 'include'), + QT3_LIBPATH = os.path.join('$QT3DIR', 'lib'), + QT3_MOC = os.path.join('$QT3_BINPATH','moc'), + QT3_UIC = os.path.join('$QT3_BINPATH','uic'), + QT3_LIB = 'qt', # may be set to qt-mt + + QT3_AUTOSCAN = 1, # scan for moc'able sources + + # Some QT specific flags. I don't expect someone wants to + # manipulate those ... + QT3_UICIMPLFLAGS = CLVar(''), + QT3_UICDECLFLAGS = CLVar(''), + QT3_MOCFROMHFLAGS = CLVar(''), + QT3_MOCFROMCXXFLAGS = CLVar('-i'), + + # suffixes/prefixes for the headers / sources to generate + QT3_UICDECLPREFIX = '', + QT3_UICDECLSUFFIX = '.h', + QT3_UICIMPLPREFIX = 'uic_', + QT3_UICIMPLSUFFIX = '$CXXFILESUFFIX', + QT3_MOCHPREFIX = 'moc_', + QT3_MOCHSUFFIX = '$CXXFILESUFFIX', + QT3_MOCCXXPREFIX = '', + QT3_MOCCXXSUFFIX = '.moc', + QT3_UISUFFIX = '.ui', + + # Commands for the qt3 support ... + # command to generate header, implementation and moc-file + # from a .ui file + QT3_UICCOM = [ + CLVar('$QT3_UIC $QT3_UICDECLFLAGS -o ${TARGETS[0]} $SOURCE'), + CLVar('$QT3_UIC $QT3_UICIMPLFLAGS -impl ${TARGETS[0].file} ' + '-o ${TARGETS[1]} $SOURCE'), + CLVar('$QT3_MOC $QT3_MOCFROMHFLAGS -o ${TARGETS[2]} ${TARGETS[0]}')], + # command to generate meta object information for a class + # declarated in a header + QT3_MOCFROMHCOM = ( + '$QT3_MOC $QT3_MOCFROMHFLAGS -o ${TARGETS[0]} $SOURCE'), + # command to generate meta object information for a class + # declarated in a cpp file + QT3_MOCFROMCXXCOM = [ + CLVar('$QT3_MOC $QT3_MOCFROMCXXFLAGS -o ${TARGETS[0]} $SOURCE'), + Action(checkMocIncluded,None)]) + + # ... and the corresponding builders + uicBld = Builder(action=SCons.Action.Action('$QT3_UICCOM', '$QT3_UICCOMSTR'), + emitter=uicEmitter, + src_suffix='$QT3_UISUFFIX', + suffix='$QT3_UICDECLSUFFIX', + prefix='$QT3_UICDECLPREFIX', + source_scanner=uicScanner) + mocBld = Builder(action={}, prefix={}, suffix={}) + for h in header_extensions: + act = SCons.Action.Action('$QT3_MOCFROMHCOM', '$QT3_MOCFROMHCOMSTR') + mocBld.add_action(h, act) + mocBld.prefix[h] = '$QT3_MOCHPREFIX' + mocBld.suffix[h] = '$QT3_MOCHSUFFIX' + for cxx in cxx_suffixes: + act = SCons.Action.Action('$QT3_MOCFROMCXXCOM', '$QT3_MOCFROMCXXCOMSTR') + mocBld.add_action(cxx, act) + mocBld.prefix[cxx] = '$QT3_MOCCXXPREFIX' + mocBld.suffix[cxx] = '$QT3_MOCCXXSUFFIX' + + # register the builders + env['BUILDERS']['Uic'] = uicBld + env['BUILDERS']['Moc'] = mocBld + static_obj, shared_obj = SCons.Tool.createObjBuilders(env) + static_obj.add_src_builder('Uic') + shared_obj.add_src_builder('Uic') + + # We use the emitters of Program / StaticLibrary / SharedLibrary + # to scan for moc'able files + # We can't refer to the builders directly, we have to fetch them + # as Environment attributes because that sets them up to be called + # correctly later by our emitter. + env.AppendUnique(PROGEMITTER =[AutomocStatic], + SHLIBEMITTER=[AutomocShared], + LDMODULEEMITTER=[AutomocShared], + LIBEMITTER =[AutomocStatic], + # Of course, we need to link against the qt3 libraries + CPPPATH=["$QT3_CPPPATH"], + LIBPATH=["$QT3_LIBPATH"], + LIBS=['$QT3_LIB']) + +def exists(env): + return _detect_qt3(env) + +# Local Variables: +# tab-width:4 +# indent-tabs-mode:nil +# End: +# vim: set expandtab tabstop=4 shiftwidth=4: diff --git a/SCons/Tool/qt3.xml b/SCons/Tool/qt3.xml new file mode 100644 index 000000000..445751b5e --- /dev/null +++ b/SCons/Tool/qt3.xml @@ -0,0 +1,527 @@ +<?xml version="1.0"?> +<!-- +__COPYRIGHT__ + +This file is processed by the bin/SConsDoc.py module. +See its __doc__ string for a discussion of the format. +--> + +<!DOCTYPE sconsdoc [ +<!ENTITY % scons SYSTEM '../../doc/scons.mod'> +%scons; +<!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'> +%builders-mod; +<!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'> +%functions-mod; +<!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'> +%tools-mod; +<!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'> +%variables-mod; +]> + +<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd"> + +<tool name="qt3"> +<summary> +<para> +Sets &consvars; for building Qt3 applications. +</para> + +<note><para> +This tool is only suitable for building targeted to Qt3, +which is obsolete +(<emphasis>the tool is deprecated since 4.3, +and was renamed to qt3 in 4.5.0. +</emphasis>). +There are contributed tools for Qt4 and Qt5, see +<ulink url="https://github.com/SCons/scons-contrib"> +https://github.com/SCons/scons-contrib</ulink>. +Qt4 has also passed end of life for standard support (in Dec 2015). +</para></note> + +<para> +Note paths for these &consvars; are assembled +using the <function>os.path.join</function> method +so they will have the appropriate separator at runtime, +but are listed here in the various +entries only with the <literal>'/'</literal> separator +for simplicity. +</para> + +<para> +In addition, the &consvars; +&cv-link-CPPPATH;, +&cv-link-LIBPATH; and +&cv-link-LIBS; may be modified +and the variables +&cv-link-PROGEMITTER;, &cv-link-SHLIBEMITTER; and &cv-link-LIBEMITTER; +are modified. Because the build-performance is affected when using this tool, +you have to explicitly specify it at Environment creation: +</para> + +<example_commands> +Environment(tools=['default','qt3']) +</example_commands> + +<para> +The &t-qt3; tool supports the following operations: +</para> + +<para> +<emphasis role="strong">Automatic moc file generation from header files.</emphasis> +You do not have to specify moc files explicitly, the tool does it for you. +However, there are a few preconditions to do so: Your header file must have +the same filebase as your implementation file and must stay in the same +directory. It must have one of the suffixes +<filename>.h</filename>, +<filename>.hpp</filename>, +<filename>.H</filename>, +<filename>.hxx</filename>, +<filename>.hh</filename>. +You can turn off automatic moc file generation by setting +&cv-link-QT3_AUTOSCAN; to <constant>False</constant>. +See also the corresponding +&b-link-Moc; Builder. +</para> + +<para> +<emphasis role="strong">Automatic moc file generation from C++ files.</emphasis> +As described in the Qt documentation, include the moc file at the end of +the C++ file. Note that you have to include the file, which is generated +by the transformation +<literal>${QT3_MOCCXXPREFIX}<basename>${QT3_MOCCXXSUFFIX}</literal>, by default +<filename><basename>.mo</filename>. A warning is generated after building the moc file if you +do not include the correct file. If you are using &f-link-VariantDir;, you may +need to specify <parameter>duplicate=True</parameter>. +You can turn off automatic moc file generation by setting &cv-QT3_AUTOSCAN; to +<literal>False</literal>. See also the corresponding +&b-link-Moc; Builder. +</para> + +<para> +<emphasis role="strong">Automatic handling of .ui files.</emphasis> +The implementation files generated from <filename>.ui</filename> +files are handled much the same as yacc or lex files. +Each <command>.ui</command> file given as a source of &b-link-Program;, +&b-link-Library; or &b-link-SharedLibrary; +will generate three files: the declaration file, the +implementation file and a moc file. Because there are also generated headers, +you may need to specify <parameter>duplicate=True</parameter> in calls to +&f-link-VariantDir;. +See also the corresponding +&b-link-Uic; Builder. +</para> +</summary> +<sets> +<item>QT3DIR</item> +<item>QT3_BINPATH</item> +<item>QT3_CPPPATH</item> +<item>QT3_LIBPATH</item> +<item>QT3_MOC</item> +<item>QT3_UIC</item> +<item>QT3_LIB</item> +<item>QT3_AUTOSCAN</item> +<item>QT3_UICIMPLFLAGS</item> +<item>QT3_UICDECLFLAGS</item> +<item>QT3_MOCFROMHFLAGS</item> +<item>QT3_MOCFROMCXXFLAGS</item> +<item>QT3_UICDECLPREFIX</item> +<item>QT3_UICDECLSUFFIX</item> +<item>QT3_UICIMPLPREFIX</item> +<item>QT3_UICIMPLSUFFIX</item> +<item>QT3_MOCHPREFIX</item> +<item>QT3_MOCHSUFFIX</item> +<item>QT3_MOCCXXPREFIX</item> +<item>QT3_MOCCXXSUFFIX</item> +<item>QT3_UISUFFIX</item> +<item>QT3_UICCOM</item> +<item>QT3_MOCFROMHCOM</item> +<item>QT3_MOCFROMCXXCOM</item> +</sets> +<uses> +<item>QT3DIR</item> +</uses> +</tool> + +<builder name="Moc"> +<summary> +<para> +Builds an output file from a <command>moc</command> input file. +<command>moc</command> input files are either header files or C++ files. +This builder is only available after using the +tool &t-link-qt3;. See the &cv-link-QT3DIR; variable for more information. +Example: +</para> + +<example_commands> +env.Moc('foo.h') # generates moc_foo.cc +env.Moc('foo.cpp') # generates foo.moc +</example_commands> +</summary> +</builder> + +<builder name="Uic"> +<summary> +<para> +Builds a header file, an implementation file and a moc file from an ui file. +and returns the corresponding nodes in the that order. +This builder is only available after using the tool &t-link-qt3;. +Note: you can specify <filename>.ui</filename> files directly as source +files to the &b-link-Program;, +&b-link-Library; and &b-link-SharedLibrary; builders +without using this builder. Using this builder lets you override the standard +naming conventions (be careful: prefixes are always prepended to names of +built files; if you don't want prefixes, you may set them to ``). +See the &cv-link-QT3DIR; variable for more information. +Example: +</para> + +<example_commands> +env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc'] +env.Uic( + target=Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'), + source='foo.ui' +) # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc'] +</example_commands> +</summary> +</builder> + +<cvar name="QT3DIR"> +<summary> +<para> +The path to the Qt installation to build against. +If not already set, +&t-link-qt3; tool tries to obtain this from +<varname>os.environ</varname>; +if not found there, it tries to make a guess. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QTDIR. +</para> +</summary> +</cvar> + +<cvar name="QT3_AUTOSCAN"> +<summary> +<para> +Turn off scanning for mocable files. Use the &b-link-Moc; Builder to explicitly +specify files to run <command>moc</command> on. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_AUTOSCAN. +</para> +</summary> +</cvar> + +<cvar name="QT3_BINPATH"> +<summary> +<para> +The path where the Qt binaries are installed. +The default value is '&cv-link-QT3DIR;<filename>/bin</filename>'. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_BINPATH. +</para> +</summary> +</cvar> + +<cvar name="QT3_CPPPATH"> +<summary> +<para> +The path where the Qt header files are installed. +The default value is '&cv-link-QT3DIR;/include'. +Note: If you set this variable to <constant>None</constant>, +the tool won't change the &cv-link-CPPPATH; +construction variable. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_CPPPATH. +</para> +</summary> +</cvar> + +<cvar name="QT3_DEBUG"> +<summary> +<para> +Prints lots of debugging information while scanning for moc files. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_DEBUG. +</para> +</summary> +</cvar> + +<cvar name="QT3_LIB"> +<summary> +<para> +Default value is <literal>'qt'</literal>. +You may want to set this to <literal>'qt-mt'</literal>. +Note: If you set this variable to <constant>None</constant>, +the tool won't change the &cv-link-LIBS; variable. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_LIB. +</para> +</summary> +</cvar> + +<cvar name="QT3_LIBPATH"> +<summary> +<para> +The path where the Qt libraries are installed. +The default value is '&cv-link-QT3DIR;<filename>/lib</filename>'. +Note: If you set this variable to <constant>None</constant>, +the tool won't change the &cv-link-LIBPATH; +construction variable. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_LIBPATH. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOC"> +<summary> +<para> +Default value is '&cv-link-QT3_BINPATH;<filename>/moc</filename>'. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCCXXPREFIX"> +<summary> +<para> +Default value is <literal>''</literal>. +Prefix for <command>moc</command> output files when source is a C++ file. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCCXXSUFFIX"> +<summary> +<para> +Default value is <literal>'.moc'</literal>. +Suffix for <command>moc</command> output files when source is a C++ file. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCCXXSUFFIX. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCFROMCXXFLAGS"> +<summary> +<para> +Default value is <literal>'-i'</literal>. +These flags are passed to <command>moc</command> when moccing a C++ file. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXFLAGS. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCFROMCXXCOM"> +<summary> +<para> +Command to generate a moc file from a C++ file. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXCOM. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCFROMCXXCOMSTR"> +<summary> +<para> +The string displayed when generating a moc file from a C++ file. +If this is not set, then &cv-link-QT3_MOCFROMCXXCOM; (the command line) is displayed. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXCOMSTR. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCFROMHCOM"> +<summary> +<para> +Command to generate a moc file from a header. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHCOM. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCFROMHCOMSTR"> +<summary> +<para> +The string displayed when generating a moc file from a C++ file. +If this is not set, then &cv-link-QT3_MOCFROMHCOM; (the command line) is displayed. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHCOMSTR. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCFROMHFLAGS"> +<summary> +<para> +Default value is <literal>''</literal>. These flags are passed to <command>moc</command> +when moccing a header file. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHFLAGS. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCHPREFIX"> +<summary> +<para> +Default value is <literal>'moc_'</literal>. +Prefix for <command>moc</command> output files when source is a header. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCHPREFIX. +</para> +</summary> +</cvar> + +<cvar name="QT3_MOCHSUFFIX"> +<summary> +<para> +Default value is '&cv-link-CXXFILESUFFIX;'. +Suffix for moc output files when source is a header. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCHSUFFIX. +</para> +</summary> +</cvar> + +<cvar name="QT3_UIC"> +<summary> +<para> +Default value is '&cv-link-QT3_BINPATH;<filename>/uic</filename>'. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UIC. +</para> +</summary> +</cvar> + +<cvar name="QT3_UICCOM"> +<summary> +<para> +Command to generate header files from <filename>.ui</filename> files. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICCOM. +</para> +</summary> +</cvar> + +<cvar name="QT3_UICCOMSTR"> +<summary> +<para> +The string displayed when generating header files from <filename>.ui</filename> files. +If this is not set, then &cv-link-QT3_UICCOM; (the command line) is displayed. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICCOMSTR. +</para> +</summary> +</cvar> + +<cvar name="QT3_UICDECLFLAGS"> +<summary> +<para> +Default value is ''. These flags are passed to <command>uic</command> +when creating a header file from a <filename>.ui</filename> file. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLFLAGS. +</para> +</summary> +</cvar> + +<cvar name="QT3_UICDECLPREFIX"> +<summary> +<para> +Default value is <literal>''</literal>. +Prefix for <command>uic</command> generated header files. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLPREFIX. +</para> +</summary> +</cvar> + +<cvar name="QT3_UICDECLSUFFIX"> +<summary> +<para> +Default value is <literal>'.h'</literal>. +Suffix for <command>uic</command> generated header files. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLSUFFIX. +</para> +</summary> +</cvar> + +<cvar name="QT3_UICIMPLFLAGS"> +<summary> +<para> +Default value is <literal>''</literal>. +These flags are passed to <command>uic</command> when creating a C++ +file from a <filename>.ui</filename> file. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPFLAGS. +</para> +</summary> +</cvar> + +<cvar name="QT3_UICIMPLPREFIX"> +<summary> +<para> +Default value is <literal>'uic_'</literal>. +Prefix for uic generated implementation files. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPLPREFIX. +</para> +</summary> +</cvar> + +<cvar name="QT3_UICIMPLSUFFIX"> +<summary> +<para> +Default value is '&cv-link-CXXFILESUFFIX;'. Suffix for uic generated implementation +files. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPLSUFFIX. +</para> +</summary> +</cvar> + +<cvar name="QT3_UISUFFIX"> +<summary> +<para> +Default value is <literal>'.ui'</literal>. +Suffix of designer input files. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UISUFFIX. +</para> +</summary> +</cvar> + +</sconsdoc> diff --git a/SCons/Util/__init__.py b/SCons/Util/__init__.py index 0281e1e17..2760298b5 100644 --- a/SCons/Util/__init__.py +++ b/SCons/Util/__init__.py @@ -32,7 +32,7 @@ import os import re import sys import time -from collections import UserDict, UserList, OrderedDict +from collections import UserDict, UserList, OrderedDict, deque from contextlib import suppress from types import MethodType, FunctionType from typing import Optional, Union @@ -516,6 +516,7 @@ _semi_deepcopy_dispatch = { tuple: _semi_deepcopy_tuple, } + def semi_deepcopy(obj): copier = _semi_deepcopy_dispatch.get(type(obj)) if copier: @@ -527,7 +528,7 @@ def semi_deepcopy(obj): if isinstance(obj, UserDict): return obj.__class__(semi_deepcopy_dict(obj)) - if isinstance(obj, UserList): + if isinstance(obj, (UserList, deque)): return obj.__class__(_semi_deepcopy_list(obj)) return obj diff --git a/SCons/Warnings.py b/SCons/Warnings.py index 754f05d86..f77a24a2d 100644 --- a/SCons/Warnings.py +++ b/SCons/Warnings.py @@ -131,7 +131,7 @@ class DeprecatedDebugOptionsWarning(MandatoryDeprecatedWarning): class DeprecatedMissingSConscriptWarning(DeprecatedWarning): pass -class ToolQtDeprecatedWarning(FutureDeprecatedWarning): +class ToolQtDeprecatedWarning(DeprecatedWarning): pass # The below is a list of 2-tuples. The first element is a class object. diff --git a/SCons/__init__.py b/SCons/__init__.py index 8f397bcd2..f53583b12 100644 --- a/SCons/__init__.py +++ b/SCons/__init__.py @@ -1,9 +1,9 @@ -__version__="4.4.1" -__copyright__="Copyright (c) 2001 - 2022 The SCons Foundation" +__version__="4.5.1" +__copyright__="Copyright (c) 2001 - 2023 The SCons Foundation" __developer__="bdbaddog" -__date__="Sun, 13 Nov 2022 11:31:29 -0400" +__date__="Mon, 06 Mar 2023 23:32:38 -0400" __buildsys__="M1DOG2021" -__revision__="15379ff3b369560c4bf13459b630387bf7349bb7" -__build__="15379ff3b369560c4bf13459b630387bf7349bb7" +__revision__="49578b34582d9e92dac7d713a8e58599ae35aa63" +__build__="49578b34582d9e92dac7d713a8e58599ae35aa63" # make sure compatibility is always in place import SCons.compat # noqa
\ No newline at end of file diff --git a/SConstruct b/SConstruct index 11ae13e1c..1f44ea4ee 100644 --- a/SConstruct +++ b/SConstruct @@ -38,7 +38,7 @@ month_year = strftime('%B %Y') project = 'scons' -default_version = '4.4.1' +default_version = '4.5.2' copyright = "Copyright (c) %s The SCons Foundation" % copyright_years # diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen index ff3bb39e5..deccae72a 100644 --- a/doc/generated/builders.gen +++ b/doc/generated/builders.gen @@ -624,9 +624,9 @@ env.Jar(target = 'bar.jar', </para> <example_commands> -env.Java(target = 'classes', source = 'src') -env.Java(target = 'classes', source = ['src1', 'src2']) -env.Java(target = 'classes', source = ['File1.java', 'File2.java']) +env.Java(target='classes', source='src') +env.Java(target='classes', source=['src1', 'src2']) +env.Java(target='classes', source=['File1.java', 'File2.java']) </example_commands> <para> @@ -768,7 +768,7 @@ env.M4(target = 'foo.c', source = 'foo.c.m4') Builds an output file from a <command>moc</command> input file. <command>moc</command> input files are either header files or C++ files. This builder is only available after using the -tool &t-link-qt;. See the &cv-link-QTDIR; variable for more information. +tool &t-link-qt3;. See the &cv-link-QT3DIR; variable for more information. Example: </para> @@ -832,70 +832,106 @@ Compile files for languages defined in <filename>LINGUAS</filename> file <term><function>MSVSProject</function>()</term> <term><replaceable>env</replaceable>.<methodname>MSVSProject</methodname>()</term> <listitem><para> - Builds a Microsoft Visual Studio project file, and by default - builds a solution file as well. + Build a Microsoft Visual C++ project file and solution file. </para> <para> - This builds a Visual Studio project file, based on the - version of Visual Studio that is configured (either the - latest installed version, or the version specified by - &cv-link-MSVS_VERSION; in the Environment constructor). For - Visual Studio 6, it will generate a <filename>.dsp</filename> - file. For Visual Studio 7, 8, and 9, it will - generate a <filename>.vcproj</filename> file. For Visual - Studio 10 and later, it will generate a - <filename>.vcxproj</filename> file. - </para> + Builds a C++ project file based on the + version of Visual Studio (or to be more precise, of MSBuild) + that is configured: either the latest installed version, + or the version specified by + &cv-link-MSVC_VERSION; in the current &consenv;. + For Visual Studio 6.0 a <filename>.dsp</filename> file is generated. + For Visual Studio versions 2002-2008, + a <filename>.vcproj</filename> file is generated. + For Visual Studio 2010 and later a <filename>.vcxproj</filename> + file is generated. + Note there are multiple versioning schemes involved in + the Microsoft compilation environment - + see the description of &cv-link-MSVC_VERSION; for equivalences. + &SCons; does not know how to construct project files for + other languages (such as <filename>.csproj</filename> for C#, + <filename>.vbproj</filename> for Visual Basic or + <filename>.pyproject</filename> for Python)). + </para> <para> - By default, this also generates a solution file for the - specified project, a <filename>.dsw</filename> file for - Visual Studio 6 or a <filename>.sln</filename> file for - Visual Studio 7 and later. This behavior may be disabled by - specifying <literal>auto_build_solution=0</literal> when you - call &b-MSVSProject;, in which case you presumably want to - build the solution file(s) by calling the &b-MSVSSolution; - Builder (see below). + For the <filename>.vcxproj</filename> file, the underlying + format is the MSBuild XML Schema, and the details conform to: + <ulink url="https://learn.microsoft.com/en-us/cpp/build/reference/vcxproj-file-structure"> + https://learn.microsoft.com/en-us/cpp/build/reference/vcxproj-file-structure</ulink>. + The generated solution file enables Visual Studio to + understand the project structure, and allows building it + using MSBuild to call back to &SCons;. + The project file encodes a toolset version that has been + selected by &SCons; as described above. Since recent Visual + Studio versions support multiple concurrent toolsets, + use &cv-link-MSVC_VERSION; to select the desired one if + it does not match the &SCons; default. + The project file also includes entries which describe + how to call &SCons; to build the project from within Visual Studio + (or from an MSBuild command line). + In some situations &SCons; may generate this incorrectly - + notably when using the <emphasis>scons-local</emphasis> + distribution, which is not installed in a way that that + matches the default invocation line. + If so, the &cv-link-SCONS_HOME; &consvar; can be used to describe + the right way to locate the &SCons; code so that it can be imported. </para> <para> - The &b-MSVSProject; builder takes several lists of filenames - to be placed into the project file. These are currently - limited to <literal>srcs</literal>, <literal>incs</literal>, - <literal>localincs</literal>, <literal>resources</literal>, and - <literal>misc</literal>. These are pretty self-explanatory, - but it should be noted that these lists are added to the - &cv-link-SOURCES; construction variable as strings, NOT as - SCons File Nodes. This is because they represent file names - to be added to the project file, not the source files used - to build the project file. + By default, a matching solution file for the project is also generated. + This behavior may be disabled by + specifying <parameter>auto_build_solution=0</parameter> + to the &b-MSVSProject; builder. + The solution file can also be independently + generated by calling the &b-MSVSSolution; builder, + such as in the case where a solution should describe + multiple projects. + See the &b-link-MSVSSolution; description for further information. </para> <para> - The above filename lists are all optional, although at least - one must be specified for the resulting project file to + The &b-MSVSProject; builder accepts several keyword arguments + describing lists of filenames to be placed into the project file. + Currently, + <parameter>srcs</parameter>, + <parameter>incs</parameter>, + <parameter>localincs</parameter>, + <parameter>resources</parameter>, + and <parameter>misc</parameter> + are recognized. + The names are intended to be self-explanatory, but note that the + filenames need to be specified as strings, <emphasis>not</emphasis> + as &SCons; File Nodes + (for example if you generate files for inclusion by using the + &f-link-Glob; function, the results should be converted to + a list of strings before passing them to &b-MSVSProject;). + This is because Visual Studio and MSBuild know nothing about &SCons; + Node types. + Each of the filename lists are individually optional, but at + least one list must be specified for the resulting project file to be non-empty. </para> <para> In addition to the above lists of values, the following values - may be specified: + may be specified as keyword arguments: </para> <variablelist> <varlistentry> - <term>target</term> + <term><parameter>target</parameter></term> <listitem> <para> The name of the target <filename>.dsp</filename> or <filename>.vcproj</filename> file. The correct suffix for the version of Visual Studio must be used, but the &cv-link-MSVSPROJECTSUFFIX; - construction variable will be defined to the correct + &consvar; will be defined to the correct value (see example below). </para> </listitem> </varlistentry> <varlistentry> - <term>variant</term> + <term><parameter>variant</parameter></term> <listitem> <para> - The name of this particular variant. For Visual Studio 7 + The name of this particular variant. Except for Visual Studio 6 projects, this can also be a list of variant names. These are typically things like "Debug" or "Release", but really can be anything you want. For Visual Studio @@ -910,145 +946,184 @@ Compile files for languages defined in <filename>LINGUAS</filename> file </listitem> </varlistentry> <varlistentry> - <term>cmdargs</term> + <term><parameter>cmdargs</parameter></term> <listitem> <para> Additional command line arguments for the different variants. The number of - <literal>cmdargs</literal> entries must match the number - of <literal>variant</literal> entries, or be empty (not + <parameter>cmdargs</parameter> entries must match the number + of <parameter>variant</parameter> entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. </para> </listitem> </varlistentry> <varlistentry> - <term>cppdefines</term> + <term><parameter>cppdefines</parameter></term> <listitem> <para> Preprocessor definitions for the different variants. - The number of <literal>cppdefines</literal> entries - must match the number of <literal>variant</literal> + The number of <parameter>cppdefines</parameter> entries + must match the number of <parameter>variant</parameter> entries, or be empty (not specified). If you give only one, it will automatically be propagated to all - variants. If you don't give this parameter, SCons + variants. If you don't give this parameter, &SCons; will use the invoking environment's - <literal>CPPDEFINES</literal> entry for all variants. + &cv-link-CPPDEFINES; entry for all variants. </para> </listitem> </varlistentry> <varlistentry> - <term>cppflags</term> + <term><parameter>cppflags</parameter></term> <listitem> <para> Compiler flags for the different variants. - If a /std:c++ flag is found then /Zc:__cplusplus is - appended to the flags if not already found, this - ensures that intellisense uses the /std:c++ switch. - The number of <literal>cppflags</literal> entries - must match the number of <literal>variant</literal> + If a <option>/std:c++</option> flag is found then + <option>/Zc:__cplusplus</option> is appended to the + flags if not already found, this ensures that Intellisense + uses the <option>/std:c++</option> switch. + The number of <parameter>cppflags</parameter> entries + must match the number of <parameter>variant</parameter> entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. If you don't give this parameter, SCons will combine the invoking environment's - <literal>CCFLAGS</literal>, <literal>CXXFLAGS</literal>, - <literal>CPPFLAGS</literal> entries for all variants. + &cv-link-CCFLAGS;, &cv-link-CXXFLAGS;, + &cv-link-CPPFLAGS; entries for all variants. </para> </listitem> </varlistentry> <varlistentry> - <term>cpppaths</term> + <term><parameter>cpppaths</parameter></term> <listitem> <para> Compiler include paths for the different variants. - The number of <literal>cpppaths</literal> entries - must match the number of <literal>variant</literal> + The number of <parameter>cpppaths</parameter> entries + must match the number of <parameter>variant</parameter> entries, or be empty (not specified). If you give only one, it will automatically be propagated to all variants. If you don't give this parameter, SCons will use the invoking environment's - <literal>CPPPATH</literal> entry for all variants. + &cv-link-CPPPATH; entry for all variants. </para> </listitem> </varlistentry> <varlistentry> - <term>buildtarget</term> + <term><parameter>buildtarget</parameter></term> <listitem> <para> An optional string, node, or list of strings or nodes (one per build variant), to tell the Visual Studio debugger what output target to use in what build variant. The number of - <literal>buildtarget</literal> entries must match the - number of <literal>variant</literal> entries. + <parameter>buildtarget</parameter> entries must match the + number of <parameter>variant</parameter> entries. </para> </listitem> </varlistentry> <varlistentry> - <term>runfile</term> + <term><parameter>runfile</parameter></term> <listitem> <para> The name of the file that Visual Studio 7 and later will run and debug. This appears as the - value of the <literal>Output</literal> field in the - resulting Visual Studio project file. If this is not + value of the <parameter>Output</parameter> field in the + resulting Visual C++ project file. If this is not specified, the default is the same as the specified - <literal>buildtarget</literal> value. + <parameter>buildtarget</parameter> value. </para> </listitem> </varlistentry> </variablelist> + <note> + <para> + &SCons; and Microsoft Visual Studio understand projects in + different ways, and the mapping is sometimes imperfect: + </para> <para> - Note that because &SCons; always executes its build commands + Because &SCons; always executes its build commands from the directory in which the &SConstruct; file is located, if you generate a project file in a different directory - than the &SConstruct; directory, users will not be able to + than the directory of the &SConstruct; file, users will not be able to double-click on the file name in compilation error messages displayed in the Visual Studio console output window. This can - be remedied by adding the Visual C/C++ <literal>/FC</literal> + be remedied by adding the Visual C/C++ <option>/FC</option> compiler option to the &cv-link-CCFLAGS; variable so that the compiler will print the full path name of any files that cause compilation errors. </para> + <para> + If the project file is only used to teach the Visual Studio + project browser about the file layout there should be no issues, + However, Visual Studio should not be used to make changes + to the project structure, build options, etc. as these will + (a) not feed back to the &SCons; description of the project + and (b) be lost if &SCons; regenerates the project file. + The SConscript files should remain the definitive description + of the build. + </para> + <para> + If the project file is used to drive MSBuild (such as selecting + "build" from the Visual Studio interface) you lose the direct + control of target selection and command-line options you would + have if launching the build directly from &SCons;, + because these will be hardcoded in the project file to the + values specified in the &b-MSVSProject; call. + You can regain some of this control by defining multiple variants, + using multiple &b-MSVSProject; calls to arrange different build + targets, arguments, defines, flags and paths for different variants. + </para> + <para> + If the build is divided into a solution with multiple MSBuild + projects the mapping is further strained. In this case, + it is important not to set Visual Studio to do parallel builds, + as it will then launch the separate project builds in parallel, + and &SCons; does not work well if called that way. + Instead you can set up the &SCons; build for parallel building - + see the &f-link-SetOption; function for how to do this with + <parameter>num_jobs</parameter>. + </para> + </note> + <para>Example usage:</para> <example_commands> barsrcs = ['bar.cpp'] barincs = ['bar.h'] barlocalincs = ['StdAfx.h'] -barresources = ['bar.rc','resource.h'] +barresources = ['bar.rc', 'resource.h'] barmisc = ['bar_readme.txt'] -dll = env.SharedLibrary(target='bar.dll', - source=barsrcs) +dll = env.SharedLibrary(target='bar.dll', source=barsrcs) buildtarget = [s for s in dll if str(s).endswith('dll')] -env.MSVSProject(target='Bar' + env['MSVSPROJECTSUFFIX'], - srcs=barsrcs, - incs=barincs, - localincs=barlocalincs, - resources=barresources, - misc=barmisc, - buildtarget=buildtarget, - variant='Release') +env.MSVSProject( + target='Bar' + env['MSVSPROJECTSUFFIX'], + srcs=barsrcs, + incs=barincs, + localincs=barlocalincs, + resources=barresources, + misc=barmisc, + buildtarget=buildtarget, + variant='Release', +) </example_commands> - <para> - Starting with version 2.4 of SCons it is - also possible to specify the optional argument - <parameter>DebugSettings</parameter>, which creates files - for debugging under Visual Studio: - </para> + <variablelist> <varlistentry> - <term>DebugSettings</term> + <term><parameter>DebugSettings</parameter></term> <listitem> <para> A dictionary of debug settings that get written to the <filename>.vcproj.user</filename> or the <filename>.vcxproj.user</filename> file, depending on the - version installed. As it is done for cmdargs (see above), + version installed. As for <parameter>cmdargs</parameter>, you can specify a <parameter>DebugSettings</parameter> dictionary per variant. If you give only one, it will be propagated to all variants. </para> + <para> + <emphasis>Changed in version 2.4:</emphasis> + Added the optional <parameter>DebugSettings</parameter> parameter. + </para> </listitem> </varlistentry> </variablelist> @@ -1072,12 +1147,17 @@ msvcver = vars.args.get('vc', '9') # Check command args to force one Microsoft Visual Studio version if msvcver == '9' or msvcver == '11': - env = Environment(MSVC_VERSION=msvcver+'.0', MSVC_BATCH=False) + env = Environment(MSVC_VERSION=msvcver + '.0', MSVC_BATCH=False) else: - env = Environment() - -AddOption('--userfile', action='store_true', dest='userfile', default=False, - help="Create Visual Studio Project user file") + env = Environment() + +AddOption( + '--userfile', + action='store_true', + dest='userfile', + default=False, + help="Create Visual C++ project file", +) # # 1. Configure your Debug Setting dictionary with options you want in the list @@ -1085,28 +1165,28 @@ AddOption('--userfile', action='store_true', dest='userfile', default=False, # a specific application for testing your dll with Microsoft Visual Studio 2008 (v9): # V9DebugSettings = { - 'Command':'c:\\myapp\\using\\thisdll.exe', + 'Command': 'c:\\myapp\\using\\thisdll.exe', 'WorkingDirectory': 'c:\\myapp\\using\\', 'CommandArguments': '-p password', -# 'Attach':'false', -# 'DebuggerType':'3', -# 'Remote':'1', -# 'RemoteMachine': None, -# 'RemoteCommand': None, -# 'HttpUrl': None, -# 'PDBPath': None, -# 'SQLDebugging': None, -# 'Environment': '', -# 'EnvironmentMerge':'true', -# 'DebuggerFlavor': None, -# 'MPIRunCommand': None, -# 'MPIRunArguments': None, -# 'MPIRunWorkingDirectory': None, -# 'ApplicationCommand': None, -# 'ApplicationArguments': None, -# 'ShimCommand': None, -# 'MPIAcceptMode': None, -# 'MPIAcceptFilter': None, + # 'Attach':'false', + # 'DebuggerType':'3', + # 'Remote':'1', + # 'RemoteMachine': None, + # 'RemoteCommand': None, + # 'HttpUrl': None, + # 'PDBPath': None, + # 'SQLDebugging': None, + # 'Environment': '', + # 'EnvironmentMerge':'true', + # 'DebuggerFlavor': None, + # 'MPIRunCommand': None, + # 'MPIRunArguments': None, + # 'MPIRunWorkingDirectory': None, + # 'ApplicationCommand': None, + # 'ApplicationArguments': None, + # 'ShimCommand': None, + # 'MPIAcceptMode': None, + # 'MPIAcceptFilter': None, } # @@ -1120,28 +1200,28 @@ V10DebugSettings = { 'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe', 'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\', 'LocalDebuggerCommandArguments': '-p password', -# 'LocalDebuggerEnvironment': None, -# 'DebuggerFlavor': 'WindowsLocalDebugger', -# 'LocalDebuggerAttach': None, -# 'LocalDebuggerDebuggerType': None, -# 'LocalDebuggerMergeEnvironment': None, -# 'LocalDebuggerSQLDebugging': None, -# 'RemoteDebuggerCommand': None, -# 'RemoteDebuggerCommandArguments': None, -# 'RemoteDebuggerWorkingDirectory': None, -# 'RemoteDebuggerServerName': None, -# 'RemoteDebuggerConnection': None, -# 'RemoteDebuggerDebuggerType': None, -# 'RemoteDebuggerAttach': None, -# 'RemoteDebuggerSQLDebugging': None, -# 'DeploymentDirectory': None, -# 'AdditionalFiles': None, -# 'RemoteDebuggerDeployDebugCppRuntime': None, -# 'WebBrowserDebuggerHttpUrl': None, -# 'WebBrowserDebuggerDebuggerType': None, -# 'WebServiceDebuggerHttpUrl': None, -# 'WebServiceDebuggerDebuggerType': None, -# 'WebServiceDebuggerSQLDebugging': None, + # 'LocalDebuggerEnvironment': None, + # 'DebuggerFlavor': 'WindowsLocalDebugger', + # 'LocalDebuggerAttach': None, + # 'LocalDebuggerDebuggerType': None, + # 'LocalDebuggerMergeEnvironment': None, + # 'LocalDebuggerSQLDebugging': None, + # 'RemoteDebuggerCommand': None, + # 'RemoteDebuggerCommandArguments': None, + # 'RemoteDebuggerWorkingDirectory': None, + # 'RemoteDebuggerServerName': None, + # 'RemoteDebuggerConnection': None, + # 'RemoteDebuggerDebuggerType': None, + # 'RemoteDebuggerAttach': None, + # 'RemoteDebuggerSQLDebugging': None, + # 'DeploymentDirectory': None, + # 'AdditionalFiles': None, + # 'RemoteDebuggerDeployDebugCppRuntime': None, + # 'WebBrowserDebuggerHttpUrl': None, + # 'WebBrowserDebuggerDebuggerType': None, + # 'WebServiceDebuggerHttpUrl': None, + # 'WebServiceDebuggerDebuggerType': None, + # 'WebServiceDebuggerSQLDebugging': None, } # @@ -1163,72 +1243,86 @@ else: barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp'] barincs = ['targetver.h'] barlocalincs = ['StdAfx.h'] -barresources = ['bar.rc','resource.h'] +barresources = ['bar.rc', 'resource.h'] barmisc = ['ReadMe.txt'] -dll = env.SharedLibrary(target='bar.dll', - source=barsrcs) - -env.MSVSProject(target='Bar' + env['MSVSPROJECTSUFFIX'], - srcs=barsrcs, - incs=barincs, - localincs=barlocalincs, - resources=barresources, - misc=barmisc, - buildtarget=[dll[0]] * 2, - variant=('Debug|Win32', 'Release|Win32'), - cmdargs='vc=%s' % msvcver, - DebugSettings=(dbgSettings, {})) +dll = env.SharedLibrary(target='bar.dll', source=barsrcs) + +env.MSVSProject( + target='Bar' + env['MSVSPROJECTSUFFIX'], + srcs=barsrcs, + incs=barincs, + localincs=barlocalincs, + resources=barresources, + misc=barmisc, + buildtarget=[dll[0]] * 2, + variant=('Debug|Win32', 'Release|Win32'), + cmdargs=f'vc={msvcver}', + DebugSettings=(dbgSettings, {}), +) </example_commands> </listitem> </varlistentry> <varlistentry id="b-MSVSSolution"> <term><function>MSVSSolution</function>()</term> <term><replaceable>env</replaceable>.<methodname>MSVSSolution</methodname>()</term> - <listitem><para>Builds a Microsoft Visual Studio solution file.</para> + <listitem><para>Build a Microsoft Visual Studio Solution file.</para> <para> - This builds a Visual Studio solution file, based on the - version of Visual Studio that is configured (either the + Builds a Visual Studio solution file based on the + version of Visual Studio that is configured: either the latest installed version, or the version specified by - &cv-link-MSVS_VERSION; in the construction environment). For - Visual Studio 6, it will generate a <filename>.dsw</filename> - file. For Visual Studio 7 (.NET), it will generate a - <filename>.sln</filename> file. + &cv-link-MSVC_VERSION; in the &consenv;. For + Visual Studio 6, a <filename>.dsw</filename> file is generated. + For Visual Studio .NET 2002 and later, + it will generate a <filename>.sln</filename> file. + Note there are multiple versioning schemes involved in + the Microsoft compilation environment - + see the description of &cv-link-MSVC_VERSION; for equivalences. + </para> + <para> + The solution file is a container for one or more projects, + and follows the format described at + <ulink url="https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file"> + https://learn.microsoft.com/en-us/visualstudio/extensibility/internals/solution-dot-sln-file</ulink>. </para> <para>The following values must be specified:</para> <variablelist> <varlistentry> - <term>target</term> + <term><parameter>target</parameter></term> <listitem> <para> - The name of the target .dsw or .sln file. The correct + The name of the target <filename>.dsw</filename> or + <filename>.sln</filename> file. The correct suffix for the version of Visual Studio must be used, but the value &cv-link-MSVSSOLUTIONSUFFIX; will be defined to the correct value (see example below). </para> </listitem> - </varlistentry> <varlistentry> - <term>variant</term> <listitem> + </varlistentry> + <varlistentry> + <term><parameter>variant</parameter></term> + <listitem> <para> The name of this particular variant, or a list of variant names (the latter is only supported for MSVS 7 solutions). These are typically things like "Debug" or "Release", but really can be anything you want. For MSVS 7 they may also specify target platform, like this - "Debug|Xbox". Default platform is Win32. + <literal>"Debug|Xbox"</literal>. Default platform is Win32. </para> </listitem> - </varlistentry> <varlistentry> - <term>projects</term> <listitem> + </varlistentry> + <varlistentry> + <term><parameter>projects</parameter></term> + <listitem> <para> A list of project file names, or Project nodes returned - by calls to the &b-MSVSProject; Builder, to be placed - into the solution file. It should be noted that these - file names are NOT added to the $SOURCES environment - variable in form of files, but rather as strings. - This is because they represent file names to be added - to the solution file, not the source files used to - build the solution file. + by calls to the &b-link-MSVSProject; Builder, to be placed + into the solution file. + Note that these filenames need to be specified as strings, + NOT as &SCons; File Nodes. + This is because the solution file will be interpreted by MSBuild + and by Visual Studio, which know nothing about &SCons; Node types. </para> </listitem> </varlistentry> @@ -1446,7 +1540,7 @@ file as the second element. Normally the object file is ignored. This builder is only provided when Microsoft Visual C++ is being used as the compiler. The &b-PCH; builder is generally used in -conjunction with the &cv-link-PCH; construction variable to force object files to use +conjunction with the &cv-link-PCH; &consvar; to force object files to use the precompiled header: </para> @@ -1988,15 +2082,17 @@ file names. </para> <example_commands> -classes = env.Java(target = 'classdir', source = 'src') -env.RMIC(target = 'outdir1', source = classes) - -env.RMIC(target = 'outdir2', - source = ['package/foo.class', 'package/bar.class']) - -env.RMIC(target = 'outdir3', - source = ['classes/foo.class', 'classes/bar.class'], - JAVACLASSDIR = 'classes') +classes = env.Java(target='classdir', source='src') +env.RMIC(target='outdir1', source=classes) +env.RMIC( + target='outdir2', + source=['package/foo.class', 'package/bar.class'], +) +env.RMIC( + target='outdir3', + source=['classes/foo.class', 'classes/bar.class'], + JAVACLASSDIR='classes', +) </example_commands> </listitem> </varlistentry> @@ -2353,6 +2449,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> @@ -2484,7 +2585,7 @@ Nested lists of source strings are flattened. Source strings need not literally be Python strings: they can be Nodes or Python objects that convert cleanly -to &f-link-Value; nodes +to &f-link-Value; nodes. </para> <para> @@ -2492,6 +2593,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. +</para> +<para> +By default the target file encoding is "utf-8" and can be changed by &cv-link-FILE_ENCODING; Examples: </para> @@ -2704,14 +2808,14 @@ files. <listitem><para> Builds a header file, an implementation file and a moc file from an ui file. and returns the corresponding nodes in the that order. -This builder is only available after using the tool &t-link-qt;. +This builder is only available after using the tool &t-link-qt3;. Note: you can specify <filename>.ui</filename> files directly as source files to the &b-link-Program;, &b-link-Library; and &b-link-SharedLibrary; builders without using this builder. Using this builder lets you override the standard naming conventions (be careful: prefixes are always prepended to names of built files; if you don't want prefixes, you may set them to ``). -See the &cv-link-QTDIR; variable for more information. +See the &cv-link-QT3DIR; variable for more information. Example: </para> diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml index 2e3b879dc..266eaa0d4 100644 --- a/doc/generated/examples/caching_ex-random_1.xml +++ b/doc/generated/examples/caching_ex-random_1.xml @@ -1,8 +1,8 @@ <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput> +cc -o f2.o -c f2.c cc -o f3.o -c f3.c -cc -o f4.o -c f4.c cc -o f1.o -c f1.c -cc -o f2.o -c f2.c cc -o f5.o -c f5.c +cc -o f4.o -c f4.c cc -o prog f1.o f2.o f3.o f4.o f5.o </screen> diff --git a/doc/generated/examples/factories_Chmod_1.xml b/doc/generated/examples/factories_Chmod_1.xml index 652fa3872..1777a239c 100644 --- a/doc/generated/examples/factories_Chmod_1.xml +++ b/doc/generated/examples/factories_Chmod_1.xml @@ -1,4 +1,4 @@ <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q</userinput> Copy("file.out", "file.in") -Chmod("file.out", 0755) +Chmod("file.out", 0o755) </screen> diff --git a/doc/generated/examples/separate_ex1_2.xml b/doc/generated/examples/separate_ex1_2.xml new file mode 100644 index 000000000..f66f413e7 --- /dev/null +++ b/doc/generated/examples/separate_ex1_2.xml @@ -0,0 +1,16 @@ +<screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q --tree=prune</userinput> +cc -o build/hello.o -c build/hello.c +cc -o build/hello build/hello.o ++-. + +-SConstruct + +-build + | +-build/SConscript + | +-build/hello + | | +-build/hello.o + | | +-build/hello.c + | +-build/hello.c + | +-[build/hello.o] + +-src + +-src/SConscript + +-src/hello.c +</screen> diff --git a/doc/generated/examples/troubleshoot_explain1_3.xml b/doc/generated/examples/troubleshoot_explain1_3.xml index 7a02fd52f..e658d89fd 100644 --- a/doc/generated/examples/troubleshoot_explain1_3.xml +++ b/doc/generated/examples/troubleshoot_explain1_3.xml @@ -2,5 +2,5 @@ cp file.in file.oout scons: warning: Cannot find target file.out after building -File "/Users/bdbaddog/devel/scons/git/scons-bugfixes-4/scripts/scons.py", line 97, in <module> +File "/Users/bdbaddog/devel/scons/git/as_scons/scripts/scons.py", line 97, in <module> </screen> diff --git a/doc/generated/examples/troubleshoot_stacktrace_2.xml b/doc/generated/examples/troubleshoot_stacktrace_2.xml index 7c471eb1a..79234f279 100644 --- a/doc/generated/examples/troubleshoot_stacktrace_2.xml +++ b/doc/generated/examples/troubleshoot_stacktrace_2.xml @@ -1,11 +1,11 @@ <screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q --debug=stacktrace</userinput> scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'. scons: internal stack trace: - File "SCons/Job.py", line 203, in start + File "SCons/Taskmaster/Job.py", line 219, in start task.prepare() File "SCons/Script/Main.py", line 180, in prepare return SCons.Taskmaster.OutOfDateTask.prepare(self) - File "SCons/Taskmaster.py", line 186, in prepare + File "SCons/Taskmaster/__init__.py", line 195, in prepare executor.prepare() File "SCons/Executor.py", line 418, in prepare raise SCons.Errors.StopError(msg % (s, self.batches[0].targets[0])) diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 1c580f5d4..5a74fc6e4 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -425,126 +425,205 @@ Multiple targets can be passed in to a single call to <varlistentry id="f-Append"> <term><replaceable>env</replaceable>.<methodname>Append</methodname>(<parameter>key=val, [...]</parameter>)</term> <listitem><para> -Intelligently append values to &consvars; in the &consenv; -named by <varname>env</varname>. +Appends value(s) intelligently to &consvars; in +<varname>env</varname>. The &consvars; and values to add to them are passed as <parameter>key=val</parameter> pairs (&Python; keyword arguments). &f-env-Append; is designed to allow adding values -without normally having to know the data type of an existing &consvar;. +without having to think about the data type of an existing &consvar;. Regular &Python; syntax can also be used to manipulate the &consvar;, -but for that you must know the type of the &consvar;: -for example, different &Python; syntax is needed to combine -a list of values with a single string value, or vice versa. +but for that you may need to know the types involved, +for example pure &Python; lets you directly "add" two lists of strings, +but adding a string to a list or a list to a string requires +different syntax - things &f-Append; takes care of. Some pre-defined &consvars; do have type expectations -based on how &SCons; will use them, -for example &cv-link-CPPDEFINES; is normally a string or a list of strings, -but can be a string, -a list of strings, -a list of tuples, -or a dictionary, while &cv-link-LIBEMITTER; -would expect a callable or list of callables, -and &cv-link-BUILDERS; would expect a mapping type. +based on how &SCons; will use them: +for example &cv-link-CPPDEFINES; is often a string or a list of strings, +but can also be a list of tuples or a dictionary; +while &cv-link-LIBEMITTER; +is expected to be a callable or list of callables, +and &cv-link-BUILDERS; is expected to be a dictionary. Consult the documentation for the various &consvars; for more details. </para> <para> -The following descriptions apply to both the append -and prepend functions, the only difference being -the insertion point of the added values. -</para> -<para> -If <varname>env</varname>. does not have a &consvar; -indicated by <parameter>key</parameter>, -<parameter>val</parameter> -is added to the environment under that key as-is. -</para> - -<para> -<parameter>val</parameter> can be almost any type, -and &SCons; will combine it with an existing value into an appropriate type, -but there are a few special cases to be aware of. -When two strings are combined, -the result is normally a new string, -with the caller responsible for supplying any needed separation. -The exception to this is the &consvar; &cv-link-CPPDEFINES;, -in which each item will be postprocessed by adding a prefix -and/or suffix, -so the contents are treated as a list of strings, that is, -adding a string will result in a separate string entry, -not a combined string. For &cv-CPPDEFINES; as well as -for &cv-link-LIBS;, and the various <literal>*PATH</literal>; -variables, &SCons; will supply the compiler-specific -syntax (e.g. adding a <literal>-D</literal> or <literal>/D</literal> -prefix for &cv-CPPDEFINES;), so this syntax should be omitted when +The following descriptions apply to both the &f-Append; +and &f-Prepend; methods, as well as their +<emphasis role="bold">Unique</emphasis> variants, +with the differences being the insertion point of the added values +and whether duplication is allowed. +</para> + +<para> +<parameter>val</parameter> can be almost any type. +If <varname>env</varname> does not have a &consvar; +named <parameter>key</parameter>, +then <parameter>key</parameter> is simply +stored with a value of <parameter>val</parameter>. +Otherwise, <parameter>val</parameter> is +combinined with the existing value, +possibly converting into an appropriate type +which can hold the expanded contents. +There are a few special cases to be aware of. +Normally, when two strings are combined, +the result is a new string containing their concatenation +(and you are responsible for supplying any needed separation); +however, the contents of &cv-link-CPPDEFINES; will +will be postprocessed by adding a prefix and/or suffix +to each entry when the command line is produced, +so &SCons; keeps them separate - +appending a string will result in a separate string entry, +not a combined string. +For &cv-CPPDEFINES;. as well as +&cv-link-LIBS;, and the various <literal>*PATH</literal> variables, +&SCons; will amend the variable by supplying the compiler-specific +syntax (e.g. prepending a <literal>-D</literal> or <literal>/D</literal> +prefix for &cv-CPPDEFINES;), so you should omit this syntax when adding values to these variables. -Example (gcc syntax shown in the expansion of &CPPDEFINES;): +Examples (gcc syntax shown in the expansion of &CPPDEFINES;): </para> <example_commands> env = Environment(CXXFLAGS="-std=c11", CPPDEFINES="RELEASE") -print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['CPPDEFINES'])) -# notice including a leading space in CXXFLAGS value +print(f"CXXFLAGS = {env['CXXFLAGS']}, CPPDEFINES = {env['CPPDEFINES']}") +# notice including a leading space in CXXFLAGS addition env.Append(CXXFLAGS=" -O", CPPDEFINES="EXTRA") -print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['CPPDEFINES'])) -print("CPPDEFINES will expand to {}".format(env.subst("$_CPPDEFFLAGS"))) +print(f"CXXFLAGS = {env['CXXFLAGS']}, CPPDEFINES = {env['CPPDEFINES']}") +print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS')) </example_commands> <screen> $ scons -Q -CXXFLAGS=-std=c11, CPPDEFINES=RELEASE -CXXFLAGS=-std=c11 -O, CPPDEFINES=['RELEASE', 'EXTRA'] +CXXFLAGS = -std=c11, CPPDEFINES = RELEASE +CXXFLAGS = -std=c11 -O, CPPDEFINES = deque(['RELEASE', 'EXTRA']) CPPDEFINES will expand to -DRELEASE -DEXTRA scons: `.' is up to date. </screen> <para> -Because &cv-link-CPPDEFINES; is intended to -describe C/C++ pre-processor macro definitions, -it accepts additional syntax. -Preprocessor macros can be valued, or un-valued, as in -<computeroutput>-DBAR=1</computeroutput> or -<computeroutput>-DFOO</computeroutput>. -The macro can be be supplied as a complete string including the value, -or as a tuple (or list) of macro, value, or as a dictionary. -Example (again gcc syntax in the expanded defines): +Because &cv-link-CPPDEFINES; is intended for command-line +specification of C/C++ preprocessor macros, +additional syntax is accepted when adding to it. +The preprocessor accepts arguments to predefine a macro name by itself +(<computeroutput>-DFOO</computeroutput> for most compilers, +<computeroutput>/DFOO</computeroutput> for Microsoft C++), +which gives it an implicit value of <constant>1</constant>, +or can be given with a replacement value +(<computeroutput>-DBAR=TEXT</computeroutput>). +&SCons; follows these rules when adding to &cv-CPPDEFINES;: +</para> +<itemizedlist> +<listitem> +<para>A string is split on spaces, +giving an easy way to enter multiple macros in one addition. +Use an <literal>=</literal> to specify a valued macro.</para> +</listitem> +<listitem> +<para>A tuple is treated as a valued macro. +Use the value <constant>None</constant> if the macro should not have a value. +It is an error to supply more than two elements in such a tuple.</para> +</listitem> +<listitem> +<para>A list is processed in order, +adding each item without further interpretation. +In this case, space-separated strings are not split.</para> +</listitem> +<listitem> +<para>A dictionary is processed in order, +adding each key:value pair as a valued macro. +Use the value <constant>None</constant> if the macro should not have a value. +</para> +</listitem> +</itemizedlist> + +<para> +Examples: </para> <example_commands> env = Environment(CPPDEFINES="FOO") -print("CPPDEFINES={}".format(env['CPPDEFINES'])) +print("CPPDEFINES =", env['CPPDEFINES']) env.Append(CPPDEFINES="BAR=1") -print("CPPDEFINES={}".format(env['CPPDEFINES'])) -env.Append(CPPDEFINES=("OTHER", 2)) -print("CPPDEFINES={}".format(env['CPPDEFINES'])) +print("CPPDEFINES =", env['CPPDEFINES']) +env.Append(CPPDEFINES=[("OTHER", 2)]) +print("CPPDEFINES =", env['CPPDEFINES']) env.Append(CPPDEFINES={"EXTRA": "arg"}) -print("CPPDEFINES={}".format(env['CPPDEFINES'])) -print("CPPDEFINES will expand to {}".format(env.subst("$_CPPDEFFLAGS"))) +print("CPPDEFINES =", env['CPPDEFINES']) +print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS')) </example_commands> <screen> $ scons -Q -CPPDEFINES=FOO -CPPDEFINES=['FOO', 'BAR=1'] -CPPDEFINES=['FOO', 'BAR=1', ('OTHER', 2)] -CPPDEFINES=['FOO', 'BAR=1', ('OTHER', 2), {'EXTRA': 'arg'}] +CPPDEFINES = FOO +CPPDEFINES = deque(['FOO', 'BAR=1']) +CPPDEFINES = deque(['FOO', 'BAR=1', ('OTHER', 2)]) +CPPDEFINES = deque(['FOO', 'BAR=1', ('OTHER', 2), ('EXTRA', 'arg')]) CPPDEFINES will expand to -DFOO -DBAR=1 -DOTHER=2 -DEXTRA=arg scons: `.' is up to date. </screen> <para> -Adding a string <parameter>val</parameter> -to a dictonary &consvar; will enter -<parameter>val</parameter> as the key in the dict, +Examples of adding multiple macros: +</para> + +<example_commands> +env = Environment() +env.Append(CPPDEFINES=[("ONE", 1), "TWO", ("THREE", )]) +print("CPPDEFINES =", env['CPPDEFINES']) +env.Append(CPPDEFINES={"FOUR": 4, "FIVE": None}) +print("CPPDEFINES =", env['CPPDEFINES']) +print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS')) +</example_commands> + +<screen> +$ scons -Q +CPPDEFINES = [('ONE', 1), 'TWO', ('THREE',)] +CPPDEFINES = deque([('ONE', 1), 'TWO', ('THREE',), ('FOUR', 4), ('FIVE', None)]) +CPPDEFINES will expand to -DONE=1 -DTWO -DTHREE -DFOUR=4 -DFIVE +scons: `.' is up to date. +</screen> + +<para> +<emphasis>Changed in version 4.5</emphasis>: +clarifined the use of tuples vs. other types, +handling is now consistent across the four functions. +</para> + +<example_commands> +env = Environment() +env.Append(CPPDEFINES=("MACRO1", "MACRO2")) +print("CPPDEFINES =", env['CPPDEFINES']) +env.Append(CPPDEFINES=[("MACRO3", "MACRO4")]) +print("CPPDEFINES =", env['CPPDEFINES']) +print("CPPDEFINES will expand to", env.subst('$_CPPDEFFLAGS')) +</example_commands> + +<screen> +$ scons -Q +CPPDEFINES = ('MACRO1', 'MACRO2') +CPPDEFINES = deque(['MACRO1', 'MACRO2', ('MACRO3', 'MACRO4')]) +CPPDEFINES will expand to -DMACRO1 -DMACRO2 -DMACRO3=MACRO4 +scons: `.' is up to date. +</screen> + +<para> +See &cv-link-CPPDEFINES; for more details. +</para> + +<para> +Appending a string <parameter>val</parameter> +to a dictonary-typed &consvar; enters +<parameter>val</parameter> as the key in the dictionary, and <literal>None</literal> as its value. -Using a tuple type to supply a key + value only works -for the special case of &cv-link-CPPDEFINES; +Using a tuple type to supply a <literal>key, value</literal> +only works for the special case of &cv-CPPDEFINES; described above. </para> <para> Although most combinations of types work without needing to know the details, some combinations -do not make sense and a &Python; exception will be raised. +do not make sense and &Python; raises an exception. </para> <para> @@ -552,7 +631,7 @@ When using &f-env-Append; to modify &consvars; which are path specifications (conventionally, the names of such end in <literal>PATH</literal>), it is recommended to add the values as a list of strings, -even if there is only a single string to add. +even if you are only adding a single string. The same goes for adding library names to &cv-LIBS;. </para> @@ -616,18 +695,18 @@ See also &f-link-env-PrependENVPath;. </listitem> </varlistentry> <varlistentry id="f-AppendUnique"> - <term><replaceable>env</replaceable>.<methodname>AppendUnique</methodname>(<parameter>key=val, [...], delete_existing=False</parameter>)</term> + <term><replaceable>env</replaceable>.<methodname>AppendUnique</methodname>(<parameter>key=val, [...], [delete_existing=False]</parameter>)</term> <listitem><para> Append values to &consvars; in the current &consenv;, maintaining uniqueness. -Works like &f-link-env-Append; (see for details), -except that values already present in the &consvar; -will not be added again. +Works like &f-link-env-Append;, +except that values that would become duplicates +are not added. If <parameter>delete_existing</parameter> -is <constant>True</constant>, -the existing matching value is first removed, -and the requested value is added, -having the effect of moving such values to the end. +is set to a true value, then for any duplicate, +the existing instance of <parameter>val</parameter> is first removed, +then <parameter>val</parameter> is appended, +having the effect of moving it to the end. </para> <para> @@ -1546,7 +1625,6 @@ will print: </varlistentry> <varlistentry id="f-EnsurePythonVersion"> <term><function>EnsurePythonVersion</function>(<parameter>major, minor</parameter>)</term> - <term><replaceable>env</replaceable>.<methodname>EnsurePythonVersion</methodname>(<parameter>major, minor</parameter>)</term> <listitem><para> Ensure that the Python version is at least <varname>major</varname>.<varname>minor</varname>. @@ -1566,7 +1644,6 @@ EnsurePythonVersion(2,2) </varlistentry> <varlistentry id="f-EnsureSConsVersion"> <term><function>EnsureSConsVersion</function>(<parameter>major, minor, [revision]</parameter>)</term> - <term><replaceable>env</replaceable>.<methodname>EnsureSConsVersion</methodname>(<parameter>major, minor, [revision]</parameter>)</term> <listitem><para> Ensure that the SCons version is at least <varname>major.minor</varname>, @@ -1669,7 +1746,6 @@ if Execute("mkdir sub/dir/ectory"): </varlistentry> <varlistentry id="f-Exit"> <term><function>Exit</function>(<parameter>[value]</parameter>)</term> - <term><replaceable>env</replaceable>.<methodname>Exit</methodname>(<parameter>[value]</parameter>)</term> <listitem><para> This tells &scons; @@ -2117,7 +2193,6 @@ Nodes or strings representing path names. </varlistentry> <varlistentry id="f-GetLaunchDir"> <term><function>GetLaunchDir</function>()</term> - <term><replaceable>env</replaceable>.<methodname>GetLaunchDir</methodname>()</term> <listitem><para> Returns the absolute path name of the directory from which &scons; @@ -2138,18 +2213,22 @@ file is found. <term><function>GetOption</function>(<parameter>name</parameter>)</term> <term><replaceable>env</replaceable>.<methodname>GetOption</methodname>(<parameter>name</parameter>)</term> <listitem><para> -This function provides a way to query the value of -options which can be set via the command line or using the -&f-link-SetOption; function. +Query the value of settable options which may have been set +on the command line, or by using the &f-link-SetOption; function. +The value of the option is returned in a type matching how the +option was declared - see the documentation for the +corresponding command line option for information about each specific +option. </para> + <para> <parameter>name</parameter> can be an entry from the following table, which shows the corresponding command line arguments that could affect the value. <parameter>name</parameter> can be also be the destination variable name from a project-specific option added using the -&f-link-AddOption; function, as long as the addition -happens prior to the &f-GetOption; call in the SConscript files. +&f-link-AddOption; function, as long as that addition has been +processed prior to the &f-GetOption; call in the &SConscript; files. </para> <informaltable rowsep="1" colsep="1" frame="topbot"> @@ -2374,56 +2453,83 @@ happens prior to the &f-GetOption; call in the SConscript files. </tbody> </tgroup> </informaltable> - -<para> -See the documentation for the -corresponding command line option for information about each specific -option. -</para> </listitem> </varlistentry> <varlistentry id="f-Glob"> - <term><function>Glob</function>(<parameter>pattern, [ondisk, source, strings, exclude]</parameter>)</term> - <term><replaceable>env</replaceable>.<methodname>Glob</methodname>(<parameter>pattern, [ondisk, source, strings, exclude]</parameter>)</term> + <term><function>Glob</function>(<parameter>pattern, [ondisk=True, source=False, strings=False, exclude=None]</parameter>)</term> + <term><replaceable>env</replaceable>.<methodname>Glob</methodname>(<parameter>pattern, [ondisk=True, source=False, strings=False, exclude=None]</parameter>)</term> <listitem><para> -Returns Nodes (or strings) that match the specified -<parameter>pattern</parameter>, -relative to the directory of the current -&SConscript; -file. +Returns a possibly empty list of Nodes (or strings) that match +pathname specification <parameter>pattern</parameter>. +<parameter>pattern</parameter> can be absolute, +top-relative, +or (most commonly) relative to the directory of the current +&SConscript; file. +&f-Glob; matches both files stored on disk and Nodes +which &SCons; already knows about, even if any corresponding +file is not currently stored on disk. The evironment method form (&f-env-Glob;) performs string substition on <parameter>pattern</parameter> -and returns whatever matches -the resulting expanded pattern. +and returns whatever matches the resulting expanded pattern. +The results are sorted, unlike for the similar &Python; +<systemitem>glob.glob</systemitem> function, +to ensure build order will be stable. </para> <para> -The specified <parameter>pattern</parameter> -uses Unix shell style metacharacters for matching: +can contain POSIX-style shell metacharacters for matching: </para> -<example_commands> - * matches everything - ? matches any single character - [seq] matches any character in seq - [!seq] matches any char not in seq -</example_commands> +<informaltable rowsep="1" colsep="1" frame="topbot"> +<tgroup cols="2"> +<thead> + <row> + <entry>Pattern</entry> + <entry>Meaning</entry> + </row> +</thead> +<tbody> + <row> + <entry><literal>*</literal></entry> + <entry>matches everything</entry> + </row> + <row> + <entry><literal>?</literal></entry> + <entry>matches any single character</entry> + </row> + <row> + <entry><literal>[seq]</literal></entry> + <entry>matches any character in <emphasis>seq</emphasis> + (can be a list or a range).</entry> + </row> + <row> + <entry><literal>[!seq]</literal></entry> + <entry>matches any character not in <emphasis>seq</emphasis></entry> + </row> +</tbody> +</tgroup> +</informaltable> <para> -If the first character of a filename is a dot, -it must be matched explicitly. -Character matches do -<emphasis>not</emphasis> -span directory separators. +For a literal match, wrap the metacharacter in brackets to +escape the normal behavior. +For example, <literal>'[?]'</literal> matches the character +<literal>'?'</literal>. +</para> + +<para> +Filenames starting with a dot are specially handled - +they can only be matched by patterns that start with a dot +(or have a dot immediately following a pathname separator +character, or slash), they are not not matched by the metacharacters. +Metacharacter matches also do not span directory separators. </para> <para> -The &f-Glob; -knows about -repositories +understands repositories (see the &f-link-Repository; function) @@ -2431,8 +2537,7 @@ and source directories (see the &f-link-VariantDir; function) -and -returns a Node (or string, if so configured) +and returns a Node (or string, if so configured) match in the local (SConscript) directory if a matching Node is found anywhere in a corresponding @@ -2440,65 +2545,60 @@ repository or source directory. </para> <para> -The +If the optional <parameter>ondisk</parameter> -argument may be set to a value which evaluates -<constant>False</constant> -to disable the search for matches on disk, -thereby only returning matches among -already-configured File or Dir Nodes. -The default behavior is to -return corresponding Nodes -for any on-disk matches found. +argument evaluates false, +the search for matches on disk is disabled, +and only matches from +already-configured File or Dir Nodes are returned. +The default is to return Nodes for +matches on disk as well. </para> <para> -The +If the optional <parameter>source</parameter> -argument may be set to a value which evaluates -<constant>True</constant> -to specify that, -when the local directory is a -&f-VariantDir;, -the returned Nodes should be from the -corresponding source directory, -not the local directory. +argument evaluates true, +and the local directory is a variant directory, +then &f-Glob; returnes Nodes from +the corresponding source directory, +rather than the local directory. +<!-- XXX what about generated files that don't exist in src but will be sources? --> </para> <para> -The +If the optional <parameter>strings</parameter> -argument may be set to a value which evaluates -<constant>True</constant> -to have the +argument evaluates true, &f-Glob; -function return strings, not Nodes, -that represent the matched files or directories. +returns matches as strings, rather than Nodes. The returned strings will be relative to the local (SConscript) directory. -(Note that This may make it easier to perform +(Note that while this may make it easier to perform arbitrary manipulation of file names, -but if the returned strings are +it loses the context &SCons; would have in the Node, +so if the returned strings are passed to a different &SConscript; file, -any Node translation will be relative -to the other +any Node translation there will be relative +to that &SConscript; directory, -not the original +not to the original &SConscript; directory.) </para> <para> -The +The optional <parameter>exclude</parameter> argument may be set to a pattern or a list of patterns -(following the same Unix shell semantics) -which must be filtered out of returned elements. -Elements matching a least one pattern of -this list will be excluded. +descibing files or directories +to filter out of the match list. +Elements matching a least one specified pattern will be excluded. +These patterns use the same syntax as for +<parameter>pattern</parameter>. </para> <para> @@ -2508,9 +2608,10 @@ Examples: <example_commands> Program("foo", Glob("*.c")) Zip("/tmp/everything", Glob(".??*") + Glob("*")) -sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) + \ - Glob( "os_%s_specific_*.cpp" % currentOS) +sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) \ + + Glob("os_%s_specific_*.cpp" % currentOS) </example_commands> + </listitem> </varlistentry> <varlistentry id="f-Help"> @@ -2542,24 +2643,26 @@ the existing help text. <term><function>Ignore</function>(<parameter>target, dependency</parameter>)</term> <term><replaceable>env</replaceable>.<methodname>Ignore</methodname>(<parameter>target, dependency</parameter>)</term> <listitem><para> -The specified dependency file(s) -will be ignored when deciding if -the target file(s) need to be rebuilt. -</para> - -<para> -You can also use -&f-Ignore; -to remove a target from the default build. -In order to do this you must specify the directory the target will -be built in as the target, and the file you want to skip building -as the dependency. +Ignores <parameter>dependency</parameter> +when deciding if +<parameter>target</parameter> needs to be rebuilt. +<parameter>target</parameter> and +<parameter>dependency</parameter> +can each be a single filename or Node +or a list of filenames or Nodes. </para> <para> -Note that this will only remove the dependencies listed from -the files built by default. It will still be built if that -dependency is needed by another object being built. +&f-Ignore; can also be used to +remove a target from the default build +by specifying the directory the target will be built in as +<parameter>target</parameter> +and the file you want to skip selecting for building as +<parameter>dependency</parameter>. +Note that this only removes the target from +the default target selection algorithm: +if it is a dependency of another object being +built &SCons; still builds it normally. See the third and forth examples below. </para> @@ -3116,20 +3219,20 @@ See also &f-link-env-AppendENVPath;. </listitem> </varlistentry> <varlistentry id="f-PrependUnique"> - <term><replaceable>env</replaceable>.<methodname>PrependUnique</methodname>(<parameter>key=val, delete_existing=False, [...]</parameter>)</term> + <term><replaceable>env</replaceable>.<methodname>PrependUnique</methodname>(<parameter>key=val, [...], [delete_existing=False]</parameter>)</term> <listitem><para> Prepend values to &consvars; in the current &consenv;, maintaining uniqueness. -Works like &f-link-env-Append; (see for details), +Works like &f-link-env-Append;, except that values are added to the front, -rather than the end, of any existing value of the &consvar;, -and values already present in the &consvar; -will not be added again. +rather than the end, of the &consvar;, +and values that would become duplicates +are not added. If <parameter>delete_existing</parameter> -is <constant>True</constant>, -the existing matching value is first removed, -and the requested value is inserted, -having the effect of moving such values to the front. +is set to a true value, then for any duplicate, +the existing instance of <parameter>val</parameter> is first removed, +then <parameter>val</parameter> is inserted, +having the effect of moving it to the front. </para> <para> @@ -3713,24 +3816,16 @@ script does not explicitly call &Return;, it returns </varlistentry> <varlistentry id="f-SConscriptChdir"> <term><function>SConscriptChdir</function>(<parameter>value</parameter>)</term> - <term><replaceable>env</replaceable>.<methodname>SConscriptChdir</methodname>(<parameter>value</parameter>)</term> <listitem><para> By default, &scons; changes its working directory to the directory in which each -subsidiary SConscript file lives. +subsidiary SConscript file lives +while reading and processing that script. This behavior may be disabled -by specifying either: -</para> - -<example_commands> -SConscriptChdir(0) -env.SConscriptChdir(0) -</example_commands> - -<para> -in which case +by specifying an argument which +evaluates false, in which case &scons; will stay in the top-level directory while reading all SConscript files. @@ -3748,10 +3843,9 @@ Example: </para> <example_commands> -env = Environment() -SConscriptChdir(0) +SConscriptChdir(False) SConscript('foo/SConscript') # will not chdir to foo -env.SConscriptChdir(1) +SConscriptChdir(True) SConscript('bar/SConscript') # will chdir to bar </example_commands> </listitem> @@ -4340,6 +4434,12 @@ appended to the &cv-link-TOOLS; </para> <para> +<emphasis>Changed in version 4.2:</emphasis> +&f-env-Tool; now returns the tool object, +previously it did not return (i.e. returned <constant>None</constant>). +</para> + +<para> Examples: </para> @@ -4376,12 +4476,6 @@ msvctool(env) # adds 'msvc' to the TOOLS variable gltool = Tool('opengl', toolpath = ['tools']) gltool(env) # adds 'opengl' to the TOOLS variable </example_commands> - -<para> -<emphasis>Changed in &SCons; 4.2: &f-env-Tool; now returns -the tool object, previously it did not return -(i.e. returned <constant>None</constant>).</emphasis> -</para> </listitem> </varlistentry> <varlistentry id="f-ValidateOptions"> @@ -4420,7 +4514,7 @@ except SConsBadOptionError as e: print("Message is :%s" % e.opt_str) Exit(3) </example_commands> - + <para> This function is useful to force SCons to fail fast before you execute any expensive logic later in your build logic. @@ -4434,9 +4528,9 @@ scons --compilers=mingw (the correct flag is --compiler) Could cause SCons to run configure steps with the incorrect compiler. Costing developer time trying to track down why the configure logic failed with a compiler which should work. </para> - - - + <para> + <emphasis>New in version 4.5.0</emphasis> + </para> </listitem> </varlistentry> <varlistentry id="f-Value"> @@ -4454,10 +4548,6 @@ will be rebuilt. files are up-to-date.) When using timestamp source signatures, Value Nodes' timestamps are equal to the system time when the Node is created. -<parameter>name</parameter> can be provided as an alternative name -for the resulting <literal>Value</literal> node; this is advised -if the <parameter>value</parameter> parameter can't be converted to -a string. </para> <para> @@ -4477,6 +4567,18 @@ method that will return the built value of the Node. </para> <para> +The optional <parameter>name</parameter> parameter can be provided as an +alternative name for the resulting <literal>Value</literal> node; +this is advised if the <parameter>value</parameter> parameter +cannot be converted to a string. +</para> + +<para> +<emphasis>Changed in version 4.0:</emphasis> +the <parameter>name</parameter> parameter was added. +</para> + +<para> Examples: </para> @@ -4496,8 +4598,8 @@ prefix = ARGUMENTS.get('prefix', '/usr/local') # Attach a .Config() builder for the above function action # to the construction environment. -env['BUILDERS']['Config'] = Builder(action = create) -env.Config(target = 'package-config', source = Value(prefix)) +env['BUILDERS']['Config'] = Builder(action=create) +env.Config(target='package-config', source=Value(prefix)) def build_value(target, source, env): # A function that "builds" a Python Value by updating @@ -4510,8 +4612,8 @@ input = env.Value('after') # Attach a .UpdateValue() builder for the above function # action to the construction environment. -env['BUILDERS']['UpdateValue'] = Builder(action = build_value) -env.UpdateValue(target = Value(output), source = Value(input)) +env['BUILDERS']['UpdateValue'] = Builder(action=build_value) +env.UpdateValue(target=Value(output), source=Value(input)) </example_commands> </listitem> </varlistentry> @@ -4585,7 +4687,7 @@ The subsidiary SConscript file must be called as if it were in <parameter>variant_dir</parameter>, regardless of the value of <parameter>duplicate</parameter>. -When calling an SConscript file, you can use the +When calling an SConscript file, you can use the <parameter>exports</parameter> keyword argument to pass parameters (individually or as an appropriately set up environment) so the SConscript can pick up the right settings for that variant build. diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen index f05b470e7..c3b4cfc51 100644 --- a/doc/generated/tools.gen +++ b/doc/generated/tools.gen @@ -779,13 +779,13 @@ the Microsoft toolchain: <varlistentry id="t-msvc"> <term>msvc</term> <listitem><para> -Sets construction variables for the Microsoft Visual C/C++ compiler. +Sets &consvars; for the Microsoft Visual C/C++ compiler. </para> -<para>Sets: &cv-link-BUILDERS;, &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCDEPFLAGS;, &cv-link-CCFLAGS;, &cv-link-CCPCHFLAGS;, &cv-link-CCPDBFLAGS;, &cv-link-CFILESUFFIX;, &cv-link-CFLAGS;, &cv-link-CPPDEFPREFIX;, &cv-link-CPPDEFSUFFIX;, &cv-link-CXX;, &cv-link-CXXCOM;, &cv-link-CXXFILESUFFIX;, &cv-link-CXXFLAGS;, &cv-link-INCPREFIX;, &cv-link-INCSUFFIX;, &cv-link-OBJPREFIX;, &cv-link-OBJSUFFIX;, &cv-link-PCHCOM;, &cv-link-PCHPDBFLAGS;, &cv-link-RC;, &cv-link-RCCOM;, &cv-link-RCFLAGS;, &cv-link-SHCC;, &cv-link-SHCCCOM;, &cv-link-SHCCFLAGS;, &cv-link-SHCFLAGS;, &cv-link-SHCXX;, &cv-link-SHCXXCOM;, &cv-link-SHCXXFLAGS;, &cv-link-SHOBJPREFIX;, &cv-link-SHOBJSUFFIX;.</para><para>Uses: &cv-link-CCCOMSTR;, &cv-link-CXXCOMSTR;, &cv-link-MSVC_NOTFOUND_POLICY;, &cv-link-PCH;, &cv-link-PCHSTOP;, &cv-link-PDB;, &cv-link-SHCCCOMSTR;, &cv-link-SHCXXCOMSTR;.</para></listitem> +<para>Sets: &cv-link-BUILDERS;, &cv-link-CC;, &cv-link-CCCOM;, &cv-link-CCDEPFLAGS;, &cv-link-CCFLAGS;, &cv-link-CCPCHFLAGS;, &cv-link-CCPDBFLAGS;, &cv-link-CFILESUFFIX;, &cv-link-CFLAGS;, &cv-link-CPPDEFPREFIX;, &cv-link-CPPDEFSUFFIX;, &cv-link-CXX;, &cv-link-CXXCOM;, &cv-link-CXXFILESUFFIX;, &cv-link-CXXFLAGS;, &cv-link-INCPREFIX;, &cv-link-INCSUFFIX;, &cv-link-OBJPREFIX;, &cv-link-OBJSUFFIX;, &cv-link-PCHCOM;, &cv-link-PCHPDBFLAGS;, &cv-link-RC;, &cv-link-RCCOM;, &cv-link-RCFLAGS;, &cv-link-SHCC;, &cv-link-SHCCCOM;, &cv-link-SHCCFLAGS;, &cv-link-SHCFLAGS;, &cv-link-SHCXX;, &cv-link-SHCXXCOM;, &cv-link-SHCXXFLAGS;, &cv-link-SHOBJPREFIX;, &cv-link-SHOBJSUFFIX;.</para><para>Uses: &cv-link-CCCOMSTR;, &cv-link-CXXCOMSTR;, &cv-link-MSVC_NOTFOUND_POLICY;, &cv-link-MSVC_SCRIPTERROR_POLICY;, &cv-link-MSVC_SCRIPT_ARGS;, &cv-link-MSVC_SDK_VERSION;, &cv-link-MSVC_SPECTRE_LIBS;, &cv-link-MSVC_TOOLSET_VERSION;, &cv-link-MSVC_USE_SCRIPT;, &cv-link-MSVC_USE_SCRIPT_ARGS;, &cv-link-MSVC_USE_SETTINGS;, &cv-link-MSVC_VERSION;, &cv-link-PCH;, &cv-link-PCHSTOP;, &cv-link-PDB;, &cv-link-SHCCCOMSTR;, &cv-link-SHCXXCOMSTR;.</para></listitem> </varlistentry> <varlistentry id="t-msvs"> <term>msvs</term> - <listitem><para>Sets construction variables for Microsoft Visual Studio.</para> + <listitem><para>Sets &consvars; for Microsoft Visual Studio.</para> <para>Sets: &cv-link-MSVSBUILDCOM;, &cv-link-MSVSCLEANCOM;, &cv-link-MSVSENCODING;, &cv-link-MSVSPROJECTCOM;, &cv-link-MSVSREBUILDCOM;, &cv-link-MSVSSCONS;, &cv-link-MSVSSCONSCOM;, &cv-link-MSVSSCONSCRIPT;, &cv-link-MSVSSCONSFLAGS;, &cv-link-MSVSSOLUTIONCOM;.</para></listitem> </varlistentry> <varlistentry id="t-mwcc"> @@ -867,13 +867,22 @@ provided to an Action that uses this environment. <varlistentry id="t-qt"> <term>qt</term> <listitem><para> +Placeholder tool to alert anyone still using qt tools to switch to qt3 or newer tool. +</para> +</listitem> + </varlistentry> + <varlistentry id="t-qt3"> + <term>qt3</term> + <listitem><para> Sets &consvars; for building Qt3 applications. </para> <note><para> This tool is only suitable for building targeted to Qt3, which is obsolete -(<emphasis>the tool is deprecated since 4.3</emphasis>). +(<emphasis>the tool is deprecated since 4.3, +and was renamed to qt3 in 4.5.0. +</emphasis>). There are contributed tools for Qt4 and Qt5, see <ulink url="https://github.com/SCons/scons-contrib"> https://github.com/SCons/scons-contrib</ulink>. @@ -901,11 +910,11 @@ you have to explicitly specify it at Environment creation: </para> <example_commands> -Environment(tools=['default','qt']) +Environment(tools=['default','qt3']) </example_commands> <para> -The &t-qt; tool supports the following operations: +The &t-qt3; tool supports the following operations: </para> <para> @@ -920,7 +929,7 @@ directory. It must have one of the suffixes <filename>.hxx</filename>, <filename>.hh</filename>. You can turn off automatic moc file generation by setting -&cv-link-QT_AUTOSCAN; to <constant>False</constant>. +&cv-link-QT3_AUTOSCAN; to <constant>False</constant>. See also the corresponding &b-link-Moc; Builder. </para> @@ -930,11 +939,11 @@ See also the corresponding As described in the Qt documentation, include the moc file at the end of the C++ file. Note that you have to include the file, which is generated by the transformation -<literal>${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}</literal>, by default +<literal>${QT3_MOCCXXPREFIX}<basename>${QT3_MOCCXXSUFFIX}</literal>, by default <filename><basename>.mo</filename>. A warning is generated after building the moc file if you do not include the correct file. If you are using &f-link-VariantDir;, you may need to specify <parameter>duplicate=True</parameter>. -You can turn off automatic moc file generation by setting &cv-QT_AUTOSCAN; to +You can turn off automatic moc file generation by setting &cv-QT3_AUTOSCAN; to <literal>False</literal>. See also the corresponding &b-link-Moc; Builder. </para> @@ -952,7 +961,7 @@ you may need to specify <parameter>duplicate=True</parameter> in calls to See also the corresponding &b-link-Uic; Builder. </para> -<para>Sets: &cv-link-QTDIR;, &cv-link-QT_AUTOSCAN;, &cv-link-QT_BINPATH;, &cv-link-QT_CPPPATH;, &cv-link-QT_LIB;, &cv-link-QT_LIBPATH;, &cv-link-QT_MOC;, &cv-link-QT_MOCCXXPREFIX;, &cv-link-QT_MOCCXXSUFFIX;, &cv-link-QT_MOCFROMCXXCOM;, &cv-link-QT_MOCFROMCXXFLAGS;, &cv-link-QT_MOCFROMHCOM;, &cv-link-QT_MOCFROMHFLAGS;, &cv-link-QT_MOCHPREFIX;, &cv-link-QT_MOCHSUFFIX;, &cv-link-QT_UIC;, &cv-link-QT_UICCOM;, &cv-link-QT_UICDECLFLAGS;, &cv-link-QT_UICDECLPREFIX;, &cv-link-QT_UICDECLSUFFIX;, &cv-link-QT_UICIMPLFLAGS;, &cv-link-QT_UICIMPLPREFIX;, &cv-link-QT_UICIMPLSUFFIX;, &cv-link-QT_UISUFFIX;.</para><para>Uses: &cv-link-QTDIR;.</para></listitem> +<para>Sets: &cv-link-QT3DIR;, &cv-link-QT3_AUTOSCAN;, &cv-link-QT3_BINPATH;, &cv-link-QT3_CPPPATH;, &cv-link-QT3_LIB;, &cv-link-QT3_LIBPATH;, &cv-link-QT3_MOC;, &cv-link-QT3_MOCCXXPREFIX;, &cv-link-QT3_MOCCXXSUFFIX;, &cv-link-QT3_MOCFROMCXXCOM;, &cv-link-QT3_MOCFROMCXXFLAGS;, &cv-link-QT3_MOCFROMHCOM;, &cv-link-QT3_MOCFROMHFLAGS;, &cv-link-QT3_MOCHPREFIX;, &cv-link-QT3_MOCHSUFFIX;, &cv-link-QT3_UIC;, &cv-link-QT3_UICCOM;, &cv-link-QT3_UICDECLFLAGS;, &cv-link-QT3_UICDECLPREFIX;, &cv-link-QT3_UICDECLSUFFIX;, &cv-link-QT3_UICIMPLFLAGS;, &cv-link-QT3_UICIMPLPREFIX;, &cv-link-QT3_UICIMPLSUFFIX;, &cv-link-QT3_UISUFFIX;.</para><para>Uses: &cv-link-QT3DIR;.</para></listitem> </varlistentry> <varlistentry id="t-rmic"> <term>rmic</term> @@ -1071,7 +1080,7 @@ Sets construction variables for the TeX formatter and typesetter. <listitem><para> Set &consvars; for the &b-Textfile; and &b-Substfile; builders. </para> -<para>Sets: &cv-link-LINESEPARATOR;, &cv-link-SUBSTFILEPREFIX;, &cv-link-SUBSTFILESUFFIX;, &cv-link-TEXTFILEPREFIX;, &cv-link-TEXTFILESUFFIX;.</para><para>Uses: &cv-link-SUBST_DICT;.</para></listitem> +<para>Sets: &cv-link-FILE_ENCODING;, &cv-link-LINESEPARATOR;, &cv-link-SUBSTFILEPREFIX;, &cv-link-SUBSTFILESUFFIX;, &cv-link-TEXTFILEPREFIX;, &cv-link-TEXTFILESUFFIX;.</para><para>Uses: &cv-link-SUBST_DICT;.</para></listitem> </varlistentry> <varlistentry id="t-tlib"> <term>tlib</term> diff --git a/doc/generated/tools.mod b/doc/generated/tools.mod index 35eea5e2b..cb92b4fb2 100644 --- a/doc/generated/tools.mod +++ b/doc/generated/tools.mod @@ -86,6 +86,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY t-pdftex "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>pdftex</literal>"> <!ENTITY t-python "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>python</literal>"> <!ENTITY t-qt "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>qt</literal>"> +<!ENTITY t-qt3 "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>qt3</literal>"> <!ENTITY t-rmic "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>rmic</literal>"> <!ENTITY t-rpcgen "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>rpcgen</literal>"> <!ENTITY t-sgiar "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>sgiar</literal>"> @@ -192,6 +193,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY t-link-pdftex "<link linkend='t-pdftex' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>pdftex</literal></link>"> <!ENTITY t-link-python "<link linkend='t-python' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>python</literal></link>"> <!ENTITY t-link-qt "<link linkend='t-qt' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>qt</literal></link>"> +<!ENTITY t-link-qt3 "<link linkend='t-qt3' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>qt3</literal></link>"> <!ENTITY t-link-rmic "<link linkend='t-rmic' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>rmic</literal></link>"> <!ENTITY t-link-rpcgen "<link linkend='t-rpcgen' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>rpcgen</literal></link>"> <!ENTITY t-link-sgiar "<link linkend='t-sgiar' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>sgiar</literal></link>"> diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen index fdfa9bc9c..42935a317 100644 --- a/doc/generated/variables.gen +++ b/doc/generated/variables.gen @@ -448,7 +448,7 @@ Options added to the compiler command line to support building with precompiled headers. The default value expands expands to the appropriate Microsoft Visual C++ command-line options -when the &cv-link-PCH; construction variable is set. +when the &cv-link-PCH; &consvar; is set. </para> </listitem> </varlistentry> @@ -462,7 +462,7 @@ to support storing debugging information in a Microsoft Visual C++ PDB file. The default value expands expands to appropriate Microsoft Visual C++ command-line options -when the &cv-link-PDB; construction variable is set. +when the &cv-link-PDB; &consvar; is set. </para> <para> @@ -709,69 +709,112 @@ to each definition in &cv-link-CPPDEFINES;. </term> <listitem><para> A platform independent specification of C preprocessor macro definitions. -The definitions will be added to command lines +The definitions are added to command lines through the automatically-generated -&cv-link-_CPPDEFFLAGS; &consvar; (see above), +&cv-link-_CPPDEFFLAGS; &consvar;, which is constructed according to -the type of value of &cv-CPPDEFINES;: +the contents of &cv-CPPDEFINES;: </para> +<itemizedlist> +<listitem> <para> If &cv-CPPDEFINES; is a string, the values of the &cv-link-CPPDEFPREFIX; and &cv-link-CPPDEFSUFFIX; &consvars; -will be respectively prepended and appended to -each definition in &cv-link-CPPDEFINES;. +are respectively prepended and appended to +each definition in &cv-CPPDEFINES;, +split on whitespace. </para> <example_commands> -# Will add -Dxyz to POSIX compiler command lines, +# Adds -Dxyz to POSIX compiler command lines, # and /Dxyz to Microsoft Visual C++ command lines. env = Environment(CPPDEFINES='xyz') </example_commands> +</listitem> +<listitem> <para> If &cv-CPPDEFINES; is a list, the values of the &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars; -will be respectively prepended and appended to +are respectively prepended and appended to each element in the list. -If any element is a list or tuple, -then the first item is the name being -defined and the second item is its value: +If any element is a tuple (or list) +then the first item of the tuple is the macro name +and the second is the macro definition. +If the definition is not omitted or <literal>None</literal>, +the name and definition are combined into a single +<literal>name=definition</literal> item +before the preending/appending. </para> <example_commands> -# Will add -DB=2 -DA to POSIX compiler command lines, +# Adds -DB=2 -DA to POSIX compiler command lines, # and /DB=2 /DA to Microsoft Visual C++ command lines. env = Environment(CPPDEFINES=[('B', 2), 'A']) </example_commands> +</listitem> +<listitem> <para> If &cv-CPPDEFINES; is a dictionary, the values of the &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX; &consvars; -will be respectively prepended and appended to -each item from the dictionary. -The key of each dictionary item -is a name being defined -to the dictionary item's corresponding value; -if the value is -<literal>None</literal>, -then the name is defined without an explicit value. -Note that the resulting flags are sorted by keyword -to ensure that the order of the options on the -command line is consistent each time -&scons; -is run. +are respectively prepended and appended to +each key from the dictionary. +If the value for a key is not <literal>None</literal>, +then the key (macro name) and the value +(macros definition) are combined into a single +<literal>name=definition</literal> item +before the prepending/appending. </para> <example_commands> -# Will add -DA -DB=2 to POSIX compiler command lines, -# and /DA /DB=2 to Microsoft Visual C++ command lines. +# Adds -DA -DB=2 to POSIX compiler command lines, +# or /DA /DB=2 to Microsoft Visual C++ command lines. env = Environment(CPPDEFINES={'B':2, 'A':None}) </example_commands> </listitem> +</itemizedlist> + +<para> +Depending on how contents are added to &cv-CPPDEFINES;, +it may be transformed into a compound type, +for example a list containing strings, tuples and/or dictionaries. +&SCons; can correctly expand such a compound type. +</para> + +<para> +Note that &SCons; may call the compiler via a shell. +If a macro definition contains characters such as spaces that +have meaning to the shell, or is intended to be a string value, +you may need to use the shell's quoting syntax to avoid +interpretation by the shell before the preprocessor sees it. +Function-like macros are not supported via this mechanism +(and some compilers do not even implement that functionality +via the command lines). +When quoting, note that +one set of quote characters are used to define a &Python; string, +then quotes embedded inside that would be consumed by the shell +unless escaped. These examples may help illustrate: +</para> + +<example_commands> +env = Environment(CPPDEFINES=['USE_ALT_HEADER=\\"foo_alt.h\\"']) +env = Environment(CPPDEFINES=[('USE_ALT_HEADER', '\\"foo_alt.h\\"')]) +</example_commands> + +<para> +:<emphasis>Changed in version 4.5</emphasis>: +&SCons; no longer sorts &cv-CPPDEFINES; values entered +in dictionary form. &Python; now preserves dictionary +keys in the order they are entered, so it is no longer +necessary to sort them to ensure a stable command line. +</para> + +</listitem> </varlistentry> <varlistentry id="cv-CPPDEFPREFIX"> <term> @@ -2658,6 +2701,16 @@ target being built. </para> </listitem> </varlistentry> + <varlistentry id="cv-FILE_ENCODING"> + <term> + <envar>FILE_ENCODING</envar> + </term> + <listitem><para> +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> +</listitem> + </varlistentry> <varlistentry id="cv-FORTRAN"> <term> <envar>FORTRAN</envar> @@ -2689,8 +2742,9 @@ in the &cv-link-FORTRANFLAGS;, <listitem><para> General user-specified options that are passed to the Fortran compiler. Similar to &cv-link-FORTRANFLAGS;, -but this variable is applied to all dialects. +but this &consvar; is applied to all dialects. </para> +<para><emphasis>New in version 4.4.</emphasis></para> </listitem> </varlistentry> <varlistentry id="cv-FORTRANCOMSTR"> @@ -2729,9 +2783,8 @@ contain (or similar) include or module search path options that scons generates automatically from &cv-link-FORTRANPATH;. See -&cv-link-_FORTRANINCFLAGS; and &cv-link-_FORTRANMODFLAG;, -below, -for the variables that expand those options. +&cv-link-_FORTRANINCFLAGS; and &cv-link-_FORTRANMODFLAG; +for the &consvars; that expand those options. </para> </listitem> </varlistentry> @@ -3225,14 +3278,13 @@ determine the version of versioned import library. <envar>IMPLICIT_COMMAND_DEPENDENCIES</envar> </term> <listitem><para> -Controls whether or not SCons will +Controls whether or not &SCons; will add implicit dependencies for the commands executed to build targets. </para> <para> -By default, SCons will add -to each target +By default, &SCons; will add to each target an implicit dependency on the command represented by the first argument of any command line it executes (which is typically @@ -3476,16 +3528,30 @@ by default. <envar>JAVABOOTCLASSPATH</envar> </term> <listitem><para> - Specifies the list of directories that - will be added to the - &javac; command line - via the <option>-bootclasspath</option> option. - The individual directory names will be - separated by the operating system's path separate character - (<filename>:</filename> on UNIX/Linux/POSIX, - <filename>;</filename> - on Windows). + Specifies the location of the bootstrap class files. + Can be specified as a string or Node object, + or as a list of strings or Node objects. </para> + <para> + The value will be added to the JDK command lines + via the <option>-bootclasspath</option> option, + which requires a system-specific search path separator. + This will be supplied by &SCons; as needed when it + constructs the command line if &cv-JAVABOOTCLASSPATH; is + provided in list form. + If &cv-JAVABOOTCLASSPATH; is a single string containing + search path separator characters + (<literal>:</literal> for POSIX systems or + <literal>;</literal> for Windows), it will not be modified; + and so is inherently system-specific; + to supply the path in a system-independent manner, + give &cv-JAVABOOTCLASSPATH; as a list of paths instead. + </para> + <note> + <para> + Can only be used when compiling for releases prior to JDK 9. + </para> + </note> </listitem> </varlistentry> <varlistentry id="cv-JAVAC"> @@ -3541,10 +3607,9 @@ env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES") </term> <listitem><para> The directory in which Java class files may be found. - This is stripped from the beginning of any Java .class - file names supplied to the - <literal>JavaH</literal> - builder. + This is stripped from the beginning of any Java + <filename>.class</filename> + file names supplied to the &b-link-JavaH; builder. </para> </listitem> </varlistentry> @@ -3553,19 +3618,54 @@ env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES") <envar>JAVACLASSPATH</envar> </term> <listitem><para> - Specifies the list of directories that - will be searched for Java - <filename>.class</filename> - file. - The directories in this list will be added to the - &javac; and &javah; command lines - via the <option>-classpath</option> option. - The individual directory names will be - separated by the operating system's path separate character - (<filename>:</filename> on UNIX/Linux/POSIX, - <filename>;</filename> - on Windows). + Specifies the class search path for the JDK tools. + Can be specified as a string or Node object, + or as a list of strings or Node objects. + Class path entries may be directory names to search + for class files or packages, pathnames to archives + (<filename>.jar</filename> or <filename>.zip</filename>) + containing classes, or paths ending in a "base name wildcard" + character (<literal>*</literal>), which matches files + in that directory with a <filename>.jar</filename> suffix. + See the Java documentation for more details. </para> + <para> + The value will be added to the JDK command lines + via the <option>-classpath</option> option, + which requires a system-specific search path separator. + This will be supplied by &SCons; as needed when it + constructs the command line if &cv-JAVACLASSPATH; is + provided in list form. + If &cv-JAVACLASSPATH; is a single string containing + search path separator characters + (<literal>:</literal> for POSIX systems or + <literal>;</literal> for Windows), + it will be split on the separator into a list of individual + paths for dependency scanning purposes. + It will not be modified for JDK command-line usage, + so such a string is inherently system-specific; + to supply the path in a system-independent manner, + give &cv-JAVACLASSPATH; as a list of paths instead. + </para> + <note> + <para> + &SCons; <emphasis role="bold">always</emphasis> + supplies a <option>-sourcepath</option> + when invoking the Java compiler &javac;, + regardless of the setting of &cv-link-JAVASOURCEPATH;, + as it passes the path(s) to the source(s) supplied + in the call to the &b-link-Java; builder via + <option>-sourcepath</option> . + From the documentation of the standard Java toolkit for &javac;: + <quote>If not compiling code for modules, if the + <option>--source-path</option> or <option>-sourcepath</option> + option is not specified, then the user class path is also + searched for source files.</quote> + Since <option>-sourcepath</option> is always supplied, + &javac; will not use the contents of the value of + &cv-JAVACLASSPATH; when searching for sources. + </para> + </note> </listitem> </varlistentry> <varlistentry id="cv-JAVACLASSSUFFIX"> @@ -3630,7 +3730,37 @@ for Java classes. <envar>JAVAINCLUDES</envar> </term> <listitem><para> - Include path for Java header files (such as jni.h) + Include path for Java header files + (such as <filename>jni.h</filename>). + </para> + </listitem> + </varlistentry> + <varlistentry id="cv-JAVAPROCESSORPATH"> + <term> + <envar>JAVAPROCESSORPATH</envar> + </term> + <listitem><para> + Specifies the location of the annotation processor class files. + Can be specified as a string or Node object, + or as a list of strings or Node objects. + </para> + <para> + The value will be added to the JDK command lines + via the <option>-processorpath</option> option, + which requires a system-specific search path separator. + This will be supplied by &SCons; as needed when it + constructs the command line if &cv-JAVAPROCESSORPATH; is + provided in list form. + If &cv-JAVAPROCESSORPATH; is a single string containing + search path separator characters + (<literal>:</literal> for POSIX systems or + <literal>;</literal> for Windows), it will not be modified; + and so is inherently system-specific; + to supply the path in a system-independent manner, + give &cv-JAVAPROCESSORPATH; as a list of paths instead. + </para> + <para> + <emphasis>New in version 4.5.0</emphasis> </para> </listitem> </varlistentry> @@ -3640,24 +3770,31 @@ for Java classes. </term> <listitem><para> Specifies the list of directories that - will be searched for input - <filename>.java</filename> - file. - The directories in this list will be added to the - &javac; command line - via the <option>-sourcepath</option> option. - The individual directory names will be - separated by the operating system's path separate character - (<filename>:</filename> on UNIX/Linux/POSIX, - <filename>;</filename> - on Windows). + will be searched for input (source) + <filename>.java</filename> files. + Can be specified as a string or Node object, + or as a list of strings or Node objects. + </para> + <para> + The value will be added to the JDK command lines + via the <option>-sourcepath</option> option, + which requires a system-specific search path separator, + This will be supplied by &SCons; as needed when it + constructs the command line if &cv-JAVASOURCEPATH; is + provided in list form. + If &cv-JAVASOURCEPATH; is a single string containing + search path separator characters + (<literal>:</literal> for POSIX systems or + <literal>;</literal> for Windows), it will not be modified, + and so is inherently system-specific; + to supply the path in a system-independent manner, + give &cv-JAVASOURCEPATH; as a list of paths instead. </para> - <para> - Note that this currently just adds the specified - directory via the <option>-sourcepath</option> option. + Note that the specified directories are only added to + the command line via the <option>-sourcepath</option> option. &SCons; does not currently search the - &cv-JAVASOURCEPATH; directories for dependency + &cv-JAVASOURCEPATH; directories for dependent <filename>.java</filename> files. </para> @@ -4720,11 +4857,11 @@ compilation of object files when calling the Microsoft Visual C/C++ compiler. All compilations of source files from the same source directory that generate target files in a same output directory -and were configured in SCons using the same construction environment +and were configured in SCons using the same &consenv; will be built in a single call to the compiler. Only source files that have changed since their object files were built will be passed to each compiler invocation -(via the &cv-link-CHANGED_SOURCES; construction variable). +(via the &cv-link-CHANGED_SOURCES; &consvar;). Any compilations where the object (target) file base name (minus the <filename>.obj</filename>) does not match the source file base name @@ -4839,6 +4976,8 @@ When &cv-MSVC_NOTFOUND_POLICY; is not specified, the default &scons; behavior is subject to the conditions listed above. The default &scons; behavior may change in the future. </para> +<para><emphasis>New in version 4.4</emphasis></para> + </listitem> </varlistentry> <varlistentry id="cv-MSVC_SCRIPT_ARGS"> @@ -4851,8 +4990,8 @@ Pass user-defined arguments to the Visual C++ batch file determined via autodete <para> &cv-MSVC_SCRIPT_ARGS; is available for msvc batch file arguments that do not have first-class support -via construction variables or when there is an issue with the appropriate construction variable validation. -When available, it is recommended to use the appropriate construction variables (e.g., &cv-link-MSVC_TOOLSET_VERSION;) +via &consvars; or when there is an issue with the appropriate &consvar; validation. +When available, it is recommended to use the appropriate &consvars; (e.g., &cv-link-MSVC_TOOLSET_VERSION;) rather than &cv-MSVC_SCRIPT_ARGS; arguments. </para> @@ -4976,6 +5115,8 @@ and compatible with the version of msvc selected. </itemizedlist> </para> +<para><emphasis>New in version 4.4</emphasis></para> + </listitem> </varlistentry> <varlistentry id="cv-MSVC_SCRIPTERROR_POLICY"> @@ -5028,6 +5169,9 @@ Issue a warning when msvc batch file errors are detected. <para> Suppress msvc batch file error messages. </para> + +<para><emphasis>New in version 4.4</emphasis></para> + </listitem> </varlistentry> @@ -5102,6 +5246,8 @@ when setting the script error policy to raise an exception (e.g., <literal>'Erro </itemizedlist> </para> +<para><emphasis>New in version 4.4</emphasis></para> + </listitem> </varlistentry> <varlistentry id="cv-MSVC_SDK_VERSION"> @@ -5221,6 +5367,8 @@ specify a Windows 10 SDK (e.g., <literal>'10.0.20348.0'</literal>) for the build </itemizedlist> </para> +<para><emphasis>New in version 4.4</emphasis></para> + </listitem> </varlistentry> <varlistentry id="cv-MSVC_SPECTRE_LIBS"> @@ -5302,6 +5450,8 @@ The burden is on the user to ensure the requisite libraries with spectre mitigat </itemizedlist> </para> +<para><emphasis>New in version 4.4</emphasis></para> + </listitem> </varlistentry> <varlistentry id="cv-MSVC_TOOLSET_VERSION"> @@ -5473,6 +5623,8 @@ The burden is on the user to ensure the requisite toolset target architecture bu </itemizedlist> </para> +<para><emphasis>New in version 4.4</emphasis></para> + </listitem> </varlistentry> <varlistentry id="cv-MSVC_USE_SCRIPT"> @@ -5500,7 +5652,7 @@ This can be useful to force the use of a compiler version that Setting &cv-MSVC_USE_SCRIPT; to <constant>None</constant> bypasses the Visual Studio autodetection entirely; -use this if you are running SCons in a Visual Studio <command>cmd</command> +use this if you are running &SCons; in a Visual Studio <command>cmd</command> window and importing the shell's environment variables - that is, if you are sure everything is set correctly already and you don't want &SCons; to change anything. @@ -5508,6 +5660,12 @@ you don't want &SCons; to change anything. <para> &cv-MSVC_USE_SCRIPT; ignores &cv-link-MSVC_VERSION; and &cv-link-TARGET_ARCH;. </para> + +<para><emphasis>Changed in version 4.4:</emphasis> +new &cv-link-MSVC_USE_SCRIPT_ARGS; provides a +way to pass arguments. +</para> + </listitem> </varlistentry> <varlistentry id="cv-MSVC_USE_SCRIPT_ARGS"> @@ -5517,6 +5675,9 @@ you don't want &SCons; to change anything. <listitem><para> Provides arguments passed to the script &cv-link-MSVC_USE_SCRIPT;. </para> + +<para><emphasis>New in version 4.4</emphasis></para> + </listitem> </varlistentry> <varlistentry id="cv-MSVC_USE_SETTINGS"> @@ -5598,11 +5759,15 @@ therefore may change at any time. </emphasis> The burden is on the user to ensure the dictionary contents are minimally sufficient to ensure successful builds. -</para></listitem> +</para> + +</listitem> </itemizedlist> </para> +<para><emphasis>New in version 4.4</emphasis></para> + </listitem> </varlistentry> <varlistentry id="cv-MSVC_UWP_APP"> @@ -5683,12 +5848,10 @@ The burden is on the user to ensure the requisite UWP libraries are installed. </term> <listitem><para> Sets the preferred version of Microsoft Visual C/C++ to use. -</para> - -<para> +If the specified version is unavailable (not installed, +or not discoverable), tool initialization will fail. If &cv-MSVC_VERSION; is not set, SCons will (by default) select the -latest version of Visual C/C++ installed on your system. If the -specified version isn't installed, tool initialization will fail. +latest version of Visual C/C++ installed on your system. </para> <para> @@ -5701,28 +5864,186 @@ loaded into the environment. </para> <para> -Valid values for Windows are -<literal>14.3</literal>, -<literal>14.2</literal>, -<literal>14.1</literal>, -<literal>14.1Exp</literal>, -<literal>14.0</literal>, -<literal>14.0Exp</literal>, -<literal>12.0</literal>, -<literal>12.0Exp</literal>, -<literal>11.0</literal>, -<literal>11.0Exp</literal>, -<literal>10.0</literal>, -<literal>10.0Exp</literal>, -<literal>9.0</literal>, -<literal>9.0Exp</literal>, -<literal>8.0</literal>, -<literal>8.0Exp</literal>, -<literal>7.1</literal>, -<literal>7.0</literal>, -and <literal>6.0</literal>. -Versions ending in <literal>Exp</literal> refer to "Express" or -"Express for Desktop" editions. +The valid values for &cv-MSVC_VERSION; represent major versions +of the compiler, except that versions ending in <literal>Exp</literal> +refer to "Express" or "Express for Desktop" Visual Studio editions, +which require distict entries because they use a different +filesystem layout and have some feature limitations compared to +the full version. +The following table shows correspondence +of the selector string to various version indicators +('x' is used as a placeholder for +a single digit that can vary). +Note that it is not necessary to install Visual Studio +to build with &SCons; (for example, you can install only +Build Tools), but if Visual Studio is installed, +additional builders such as &b-link-MSVSSolution; and +&b-link-MSVSProject; become avaialable and will +correspond to the indicated versions. +</para> + +<informaltable> + <tgroup cols="5"> + <colspec align="left"/> + <colspec align="center"/> + <colspec align="center"/> + <colspec align="left"/> + <colspec align="center"/> + <thead> + <row> + <entry> SCons Key </entry> + <entry> MSVC++ Version </entry> + <entry> <literal>_MSVC_VER</literal> </entry> + <entry> VS Product </entry> + <entry> MSBuild/VS Version </entry> + </row> + </thead> + <tbody> + <row> + <entry> <literal>14.3</literal> </entry> + <entry> 14.3x </entry> + <entry> 193x </entry> + <entry> Visual Studio 2022 </entry> + <entry> 17.x </entry> + </row> + <row> + <entry> <literal>14.2</literal> </entry> + <entry> 14.2x </entry> + <entry> 192x </entry> + <entry> Visual Studio 2019 </entry> + <entry> 16.x, 16.1x </entry> + </row> + <row> + <entry> <literal>14.1</literal> </entry> + <entry> 14.1 or 14.1x </entry> + <entry> 191x </entry> + <entry> Visual Studio 2017 </entry> + <entry> 15.x </entry> + </row> + <row> + <entry> <literal>14.1Exp</literal> </entry> + <entry> 14.1 </entry> + <entry> 1910 </entry> + <entry> Visual Studio 2017 Express </entry> + <entry> 15.0 </entry> + </row> + <row> + <entry> <literal>14.0</literal> </entry> + <entry> 14.0 </entry> + <entry> 1900 </entry> + <entry> Visual Studio 2015 </entry> + <entry> 14.0 </entry> + </row> + <row> + <entry> <literal>14.0Exp</literal> </entry> + <entry> 14.0 </entry> + <entry> 1900 </entry> + <entry> Visual Studio 2015 Express </entry> + <entry> 14.0 </entry> + </row> + <row> + <entry> <literal>12.0</literal> </entry> + <entry> 12.0 </entry> + <entry> 1800 </entry> + <entry> Visual Studio 2013 </entry> + <entry> 12.0 </entry> + </row> + <row> + <entry> <literal>12.0Exp</literal> </entry> + <entry> 12.0 </entry> + <entry> 1800 </entry> + <entry> Visual Studio 2013 Express </entry> + <entry> 12.0 </entry> + </row> + <row> + <entry> <literal>11.0</literal> </entry> + <entry> 11.0 </entry> + <entry> 1700 </entry> + <entry> Visual Studio 2012 </entry> + <entry> 11.0 </entry> + </row> + <row> + <entry> <literal>11.0Exp</literal> </entry> + <entry> 11.0 </entry> + <entry> 1700 </entry> + <entry> Visual Studio 2012 Express </entry> + <entry> 11.0 </entry> + </row> + <row> + <entry> <literal>10.0</literal> </entry> + <entry> 10.0 </entry> + <entry> 1600 </entry> + <entry> Visual Studio 2010 </entry> + <entry> 10.0 </entry> + </row> + <row> + <entry> <literal>10.0Exp</literal> </entry> + <entry> 10.0 </entry> + <entry> 1600 </entry> + <entry> Visual C++ Express 2010 </entry> + <entry> 10.0 </entry> + </row> + <row> + <entry> <literal>9.0</literal> </entry> + <entry> 9.0 </entry> + <entry> 1500 </entry> + <entry> Visual Studio 2008 </entry> + <entry> 9.0 </entry> + </row> + <row> + <entry> <literal>9.0Exp</literal> </entry> + <entry> 9.0 </entry> + <entry> 1500 </entry> + <entry> Visual C++ Express 2008 </entry> + <entry> 9.0 </entry> + </row> + <row> + <entry> <literal>8.0</literal> </entry> + <entry> 8.0 </entry> + <entry> 1400 </entry> + <entry> Visual Studio 2005 </entry> + <entry> 8.0 </entry> + </row> + <row> + <entry> <literal>8.0Exp</literal> </entry> + <entry> 8.0 </entry> + <entry> 1400 </entry> + <entry> Visual C++ Express 2005 </entry> + <entry> 8.0 </entry> + </row> + <row> + <entry> <literal>7.1</literal> </entry> + <entry> 7.1 </entry> + <entry> 1300 </entry> + <entry> Visual Studio .NET 2003 </entry> + <entry> 7.1 </entry> + </row> + <row> + <entry> <literal>7.0</literal> </entry> + <entry> 7.0 </entry> + <entry> 1200 </entry> + <entry> Visual Studio .NET 2002 </entry> + <entry> 7.0 </entry> + </row> + <row> + <entry> <literal>6.0</literal> </entry> + <entry> 6.0 </entry> + <entry> 1100 </entry> + <entry> Visual Studio 6.0 </entry> + <entry> 6.0 </entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +The compilation environment can be further or more precisely specified through the +use of several other &consvars;: see the descriptions of +&cv-link-MSVC_TOOLSET_VERSION;, +&cv-link-MSVC_SDK_VERSION;, +&cv-link-MSVC_USE_SCRIPT;, +&cv-link-MSVC_USE_SCRIPT_ARGS;, +and &cv-link-MSVC_USE_SETTINGS;. </para> </listitem> @@ -5737,28 +6058,39 @@ Versions ending in <literal>Exp</literal> refer to "Express" or </para> <variablelist> <varlistentry> - <term>VERSION</term> <listitem> + <term>VERSION</term> + <listitem> <para>the version of MSVS being used (can be set via - &cv-link-MSVS_VERSION;)</para> + &cv-link-MSVC_VERSION;)</para> </listitem> - </varlistentry> <varlistentry> - <term>VERSIONS</term> <listitem> + </varlistentry> + <varlistentry> + <term>VERSIONS</term> + <listitem> <para>the available versions of MSVS installed</para> </listitem> - </varlistentry> <varlistentry> - <term>VCINSTALLDIR</term> <listitem> + </varlistentry> + <varlistentry> + <term>VCINSTALLDIR</term> + <listitem> <para>installed directory of Visual C++</para> </listitem> - </varlistentry> <varlistentry> - <term>VSINSTALLDIR</term> <listitem> + </varlistentry> + <varlistentry> + <term>VSINSTALLDIR</term> + <listitem> <para>installed directory of Visual Studio</para> </listitem> - </varlistentry> <varlistentry> - <term>FRAMEWORKDIR</term> <listitem> + </varlistentry> + <varlistentry> + <term>FRAMEWORKDIR</term> + <listitem> <para>installed directory of the .NET framework</para> </listitem> - </varlistentry> <varlistentry> - <term>FRAMEWORKVERSIONS</term> <listitem> + </varlistentry> + <varlistentry> + <term>FRAMEWORKVERSIONS</term> + <listitem> <para> list of installed versions of the .NET framework, sorted latest to oldest. @@ -5795,7 +6127,12 @@ Versions ending in <literal>Exp</literal> refer to "Express" or </listitem> </varlistentry> </variablelist> - <para>If a value is not set, it was not available in the registry.</para> + <para>If a value is not set, it was not available in the registry. + Visual Studio 2017 and later do not use the registry for + primary storage of this information, so typically for these + versions only <literal>PROJECTSUFFIX</literal> and + <literal>SOLUTIONSUFFIX</literal> will be set. + </para> </listitem> </varlistentry> <varlistentry id="cv-MSVS_ARCH"> @@ -5821,7 +6158,7 @@ Versions ending in <literal>Exp</literal> refer to "Express" or </term> <listitem><para> The string placed in a generated -Microsoft Visual Studio project file as the value of the +Microsoft Visual C++ project file as the value of the <literal>ProjectGUID</literal> attribute. There is no default value. If not defined, a new GUID is generated. @@ -5835,9 +6172,9 @@ defined, a new GUID is generated. </term> <listitem><para> The path name placed in a generated -Microsoft Visual Studio project file as the value of the +Microsoft Visual C++ project file as the value of the <literal>SccAuxPath</literal> attribute if the - <envar>MSVS_SCC_PROVIDER</envar> construction variable is + <envar>MSVS_SCC_PROVIDER</envar> &consvar; is also set. There is no default value. @@ -5852,7 +6189,7 @@ no default value. The root path of projects in your SCC workspace, i.e the path under which all project and solution files will be generated. It is used as a reference path from which the - relative paths of the generated Microsoft Visual Studio project + relative paths of the generated Microsoft Visual C++ project and solution files are computed. The relative project file path is placed as the value of the <literal>SccLocalPath</literal> attribute of the project file and as the values of the @@ -5865,7 +6202,7 @@ no default value. to the number of projects in the solution) attributes of the <literal>GlobalSection(SourceCodeControl)</literal> section of the Microsoft Visual Studio solution file. This is used only if - the <envar>MSVS_SCC_PROVIDER</envar> construction variable is + the <envar>MSVS_SCC_PROVIDER</envar> &consvar; is also set. The default value is the current working directory. </para> </listitem> @@ -5876,9 +6213,9 @@ no default value. </term> <listitem><para> The project name placed in a generated Microsoft - Visual Studio project file as the value of the + Visual C++ project file as the value of the <literal>SccProjectName</literal> attribute if the - <envar>MSVS_SCC_PROVIDER</envar> construction variable + <envar>MSVS_SCC_PROVIDER</envar> &consvar; is also set. In this case the string is also placed in the <literal>SccProjectName0</literal> attribute of the <literal>GlobalSection(SourceCodeControl)</literal> section @@ -5893,7 +6230,7 @@ no default value. </term> <listitem><para> The string placed in a generated Microsoft - Visual Studio project file as the value of the + Visual C++ project file as the value of the <literal>SccProvider</literal> attribute. The string is also placed in the <literal>SccProvider0</literal> attribute of the <literal>GlobalSection(SourceCodeControl)</literal> @@ -5906,23 +6243,25 @@ no default value. <term> <envar>MSVS_VERSION</envar> </term> - <listitem><para>Sets the preferred version of Microsoft Visual Studio to use.</para> + <listitem><para>Set the preferred version of Microsoft Visual Studio to use.</para> <para> If &cv-MSVS_VERSION; is not set, &SCons; will (by default) select the latest version of Visual Studio installed on your system. So, if you have version 6 and version 7 (MSVS .NET) installed, it will prefer version 7. You can override this by - specifying the <envar>MSVS_VERSION</envar> variable in the - Environment initialization, setting it to the appropriate + specifying the &cv-link-MSVS_VERSION; variable when + initializing the Environment, setting it to the appropriate version ('6.0' or '7.0', for example). If the specified version isn't installed, tool initialization will fail. </para> <para> - This is obsolete: use &cv-MSVC_VERSION; instead. If - &cv-MSVS_VERSION; is set and &cv-MSVC_VERSION; is - not, &cv-MSVC_VERSION; will be set automatically to - &cv-MSVS_VERSION;. If both are set to different values, - scons will raise an error. + <emphasis>Deprecated since 1.3.0:</emphasis> + &cv-MSVS_VERSION; is deprecated in favor of &cv-link-MSVC_VERSION;. + As a transitional aid, if &cv-MSVS_VERSION; is set + and &cv-MSVC_VERSION; is not, + &cv-MSVC_VERSION; will be initialized to the value + of &cv-MSVS_VERSION;. + An error is raised if If both are set and have different values, </para> </listitem> </varlistentry> @@ -5932,8 +6271,8 @@ no default value. </term> <listitem><para> The build command line placed in a generated Microsoft Visual - Studio project file. The default is to have Visual Studio - invoke SCons with any specified build targets. + C++ project file. The default is to have Visual Studio + invoke &SCons; with any specified build targets. </para> </listitem> </varlistentry> @@ -5943,9 +6282,9 @@ no default value. </term> <listitem><para> The clean command line placed in a generated Microsoft Visual - Studio project file. The default is to have Visual Studio - invoke SCons with the -c option to remove any specified - targets. + C++ project file. The default is to have Visual Studio + invoke &SCons; with the <option>-c</option> option to remove + any specified targets. </para> </listitem> </varlistentry> @@ -5955,7 +6294,7 @@ no default value. </term> <listitem><para> The encoding string placed in a generated Microsoft - Visual Studio project file. The default is encoding + Visual C++ project file. The default is encoding <literal>Windows-1252</literal>. </para> </listitem> @@ -5964,7 +6303,7 @@ no default value. <term> <envar>MSVSPROJECTCOM</envar> </term> - <listitem><para>The action used to generate Microsoft Visual Studio project files.</para> + <listitem><para>The action used to generate Microsoft Visual C++ project files.</para> </listitem> </varlistentry> <varlistentry id="cv-MSVSPROJECTSUFFIX"> @@ -5972,11 +6311,12 @@ no default value. <envar>MSVSPROJECTSUFFIX</envar> </term> <listitem><para> - The suffix used for Microsoft Visual Studio project (DSP) - files. The default value is <filename>.vcproj</filename> - when using Visual Studio version 7.x (.NET) or later version, - and <filename>.dsp</filename> when using earlier versions of - Visual Studio. + The suffix used for Microsoft Visual C++ project (DSP) + files. The default value is + <filename>.vcxproj</filename> when using Visual Studio 2010 + and later, <filename>.vcproj</filename> + when using Visual Studio versions between 2002 and 2008, + and <filename>.dsp</filename> when using Visual Studio 6.0. </para> </listitem> </varlistentry> @@ -5986,8 +6326,8 @@ no default value. </term> <listitem><para> The rebuild command line placed in a generated Microsoft - Visual Studio project file. The default is to have Visual - Studio invoke SCons with any specified rebuild targets. + Visual C++ project file. The default is to have Visual + Studio invoke &SCons; with any specified rebuild targets. </para> </listitem> @@ -5997,8 +6337,8 @@ no default value. <envar>MSVSSCONS</envar> </term> <listitem><para> - The SCons used in generated Microsoft Visual Studio project - files. The default is the version of SCons being used to + The &SCons; used in generated Microsoft Visual C++ project + files. The default is the version of &SCons; being used to generate the project file. </para> </listitem> @@ -6008,8 +6348,8 @@ no default value. <envar>MSVSSCONSCOM</envar> </term> <listitem><para> - The default SCons command used in generated Microsoft Visual - Studio project files. + The default &SCons; command used in generated Microsoft Visual + C++ project files. </para> </listitem> </varlistentry> @@ -6019,10 +6359,10 @@ no default value. </term> <listitem><para> The sconscript file (that is, &SConstruct; or &SConscript; - file) that will be invoked by Visual Studio project files + file) that will be invoked by Visual C++ project files (through the &cv-link-MSVSSCONSCOM; variable). The default is the same sconscript file that contains the call to - &b-MSVSProject; to build the project file. + &b-link-MSVSProject; to build the project file. </para> </listitem> </varlistentry> @@ -6031,7 +6371,7 @@ no default value. <envar>MSVSSCONSFLAGS</envar> </term> <listitem><para> - The SCons flags used in generated Microsoft Visual Studio project files. + The &SCons; flags used in generated Microsoft Visual C++ project files. </para> </listitem> </varlistentry> @@ -6049,9 +6389,8 @@ no default value. <listitem><para> The suffix used for Microsoft Visual Studio solution (DSW) files. The default value is <filename>.sln</filename> - when using Visual Studio version 7.x (.NET), and - <filename>.dsw</filename> when using earlier versions of - Visual Studio. + when using Visual Studio version 7.x (.NET 2002) and later, + and <filename>.dsw</filename> when using Visual Studio 6.0. </para> </listitem> </varlistentry> @@ -6475,9 +6814,9 @@ If this is not set, then &cv-link-PCHCOM; (the command line) is displayed. <envar>PCHPDBFLAGS</envar> </term> <listitem><para> -A construction variable that, when expanded, +A &consvar; that, when expanded, adds the <option>/yD</option> flag to the command line -only if the &cv-link-PDB; construction variable is set. +only if the &cv-link-PDB; &consvar; is set. </para> </listitem> </varlistentry> @@ -6909,51 +7248,63 @@ The prefix used for PostScript file names. </para> </listitem> </varlistentry> - <varlistentry id="cv-QT_AUTOSCAN"> + <varlistentry id="cv-QT3_AUTOSCAN"> <term> - <envar>QT_AUTOSCAN</envar> + <envar>QT3_AUTOSCAN</envar> </term> <listitem><para> Turn off scanning for mocable files. Use the &b-link-Moc; Builder to explicitly specify files to run <command>moc</command> on. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_AUTOSCAN. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_BINPATH"> + <varlistentry id="cv-QT3_BINPATH"> <term> - <envar>QT_BINPATH</envar> + <envar>QT3_BINPATH</envar> </term> <listitem><para> The path where the Qt binaries are installed. -The default value is '&cv-link-QTDIR;<filename>/bin</filename>'. +The default value is '&cv-link-QT3DIR;<filename>/bin</filename>'. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_BINPATH. </para> </listitem> </varlistentry> - <varlistentry id="cv-QT_CPPPATH"> + <varlistentry id="cv-QT3_CPPPATH"> <term> - <envar>QT_CPPPATH</envar> + <envar>QT3_CPPPATH</envar> </term> <listitem><para> The path where the Qt header files are installed. -The default value is '&cv-link-QTDIR;/include'. +The default value is '&cv-link-QT3DIR;/include'. Note: If you set this variable to <constant>None</constant>, the tool won't change the &cv-link-CPPPATH; construction variable. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_CPPPATH. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_DEBUG"> + <varlistentry id="cv-QT3_DEBUG"> <term> - <envar>QT_DEBUG</envar> + <envar>QT3_DEBUG</envar> </term> <listitem><para> Prints lots of debugging information while scanning for moc files. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_DEBUG. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_LIB"> + <varlistentry id="cv-QT3_LIB"> <term> - <envar>QT_LIB</envar> + <envar>QT3_LIB</envar> </term> <listitem><para> Default value is <literal>'qt'</literal>. @@ -6961,33 +7312,39 @@ You may want to set this to <literal>'qt-mt'</literal>. Note: If you set this variable to <constant>None</constant>, the tool won't change the &cv-link-LIBS; variable. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_LIB. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_LIBPATH"> + <varlistentry id="cv-QT3_LIBPATH"> <term> - <envar>QT_LIBPATH</envar> + <envar>QT3_LIBPATH</envar> </term> <listitem><para> The path where the Qt libraries are installed. -The default value is '&cv-link-QTDIR;<filename>/lib</filename>'. +The default value is '&cv-link-QT3DIR;<filename>/lib</filename>'. Note: If you set this variable to <constant>None</constant>, the tool won't change the &cv-link-LIBPATH; construction variable. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_LIBPATH. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOC"> + <varlistentry id="cv-QT3_MOC"> <term> - <envar>QT_MOC</envar> + <envar>QT3_MOC</envar> </term> <listitem><para> -Default value is '&cv-link-QT_BINPATH;<filename>/moc</filename>'. +Default value is '&cv-link-QT3_BINPATH;<filename>/moc</filename>'. </para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCCXXPREFIX"> + <varlistentry id="cv-QT3_MOCCXXPREFIX"> <term> - <envar>QT_MOCCXXPREFIX</envar> + <envar>QT3_MOCCXXPREFIX</envar> </term> <listitem><para> Default value is <literal>''</literal>. @@ -6995,204 +7352,264 @@ Prefix for <command>moc</command> output files when source is a C++ file. </para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCCXXSUFFIX"> + <varlistentry id="cv-QT3_MOCCXXSUFFIX"> <term> - <envar>QT_MOCCXXSUFFIX</envar> + <envar>QT3_MOCCXXSUFFIX</envar> </term> <listitem><para> Default value is <literal>'.moc'</literal>. Suffix for <command>moc</command> output files when source is a C++ file. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCCXXSUFFIX. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCFROMCXXCOM"> + <varlistentry id="cv-QT3_MOCFROMCXXCOM"> <term> - <envar>QT_MOCFROMCXXCOM</envar> + <envar>QT3_MOCFROMCXXCOM</envar> </term> <listitem><para> Command to generate a moc file from a C++ file. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXCOM. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCFROMCXXCOMSTR"> + <varlistentry id="cv-QT3_MOCFROMCXXCOMSTR"> <term> - <envar>QT_MOCFROMCXXCOMSTR</envar> + <envar>QT3_MOCFROMCXXCOMSTR</envar> </term> <listitem><para> The string displayed when generating a moc file from a C++ file. -If this is not set, then &cv-link-QT_MOCFROMCXXCOM; (the command line) is displayed. +If this is not set, then &cv-link-QT3_MOCFROMCXXCOM; (the command line) is displayed. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXCOMSTR. </para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCFROMCXXFLAGS"> + <varlistentry id="cv-QT3_MOCFROMCXXFLAGS"> <term> - <envar>QT_MOCFROMCXXFLAGS</envar> + <envar>QT3_MOCFROMCXXFLAGS</envar> </term> <listitem><para> Default value is <literal>'-i'</literal>. These flags are passed to <command>moc</command> when moccing a C++ file. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMCXXFLAGS. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCFROMHCOM"> + <varlistentry id="cv-QT3_MOCFROMHCOM"> <term> - <envar>QT_MOCFROMHCOM</envar> + <envar>QT3_MOCFROMHCOM</envar> </term> <listitem><para> Command to generate a moc file from a header. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHCOM. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCFROMHCOMSTR"> + <varlistentry id="cv-QT3_MOCFROMHCOMSTR"> <term> - <envar>QT_MOCFROMHCOMSTR</envar> + <envar>QT3_MOCFROMHCOMSTR</envar> </term> <listitem><para> The string displayed when generating a moc file from a C++ file. -If this is not set, then &cv-link-QT_MOCFROMHCOM; (the command line) is displayed. +If this is not set, then &cv-link-QT3_MOCFROMHCOM; (the command line) is displayed. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHCOMSTR. </para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCFROMHFLAGS"> + <varlistentry id="cv-QT3_MOCFROMHFLAGS"> <term> - <envar>QT_MOCFROMHFLAGS</envar> + <envar>QT3_MOCFROMHFLAGS</envar> </term> <listitem><para> Default value is <literal>''</literal>. These flags are passed to <command>moc</command> when moccing a header file. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCFROMSHFLAGS. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCHPREFIX"> + <varlistentry id="cv-QT3_MOCHPREFIX"> <term> - <envar>QT_MOCHPREFIX</envar> + <envar>QT3_MOCHPREFIX</envar> </term> <listitem><para> Default value is <literal>'moc_'</literal>. Prefix for <command>moc</command> output files when source is a header. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCHPREFIX. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_MOCHSUFFIX"> + <varlistentry id="cv-QT3_MOCHSUFFIX"> <term> - <envar>QT_MOCHSUFFIX</envar> + <envar>QT3_MOCHSUFFIX</envar> </term> <listitem><para> Default value is '&cv-link-CXXFILESUFFIX;'. Suffix for moc output files when source is a header. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_MOCHSUFFIX. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UIC"> + <varlistentry id="cv-QT3_UIC"> <term> - <envar>QT_UIC</envar> + <envar>QT3_UIC</envar> </term> <listitem><para> -Default value is '&cv-link-QT_BINPATH;<filename>/uic</filename>'. +Default value is '&cv-link-QT3_BINPATH;<filename>/uic</filename>'. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UIC. </para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UICCOM"> + <varlistentry id="cv-QT3_UICCOM"> <term> - <envar>QT_UICCOM</envar> + <envar>QT3_UICCOM</envar> </term> <listitem><para> Command to generate header files from <filename>.ui</filename> files. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICCOM. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UICCOMSTR"> + <varlistentry id="cv-QT3_UICCOMSTR"> <term> - <envar>QT_UICCOMSTR</envar> + <envar>QT3_UICCOMSTR</envar> </term> <listitem><para> The string displayed when generating header files from <filename>.ui</filename> files. -If this is not set, then &cv-link-QT_UICCOM; (the command line) is displayed. +If this is not set, then &cv-link-QT3_UICCOM; (the command line) is displayed. +</para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICCOMSTR. </para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UICDECLFLAGS"> + <varlistentry id="cv-QT3_UICDECLFLAGS"> <term> - <envar>QT_UICDECLFLAGS</envar> + <envar>QT3_UICDECLFLAGS</envar> </term> <listitem><para> Default value is ''. These flags are passed to <command>uic</command> when creating a header file from a <filename>.ui</filename> file. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLFLAGS. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UICDECLPREFIX"> + <varlistentry id="cv-QT3_UICDECLPREFIX"> <term> - <envar>QT_UICDECLPREFIX</envar> + <envar>QT3_UICDECLPREFIX</envar> </term> <listitem><para> Default value is <literal>''</literal>. Prefix for <command>uic</command> generated header files. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLPREFIX. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UICDECLSUFFIX"> + <varlistentry id="cv-QT3_UICDECLSUFFIX"> <term> - <envar>QT_UICDECLSUFFIX</envar> + <envar>QT3_UICDECLSUFFIX</envar> </term> <listitem><para> Default value is <literal>'.h'</literal>. Suffix for <command>uic</command> generated header files. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICDECLSUFFIX. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UICIMPLFLAGS"> + <varlistentry id="cv-QT3_UICIMPLFLAGS"> <term> - <envar>QT_UICIMPLFLAGS</envar> + <envar>QT3_UICIMPLFLAGS</envar> </term> <listitem><para> Default value is <literal>''</literal>. These flags are passed to <command>uic</command> when creating a C++ file from a <filename>.ui</filename> file. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPFLAGS. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UICIMPLPREFIX"> + <varlistentry id="cv-QT3_UICIMPLPREFIX"> <term> - <envar>QT_UICIMPLPREFIX</envar> + <envar>QT3_UICIMPLPREFIX</envar> </term> <listitem><para> Default value is <literal>'uic_'</literal>. Prefix for uic generated implementation files. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPLPREFIX. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UICIMPLSUFFIX"> + <varlistentry id="cv-QT3_UICIMPLSUFFIX"> <term> - <envar>QT_UICIMPLSUFFIX</envar> + <envar>QT3_UICIMPLSUFFIX</envar> </term> <listitem><para> Default value is '&cv-link-CXXFILESUFFIX;'. Suffix for uic generated implementation files. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UICIMPLSUFFIX. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QT_UISUFFIX"> + <varlistentry id="cv-QT3_UISUFFIX"> <term> - <envar>QT_UISUFFIX</envar> + <envar>QT3_UISUFFIX</envar> </term> <listitem><para> Default value is <literal>'.ui'</literal>. Suffix of designer input files. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QT_UISUFFIX. +</para> </listitem> </varlistentry> - <varlistentry id="cv-QTDIR"> + <varlistentry id="cv-QT3DIR"> <term> - <envar>QTDIR</envar> + <envar>QT3DIR</envar> </term> <listitem><para> The path to the Qt installation to build against. If not already set, -&t-link-qt; tool tries to obtain this from +&t-link-qt3; tool tries to obtain this from <varname>os.environ</varname>; if not found there, it tries to make a guess. </para> +<para> +<emphasis>Changed in 4.5.0</emphasis>: renamed from QTDIR. +</para> </listitem> </varlistentry> <varlistentry id="cv-RANLIB"> @@ -7281,7 +7698,7 @@ The flags passed to the resource compiler by the &b-link-RES; builder. <envar>RCINCFLAGS</envar> </term> <listitem><para> -An automatically-generated construction variable +An automatically-generated &consvar; containing the command-line options for specifying directories to be searched by the resource compiler. @@ -7301,7 +7718,7 @@ of each directory in &cv-link-CPPPATH;. The prefix (flag) used to specify an include directory on the resource compiler command line. This will be prepended to the beginning of each directory -in the &cv-link-CPPPATH; construction variable +in the &cv-link-CPPPATH; &consvar; when the &cv-link-RCINCFLAGS; variable is expanded. </para> </listitem> @@ -7314,7 +7731,7 @@ when the &cv-link-RCINCFLAGS; variable is expanded. The suffix used to specify an include directory on the resource compiler command line. This will be appended to the end of each directory -in the &cv-link-CPPPATH; construction variable +in the &cv-link-CPPPATH; &consvar; when the &cv-link-RCINCFLAGS; variable is expanded. </para> </listitem> @@ -7411,7 +7828,9 @@ If this is not set, then &cv-link-RMICCOM; (the command line) is displayed. </para> <example_commands> -env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES") +env = Environment( + RMICCOMSTR="Generating stub/skeleton class files $TARGETS from $SOURCES" +) </example_commands> </listitem> </varlistentry> @@ -7574,11 +7993,11 @@ for more information. <envar>SCONS_HOME</envar> </term> <listitem><para> - The (optional) path to the SCons library directory, + The (optional) path to the &SCons; library directory, initialized from the external environment. If set, this is used to construct a shorter and more efficient search path in the &cv-link-MSVSSCONS; command line executed from Microsoft - Visual Studio project files. + Visual C++ project files. </para> </listitem> </varlistentry> @@ -7790,21 +8209,39 @@ construction variable for more information. <envar>SHELL_ENV_GENERATORS</envar> </term> <listitem><para> -Must be a list (or an iterable) containing functions where each function generates or -alters the environment dictionary which will be used -when executing the &cv-link-SPAWN; function. The functions will initially -be passed a reference of the current execution environment (e.g. env['ENV']), -and each called while iterating the list. Each function must return a dictionary -which will then be passed to the next function iterated. The return dictionary -should contain keys which represent the environment variables and their respective -values. +A hook allowing the execution environment to be modified prior +to the actual execution of a command line from an action +via the spawner function defined by &cv-link-SPAWN;. +Allows substitution based on targets and sources, +as well as values from the &consenv;, +adding extra environment variables, etc. + </para> -This primary purpose of this construction variable is to give the user the ability -to substitute execution environment variables based on env, targets, and sources. -If desired, the user can completely customize the execution environment for particular -targets. + <para> +The value must be a list (or other iterable) +of functions which each generate or +alter the execution environment dictionary. +The first function will be passed a copy of the initial execution environment +(&cv-link-ENV; in the current &consenv;); +the dictionary returned by that function is passed to the next, +until the iterable is exhausted and the result returned +for use by the command spawner. +The original execution environment is not modified. </para> + <para> +Each function provided in &cv-SHELL_ENV_GENERATORS; must accept four +arguments and return a dictionary: +<varname>env</varname> is the &consenv; for this action; +<varname>target</varname> is the list of targets associated with this action; +<varname>source</varname> is the list of sources associated with this action; +and <varname>shell_env</varname> is the current dictionary after iterating +any previous &cv-SHELL_ENV_GENERATORS; functions +(this can be compared to the original execution environment, +which is available as <literal>env['ENV']</literal>, to detect any changes). + </para> + + <para>Example:</para> <example_commands> def custom_shell_env(env, target, source, shell_env): """customize shell_env if desired""" @@ -7815,24 +8252,7 @@ def custom_shell_env(env, target, source, shell_env): env["SHELL_ENV_GENERATORS"] = [custom_shell_env] </example_commands> - <para> - <varname>env</varname> -The SCons construction environment from which the -execution environment can be derived from. - </para> - <para> - <varname>target</varname> -The list of targets associated with this action. - </para> - <para> - <varname>source</varname> -The list of sources associated with this action. - </para> - <para> - <varname>shell_env</varname> -The current shell_env after iterating other SHELL_ENV_GENERATORS functions. This can be compared -to the passed env['ENV'] to detect any changes. - </para> + <para><emphasis>Available since 4.4</emphasis></para> </listitem> </varlistentry> <varlistentry id="cv-SHF03"> diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod index ceb58acaf..c10e52033 100644 --- a/doc/generated/variables.mod +++ b/doc/generated/variables.mod @@ -184,6 +184,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY cv-F95PPCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$F95PPCOMSTR</envar>"> <!ENTITY cv-F95PPFILESUFFIXES "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$F95PPFILESUFFIXES</envar>"> <!ENTITY cv-File "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$File</envar>"> +<!ENTITY cv-FILE_ENCODING "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FILE_ENCODING</envar>"> <!ENTITY cv-FORTRAN "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FORTRAN</envar>"> <!ENTITY cv-FORTRANCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FORTRANCOM</envar>"> <!ENTITY cv-FORTRANCOMMONFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$FORTRANCOMMONFLAGS</envar>"> @@ -245,6 +246,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY cv-JAVAHCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$JAVAHCOMSTR</envar>"> <!ENTITY cv-JAVAHFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$JAVAHFLAGS</envar>"> <!ENTITY cv-JAVAINCLUDES "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$JAVAINCLUDES</envar>"> +<!ENTITY cv-JAVAPROCESSORPATH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$JAVAPROCESSORPATH</envar>"> <!ENTITY cv-JAVASOURCEPATH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$JAVASOURCEPATH</envar>"> <!ENTITY cv-JAVASUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$JAVASUFFIX</envar>"> <!ENTITY cv-JAVAVERSION "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$JAVAVERSION</envar>"> @@ -419,34 +421,34 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY cv-PSCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$PSCOMSTR</envar>"> <!ENTITY cv-PSPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$PSPREFIX</envar>"> <!ENTITY cv-PSSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$PSSUFFIX</envar>"> -<!ENTITY cv-QT_AUTOSCAN "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_AUTOSCAN</envar>"> -<!ENTITY cv-QT_BINPATH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_BINPATH</envar>"> -<!ENTITY cv-QT_CPPPATH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_CPPPATH</envar>"> -<!ENTITY cv-QT_DEBUG "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_DEBUG</envar>"> -<!ENTITY cv-QT_LIB "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_LIB</envar>"> -<!ENTITY cv-QT_LIBPATH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_LIBPATH</envar>"> -<!ENTITY cv-QT_MOC "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOC</envar>"> -<!ENTITY cv-QT_MOCCXXPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCCXXPREFIX</envar>"> -<!ENTITY cv-QT_MOCCXXSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCCXXSUFFIX</envar>"> -<!ENTITY cv-QT_MOCFROMCXXCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCFROMCXXCOM</envar>"> -<!ENTITY cv-QT_MOCFROMCXXCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCFROMCXXCOMSTR</envar>"> -<!ENTITY cv-QT_MOCFROMCXXFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCFROMCXXFLAGS</envar>"> -<!ENTITY cv-QT_MOCFROMHCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCFROMHCOM</envar>"> -<!ENTITY cv-QT_MOCFROMHCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCFROMHCOMSTR</envar>"> -<!ENTITY cv-QT_MOCFROMHFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCFROMHFLAGS</envar>"> -<!ENTITY cv-QT_MOCHPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCHPREFIX</envar>"> -<!ENTITY cv-QT_MOCHSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_MOCHSUFFIX</envar>"> -<!ENTITY cv-QT_UIC "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UIC</envar>"> -<!ENTITY cv-QT_UICCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UICCOM</envar>"> -<!ENTITY cv-QT_UICCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UICCOMSTR</envar>"> -<!ENTITY cv-QT_UICDECLFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UICDECLFLAGS</envar>"> -<!ENTITY cv-QT_UICDECLPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UICDECLPREFIX</envar>"> -<!ENTITY cv-QT_UICDECLSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UICDECLSUFFIX</envar>"> -<!ENTITY cv-QT_UICIMPLFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UICIMPLFLAGS</envar>"> -<!ENTITY cv-QT_UICIMPLPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UICIMPLPREFIX</envar>"> -<!ENTITY cv-QT_UICIMPLSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UICIMPLSUFFIX</envar>"> -<!ENTITY cv-QT_UISUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT_UISUFFIX</envar>"> -<!ENTITY cv-QTDIR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QTDIR</envar>"> +<!ENTITY cv-QT3_AUTOSCAN "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_AUTOSCAN</envar>"> +<!ENTITY cv-QT3_BINPATH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_BINPATH</envar>"> +<!ENTITY cv-QT3_CPPPATH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_CPPPATH</envar>"> +<!ENTITY cv-QT3_DEBUG "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_DEBUG</envar>"> +<!ENTITY cv-QT3_LIB "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_LIB</envar>"> +<!ENTITY cv-QT3_LIBPATH "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_LIBPATH</envar>"> +<!ENTITY cv-QT3_MOC "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOC</envar>"> +<!ENTITY cv-QT3_MOCCXXPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCCXXPREFIX</envar>"> +<!ENTITY cv-QT3_MOCCXXSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCCXXSUFFIX</envar>"> +<!ENTITY cv-QT3_MOCFROMCXXCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCFROMCXXCOM</envar>"> +<!ENTITY cv-QT3_MOCFROMCXXCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCFROMCXXCOMSTR</envar>"> +<!ENTITY cv-QT3_MOCFROMCXXFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCFROMCXXFLAGS</envar>"> +<!ENTITY cv-QT3_MOCFROMHCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCFROMHCOM</envar>"> +<!ENTITY cv-QT3_MOCFROMHCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCFROMHCOMSTR</envar>"> +<!ENTITY cv-QT3_MOCFROMHFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCFROMHFLAGS</envar>"> +<!ENTITY cv-QT3_MOCHPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCHPREFIX</envar>"> +<!ENTITY cv-QT3_MOCHSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_MOCHSUFFIX</envar>"> +<!ENTITY cv-QT3_UIC "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UIC</envar>"> +<!ENTITY cv-QT3_UICCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UICCOM</envar>"> +<!ENTITY cv-QT3_UICCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UICCOMSTR</envar>"> +<!ENTITY cv-QT3_UICDECLFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UICDECLFLAGS</envar>"> +<!ENTITY cv-QT3_UICDECLPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UICDECLPREFIX</envar>"> +<!ENTITY cv-QT3_UICDECLSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UICDECLSUFFIX</envar>"> +<!ENTITY cv-QT3_UICIMPLFLAGS "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UICIMPLFLAGS</envar>"> +<!ENTITY cv-QT3_UICIMPLPREFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UICIMPLPREFIX</envar>"> +<!ENTITY cv-QT3_UICIMPLSUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UICIMPLSUFFIX</envar>"> +<!ENTITY cv-QT3_UISUFFIX "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3_UISUFFIX</envar>"> +<!ENTITY cv-QT3DIR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$QT3DIR</envar>"> <!ENTITY cv-RANLIB "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$RANLIB</envar>"> <!ENTITY cv-RANLIBCOM "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$RANLIBCOM</envar>"> <!ENTITY cv-RANLIBCOMSTR "<envar xmlns='http://www.scons.org/dbxsd/v1.0'>$RANLIBCOMSTR</envar>"> @@ -858,6 +860,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY cv-link-F95PPCOMSTR "<link linkend='cv-F95PPCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$F95PPCOMSTR</envar></link>"> <!ENTITY cv-link-F95PPFILESUFFIXES "<link linkend='cv-F95PPFILESUFFIXES' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$F95PPFILESUFFIXES</envar></link>"> <!ENTITY cv-link-File "<link linkend='cv-File' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$File</envar></link>"> +<!ENTITY cv-link-FILE_ENCODING "<link linkend='cv-FILE_ENCODING' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FILE_ENCODING</envar></link>"> <!ENTITY cv-link-FORTRAN "<link linkend='cv-FORTRAN' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FORTRAN</envar></link>"> <!ENTITY cv-link-FORTRANCOM "<link linkend='cv-FORTRANCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FORTRANCOM</envar></link>"> <!ENTITY cv-link-FORTRANCOMMONFLAGS "<link linkend='cv-FORTRANCOMMONFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$FORTRANCOMMONFLAGS</envar></link>"> @@ -919,6 +922,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY cv-link-JAVAHCOMSTR "<link linkend='cv-JAVAHCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$JAVAHCOMSTR</envar></link>"> <!ENTITY cv-link-JAVAHFLAGS "<link linkend='cv-JAVAHFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$JAVAHFLAGS</envar></link>"> <!ENTITY cv-link-JAVAINCLUDES "<link linkend='cv-JAVAINCLUDES' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$JAVAINCLUDES</envar></link>"> +<!ENTITY cv-link-JAVAPROCESSORPATH "<link linkend='cv-JAVAPROCESSORPATH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$JAVAPROCESSORPATH</envar></link>"> <!ENTITY cv-link-JAVASOURCEPATH "<link linkend='cv-JAVASOURCEPATH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$JAVASOURCEPATH</envar></link>"> <!ENTITY cv-link-JAVASUFFIX "<link linkend='cv-JAVASUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$JAVASUFFIX</envar></link>"> <!ENTITY cv-link-JAVAVERSION "<link linkend='cv-JAVAVERSION' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$JAVAVERSION</envar></link>"> @@ -1093,34 +1097,34 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. <!ENTITY cv-link-PSCOMSTR "<link linkend='cv-PSCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$PSCOMSTR</envar></link>"> <!ENTITY cv-link-PSPREFIX "<link linkend='cv-PSPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$PSPREFIX</envar></link>"> <!ENTITY cv-link-PSSUFFIX "<link linkend='cv-PSSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$PSSUFFIX</envar></link>"> -<!ENTITY cv-link-QT_AUTOSCAN "<link linkend='cv-QT_AUTOSCAN' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_AUTOSCAN</envar></link>"> -<!ENTITY cv-link-QT_BINPATH "<link linkend='cv-QT_BINPATH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_BINPATH</envar></link>"> -<!ENTITY cv-link-QT_CPPPATH "<link linkend='cv-QT_CPPPATH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_CPPPATH</envar></link>"> -<!ENTITY cv-link-QT_DEBUG "<link linkend='cv-QT_DEBUG' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_DEBUG</envar></link>"> -<!ENTITY cv-link-QT_LIB "<link linkend='cv-QT_LIB' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_LIB</envar></link>"> -<!ENTITY cv-link-QT_LIBPATH "<link linkend='cv-QT_LIBPATH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_LIBPATH</envar></link>"> -<!ENTITY cv-link-QT_MOC "<link linkend='cv-QT_MOC' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOC</envar></link>"> -<!ENTITY cv-link-QT_MOCCXXPREFIX "<link linkend='cv-QT_MOCCXXPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCCXXPREFIX</envar></link>"> -<!ENTITY cv-link-QT_MOCCXXSUFFIX "<link linkend='cv-QT_MOCCXXSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCCXXSUFFIX</envar></link>"> -<!ENTITY cv-link-QT_MOCFROMCXXCOM "<link linkend='cv-QT_MOCFROMCXXCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCFROMCXXCOM</envar></link>"> -<!ENTITY cv-link-QT_MOCFROMCXXCOMSTR "<link linkend='cv-QT_MOCFROMCXXCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCFROMCXXCOMSTR</envar></link>"> -<!ENTITY cv-link-QT_MOCFROMCXXFLAGS "<link linkend='cv-QT_MOCFROMCXXFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCFROMCXXFLAGS</envar></link>"> -<!ENTITY cv-link-QT_MOCFROMHCOM "<link linkend='cv-QT_MOCFROMHCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCFROMHCOM</envar></link>"> -<!ENTITY cv-link-QT_MOCFROMHCOMSTR "<link linkend='cv-QT_MOCFROMHCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCFROMHCOMSTR</envar></link>"> -<!ENTITY cv-link-QT_MOCFROMHFLAGS "<link linkend='cv-QT_MOCFROMHFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCFROMHFLAGS</envar></link>"> -<!ENTITY cv-link-QT_MOCHPREFIX "<link linkend='cv-QT_MOCHPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCHPREFIX</envar></link>"> -<!ENTITY cv-link-QT_MOCHSUFFIX "<link linkend='cv-QT_MOCHSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_MOCHSUFFIX</envar></link>"> -<!ENTITY cv-link-QT_UIC "<link linkend='cv-QT_UIC' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UIC</envar></link>"> -<!ENTITY cv-link-QT_UICCOM "<link linkend='cv-QT_UICCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UICCOM</envar></link>"> -<!ENTITY cv-link-QT_UICCOMSTR "<link linkend='cv-QT_UICCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UICCOMSTR</envar></link>"> -<!ENTITY cv-link-QT_UICDECLFLAGS "<link linkend='cv-QT_UICDECLFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UICDECLFLAGS</envar></link>"> -<!ENTITY cv-link-QT_UICDECLPREFIX "<link linkend='cv-QT_UICDECLPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UICDECLPREFIX</envar></link>"> -<!ENTITY cv-link-QT_UICDECLSUFFIX "<link linkend='cv-QT_UICDECLSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UICDECLSUFFIX</envar></link>"> -<!ENTITY cv-link-QT_UICIMPLFLAGS "<link linkend='cv-QT_UICIMPLFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UICIMPLFLAGS</envar></link>"> -<!ENTITY cv-link-QT_UICIMPLPREFIX "<link linkend='cv-QT_UICIMPLPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UICIMPLPREFIX</envar></link>"> -<!ENTITY cv-link-QT_UICIMPLSUFFIX "<link linkend='cv-QT_UICIMPLSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UICIMPLSUFFIX</envar></link>"> -<!ENTITY cv-link-QT_UISUFFIX "<link linkend='cv-QT_UISUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT_UISUFFIX</envar></link>"> -<!ENTITY cv-link-QTDIR "<link linkend='cv-QTDIR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QTDIR</envar></link>"> +<!ENTITY cv-link-QT3_AUTOSCAN "<link linkend='cv-QT3_AUTOSCAN' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_AUTOSCAN</envar></link>"> +<!ENTITY cv-link-QT3_BINPATH "<link linkend='cv-QT3_BINPATH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_BINPATH</envar></link>"> +<!ENTITY cv-link-QT3_CPPPATH "<link linkend='cv-QT3_CPPPATH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_CPPPATH</envar></link>"> +<!ENTITY cv-link-QT3_DEBUG "<link linkend='cv-QT3_DEBUG' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_DEBUG</envar></link>"> +<!ENTITY cv-link-QT3_LIB "<link linkend='cv-QT3_LIB' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_LIB</envar></link>"> +<!ENTITY cv-link-QT3_LIBPATH "<link linkend='cv-QT3_LIBPATH' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_LIBPATH</envar></link>"> +<!ENTITY cv-link-QT3_MOC "<link linkend='cv-QT3_MOC' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOC</envar></link>"> +<!ENTITY cv-link-QT3_MOCCXXPREFIX "<link linkend='cv-QT3_MOCCXXPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCCXXPREFIX</envar></link>"> +<!ENTITY cv-link-QT3_MOCCXXSUFFIX "<link linkend='cv-QT3_MOCCXXSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCCXXSUFFIX</envar></link>"> +<!ENTITY cv-link-QT3_MOCFROMCXXCOM "<link linkend='cv-QT3_MOCFROMCXXCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCFROMCXXCOM</envar></link>"> +<!ENTITY cv-link-QT3_MOCFROMCXXCOMSTR "<link linkend='cv-QT3_MOCFROMCXXCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCFROMCXXCOMSTR</envar></link>"> +<!ENTITY cv-link-QT3_MOCFROMCXXFLAGS "<link linkend='cv-QT3_MOCFROMCXXFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCFROMCXXFLAGS</envar></link>"> +<!ENTITY cv-link-QT3_MOCFROMHCOM "<link linkend='cv-QT3_MOCFROMHCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCFROMHCOM</envar></link>"> +<!ENTITY cv-link-QT3_MOCFROMHCOMSTR "<link linkend='cv-QT3_MOCFROMHCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCFROMHCOMSTR</envar></link>"> +<!ENTITY cv-link-QT3_MOCFROMHFLAGS "<link linkend='cv-QT3_MOCFROMHFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCFROMHFLAGS</envar></link>"> +<!ENTITY cv-link-QT3_MOCHPREFIX "<link linkend='cv-QT3_MOCHPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCHPREFIX</envar></link>"> +<!ENTITY cv-link-QT3_MOCHSUFFIX "<link linkend='cv-QT3_MOCHSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_MOCHSUFFIX</envar></link>"> +<!ENTITY cv-link-QT3_UIC "<link linkend='cv-QT3_UIC' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UIC</envar></link>"> +<!ENTITY cv-link-QT3_UICCOM "<link linkend='cv-QT3_UICCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UICCOM</envar></link>"> +<!ENTITY cv-link-QT3_UICCOMSTR "<link linkend='cv-QT3_UICCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UICCOMSTR</envar></link>"> +<!ENTITY cv-link-QT3_UICDECLFLAGS "<link linkend='cv-QT3_UICDECLFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UICDECLFLAGS</envar></link>"> +<!ENTITY cv-link-QT3_UICDECLPREFIX "<link linkend='cv-QT3_UICDECLPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UICDECLPREFIX</envar></link>"> +<!ENTITY cv-link-QT3_UICDECLSUFFIX "<link linkend='cv-QT3_UICDECLSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UICDECLSUFFIX</envar></link>"> +<!ENTITY cv-link-QT3_UICIMPLFLAGS "<link linkend='cv-QT3_UICIMPLFLAGS' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UICIMPLFLAGS</envar></link>"> +<!ENTITY cv-link-QT3_UICIMPLPREFIX "<link linkend='cv-QT3_UICIMPLPREFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UICIMPLPREFIX</envar></link>"> +<!ENTITY cv-link-QT3_UICIMPLSUFFIX "<link linkend='cv-QT3_UICIMPLSUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UICIMPLSUFFIX</envar></link>"> +<!ENTITY cv-link-QT3_UISUFFIX "<link linkend='cv-QT3_UISUFFIX' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3_UISUFFIX</envar></link>"> +<!ENTITY cv-link-QT3DIR "<link linkend='cv-QT3DIR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$QT3DIR</envar></link>"> <!ENTITY cv-link-RANLIB "<link linkend='cv-RANLIB' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$RANLIB</envar></link>"> <!ENTITY cv-link-RANLIBCOM "<link linkend='cv-RANLIBCOM' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$RANLIBCOM</envar></link>"> <!ENTITY cv-link-RANLIBCOMSTR "<link linkend='cv-RANLIBCOMSTR' xmlns='http://www.scons.org/dbxsd/v1.0'><envar>$RANLIBCOMSTR</envar></link>"> diff --git a/doc/user/main.xml b/doc/user/main.xml index 5006339a4..7fcd92214 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -54,10 +54,10 @@ <corpauthor>The SCons Development Team</corpauthor> - <pubdate>Released: Mon, 30 Jul 2022 14:49:54 -0700</pubdate> + <pubdate>Released: Mon, 06 Mar 2023 23:58:40 -0400</pubdate> <copyright> - <year>2004 - 2022</year> + <year>2004 - 2023</year> <holder>The SCons Foundation</holder> </copyright> diff --git a/pyproject.toml b/pyproject.toml index 1725456de..548ae2d65 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [build-system] build-backend = "setuptools.build_meta" -requires = ["setuptools", "wheel"] +requires = ["setuptools"] # for black and mypy, set the lowest Python version supported [tool.black] diff --git a/test/ParseConfig.py b/test/ParseConfig.py index efb3a75f1..109a3a76c 100644 --- a/test/ParseConfig.py +++ b/test/ParseConfig.py @@ -33,6 +33,7 @@ test = TestSCons.TestSCons() test_config1 = test.workpath('test-config1') test_config2 = test.workpath('test-config2') test_config3 = test.workpath('test-config3') +test_config4 = test.workpath('test-config4') # 'abc' is supposed to be a static lib; it is included in LIBS as a # File node. @@ -51,6 +52,10 @@ test.write(test_config3, """\ print("-L foo -L lib_dir -isysroot /tmp -arch ppc -arch i386") """) +test.write(test_config4, """\ +print("-D_REENTRANT -lpulse -pthread") +""") + test.write('SConstruct1', """ env = Environment(CPPPATH = [], LIBPATH = [], LIBS = [], CCFLAGS = '-pipe -Wall') @@ -85,6 +90,23 @@ print([str(x) for x in env['LIBS']]) print(env['CCFLAGS']) """ % locals()) +# issue #4321: if CPPDEFINES has been promoted to deque, adding would fail +test.write('SConstruct4', f"""\ +env = Environment( + CPPDEFINES="_REENTRANT", + LIBS=[], + CCFLAGS=[], + LINKFLAGS=[], + PYTHON=r'{_python_}', +) +env.Append(CPPDEFINES="TOOLS_ENABLED") +env.ParseConfig(r"$PYTHON {test_config4} --libs --cflags") +print([str(x) for x in env['CPPDEFINES']]) +print([str(x) for x in env['LIBS']]) +print(env['CCFLAGS']) +print(env['LINKFLAGS']) +""") + good_stdout = """\ ['/usr/include/fum', 'bar'] ['/usr/fax', 'foo', 'lib_dir'] @@ -99,12 +121,21 @@ stdout3 = """\ ['-pipe', '-Wall', ('-isysroot', '/tmp'), ('-arch', 'ppc'), ('-arch', 'i386')] """ +stdout4 = """\ +['TOOLS_ENABLED', '_REENTRANT'] +['pulse'] +['-pthread'] +['-pthread'] +""" + test.run(arguments = "-q -Q -f SConstruct1 .", stdout = good_stdout) test.run(arguments = "-q -Q -f SConstruct2 .", stdout = good_stdout) test.run(arguments = "-q -Q -f SConstruct3 .", stdout = stdout3) +test.run(arguments = "-q -Q -f SConstruct4 .", stdout = stdout4) + test.pass_test() # Local Variables: diff --git a/test/QT/CPPPATH-appended.py b/test/QT/qt3/CPPPATH-appended.py index ee1808faf..ee1808faf 100644 --- a/test/QT/CPPPATH-appended.py +++ b/test/QT/qt3/CPPPATH-appended.py diff --git a/test/QT/CPPPATH.py b/test/QT/qt3/CPPPATH.py index b56efad44..b56efad44 100644 --- a/test/QT/CPPPATH.py +++ b/test/QT/qt3/CPPPATH.py diff --git a/test/QT/QTFLAGS.py b/test/QT/qt3/QTFLAGS.py index c759c2a4a..56536845f 100644 --- a/test/QT/QTFLAGS.py +++ b/test/QT/qt3/QTFLAGS.py @@ -24,7 +24,7 @@ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. """ -Testing the configuration mechanisms of the 'qt' tool. +Testing the configuration mechanisms of the 'qt3' tool. """ import TestSCons @@ -39,24 +39,24 @@ test.subdir('work1', 'work2') test.run( chdir=test.workpath('qt', 'lib'), - arguments="--warn=no-tool-qt-deprecated .", + arguments=".", stderr=TestSCons.noisy_ar, match=TestSCons.match_re_dotall, ) -QT = test.workpath('qt') -QT_LIB = 'myqt' -QT_MOC = '%s %s' % (_python_, test.workpath('qt', 'bin', 'mymoc.py')) -QT_UIC = '%s %s' % (_python_, test.workpath('qt', 'bin', 'myuic.py')) +QT3 = test.workpath('qt') +QT3_LIB = 'myqt' +QT3_MOC = '%s %s' % (_python_, test.workpath('qt', 'bin', 'mymoc.py')) +QT3_UIC = '%s %s' % (_python_, test.workpath('qt', 'bin', 'myuic.py')) def createSConstruct(test, place, overrides): test.write(place, """\ env = Environment( - tools=['default','qt'], - QTDIR = r'%s', - QT_LIB = r'%s', - QT_MOC = r'%s', - QT_UIC = r'%s', + tools=['default','qt3'], + QT3DIR = r'%s', + QT3_LIB = r'%s', + QT3_MOC = r'%s', + QT3_UIC = r'%s', %s # last because 'overrides' may add comma ) if ARGUMENTS.get('variant_dir', 0): @@ -70,23 +70,23 @@ else: sconscript = File('SConscript') Export("env") SConscript(sconscript) -""" % (QT, QT_LIB, QT_MOC, QT_UIC, overrides)) +""" % (QT3, QT3_LIB, QT3_MOC, QT3_UIC, overrides)) createSConstruct(test, ['work1', 'SConstruct'], - """QT_UICIMPLFLAGS='-x', - QT_UICDECLFLAGS='-y', - QT_MOCFROMHFLAGS='-z', - QT_MOCFROMCXXFLAGS='-i -w', - QT_UICDECLPREFIX='uic-', - QT_UICDECLSUFFIX='.hpp', - QT_UICIMPLPREFIX='', - QT_UICIMPLSUFFIX='.cxx', - QT_MOCHPREFIX='mmm', - QT_MOCHSUFFIX='.cxx', - QT_MOCCXXPREFIX='moc', - QT_MOCCXXSUFFIX='.inl', - QT_UISUFFIX='.myui',""") + """QT3_UICIMPLFLAGS='-x', + QT3_UICDECLFLAGS='-y', + QT3_MOCFROMHFLAGS='-z', + QT3_MOCFROMCXXFLAGS='-i -w', + QT3_UICDECLPREFIX='uic-', + QT3_UICDECLSUFFIX='.hpp', + QT3_UICIMPLPREFIX='', + QT3_UICIMPLSUFFIX='.cxx', + QT3_MOCHPREFIX='mmm', + QT3_MOCHSUFFIX='.cxx', + QT3_MOCCXXPREFIX='moc', + QT3_MOCCXXSUFFIX='.inl', + QT3_UISUFFIX='.myui',""") test.write(['work1', 'SConscript'],""" Import("env") env.Program('mytest', ['mocFromH.cpp', @@ -137,7 +137,7 @@ int main(void) { } """) -test.run(chdir='work1', arguments="--warn=no-tool-qt-deprecated mytest" + _exe) +test.run(chdir='work1', arguments="mytest" + _exe) test.must_exist( ['work1', 'mmmmocFromH.cxx'], @@ -173,32 +173,32 @@ test.write(['work2', 'SConstruct'], """ import os.path env1 = Environment( - tools=['qt'], - QTDIR=r'%(QTDIR)s', - QT_BINPATH='$QTDIR/bin64', - QT_LIBPATH='$QTDIR/lib64', - QT_CPPPATH='$QTDIR/h64', + tools=['qt3'], + QT3DIR=r'%(QT3DIR)s', + QT3_BINPATH='$QT3DIR/bin64', + QT3_LIBPATH='$QT3DIR/lib64', + QT3_CPPPATH='$QT3DIR/h64', ) cpppath = env1.subst('$CPPPATH') -if os.path.normpath(cpppath) != os.path.join(r'%(QTDIR)s', 'h64'): +if os.path.normpath(cpppath) != os.path.join(r'%(QT3DIR)s', 'h64'): print(cpppath) Exit(1) libpath = env1.subst('$LIBPATH') -if os.path.normpath(libpath) != os.path.join(r'%(QTDIR)s', 'lib64'): +if os.path.normpath(libpath) != os.path.join(r'%(QT3DIR)s', 'lib64'): print(libpath) Exit(2) -qt_moc = env1.subst('$QT_MOC') -if os.path.normpath(qt_moc) != os.path.join(r'%(QTDIR)s', 'bin64', 'moc'): +qt_moc = env1.subst('$QT3_MOC') +if os.path.normpath(qt_moc) != os.path.join(r'%(QT3DIR)s', 'bin64', 'moc'): print(qt_moc) Exit(3) env2 = Environment( - tools=['default', 'qt'], QTDIR=None, QT_LIB=None, QT_CPPPATH=None, QT_LIBPATH=None + tools=['default', 'qt3'], QT3DIR=None, QT3_LIB=None, QT3_CPPPATH=None, QT3_LIBPATH=None ) env2.Program('main.cpp') -""" % {'QTDIR':QT}) +""" % {'QT3DIR':QT3}) test.write(['work2', 'main.cpp'], """ int main(void) { return 0; } @@ -206,7 +206,7 @@ int main(void) { return 0; } # Ignore stderr, because if Qt is not installed, # there may be a warning about an empty QTDIR on stderr. -test.run(arguments="--warn=no-tool-qt-deprecated", chdir='work2', stderr=None) +test.run(chdir='work2', stderr=None) test.must_exist(['work2', 'main' + _exe]) diff --git a/test/QT/Tool.py b/test/QT/qt3/Tool.py index 122e7f413..1b34ea2ab 100644 --- a/test/QT/Tool.py +++ b/test/QT/qt3/Tool.py @@ -24,7 +24,7 @@ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. """ -Verify that applying env.Tool('qt') after running Configure checks +Verify that applying env.Tool('qt3') after running Configure checks works properly. This was broken in 0.96.95. The configuration here is a moderately stripped-down version of the @@ -90,7 +90,7 @@ def CheckForQt(context): ] if 'QTDIR' in os.environ: - potential_qt_dirs.insert(0, os.environ[ 'QTDIR' ]) + potential_qt_dirs.insert(0, os.environ['QTDIR']) if env[ 'qt_directory' ] != "/": uic_path = os.path.join(env['qt_directory'], 'bin', 'uic') @@ -101,7 +101,7 @@ def CheckForQt(context): return 0 for i in potential_qt_dirs: - context.env.Replace(QTDIR = i) + context.env.Replace(QT3DIR = i) if CheckForQtAt(context, i): # additional checks to validate QT installation if not os.path.isfile(os.path.join(i, 'bin', 'uic')): @@ -133,7 +133,7 @@ opts = Variables('lprof.conf') opts.Add(PathVariable("qt_directory", "Path to Qt directory", "/")) opts.Update(env) -env['QT_LIB'] = 'qt-mt' +env['QT3_LIB'] = 'qt-mt' config = env.Configure(custom_tests = { 'CheckForQt' : CheckForQt, }) @@ -142,10 +142,10 @@ if not config.CheckForQt(): print("Failed to find valid QT environment.") Exit(1) -env.Tool('qt', ['$TOOL_PATH']) +env.Tool('qt3', ['$TOOL_PATH']) """) -test.run(arguments='--warn=no-tool-qt-deprecated .') +test.run(arguments='.') test.pass_test() diff --git a/test/QT/copied-env.py b/test/QT/qt3/copied-env.py index 74f59b7fc..9bcb95b68 100644 --- a/test/QT/copied-env.py +++ b/test/QT/qt3/copied-env.py @@ -33,7 +33,7 @@ test = TestSCons.TestSCons() test.Qt_dummy_installation() -test.Qt_create_SConstruct('SConstruct') +test.Qt_create_SConstruct('SConstruct', qt_tool='qt3') test.write('SConscript', """\ Import("env") @@ -63,7 +63,7 @@ test.write('MyForm.ui', r""" void aaa(void) """) -test.run(arguments="--warn=no-tool-qt-deprecated") +test.run() moc_MyForm = [x for x in test.stdout().split('\n') if x.find('moc_MyForm') != -1] diff --git a/test/QT/empty-env.py b/test/QT/qt3/empty-env.py index e9dfc81b1..cd1434080 100644 --- a/test/QT/empty-env.py +++ b/test/QT/qt3/empty-env.py @@ -35,11 +35,11 @@ test.Qt_dummy_installation('qt') test.write('SConstruct', """\ orig = Environment() -env = orig.Clone(QTDIR = r'%s', - QT_LIB = r'%s', - QT_MOC = r'%s', - QT_UIC = r'%s', - tools=['qt']) +env = orig.Clone(QT3DIR = r'%s', + QT3_LIB = r'%s', + QT3_MOC = r'%s', + QT3_UIC = r'%s', + tools=['qt3']) env.Program('main', 'main.cpp', CPPDEFINES=['FOO'], LIBS=[]) """ % (test.QT, test.QT_LIB, test.QT_MOC, test.QT_UIC)) @@ -61,11 +61,10 @@ foo6(void) # we can receive warnings about a non detected qt (empty QTDIR) # these are not critical, but may be annoying. -test.run(stderr=None, arguments='--warn=no-tool-qt-deprecated') +test.run(stderr=None) test.run( program=test.workpath('main' + TestSCons._exe), - arguments='--warn=no-tool-qt-deprecated', stderr=None, stdout='qt/include/foo6.h\n', ) diff --git a/test/QT/generated-ui.py b/test/QT/qt3/generated-ui.py index fd368b34d..d43b21b00 100644 --- a/test/QT/generated-ui.py +++ b/test/QT/qt3/generated-ui.py @@ -45,7 +45,7 @@ test.write(['SConstruct'], """\ import os aa=os.getcwd() -env=Environment(tools=['default','expheaders','qt'],toolpath=[aa]) +env=Environment(tools=['default','expheaders','qt3'],toolpath=[aa]) if 'HOME' in os.environ: env['ENV']['HOME'] = os.environ['HOME'] env["EXP_HEADER_ABS"]=os.path.join(os.getcwd(),'include') @@ -120,12 +120,11 @@ test.write(['layer', 'aclock', 'qt_bug', 'migraform.ui'], """\ """) test.run( - arguments='--warn=no-tool-qt-deprecated', stderr=TestSCons.noisy_ar, match=TestSCons.match_re_dotall, ) -test.up_to_date(options="--warn=no-tool-qt-deprecated", arguments=".") +test.up_to_date(arguments=".") test.pass_test() diff --git a/test/QT/installed.py b/test/QT/qt3/installed.py index 9e8693e3f..71ff98fb7 100644 --- a/test/QT/installed.py +++ b/test/QT/qt3/installed.py @@ -24,7 +24,7 @@ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. """ -Look if qt is installed, and try out all builders. +Look if qt3 is installed, and try out all builders. """ import os @@ -56,7 +56,7 @@ try: except KeyError: ENV_PATH=ENV.get('PATH', '') -env = Environment(tools=['default','qt'], +env = Environment(tools=['default','qt3'], ENV={'PATH':ENV_PATH, 'PATHEXT':os.environ.get('PATHEXT'), 'HOME':os.getcwd(), @@ -65,9 +65,9 @@ env = Environment(tools=['default','qt'], CXXFILESUFFIX=".cpp") conf = env.Configure() -if not conf.CheckLib(env.subst("$QT_LIB"), autoadd=0): - conf.env['QT_LIB'] = 'qt-mt' - if not conf.CheckLib(env.subst("$QT_LIB"), autoadd=0): +if not conf.CheckLib(env.subst("$QT3_LIB"), autoadd=0): + conf.env['QT3_LIB'] = 'qt-mt' + if not conf.CheckLib(env.subst("$QT3_LIB"), autoadd=0): Exit(0) env = conf.Finish() VariantDir('bld', '.') @@ -196,18 +196,18 @@ if test.stdout() != "Hello World\n" or test.stderr() != '' or test.status: sys.stdout.write('test_realqt returned status %s\n' % test.status) test.fail_test() -QTDIR = os.environ['QTDIR'] +QT3DIR = os.environ['QTDIR'] PATH = os.environ['PATH'] os.environ['QTDIR'] = '' os.environ['PATH'] = '.' test.run( stderr=None, - arguments="--warn=no-tool-qt-deprecated -c bld/test_realqt" + TestSCons._exe, + arguments="-c bld/test_realqt" + TestSCons._exe, ) -expect1 = "scons: warning: Could not detect qt, using empty QTDIR" -expect2 = "scons: warning: Could not detect qt, using moc executable as a hint" +expect1 = "scons: warning: Could not detect qt3, using empty QT3DIR" +expect2 = "scons: warning: Could not detect qt3, using moc executable as a hint" test.fail_test(expect1 not in test.stderr() and expect2 not in test.stderr()) diff --git a/test/QT/manual.py b/test/QT/qt3/manual.py index 84c6df8e0..f467b5ae2 100644 --- a/test/QT/manual.py +++ b/test/QT/qt3/manual.py @@ -24,7 +24,7 @@ # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. """ -Test the manual QT builder calls. +Test the manual QT3 builder calls. """ import TestSCons @@ -51,7 +51,7 @@ sources.extend(env.Uic('ui/ccc.ui')[1:]) # manual target specification sources.append(env.Moc('moc-ddd.cpp', 'include/ddd.h', - QT_MOCHPREFIX='')) # Watch out ! + QT3_MOCHPREFIX='')) # Watch out ! moc = env.Moc('moc_eee.cpp', 'eee.cpp') env.Ignore( moc, moc ) sources.extend(env.Uic(['include/uic_fff.hpp', 'fff.cpp', 'fff.moc.cpp'], @@ -61,7 +61,7 @@ print(list(map(str,sources))) env.Program(target='aaa', source=sources, CPPPATH=['$CPPPATH', './include'], - QT_AUTOSCAN=0) + QT3_AUTOSCAN=0) """) test.write('aaa.cpp', r""" @@ -123,7 +123,7 @@ int main(void) { } """) -test.run(arguments="--warn=no-tool-qt-deprecated " + aaa_exe) +test.run(arguments=aaa_exe) # normal invocation test.must_exist(test.workpath('include', 'moc_aaa.cc')) diff --git a/test/QT/moc-from-cpp.py b/test/QT/qt3/moc-from-cpp.py index bbab8cab8..bbab8cab8 100644 --- a/test/QT/moc-from-cpp.py +++ b/test/QT/qt3/moc-from-cpp.py diff --git a/test/QT/moc-from-header.py b/test/QT/qt3/moc-from-header.py index 65a12e1ed..65a12e1ed 100644 --- a/test/QT/moc-from-header.py +++ b/test/QT/qt3/moc-from-header.py diff --git a/test/QT/qt_warnings.py b/test/QT/qt3/qt_warnings.py index fb23a7151..1cbf2b013 100644 --- a/test/QT/qt_warnings.py +++ b/test/QT/qt3/qt_warnings.py @@ -51,7 +51,7 @@ import os env.StaticLibrary('aaa.cpp') """) -test.run(arguments="--warn=no-tool-qt-deprecated", stderr=None) +test.run(stderr=None) match12 = r""" scons: warning: Generated moc file 'aaa.moc' is not included by 'aaa.cpp' @@ -64,7 +64,7 @@ if not re.search(match12, test.stderr()): os.environ['QTDIR'] = test.QT -test.run(arguments='--warn=no-tool-qt-deprecated -n noqtdir=1') +test.run(arguments='-n noqtdir=1') # We'd like to eliminate $QTDIR from the environment as follows: # del os.environ['QTDIR'] @@ -74,7 +74,7 @@ test.run(arguments='--warn=no-tool-qt-deprecated -n noqtdir=1') # environment, so it only gets removed from the Python dictionary. # Consequently, we need to just wipe out its value as follows> os.environ['QTDIR'] = '' -test.run(stderr=None, arguments='--warn=no-tool-qt-deprecated -n noqtdir=1') +test.run(stderr=None, arguments='-n noqtdir=1') moc = test.where_is('moc') if moc: @@ -83,13 +83,13 @@ if moc: qtdir = qtdir.replace('\\', '\\\\' ) expect = r""" -scons: warning: Could not detect qt, using moc executable as a hint \(QTDIR=%s\) +scons: warning: Could not detect qt3, using moc executable as a hint \(QT3DIR=%s\) File "%s", line \d+, in (\?|<module>) """ % (qtdir, re.escape(SConstruct_path)) else: expect = r""" -scons: warning: Could not detect qt, using empty QTDIR +scons: warning: Could not detect qt3, using empty QT3DIR File "%s", line \d+, in (\?|<module>) """ % re.escape(SConstruct_path) diff --git a/test/QT/reentrant.py b/test/QT/qt3/reentrant.py index 40fb1f19a..be6d8a62f 100644 --- a/test/QT/reentrant.py +++ b/test/QT/qt3/reentrant.py @@ -49,7 +49,7 @@ test.Qt_create_SConstruct('SConstruct') test.write('SConscript', """\ Import("env") -env = env.Clone(tools=['qt']) +env = env.Clone(tools=['qt3']) env.Program('main', 'main.cpp', CPPDEFINES=['FOO'], LIBS=[]) """) diff --git a/test/QT/source-from-ui.py b/test/QT/qt3/source-from-ui.py index 569fbab2c..1404f7532 100644 --- a/test/QT/source-from-ui.py +++ b/test/QT/qt3/source-from-ui.py @@ -67,9 +67,9 @@ void useit() { } """) -test.run(arguments="--warn=no-tool-qt-deprecated " + aaa_dll) +test.run(arguments=aaa_dll) -test.up_to_date(options='--warn=no-tool-qt-deprecated -n', arguments=aaa_dll) +test.up_to_date(options='-n', arguments=aaa_dll) test.write('aaa.ui', r""" /* a change */ @@ -81,11 +81,11 @@ test.write('aaa.ui', r""" DLLEXPORT void aaa(void) """) -test.not_up_to_date(options='--warn=no-tool-qt-deprecated -n', arguments=moc) -test.not_up_to_date(options='--warn=no-tool-qt-deprecated -n', arguments=cpp) -test.not_up_to_date(options='--warn=no-tool-qt-deprecated -n', arguments=h) +test.not_up_to_date(options='-n', arguments=moc) +test.not_up_to_date(options='-n', arguments=cpp) +test.not_up_to_date(options='-n', arguments=h) -test.run(arguments="--warn=no-tool-qt-deprecated " + aaa_dll) +test.run(arguments=" " + aaa_dll) test.write('aaa.ui', r""" void aaa(void) @@ -93,28 +93,28 @@ void aaa(void) """) # test that non-existant ui.h files are ignored (as uic does) -test.run(arguments="--warn=no-tool-qt-deprecated " + aaa_dll) +test.run(arguments=" " + aaa_dll) test.write('aaa.ui.h', r""" /* test dependency to .ui.h */ """) -test.run(arguments="--warn=no-tool-qt-deprecated " + aaa_dll) +test.run(arguments=" " + aaa_dll) test.write('aaa.ui.h', r""" /* changed */ """) -test.not_up_to_date(options='--warn=no-tool-qt-deprecated -n', arguments=obj) -test.not_up_to_date(options='--warn=no-tool-qt-deprecated -n', arguments=cpp) -test.not_up_to_date(options='--warn=no-tool-qt-deprecated -n', arguments=h) -test.not_up_to_date(options='--warn=no-tool-qt-deprecated -n', arguments=moc) +test.not_up_to_date(options='-n', arguments=obj) +test.not_up_to_date(options='-n', arguments=cpp) +test.not_up_to_date(options='-n', arguments=h) +test.not_up_to_date(options='-n', arguments=moc) # clean up -test.run(arguments="--warn=no-tool-qt-deprecated -c " + aaa_dll) +test.run(arguments=" -c " + aaa_dll) test.run( - arguments="--warn=no-tool-qt-deprecated variant_dir=1 " + arguments="variant_dir=1 " + test.workpath('build', aaa_dll) ) @@ -129,7 +129,7 @@ cppContents = test.read(test.workpath('build', cpp), mode='r') test.fail_test(cppContents.find('#include "aaa.ui.h"') == -1) test.run( - arguments="--warn=no-tool-qt-deprecated variant_dir=1 chdir=1 " + arguments="variant_dir=1 chdir=1 " + test.workpath('build', aaa_dll) ) @@ -141,7 +141,7 @@ test.must_not_exist(test.workpath(cpp)) test.must_not_exist(test.workpath(h)) test.run( - arguments="--warn=no-tool-qt-deprecated variant_dir=1 chdir=1 dup=0 " + arguments=" variant_dir=1 chdir=1 dup=0 " + test.workpath('build_dup0', aaa_dll) ) diff --git a/test/QT/up-to-date.py b/test/QT/qt3/up-to-date.py index 06fb5590e..ec5123827 100644 --- a/test/QT/up-to-date.py +++ b/test/QT/qt3/up-to-date.py @@ -53,7 +53,7 @@ test.write('SConstruct', """\ import os aa=os.getcwd() -env=Environment(tools=['default','expheaders','qt'],toolpath=[aa]) +env=Environment(tools=['default','expheaders','qt3'],toolpath=[aa]) env["EXP_HEADER_ABS"]=os.path.join(os.getcwd(),'include') if not os.access(env["EXP_HEADER_ABS"],os.F_OK): os.mkdir (env["EXP_HEADER_ABS"]) diff --git a/test/import.py b/test/import.py index 55a40cc43..50d7b2178 100644 --- a/test/import.py +++ b/test/import.py @@ -128,23 +128,26 @@ if moc: import os.path qtdir = os.path.dirname(os.path.dirname(moc)) - - qt_err = r""" -scons: warning: Could not detect qt, using moc executable as a hint \(QTDIR=%(qtdir)s\) -""" % locals() - + qt3_err = fr""" +scons: warning: Could not detect qt3, using moc executable as a hint \(QT3DIR={qtdir}\) +""" else: + qt3_err = r""" +scons: warning: Could not detect qt3, using empty QT3DIR +""" - qt_err = """ -scons: warning: Could not detect qt, using empty QTDIR +qt_moved = r""" +scons: \*\*\* Deprecated tool 'qt' renamed to 'qt3'. Please update your build accordingly. 'qt3' will be removed entirely in a future release. """ -qt_warnings = [ re.compile(qt_err + TestSCons.file_expr) ] +qt3_warnings = [re.compile(qt3_err + TestSCons.file_expr)] +qt_error = [re.compile(qt_moved + TestSCons.file_expr)] error_output = { - 'icl' : intel_warnings, - 'intelc' : intel_warnings, - 'qt' : qt_warnings, + 'icl': intel_warnings, + 'intelc': intel_warnings, + 'qt3': qt3_warnings, + 'qt': qt_error, } # An SConstruct for importing Tool names that have illegal characters @@ -178,16 +181,16 @@ for tool in tools: test.write('SConstruct', indirect_import % locals()) else: test.write('SConstruct', direct_import % locals()) - test.run(stderr=None) + test.run(stderr=None, status=None) stderr = test.stderr() - if stderr: + if stderr or test.status: matched = None for expression in error_output.get(tool, []): if expression.match(stderr): matched = 1 break if not matched: - print("Failed importing '%s', stderr:" % tool) + print(f"Failed importing '{tool}', stderr:") print(stderr) failures.append(tool) diff --git a/test/textfile/textfile.py b/test/textfile/textfile.py index f614dfc94..d7d19e5e2 100644 --- a/test/textfile/textfile.py +++ b/test/textfile/textfile.py @@ -34,7 +34,8 @@ test = TestSCons.TestSCons() # foo1a = test.workpath('foo1a.txt') # foo2a = test.workpath('foo2a.txt') -match_mode = 'r' +# Must be read binary as now we're including unicode characters in our textparts +match_mode = 'rb' test.file_fixture('fixture/SConstruct', 'SConstruct') diff --git a/testing/framework/TestSCons.py b/testing/framework/TestSCons.py index 469f6c1c5..2c96995cf 100644 --- a/testing/framework/TestSCons.py +++ b/testing/framework/TestSCons.py @@ -55,7 +55,7 @@ from TestCmd import PIPE # here provides some independent verification that what we packaged # conforms to what we expect. -default_version = '4.4.1ayyyymmdd' +default_version = '4.5.2ayyyymmdd' # TODO: these need to be hand-edited when there are changes python_version_unsupported = (3, 6, 0) @@ -1172,17 +1172,20 @@ else: self.QT_UIC = f"{_python_} {self.workpath(dir, 'bin', 'myuic.py')}" self.QT_LIB_DIR = self.workpath(dir, 'lib') - def Qt_create_SConstruct(self, place): + def Qt_create_SConstruct(self, place, qt_tool='qt3'): if isinstance(place, list): place = test.workpath(*place) - self.write(place, """\ + + var_prefix=qt_tool.upper() + self.write(place, f"""\ if ARGUMENTS.get('noqtdir', 0): - QTDIR = None + {var_prefix}DIR = None else: - QTDIR = r'%s' + {var_prefix}DIR = r'{self.QT}' DefaultEnvironment(tools=[]) # test speedup env = Environment( - QTDIR=QTDIR, QT_LIB=r'%s', QT_MOC=r'%s', QT_UIC=r'%s', tools=['default', 'qt'] + {var_prefix}DIR={var_prefix}DIR, {var_prefix}_LIB=r'{self.QT_LIB}', {var_prefix}_MOC=r'{self.QT_MOC}', + {var_prefix}_UIC=r'{self.QT_UIC}', tools=['default', '{qt_tool}'] ) dup = 1 if ARGUMENTS.get('variant_dir', 0): @@ -1203,7 +1206,7 @@ else: sconscript = File('SConscript') Export("env dup") SConscript(sconscript) -""" % (self.QT, self.QT_LIB, self.QT_MOC, self.QT_UIC)) +""") NCR = 0 # non-cached rebuild CR = 1 # cached rebuild (up to date) |