From ac5f38d85dba2eb4f4c9569d4c2dc718a98d3888 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 22 Apr 2020 18:04:30 -0600 Subject: docs: update Tool description [ci skip] Tools is now is own subsection of Construction Environments, with an expanded description, also slightly reorganizing existing content. The description of the Tool function/method was also reworded to be more descriptive and less repetitive. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 155 ++++++++++++++++++++++++++------------- src/engine/SCons/Environment.xml | 75 +++++++++---------- 2 files changed, 142 insertions(+), 88 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index db173c5..49e09ce 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2179,28 +2179,75 @@ def my_platform(env): env = Environment(platform=my_platform) -Additionally, a specific set of tools -with which to initialize the environment + + + +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. +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 +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.). + + + +A specific set of tools +with which to initialize the environment when +creating it may be specified using the optional keyword argument -tools: +tools. +This is useful to override the defaults, +to specify non-default built-in tools, and +to supply added tools: env = Environment(tools=['msvc', 'lex']) +Tools can also be called by using the &f-link-Tool; +method (see below). + + + The tools argument overrides -the tool list, it does not add to it, so be +the default tool list, it does not add to it, so be sure to include all the tools you need. For example if you are building a c/c++ program -you must add a tool for both compiler and linker, +you must specify a tool for at least a compiler and a linker, as in tools=['clang', 'link']. The tool name 'default' can be used to retain the default list. -Non-built-in tools may be specified using the -optional toolpath keyword argument: +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) +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. + +To help locate added tools, specify the +toolpath keyword argument: env = Environment(tools=['default', 'foo'], toolpath=['tools']) @@ -2212,33 +2259,14 @@ as well as using the ordinary default tools for the platform. -A tool specification must include two functions: -generate(env, **kw) -and exists(env). -The -generate -function -modifies the environment referenced by env -to set up variables so that the tool -can be executed; -it may use any keyword arguments -that the user supplies in kw (see below) -to vary its initialization. -The -exists -function should return a true -value if the tool is available. - - - -Tools in the toolpath are used before +Tools in the toolpath are used in preference to any of the built-in ones. For example, adding -gcc.py to the toolpath -would override the built-in gcc tool. +a tool gcc.py to the toolpath +directory would override the built-in gcc tool. The toolpath is stored in the environment and will be picked up by subsequent calls to the -&Clone; and &Tool; methods: +&f-Clone; and &f-Tool; methods: @@ -2247,11 +2275,40 @@ derived = base.Clone(tools=['custom_tool']) derived.CustomBuilder() -The elements of the tools list may also + +A tool specification must include two functions: + + + + + generate(env, **kwargs) + +Modifies the environment referenced by env +to set up variables so that the facilities represented by +the tool can be executed. +It may use any keyword arguments +that the user supplies in kwargs +to vary its initialization. + + + + exists(env) + +Return True if the tool can +be called. 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. + + + + + +The elements of the tools list may also be functions or callable objects, -in which case the Environment() method -will call the specified elements -to update the new &consenv;: +in which case the &Environment; method +will call those objects +to update the new &consenv; (see &f-link-Tool; for more details): def my_tool(env): @@ -2260,9 +2317,9 @@ def my_tool(env): env = Environment(tools=[my_tool]) -The individual elements of the tools list -may also themselves be two-element lists of the form -(toolname, kw_dict). +The individual elements of the tools list +may also themselves be lists or tuples of the form +(toolname, kw_dict). SCons searches for the toolname specification file as described above, and @@ -2279,9 +2336,9 @@ or otherwise changing its initialization. # in tools/my_tool.py: -def generate(env, **kw): - # Sets MY_TOOL to the value of keyword argument 'arg1' or 1. - env['MY_TOOL'] = kw.get('arg1', '1') +def generate(env, **kwargs): + # Sets MY_TOOL to the value of keyword 'arg1' '1' if not supplied + env['MY_TOOL'] = kwargs.get('arg1', '1') def exists(env): return True @@ -2291,18 +2348,14 @@ env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})], toolpath=['tools']) -The tool definition (i.e. my_tool()) can use the PLATFORM variable from -the environment it receives to customize the tool for different platforms. - -If no tool list is specified, then SCons will auto-detect the installed -tools using the PATH variable in the ENV &consvar; and the -platform name when the Environment is constructed. Changing the PATH -variable after the Environment is constructed will not cause the tools to -be redetected. +The tool definition (my_tool in the example) +can use the +PLATFORM variable from +the &consenv; it is passed to customize the tool for different platforms. - One feature now present within Scons is the ability to have nested tools. -Tools which can be located within a subdirectory in the toolpath. -With a nested tool name the dot represents a directory seperator +Tools can be "nested" - that is, they +can be located within a subdirectory in the toolpath. +A nested tool name uses a dot to represent a directory seperator # namespaced builder diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml index 48980e2..5dea66e 100644 --- a/src/engine/SCons/Environment.xml +++ b/src/engine/SCons/Environment.xml @@ -3017,31 +3017,29 @@ source_nodes = env.subst('$EXPAND_TO_NODELIST', -(string, [toolpath, **kw]) +(name, [toolpath, **kwargs]) + -The -&f-Tool; -form of the function -returns a callable object -that can be used to initialize -a construction environment using the -tools keyword of the Environment() method. -The object may be called with a construction -environment as an argument, -in which case the object will -add the necessary variables -to the construction environment -and the name of the tool will be added to the -&cv-link-TOOLS; -construction variable. +Runs the tool identified by +name, which is +searched for in standard locations and any +paths specified by the optional +toolpath, +to update a &consenv; with &consvars; +needed to use the mechanisms that tool describes. +Any additional keyword arguments +kwargs are passed +on to the tool module's generate function. -Additional keyword arguments are passed to the tool's -generate() -method. +When called as a &consenv; method, +the tool module is called to update the +&consenv; and the name of the tool is +appended to the &cv-link-TOOLS; +&consvar; in that environment. @@ -3049,33 +3047,36 @@ Examples: -env = Environment(tools = [ Tool('msvc') ]) - -env = Environment() -t = Tool('msvc') -t(env) # adds 'msvc' to the TOOLS variable -u = Tool('opengl', toolpath = ['tools']) -u(env) # adds 'opengl' to the TOOLS variable +env.Tool('gcc') +env.Tool('opengl', toolpath=['build/tools']) -The -&f-env-Tool; -form of the function -applies the callable object for the specified tool -string -to the environment through which the method was called. +When called as a global function, +returns a callable tool object; +the tool is not called at this time, +as it lacks the context of an environment to update. +This tool object can be passed to an +&f-link-Environment; or &f-link-Clone; call +as part of the tools keyword argument, +or it can be called directly, +passing a &consenv; to update as the argument. +Either approach will also update the +TOOLS &consvar;. -Additional keyword arguments are passed to the tool's -generate() -method. +Examples: -env.Tool('gcc') -env.Tool('opengl', toolpath = ['build/tools']) +env = Environment(tools=[Tool('msvc')]) + +env = Environment() +t = Tool('msvc') +t(env) # adds 'msvc' to the TOOLS variable +u = Tool('opengl', toolpath = ['tools']) +u(env) # adds 'opengl' to the TOOLS variable -- cgit v0.12 From eb33c9cb44f91356a40b108606ee2a03ec93cadc Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Wed, 22 Apr 2020 19:00:54 -0600 Subject: Fix typo "seperator" caught by sider [ci skip] Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 49e09ce..c201f05 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2355,7 +2355,7 @@ the &consenv; it is passed to customize the tool for different platforms. Tools can be "nested" - that is, they can be located within a subdirectory in the toolpath. -A nested tool name uses a dot to represent a directory seperator +A nested tool name uses a dot to represent a directory separator # namespaced builder -- cgit v0.12