From 9c7bbc0c9b88892e41d3490c5b745e0f7845d071 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 27 Sep 2021 08:52:42 -0600 Subject: Rework wording of {HOST,TAGET}_{ARCH_OS}. Also some wording tweaks on environment creation in manpage; Signed-off-by: Mats Wichmann --- SCons/Environment.py | 12 +-- SCons/Environment.xml | 27 +++-- SCons/Platform/Platform.xml | 235 +++++++++++++++++++++----------------------- doc/man/scons.xml | 29 ++++-- 4 files changed, 153 insertions(+), 150 deletions(-) diff --git a/SCons/Environment.py b/SCons/Environment.py index 4868e75..7713bb7 100644 --- a/SCons/Environment.py +++ b/SCons/Environment.py @@ -970,13 +970,13 @@ class Base(SubstitutionEnvironment): self._dict['PLATFORM'] = str(platform) platform(self) - self._dict['HOST_OS'] = self._dict.get('HOST_OS',None) - self._dict['HOST_ARCH'] = self._dict.get('HOST_ARCH',None) - - # Now set defaults for TARGET_{OS|ARCH} - self._dict['TARGET_OS'] = self._dict.get('TARGET_OS',None) - self._dict['TARGET_ARCH'] = self._dict.get('TARGET_ARCH',None) + # these should be set by the platform, backstop just in case + self._dict['HOST_OS'] = self._dict.get('HOST_OS', None) + self._dict['HOST_ARCH'] = self._dict.get('HOST_ARCH', None) + # these are not currently set by the platform, give them a default + self._dict['TARGET_OS'] = self._dict.get('TARGET_OS', None) + self._dict['TARGET_ARCH'] = self._dict.get('TARGET_ARCH', None) # Apply the passed-in and customizable variables to the # environment before calling the tools, because they may use diff --git a/SCons/Environment.xml b/SCons/Environment.xml index a21a8d7..43e3b25 100644 --- a/SCons/Environment.xml +++ b/SCons/Environment.xml @@ -3090,14 +3090,12 @@ and can be used to split a list of filenames (for example) rather than having to type them as a list of individually quoted words. If arg is a list or tuple -returns arg unchanged. -Use this form to specify strings where whitespace -should be preserved -(it is not necessary to call &f-Split; at all in this case, -but as a convenience it just works as a pass-through -so you don't have to check whether to call &f-Split; or not). +returns the list or tuple unchanged. If arg is any other type of object, returns a list containing just the object. +These non-string cases do not actually do any spliting, +but allow an argument variable to be passed to +&f-Split; without having to first check its type. @@ -3108,9 +3106,9 @@ Example: files = Split("f1.c f2.c f3.c") files = env.Split("f4.c f5.c f6.c") files = Split(""" - f7.c - f8.c - f9.c + f7.c + f8.c + f9.c """) @@ -3123,14 +3121,14 @@ files = Split(""" Performs construction variable interpolation -on the specified string or sequence argument -input. +on input, +which can be a string or a sequence. By default, leading or trailing white space will -be removed from the result. +be removed from the result, and all sequences of white space will be compressed to a single space character. Additionally, any @@ -3149,9 +3147,8 @@ The raw argument may be set to 2 -if you want to strip -all characters between -any +if you want to additionally discard +all characters between any $( and $) diff --git a/SCons/Platform/Platform.xml b/SCons/Platform/Platform.xml index ef516f1..08199f4 100644 --- a/SCons/Platform/Platform.xml +++ b/SCons/Platform/Platform.xml @@ -100,142 +100,135 @@ The suffix used for (static) object file names. - - -The name of the platform used to create the Environment. If no platform is -specified when the Environment is created, -&scons; -autodetects the platform. - - - -env = Environment(tools = []) + + + The name of the platform used to create this &consenv;. + &SCons; sets this when initializing the platform, + which by default is auto-detected + (see the platform + argument to &f-link-Environment;). + + + +env = Environment(tools=[]) if env['PLATFORM'] == 'cygwin': Tool('mingw')(env) else: Tool('msvc')(env) - - + + - - - The name of the host operating system. - Can be set when creating a &consenv; by passing as a keyword - argument in the &f-link-Environment; call; should not be - changed otherwise. - If not specified in the &f-Environment; call, will be set to - the defaults for the particular platform, which is in turn - auto-detected unless the platform - argument to &f-Environment; is given. - - - This &consvar; is informational and does not currently - affect construction activities. - - + + + The name of the host operating system for the platform + used to create this &consenv;. + The platform code sets this when initializing + (see &cv-link-PLATFORM; and the + platform argument to &f-link-Environment;). + + + Should be considered immutable. + &cv-HOST_OS; is not currently used by &SCons;, + but the option is reserved to do so in future + + - - - The name of the operating system compiled objects - created by this &consenv; should target. - Can be set when creating a &consenv; by passing as a keyword - argument in the &f-link-Environment; call; should not be - changed otherwise. - If not specified in the &f-Environment; call, will be set to - the defaults for the particular platform, which is in turn - auto-detected unless the platform - argument to &f-Environment; is given. - Defaults to the same value as &cv-HOST_OS;. - - - This &consvar; is informational and does not currently - affect construction activities. - - + + + The name of the operating system that objects + created using this &consenv; should target. + Can be set when creating a &consenv; by passing as a keyword + argument in the &f-link-Environment; call;. + + + &cv-TARGET_OS; is not currently used by &SCons; + but the option is reserved to do so in future + + - - - The name of the host hardware architecture. - Can be set when creating a &consenv; by passing as a keyword - argument in the &f-link-Environment; call; should not be - changed otherwise. - If not specified in the &f-Environment; call, will be set to - the defaults for the particular platform, which is in turn - auto-detected unless the platform - argument to &f-Environment; is given. - Note the detected value of the architecture may not be identical to - that from the &Python; platform.machine method. - - - On the Windows platform, if the Microsoft Visual C++ compiler - is available, &t-link-msvc; tool setup is done using - &cv-HOST_ARCH; and &cv-link-TARGET_ARCH;. Changing the values at - any later time will not cause the tool to be reinitialized. - Valid values for this usage are the same as for &cv-link-TARGET_ARCH;. - - - On other platforms, this &consvar; is informational and does - not currently affect construction activities. - - + + + The name of the host hardware architecture + used to create this &consenv;. + The platform code sets this when initializing + (see &cv-link-PLATFORM; and the + platform argument to &f-link-Environment;). + Note the detected name of the architecture may not be identical to + that returned by the &Python; + platform.machine method. + + + On the win32 platform, + if the Microsoft Visual C++ compiler is available, + &t-link-msvc; tool setup is done using + &cv-HOST_ARCH; and &cv-link-TARGET_ARCH;. + Changing the values at any later time will not cause + the tool to be reinitialized. + Valid host arch values are + x86 and arm + for 32-bit hosts and + amd64 and x86_64 + for 64-bit hosts. + + + Should be considered immutable. + &cv-HOST_ARCH; is not currently used by other platforms, + but the option is reserved to do so in future + + - - - The name of the hardware architecture compiled objects - created by this &consenv; should target. - Can be set when creating a &consenv; by passing as a keyword - argument in the &f-link-Environment; call; should not be - changed otherwise. - If not specified in the &f-Environment; call, will be set to - the defaults for the particular platform, which is in turn - auto-detected unless the platform - argument to &f-Environment; is given. - Defaults to the same value as &cv-link-HOST_ARCH;. - - - On the Windows platform, if the Microsoft Visual C++ compiler - is available, &t-link-msvc; tool setup is done using - &cv-link-HOST_ARCH; and &cv-TARGET_ARCH;. Changing the values at - any later time will not cause the tool to be reinitialized. - Compiled objects will be in the target architecture if - the compilation system supports generating for that target. - The latest compiler which can fulfill the requirement will - be selected, unless a different version is directed by the - value of the &cv-link-MSVC_VERSION; &consvar;. - - - On the Windows/msvc combination, valid target values are - x86, - arm, - i386 - for 32-bit targets and - amd64, - arm64, - em64t, - x86_64 - and ia64 (Itanium) - for 64-bit targets. - Note that not all target architectures are - supported for all Visual Studio / MSVC versions. - Check the relevant Microsoft documentation. - - - For example, if you want to compile 64-bit binaries, you would set - TARGET_ARCH='x86_64' when creating the &consenv;. - - - On other platforms, this &consvar; is informational and does - not currently affect construction activities. - - + + + The name of the hardware architecture that objects + created using this &consenv; should target. + Can be set when creating a &consenv; by passing as a keyword + argument in the &f-link-Environment; call. + + + On the win32 platform, + if the Microsoft Visual C++ compiler is available, + &t-link-msvc; tool setup is done using + &cv-link-HOST_ARCH; and &cv-TARGET_ARCH;. + If a value is not specified, + will be set to the same value as &cv-link-HOST_ARCH;. + Changing the value after the environment is initialized + will not cause the tool to be reinitialized. + Compiled objects will be in the target architecture if + the compilation system supports generating for that target. + The latest compiler which can fulfill the requirement will + be selected, unless a different version is directed by the + value of the &cv-link-MSVC_VERSION; &consvar;. + + + On the win32/msvc combination, valid target arch values are + x86, + arm, + i386 + for 32-bit targets and + amd64, + arm64, + x86_64 + and ia64 (Itanium) + for 64-bit targets. + For example, if you want to compile 64-bit binaries, you would set + TARGET_ARCH='x86_64' when creating the &consenv;. + Note that not all target architectures are + supported for all Visual Studio / MSVC versions. + Check the relevant Microsoft documentation. + + + &cv-TARGET_ARCH; is not currently used by other compilation tools, + but the option is reserved to do so in future + + @@ -342,7 +335,7 @@ or '-via' for ARM toolchain. The suffix for the name of the temporary file used to store command lines exceeding &cv-link-MAXLINELENGTH;. -The suffix shouldinclude the dot ('.') if one is wanted as +The suffix should include the dot ('.') if one is wanted as it will not be added automatically. The default is .lnk. diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 1f53892..f5c77c2 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2316,8 +2316,8 @@ env = Environment() &Consenv; attributes called &ConsVars; may be set either by specifying them as keyword arguments when the object is created -or by assigning them a value after the object is created. These two are -nominally equivalent: +or by assigning them a value after the object is created. +These two are nominally equivalent: env = Environment(FOO='foo') @@ -2326,13 +2326,26 @@ env['FOO'] = 'foo' Note that certain settings which affect tool detection are -referenced only during initialization, and so need to -be supplied as part of the call to &f-link-Environment;. -For example, setting &cv-link-MSVC_VERSION; in the &f-Environment; -call selects the version of Microsoft Visual C++ you wish to use, -but setting it after the &consenv; is constructed has no effect. +referenced only when the tools are initializided, +so you either need either to supply them as part of the call to +&f-link-Environment;, or defer tool initialization. +For example, initializing the Microsoft Visual C++ version you wish to use: + +# initializes msvc to v14.1 +env = Environment(MSVC_VERSION="14.1") + +env = Environment() +# msvc tool was initialized to default, does not reinitialize +env['MSVC_VERSION'] = "14.1" + +env = Environment(tools=[]) +env['MSVC_VERSION'] = "14.1" +# msvc tool initialization was deferred, so will pick up new value +env.Tool('default') + + As a convenience, &consvars; may also be set or modified by the parse_flags @@ -2440,7 +2453,7 @@ may bypass settings that should happen for the host system and should be used with care. It is most useful in the case where the platform is an alternative for the one that would be auto-detected, -such as cygwin +such as platform="cygwin" on a system which would otherwise identify as win32. -- cgit v0.12