From 6e7f1530dedce1445e4d5d9640abaf293ac8032d Mon Sep 17 00:00:00 2001 From: Joseph Brill <48932340+jcbrill@users.noreply.github.com> Date: Fri, 7 Aug 2020 07:09:26 -0400 Subject: Remove hard-coded MSCommon from debug logging record filename field. Add method to retrieve truncated relative module file name path. Add filter and derived path field for debug log record processing to produce the correct relative file name information for calls to debug from above MSCommon (e.g, msvsTests). --- CHANGES.txt | 4 ++++ SCons/Tool/MSCommon/common.py | 31 +++++++++++++++++++++++++++++-- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 7250a9b..eae76c8 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -8,6 +8,10 @@ NOTE: The 4.0.0 Release of SCons dropped Python 2.7 Support RELEASE VERSION/DATE TO BE FILLED IN LATER + From Joseph Brill: + - Modify the MSCommon internal-use only debug logging records to contain the correct relative + file path when the debug function is called from outside the MSCommon module. + From William Deegan: - Fix yacc tool, not respecting YACC set at time of tool initialization. diff --git a/SCons/Tool/MSCommon/common.py b/SCons/Tool/MSCommon/common.py index e1a82f2..81004df 100644 --- a/SCons/Tool/MSCommon/common.py +++ b/SCons/Tool/MSCommon/common.py @@ -42,19 +42,46 @@ if LOGFILE == '-': print(message) elif LOGFILE: import logging + modulelist = ( + # root module and parent/root module + 'MSCommon', 'Tool', + # python library and below: correct iff scons does not have a lib folder + 'lib', + # scons modules + 'SCons', 'test', 'scons' + ) + def get_relative_filename(filename, module_list): + if not filename: + return filename + for module in module_list: + try: + ind = filename.rindex(module) + return filename[ind:] + except ValueError: + pass + return filename + class _Debug_Filter(logging.Filter): + # custom filter for module relative filename + def filter(self, record): + relfilename = get_relative_filename(record.pathname, modulelist) + relfilename = relfilename.replace('\\', '/') + record.relfilename = relfilename + return True logging.basicConfig( # This looks like: # 00109ms:MSCommon/vc.py:find_vc_pdir#447: format=( '%(relativeCreated)05dms' - ':MSCommon/%(filename)s' + ':%(relfilename)s' ':%(funcName)s' '#%(lineno)s' ':%(message)s: ' ), filename=LOGFILE, level=logging.DEBUG) - debug = logging.getLogger(name=__name__).debug + logger = logging.getLogger(name=__name__) + logger.addFilter(_Debug_Filter()) + debug = logger.debug else: def debug(x): return None -- cgit v0.12 From d97ab435efedef58940aed901303e5e2a89f76c5 Mon Sep 17 00:00:00 2001 From: Joseph Brill <48932340+jcbrill@users.noreply.github.com> Date: Mon, 10 Aug 2020 12:08:25 -0400 Subject: Restore inadvertent character changes from master. [ci skip] --- CHANGES.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES.txt b/CHANGES.txt index c1ee31f..8a8cc24 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,4 +1,4 @@ - + SCons - a software construction tool -- cgit v0.12 From 0949d5bbe3056e51e45b3975c0c3a1fb36be1c14 Mon Sep 17 00:00:00 2001 From: Joachim Kuebart Date: Tue, 11 Aug 2020 08:32:48 +0200 Subject: Conditionally suppress deprecation message. Suppress missing SConscript deprecation message when must_exist is used. --- CHANGES.txt | 4 ++ SCons/Script/SConscript.py | 2 +- test/SConscript/must_exist_deprecation.py | 79 +++++++++++++++++++++++++++++++ 3 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 test/SConscript/must_exist_deprecation.py diff --git a/CHANGES.txt b/CHANGES.txt index f3900f0..0bb45cf 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -28,6 +28,10 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - Complete tests for Dictionary, env.keys() and env.values() for OverrideEnvironment. Enable env.setdefault() method, add tests. + From Joachim Kuebart: + - Suppress missing SConscript deprecation warning if `must_exist` is + used. + RELEASE 4.0.1 - Mon, 16 Jul 2020 16:06:40 -0700 diff --git a/SCons/Script/SConscript.py b/SCons/Script/SConscript.py index 309bed3..e7f53f5 100644 --- a/SCons/Script/SConscript.py +++ b/SCons/Script/SConscript.py @@ -172,7 +172,7 @@ def handle_missing_SConscript(f, must_exist=None): msg = "Fatal: missing SConscript '%s'" % f.get_internal_path() raise SCons.Errors.UserError(msg) - if SCons.Script._warn_missing_sconscript_deprecated: + if SCons.Script._warn_missing_sconscript_deprecated and must_exist is None: msg = "Calling missing SConscript without error is deprecated.\n" + \ "Transition by adding must_exist=0 to SConscript calls.\n" + \ "Missing SConscript '%s'" % f.get_internal_path() diff --git a/test/SConscript/must_exist_deprecation.py b/test/SConscript/must_exist_deprecation.py new file mode 100644 index 0000000..86f753b --- /dev/null +++ b/test/SConscript/must_exist_deprecation.py @@ -0,0 +1,79 @@ +#!/usr/bin/env python +# +# __COPYRIGHT__ +# +# 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. +# + +__revision__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__" + +''' +Test deprecation warning if must_exist flag is used in a SConscript call +''' + +import os +import TestSCons + +test = TestSCons.TestSCons() + +# catch the exception if is raised, send it on as a warning +# this gives us traceability of the line responsible +SConstruct_path = test.workpath('SConstruct') +test.write(SConstruct_path, """\ +import SCons +from SCons.Warnings import _warningOut +import sys + +DefaultEnvironment(tools=[]) +# 1. call should succeed without deprecation warning +try: + SConscript('missing/SConscript', must_exist=False) +except SCons.Errors.UserError as e: + if _warningOut: + _warningOut(e) +# 2. call should succeed with deprecation warning +try: + SConscript('missing/SConscript') +except SCons.Errors.UserError as e: + if _warningOut: + _warningOut(e) +""") + +# we should see two warnings, the second being the deprecation message. +# need to build the path in the expected msg in an OS-agnostic way +missing = os.path.normpath('missing/SConscript') +warn1 = """ +scons: warning: Ignoring missing SConscript '{}' +""".format(missing) + test.python_file_line(SConstruct_path, 8) +warn2 = """ +scons: warning: Calling missing SConscript without error is deprecated. +Transition by adding must_exist=0 to SConscript calls. +Missing SConscript '{}' +""".format(missing) + test.python_file_line(SConstruct_path, 14) + +expect_stderr = warn1 + warn2 +test.run(arguments = ".", stderr = expect_stderr) +test.pass_test() + +# Local Variables: +# tab-width:4 +# indent-tabs-mode:nil +# End: +# vim: set expandtab tabstop=4 shiftwidth=4: -- cgit v0.12 From 186736d72074ba06c962900bcd8c2d49fd5e828d Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 11 Aug 2020 08:22:03 -0600 Subject: Tweak Installing Python section in User Guide [skip appveyor] Signed-off-by: Mats Wichmann --- doc/user/build-install.xml | 49 ++++++++++++++++++++++++---------------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/doc/user/build-install.xml b/doc/user/build-install.xml index 87a86aa..c106dc5 100644 --- a/doc/user/build-install.xml +++ b/doc/user/build-install.xml @@ -110,12 +110,13 @@ Python 3.7.1 - Note to Windows users: there are many different ways Python - can get installed or invoked on Windows, it is beyond the scope - of this guide to unravel all of them. Try using the - Python launcher (see - PEP 397) - by using the name py instead of + Note to Windows users: there are a number of different ways Python + can be installed or invoked on Windows, it is beyond the scope + of this guide to unravel all of them. Many will have an additional + program called the Python launcher (described, + somewhat technically, in + PEP 397): + try using the command name py instead of python, if that is not available drop back to trying python. @@ -129,21 +130,23 @@ Python 3.7.1 If Python is not installed on your system, or is not findable in the current search path, you will see an error message - stating something like "command not found" + stating something like "command not found" (on UNIX or Linux) - or "'python' is not recognized - as an internal or external command, operable progam or batch file" + or "'python' is not recognized as an internal + or external command, operable progam or batch file" (on Windows cmd). - In that case, you need to install Python - (or fix the search path) + In that case, you need to either install Python + or fix the search path before you can install &SCons;. - The canonical location for information - about downloading and installing Python is - http://www.python.org/download/. - See that page and associated links to get started. + The canonical location for downloading Python + from Python's own website is: + https://www.python.org/download. + There are useful system-specific entries on setup and + usage to be found at: + https://docs.python.org/3/using @@ -153,7 +156,7 @@ Python 3.7.1 by other means, and is easier than installing from source code. Many such systems have separate packages for Python 2 and Python 3 - make sure the Python 3 package is - installed, as &SCons; requires it. + installed, as the latest &SCons; requires it. Building from source may still be a useful option if you need a version that is not offered by the distribution you are using. @@ -195,7 +198,7 @@ Python 3.7.1 For those users using Anaconda or Miniconda, use the conda installer instead, so the &scons; install location will match the version of Python that - system will be using: + system will be using. For example: @@ -211,14 +214,14 @@ Python 3.7.1 During the still-ongoing Python 2 to 3 transition, some distributions may still have two &SCons; packages available, one which uses Python 2 and one which uses Python 3. Since - latest &scons; only runs on Python 3, to get the current version + the latest &scons; only runs on Python 3, to get the current version you should choose the Python 3 package. If you need a specific version of &SCons; that is different from the package available, - pip has a version option or you can follow + pip has a version option or you can follow the instructions in the next section. @@ -229,9 +232,9 @@ Python 3.7.1 If a pre-built &SCons; package is not available for your system, - and installing using pip is not suitable, + and installing using pip is not suitable, then you can still easily build and install &SCons; using the native - Python distutils package. + Python setuptools package. @@ -265,11 +268,11 @@ Python 3.7.1 install the &scons; script in the python which is used to run the setup.py's scripts directory (/usr/local/bin or - C:\Python27\Scripts), + C:\Python37\Scripts), and will install the &SCons; build engine in the corresponding library directory for the python used (/usr/local/lib/scons or - C:\Python27\scons). + C:\Python37\scons). Because these are system directories, you may need root (on Linux or UNIX) or Administrator (on Windows) privileges to install &SCons; like this. -- cgit v0.12 From a8d13e28332585b5c9e83e85ae424d53b387b154 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Tue, 11 Aug 2020 11:09:33 -0700 Subject: Add check for pre-specified YACC to yacc tool's exist() --- SCons/Tool/yacc.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/SCons/Tool/yacc.py b/SCons/Tool/yacc.py index c7bdf4c..ab019b2 100644 --- a/SCons/Tool/yacc.py +++ b/SCons/Tool/yacc.py @@ -162,6 +162,9 @@ def generate(env): def exists(env): + if 'YACC' in env: + return env.Detect(env['YACC']) + if sys.platform == 'win32': return get_yacc_path(env) else: -- cgit v0.12 From 5fa8009133ed8bd61828fafae4f0a14869fc8c23 Mon Sep 17 00:00:00 2001 From: Joachim Kuebart Date: Tue, 11 Aug 2020 20:50:31 +0200 Subject: Convert new e2e test to file fixture. --- test/SConscript/fixture/SConstruct | 17 +++++++++++++++++ test/SConscript/must_exist_deprecation.py | 20 +------------------- 2 files changed, 18 insertions(+), 19 deletions(-) create mode 100644 test/SConscript/fixture/SConstruct diff --git a/test/SConscript/fixture/SConstruct b/test/SConscript/fixture/SConstruct new file mode 100644 index 0000000..a955efc --- /dev/null +++ b/test/SConscript/fixture/SConstruct @@ -0,0 +1,17 @@ +import SCons +from SCons.Warnings import _warningOut +import sys + +DefaultEnvironment(tools=[]) +# 1. call should succeed without deprecation warning +try: + SConscript('missing/SConscript', must_exist=False) +except SCons.Errors.UserError as e: + if _warningOut: + _warningOut(e) +# 2. call should succeed with deprecation warning +try: + SConscript('missing/SConscript') +except SCons.Errors.UserError as e: + if _warningOut: + _warningOut(e) diff --git a/test/SConscript/must_exist_deprecation.py b/test/SConscript/must_exist_deprecation.py index 86f753b..8b267ce 100644 --- a/test/SConscript/must_exist_deprecation.py +++ b/test/SConscript/must_exist_deprecation.py @@ -36,25 +36,7 @@ test = TestSCons.TestSCons() # catch the exception if is raised, send it on as a warning # this gives us traceability of the line responsible SConstruct_path = test.workpath('SConstruct') -test.write(SConstruct_path, """\ -import SCons -from SCons.Warnings import _warningOut -import sys - -DefaultEnvironment(tools=[]) -# 1. call should succeed without deprecation warning -try: - SConscript('missing/SConscript', must_exist=False) -except SCons.Errors.UserError as e: - if _warningOut: - _warningOut(e) -# 2. call should succeed with deprecation warning -try: - SConscript('missing/SConscript') -except SCons.Errors.UserError as e: - if _warningOut: - _warningOut(e) -""") +test.file_fixture("fixture/SConstruct") # we should see two warnings, the second being the deprecation message. # need to build the path in the expected msg in an OS-agnostic way -- cgit v0.12 From 690126b9f148b5b6e3f1b62f95283cf262e52dbc Mon Sep 17 00:00:00 2001 From: Joachim Kuebart Date: Tue, 11 Aug 2020 21:00:50 +0200 Subject: Clarify change description. --- CHANGES.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 0bb45cf..b9835c9 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -29,8 +29,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER OverrideEnvironment. Enable env.setdefault() method, add tests. From Joachim Kuebart: - - Suppress missing SConscript deprecation warning if `must_exist` is - used. + - Suppress missing SConscript deprecation warning if `must_exist=False` + is used. RELEASE 4.0.1 - Mon, 16 Jul 2020 16:06:40 -0700 -- cgit v0.12 From bac92fa6f1b86ae5667a870a87a07070a37bc69e Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 10 Aug 2020 08:15:15 -0600 Subject: manpage tweaks [skip appveyor] In DESCRIPTION, turn function references into clickable links. Also turn special variables into link references, which necessitated defining identifiers for them, as these are not part of the generated entities process. Introduce the term "execution environment" in the intro section for terminology consistency, since this term is defined in the User Guide (Chapter 7, Environments). Change wording of the -c option slightly. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 80 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 42 insertions(+), 38 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 5cad5c7..3d04ead 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -111,14 +111,15 @@ and, if necessary, the rules to build those files. Premade rules exist for building many common software components such as executable programs, object files, libraries, so that for many software projects, -only the target and input files need be specified. +only the target and input files (sources) +need be specified. When invoked, &scons; searches for a file named &SConstruct; (it also checks alternate spellings -&Sconstruct;, &sconstruct;, &SConstruct.py; &Sconstruct.py; +&Sconstruct;, &sconstruct;, &SConstruct.py;, &Sconstruct.py; and &sconstruct.py; in that order) in the current directory and reads its configuration from that file. @@ -214,12 +215,10 @@ that you want to use to build your target files are not in standard system locations, &scons; will not find them unless -you explicitly include the locations into the value of -PATH in the ENV -variable in the internal &consenv;. -Whenever you create a &consenv;, -you can propagate the value of PATH -from your external environment as follows: +you explicitly include the locations into the +execution environment by setting the path in the +ENV &consvar; in the +internal &consenv;: import os @@ -229,13 +228,18 @@ env = Environment(ENV={'PATH': os.environ['PATH']}) Similarly, if the commands use specific external environment variables that &scons; does not recognize, they can be propagated into -the internal environment: +the execution environment: import os -env = Environment(ENV={'PATH': os.environ['PATH'], - 'ANDROID_HOME': os.environ['ANDROID_HOME'], - 'ANDROID_NDK_HOME': os.environ['ANDROID_NDK_HOME']}) + +env = Environment( + ENV={ + 'PATH': os.environ['PATH'], + 'ANDROID_HOME': os.environ['ANDROID_HOME'], + 'ANDROID_NDK_HOME': os.environ['ANDROID_NDK_HOME'], + } +) Or you may explicitly propagate the invoking user's @@ -269,9 +273,9 @@ ability to define new scanners for unknown input file types. is normally executed in a top-level directory containing an &SConstruct; file. When &scons; is invoked, -the command line (including the contents -of the &SCONSFLAGS; environment variable, -if set) is processed. +the command line (including the contents of the +&SCONSFLAGS; +environment variable, if set) is processed. Command-line options (see ) are consumed. Any variable argument assignments are collected, and remaining arguments are taken as the targets to build. @@ -283,8 +287,8 @@ may be specified on the command line: scons debug=1 -These variables are available -through the &ARGUMENTS; dictionary, +These variables are available through the +&ARGUMENTS; dictionary, and can be used in the SConscript files to modify the build in any way: @@ -296,7 +300,7 @@ else: The command-line variable arguments are also available -in the &ARGLIST; list, +in the &ARGLIST; list, indexed by their order on the command line. This allows you to process them in order rather than by name, if necessary. Each &ARGLIST; entry is a tuple containing @@ -304,19 +308,19 @@ if necessary. Each &ARGLIST; entry is a tuple containing Targets on the command line may be files, directories, -or phony targets defined using the &Alias; function. +or phony targets defined using the &f-link-Alias; function. The command line targets are made available in the -&COMMAND_LINE_TARGETS; list. +&COMMAND_LINE_TARGETS; list. If no targets are specified on the command line, &scons; will build the default targets. The default targets are those specified in the SConscript files via calls -to the &Default; function; if none, the default targets are +to the &f-link-Default; function; if none, the default targets are those target files in or below the current directory. Targets specified via the &Default; function are available -in the &DEFAULT_TARGETS; list. +in the &DEFAULT_TARGETS; list. To ignore the default targets specified @@ -394,11 +398,11 @@ and export. Additional files or directories to remove can be specified using the -&Clean; function in the SConscript files. +&f-link-Clean; function in the SConscript files. Conversely, targets that would normally be removed by the invocation can be retained by calling the -&NoClean; function with those targets. +&f-link-NoClean; function with those targets. &scons; supports building multiple targets in parallel via a @@ -414,7 +418,7 @@ of simultaneous tasks that may be spawned: &scons; can maintain a cache of target (derived) files that can -be shared between multiple builds. When caching is enabled in a +be shared between multiple builds. When derived-file caching is enabled in an SConscript file, any target files built by &scons; will be copied @@ -511,11 +515,11 @@ and many of those supported by cons. -Clean up by removing all target files for which a construction -command is specified. -Also remove any files or directories associated to the construction command -using the &Clean; function. -Will not remove any targets specified by the &NoClean; function. +Clean up by removing the specified targets and their +dependencies, as well as any files or directories associated +with the specified targets through calls to the &f-link-Clean; function. +Will not remove any targets specified by the &f-link-NoClean; function. + @@ -2152,7 +2156,7 @@ but setting it after the &consenv; is constructed has no effect. As a convenience, &consvars; may also be set or modified by the parse_flags -keyword argument during object creation, +keyword argument during object creation, which has the effect of the &f-link-env-MergeFlags; method being applied to the argument value @@ -2681,7 +2685,7 @@ see the descriptions below of these variables for more information. The optional parse_flags keyword argument is recognized by builders. -This works similarly to the +This works similarly to the &f-link-env-MergeFlags; method, where the argument value is broken into individual settings and merged into the appropriate &consvars;. @@ -3072,7 +3076,7 @@ that can be used in SConscript files to affect how you want the build to be performed. - + &ARGLIST; A list of the @@ -3104,7 +3108,7 @@ for key, value in ARGLIST: - + &ARGUMENTS; A dictionary of all the @@ -3129,7 +3133,7 @@ else: - + &BUILD_TARGETS; A list of the targets which @@ -3175,7 +3179,7 @@ if 'special/program' in BUILD_TARGETS: - + &COMMAND_LINE_TARGETS; A list of the targets explicitly specified on @@ -3198,7 +3202,7 @@ if 'special/program' in COMMAND_LINE_TARGETS: - + &DEFAULT_TARGETS; A list of the target @@ -7464,7 +7468,7 @@ release, it may be necessary to specify - + SCONSFLAGS A string of options that will be used by &scons; -- cgit v0.12 From aac831b3042a63fc21aa8eb4fbaa240d30baf94b Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 12 Aug 2020 10:18:52 -0600 Subject: [PR #3772] add definition of selected targets [skip appveyor] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 79 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 59 insertions(+), 20 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 3d04ead..073b0d0 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -109,7 +109,7 @@ commands to build them. which specifies the files to be built (targets), and, if necessary, the rules to build those files. Premade rules exist for building many common software components -such as executable programs, object files, libraries, +such as executable programs, object files and libraries, so that for many software projects, only the target and input files (sources) need be specified. @@ -277,8 +277,10 @@ the command line (including the contents of the &SCONSFLAGS; environment variable, if set) is processed. Command-line options (see ) are consumed. -Any variable argument assignments are collected, and -remaining arguments are taken as the targets to build. +Any variable argument assignments +(see ) +are collected, and +remaining arguments are taken as targets to build. Values of variables to be passed to the SConscript files may be specified on the command line: @@ -307,21 +309,55 @@ if necessary. Each &ARGLIST; entry is a tuple containing (argname, argvalue). -Targets on the command line may be files, directories, +&SCons; acts on the selected targets, +whether the requested operation is build, no-exec or clean. +Targets are selected as follows: + + + + +Targets specified on the command line. +These may be files, directories, or phony targets defined using the &f-link-Alias; function. -The command line targets are made available in the +Directory targets are scanned by &scons; for any targets +that may be found with a destination in or under that directory. +The targets listed on the command line are made available in the &COMMAND_LINE_TARGETS; list. - + + If no targets are specified on the command line, -&scons; -will build the default targets. The default targets -are those specified in the SConscript files via calls -to the &f-link-Default; function; if none, the default targets are -those target files in or below the current directory. -Targets specified via the &Default; function are available -in the &DEFAULT_TARGETS; list. +&scons; will select those targets +specified in the SConscript files via calls +to the &f-link-Default; function. These are +known as the default targets, +and are made available in the +&DEFAULT_TARGETS; list. + + + +If there are no targets from the previous steps, +&scons; selects the current directory for scanning, +unless command-line options which affect the target +scan are detected (, +, , ). +Since targets thus selected were not the result of +user instructions, this target list is not made available +for direct inspection; use the +option if they need to be examined. + + + + +&scons; always adds to the selected targets any intermediate +targets which are necessary to build the specified ones. +For example, if constructing a shared library or dll from C +source files, &scons; will also build the object files which +will make up the library. + + + To ignore the default targets specified through calls to &Default; and instead build all @@ -377,11 +413,12 @@ also the related and options): requested, as &scons; needs to make sure any dependent files are built. -Specifying "cleanup" targets in SConscript files is not usually necessary. +Specifying "cleanup" targets in SConscript files is +usually not necessary. The -flag removes all files -necessary to build the specified target: +flag removes all selected targets: + scons -c . @@ -515,10 +552,11 @@ and many of those supported by cons. -Clean up by removing the specified targets and their -dependencies, as well as any files or directories associated -with the specified targets through calls to the &f-link-Clean; function. -Will not remove any targets specified by the &f-link-NoClean; function. +Clean up by removing the selected targets, +well as any files or directories associated +with a selected target through calls to the &f-link-Clean; function. +Will not remove any targets which are marked for +preservation through calls to the &f-link-NoClean; function. @@ -1449,6 +1487,7 @@ be appropriate for most uses. , + , , , -- cgit v0.12 From 1b2e8e9e8b5aaa938ef78a5d29e31ad4b514746a Mon Sep 17 00:00:00 2001 From: Daniel Date: Mon, 10 Aug 2020 10:37:31 -0500 Subject: fix issue where java parses class incorrectly from lambdas after new --- CHANGES.txt | 3 +++ SCons/Tool/JavaCommon.py | 3 ++- SCons/Tool/JavaCommonTests.py | 41 +++++++++++++++++++++++++++++++++++++++-- 3 files changed, 44 insertions(+), 3 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index b9835c9..fe45dc9 100755 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -24,6 +24,9 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER like zip(["test.zip"], ["zip_scons.py"]) and ignore ZIPCOMSTR if ZIPCOM and ZIPCOMSTR weren't set after the Environment/Tool is initialized. (Explained in PR #3659) + From Daniel Moody: + - Fix issue where java parsed a class incorrectly from lambdas used after a new. + From Mats Wichmann: - Complete tests for Dictionary, env.keys() and env.values() for OverrideEnvironment. Enable env.setdefault() method, add tests. diff --git a/SCons/Tool/JavaCommon.py b/SCons/Tool/JavaCommon.py index bb05977..d869b38 100644 --- a/SCons/Tool/JavaCommon.py +++ b/SCons/Tool/JavaCommon.py @@ -87,9 +87,10 @@ if java_parsing: # any alphanumeric token surrounded by angle brackets (generics); # the multi-line comment begin and end tokens /* and */; # array declarations "[]". + # Lambda function symbols: -> _reToken = re.compile(r'(\n|\\\\|//|\\[\'"]|[\'"{\};.()]|' + r'\d*\.\d*|[A-Za-z_][\w$.]*|<[A-Za-z_]\w+>|' + - r'/\*|\*/|\[\])') + r'/\*|\*/|\[\]|->)') class OuterState: diff --git a/SCons/Tool/JavaCommonTests.py b/SCons/Tool/JavaCommonTests.py index b0a788e..83354b8 100644 --- a/SCons/Tool/JavaCommonTests.py +++ b/SCons/Tool/JavaCommonTests.py @@ -97,7 +97,7 @@ public class Foo """Test class names with $ in them""" input = """\ -public class BadDep { +public class BadDep { public void new$rand () {} } """ @@ -484,6 +484,43 @@ public class NestedExample expect = [ 'NestedExample$1', 'NestedExample$1$1', 'NestedExample' ] assert expect == classes, (expect, classes) + def test_lambda_after_new(self): + """Test lamdas after new""" + + input = """\ +// import java.util.*; + +public class LamdaExample +{ + + public void testFunc (int arg1, String arg2, Runnable lambda){ + } + public LamdaExample() + { + testFunc( + 5, + new String("test"), + // Lambda symbol is after new, and used curly braces so + // we should not parse this as a new class. + () -> {} + ); + } + + + public static void main(String argv[]) + { + LamdaExample e = new LamdaExample(); + } +} +""" + pkg_dir, classes = SCons.Tool.JavaCommon.parse_java(input, '1.4') + expect = [ 'LamdaExample' ] + assert expect == classes, (expect, classes) + + pkg_dir, classes = SCons.Tool.JavaCommon.parse_java(input, '1.8') + expect = [ 'LamdaExample' ] + assert expect == classes, (expect, classes) + def test_private_inner_class_instantiation(self): """Test anonymous inner class generated by private instantiation""" @@ -532,7 +569,7 @@ class Broken * Detected. */ class InnerOK { InnerOK () { } } - + { System.out.println("a number: " + 1000.0 + ""); } -- cgit v0.12 From 1f726753e6776b6b9e0af8284f465dbeabaa2d53 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 15 Aug 2020 08:30:16 -0600 Subject: man: expand explanations on selecting Tool modules [ci skip] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 90 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 32 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 073b0d0..407118b 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -148,7 +148,10 @@ regardless of the actual file names or number of such files. looks for a directory named site_scons in various system directories and in the directory containing the -&SConstruct; file and prepends the ones it +&SConstruct; file +or, if specified, the +directory from the option instead, +and prepends the ones it finds to the Python module search path (sys.path), thus allowing modules in such directories to be imported in the normal Python way in SConscript files. @@ -2302,31 +2305,32 @@ See for details. Tools -&SCons; has a large number of predefined tools which -are used to help initialize the &consenv;, -and additional tools can be added. -An &scons; tool specification -is only responsible for setup. +&SCons; has a large number of predefined tools +(more properly, tool specifications) +which are used to help initialize the &consenv;. +An &scons; tool is only responsible for setup. For example, if the SConscript file declares the need to construct an object file from a C-language source file by calling the &b-link-Object; builder, then a tool representing an available C compiler needs to have run first, to set up the builder and all the &consvars; -it needs, in that &consenv;. Normally this +it needs in the associated &consenv;; the tool itself +is not called in the process of the build. Normally this happens invisibly: &scons; has per-platform lists of default tools, and it runs through those tools, -calling the ones which are actually applicable -(skipping those where necessary programs are not -installed on the build system, etc.). +calling the ones which are actually applicable, +skipping those where necessary programs are not +installed on the build system, or other preconditions are not met. A specific set of tools -with which to initialize the environment when +with which to initialize an environment when creating it may be specified using the optional keyword argument -tools. +tools, which takes a list +of tool names. This is useful to override the defaults, to specify non-default built-in tools, and to supply added tools: @@ -2336,7 +2340,7 @@ env = Environment(tools=['msvc', 'lex']) -Tools can also be called by using the &f-link-Tool; +Tools can also be directly called by using the &f-link-Tool; method (see below). @@ -2351,39 +2355,48 @@ The tool name 'default' can be used to retain the default list. -If no tools list is specified, -or the list includes 'default', -then &scons; will detect usable tools, -using the value of PATH -in the ENV &consvar; (not -the external PATH from os.environ) +If no tools argument is specified, +or if tools includes 'default', +then &scons; will auto-detect usable tools, +using the execution environment value of PATH +(that is, env['ENV']['PATH'] - +the external evironment PATH from os.environ +is not used) for looking up any backing programs, and the platform name in effect to determine the default tools for that platform. Changing the PATH variable after the &consenv; is constructed will not cause the tools to -be redetected. +be re-detected. -To help locate added tools, specify the -toolpath keyword argument: + +Additional tools can be added to a project either by +placing them in a site_tools subdirectory +of a site directory, or in a custom location specified to +&scons; by giving the +toolpath keyword argument. +toolpath also takes a list as its value: + env = Environment(tools=['default', 'foo'], toolpath=['tools']) -This looks for a tool specification in tools/foo.py +This looks for a tool specification module foo.py +in directory tools and in the standard locations, as well as using the ordinary default tools for the platform. -Tools in the toolpath are used in preference to -any of the built-in ones. For example, adding -a tool gcc.py to the toolpath -directory would override the built-in gcc tool. +Tools in a specified toolpath are used in preference to any other location; +tools in a site_tools directory are also +take precedence over built-in ones. For example, adding +a tool specification module gcc.py to the toolpath +directory would override the built-in &t-link-gcc; tool. The toolpath is stored in the environment and will be -picked up by subsequent calls to the -&f-Clone; and &f-Tool; methods: +used by subsequent calls to the &f-link-Tool; method, +as well as by &f-link-env-Clone;. @@ -2393,7 +2406,7 @@ derived.CustomBuilder() -A tool specification must include two functions: +A tool specification module must include two functions: @@ -2412,7 +2425,8 @@ to vary its initialization. exists(env) Return True if the tool can -be called. Usually this means looking up one or more +be called in the context of env. +Usually this means looking up one or more known programs using the PATH from the supplied env, but the tool can make the "exists" decision in any way it chooses. @@ -2421,6 +2435,18 @@ make the "exists" decision in any way it chooses. + + +At the moment, user-added tools do not automatically have their +exists function called. +As a result, it is recommended that the generate +function be defensively coded - that is, do not rely on any +necessary existence checks already having been performed. +This is expected to be a temporary limitation, +and the exists function should still be provided. + + + The elements of the tools list may also be functions or callable objects, in which case the &Environment; method @@ -6906,7 +6932,7 @@ script named The MinGW bin directory must be in your PATH environment variable or the -ENV['PATH'] &consvar; for &scons; +['ENV']['PATH'] &consvar; for &scons; to detect and use the MinGW tools. When running under the native Windows Python interpreter, &scons; will prefer the MinGW tools over the Cygwin tools, if they are both installed, regardless of the order of the bin -- cgit v0.12 From 28c58aaa3d34a37723a7d475495eb763ba51d009 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 17 Aug 2020 08:20:51 -0600 Subject: Update docs on documentation [ci skip] Signed-off-by: Mats Wichmann --- bin/SConsDoc.py | 36 ++++++++++++++++++------ doc/overview.rst | 86 +++++++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 96 insertions(+), 26 deletions(-) diff --git a/bin/SConsDoc.py b/bin/SConsDoc.py index ba9c923..baffbdc 100644 --- a/bin/SConsDoc.py +++ b/bin/SConsDoc.py @@ -41,9 +41,11 @@ Builder example: This is the summary description of an SCons Builder. It will get placed in the man page, and in the appropriate User's Guide appendix. - The name of any builder may be interpolated + The name of this builder may be interpolated anywhere in the document by specifying the - &b-BUILDER; element. It need not be on a line by itself. + &b-BUILDER; element. A link to this definition may be + interpolated by specifying the &b-link-BUILDER; element. + Unlike normal XML, blank lines are significant in these descriptions and serve to separate paragraphs. @@ -59,16 +61,28 @@ Builder example: Function example: - + (arg1, arg2, key=value) This is the summary description of an SCons function. It will get placed in the man page, and in the appropriate User's Guide appendix. - The name of any builder may be interpolated + If the "signature" attribute is specified, SIGTYPE may be one + of "global", "env" or "both" (the default if omitted is "both"), + to indicate the signature applies to the global form or the + environment form, or to generate both with the same signature + (excepting the insertion of "env."). + This allows for the cases of + describing that only one signature should be generated, + or both signatures should be generated and they differ, + or both signatures should be generated and they are the same. + The name of this function may be interpolated anywhere in the document by specifying the - &f-FUNCTION; element. It need not be on a line by itself. + &f-FUNCTION; element or the &f-env-FUNCTION; element. + Links to this definition may be interpolated by specifying + the &f-link-FUNCTION: or &f-link-env-FUNCTION; element. + print("this is example code, it will be offset and indented") @@ -83,9 +97,11 @@ Construction variable example: This is the summary description of a construction variable. It will get placed in the man page, and in the appropriate User's Guide appendix. - The name of any construction variable may be interpolated + The name of this construction variable may be interpolated anywhere in the document by specifying the - &t-VARIABLE; element. It need not be on a line by itself. + &cv-VARIABLE; element. A link to this definition may be + interpolated by specifying the &cv-link-VARIABLE; element. + print("this is example code, it will be offset and indented") @@ -100,9 +116,11 @@ Tool example: This is the summary description of an SCons Tool. It will get placed in the man page, and in the appropriate User's Guide appendix. - The name of any tool may be interpolated + The name of this tool may be interpolated anywhere in the document by specifying the - &t-TOOL; element. It need not be on a line by itself. + &t-TOOL; element. A link to this definition may be + interpolated by specifying the &t-link-TOOL; element. + print("this is example code, it will be offset and indented") diff --git a/doc/overview.rst b/doc/overview.rst index 9a2558a..74aa688 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -92,12 +92,19 @@ Entities ======== We are using entities for special keywords like ``SCons`` that should -appear with the same formatting throughout the text. These are kept in -a single file ``doc/scons.mod`` which gets included by the documents. - -Additionally, for each Tool, Builder, Cvar (construction variable) and -Function, a bunch of linkends in the form of entities get defined. They -can be used in the MAN page and the User manual. +appear with the same formatting throughout the text. This allows a +single place to make styling changes if needed. These are kept in +a single file ``doc/scons.mod`` which gets included by the documents, +and can be used anywhere in the documentation files. + +Additionally, for the definitions of the four special types available +in the SCons doctype - Tool, Builder, Construction Variable and Function - +a bunch of reference links in the form of entities are generated. +These entities can be used in the MAN page and the User manual. +Note that the four type tags themselves (````, ````, +```` and ````) can only be used in documentation +sources in the ``SCons`` directory; the build will not scan for these +in the ``doc`` directory. When you add an XML file in the ``SCons/Tools`` folder, e.g. for a tool named ``foobar``, you can use the two entities @@ -134,12 +141,12 @@ By calling the script :: python bin/docs-update-generated.py - + you can recreate the lists of entities (``*.mod``) in the ``generated`` -folder, if required. At the same time, this will generate the ``*.gen`` +folder. At the same time, this will generate the matching ``*.gen`` files, which list the full description of all the Builders, Tools, -Functions and CVars for the MAN page and the User Guide's appendix. -Thus, you want to regenerate when there's a change to +Functions and CVars for the MAN page and the User Guide's appendix. +Thus, you want to regenerate when there's a change to any of those four special elements, or an added or deleted element. These generated files are left checked in so in the normal case you can just rebuild the docs without having to first generate the entity @@ -150,14 +157,59 @@ refer to the start of the Python script ``bin/SConsDoc.py``. It explains the available tags and the exact syntax in detail. -Examples -======== +Linking +======= + +Normal Docbook (v4.5 style, as of this writing) in-document linking +is supported, as is linking to documents with a web address. +For any element in a document, you can include an ``id=name`` +attribute to set an identifier, and write a link to that identifier. +Many of the section headings already have such identifiers, +and it is fine to add more, as long as they remain unique. +As noted in the previous section, for the special types, +entities are generated which contain links, +so you can just use those entities instead +of writing the link reference manually. + +There is something to keep in mind about linking, however. +Cross-document links between the MAN page and the User Guide +do not work. But some text is shared between the two, which +allows the appearance of such linking, and this is where it +gets a little confusing. The text defined by the four special +types is generated into the ``*.gen`` files, +which get included both in the appropriate places in the MAN page, +and in the Appendix in the User Guide. Using entities within +this shared content is fine. Writing links in this shared +content to element identifiers defined elsewhere is not. + +That sounds a little confusing so here is a real example: +an xml source file in ``SCons`` defines the ``SCANNERS`` +construction variable by using `` ... ``. +This will generate the linking entity ``&cv-link-SCANNERS;``, +which can be used anywhere the ``doc/generated/variables.gen`` +file is included (i.e. MAN page and User Guide for now) +to leave a link to this definition. +But the text written inside the ``SCANNERS`` definition +also wants to refer to the "Builder Objects" and "Scanner +Objects" sections in the MAN page, as this contains relevant +further description. This reference should not include an +XML link, even though the MAN page defines the two identifiers +``scanner_objects`` and ``builder_objects``, because this +definition will *also* be included in the User Guide, which +has no such section names or identifiers. It is better here +to write it all in text, as in *See the manpage section +"Builder Objects"* than to leave a dangling reference in one +of the docs. + +SCons Examples +============== In the User Guide, we support automatically created examples. This means that the output of the specified source files and SConstructs is generated by running them with the current SCons version. We do this to ensure that the output displayed in the manual is identical to what -you get when you run the example on the command-line. +you get when you run the example on the command-line, without having +to remember to manually update the example outputs all the time. A short description about how these examples have to be defined can be found at the start of the file ``bin/SConsExamples.py``. Call @@ -212,17 +264,17 @@ User Guide. *generated* Entity lists and outputs of the UserGuide examples. They get generated - by the update scripts ``bin/docs-update-generated.py`` + by the update scripts ``bin/docs-update-generated.py`` and ``bin/docs-create-example-outputs.py``. *images* Images for the ``overview.rst`` document. - + *xsd* The SCons Docbook schema (XSD), based on the Docbook v4.5 DTD/XSD. - + *xslt* XSLT transformation scripts for converting the special SCons tags like ``scons_output`` to valid Docbook during document processing. - + -- cgit v0.12 From a566609d60b893e018926b178992030b783d697d Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 18 Aug 2020 11:00:10 -0600 Subject: Further tweak to tool location doc (toolpath vs. site_tools vs builtin) [ci skip] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 407118b..fc28e2a 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2388,12 +2388,15 @@ as well as using the ordinary default tools for the platform. -Tools in a specified toolpath are used in preference to any other location; -tools in a site_tools directory are also -take precedence over built-in ones. For example, adding +Directories specified via toolpath are prepended +to the existing tool path. The default tool path is any site_tools +directories, so tools in a specified toolpath +take priority, +followed by tools in a site_tools directory, +followed by built-in tools. For example, adding a tool specification module gcc.py to the toolpath directory would override the built-in &t-link-gcc; tool. -The toolpath is +The tool path is stored in the environment and will be used by subsequent calls to the &f-link-Tool; method, as well as by &f-link-env-Clone;. -- cgit v0.12