From 91d46fc9be159ad0455b03eb00916bee3d2c3ee6 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 11 May 2021 11:11:29 -0600 Subject: Update the documentation for GetOption Since working on Get/SetOption anyway via tests, update the documentation as well. GetOption now has a table (instead of a spread out list) to match SetOption, and the available vars are all listed, as well as a note on AddOption'd vars. Signed-off-by: Mats Wichmann --- SCons/Script/Main.xml | 562 ++++++++++++++++++++--------------------- test/GetOption/GetSetOption.py | 3 +- test/GetOption/help.py | 6 +- 3 files changed, 282 insertions(+), 289 deletions(-) diff --git a/SCons/Script/Main.xml b/SCons/Script/Main.xml index ce21ee1..f4f4705 100644 --- a/SCons/Script/Main.xml +++ b/SCons/Script/Main.xml @@ -317,261 +317,242 @@ atexit.register(print_build_failures) This function provides a way to query the value of -SCons options set on scons command line -(or set using the -&f-link-SetOption; -function). -The options supported are: +options which can be set via the command line or using the +&f-link-SetOption; function. - - - - -cache_debug - - -which corresponds to ; - - - - -cache_disable - - -which corresponds to ; - - - - -cache_force - - -which corresponds to ; - - - - -cache_show - - -which corresponds to ; - - - - -clean - - -which corresponds to , -and ; - - - - -config - - -which corresponds to ; - - - - -directory - - -which corresponds to and ; - - - - -diskcheck - - -which corresponds to ; - - - - -duplicate - - -which corresponds to ; - - - - -file - - -which corresponds to , , and ; - - - - -help - - -which corresponds to and ; - - - - -ignore_errors - - -which corresponds to ; - - - - -implicit_cache - - -which corresponds to ; - - - - -implicit_deps_changed - - -which corresponds to ; - - - - -implicit_deps_unchanged - - -which corresponds to ; - - - - -interactive - - -which corresponds to and ; - - - - -keep_going - - -which corresponds to and ; - - - - -max_drift - - -which corresponds to ; - - - - -no_exec - - -which corresponds to , -, , - and ; - - - - -no_site_dir - - -which corresponds to ; - - - - -num_jobs - - -which corresponds to and ; - - - - -profile_file - - -which corresponds to ; - - - - -question - -which corresponds to and ; - - - - -random - - -which corresponds to ; - - - - -repository - - -which corresponds to , and ; - - - - -silent - - -which corresponds to , and ; - - - - -site_dir - - -which corresponds to ; - - - - -stack_size - - -which corresponds to ; - - - - -taskmastertrace_file - - -which corresponds to ; and - - - - -warn - - -which corresponds to and . - - - - +name can be an entry from the following table, +which shows the corresponding command line arguments +that could affect the value. +name 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. + + + + + Query name + Command-line options + Notes + + + + + + cache_debug + + + + cache_disable + + , + + + + + cache_force + + , + + + + + cache_readonly + + + + cache_show + + + + clean + + , + , + + + + + climb_up + + + + + + + + + + config + + + + debug + + + + directory + , + + + diskcheck + + + + duplicate + + + + enable_virtualenv + + + + experimental + + since 4.2 + + + file + + , + , + , + + + + + hash_format + + since 4.2 + + + help + , + + + ignore_errors + , + + + ignore_virtualenv + + + + implicit_cache + + + + implicit_deps_changed + + + + implicit_deps_unchanged + + + + include_dir + , + + + install_sandbox + + Available only if the &t-link-install; tool has been called + + + keep_going + , + + + max_drift + + + + md5_chunksize + + , + + + since 4.2 + + + no_exec + + , + , + , + , + + + + + no_progress + + + + num_jobs + , + + + package_type + + Available only if the &t-link-packaging; tool has been called + + + profile_file + + + + question + , + + + random + + + + repository + + , + , + + + + + silent + + , + , + + + + + site_dir + , + + + stack_size + + + + taskmastertrace_file + + + + tree_printers + + + + warn + , + + + + + + See the documentation for the corresponding command line option for information about each specific @@ -775,10 +756,22 @@ A value set via command-line option will take precedence over one set with &f-SetOption;, which allows setting a project default in the scripts and temporarily overriding it via command line. -Project-wide &f-SetOption; calls can also be placed in the site_init.py file. + + +See the documentation in the manpage for the +corresponding command line option for information about each specific option. +The value parameter is mandatory, +for option values which are boolean in nature +(that is, the command line option does not take an argument) +use a value +which evaluates to true (e.g. True, +1) or false (e.g. False, +0). + + Options which affect the reading and processing of SConscript files are not settable using &f-SetOption; since those files must @@ -796,9 +789,9 @@ The settable variables with their associated command-line options are: - Variable - Command-line options - Notes + Settable name + Command-line options + Notes @@ -831,7 +824,10 @@ The settable variables with their associated command-line options are: hash_chunksize - since 4.2 + + Actually sets md5_chunksize. + since 4.2 + @@ -848,21 +844,24 @@ The settable variables with their associated command-line options are: implicit_cache - since 4.2 implicit_deps_changed - Also sets implicit_cache - (since 4.2) + + Also sets implicit_cache. + (settable since 4.2) + implicit_deps_unchanged - Also sets implicit_cache - (since 4.2) + + Also sets implicit_cache. + (settable since 4.2) + @@ -889,6 +888,18 @@ The settable variables with their associated command-line options are: no_progress + See + + If no_progress is set via &f-SetOption; + in an SConscript file + (but not if set in a site_init.py file) + there will still be an initial status message about + reading SConscript files since &SCons; has + to start reading them before it can see the + &f-SetOption;. + + + @@ -903,7 +914,11 @@ The settable variables with their associated command-line options are: silent - + + , + , + + @@ -921,29 +936,6 @@ The settable variables with their associated command-line options are: -See the documentation in the manpage for the -corresponding command line option for information about each specific option. -The value parameter is mandatory, -for option values which are boolean in nature -(that is, the command line option does not take an argument) -use a value -which evaluates to true (e.g. True, -1) or false (e.g. False, -0). - - - - -If no_progress is set via &f-SetOption; -in an SConscript file, -there will still be initial progress output as &SCons; has -to start reading SConscript files before it can see the -&f-SetOption; in an SConscript file: -scons: Reading SConscript files ... - - - - Example: diff --git a/test/GetOption/GetSetOption.py b/test/GetOption/GetSetOption.py index e773ec6..3ab3e7b 100644 --- a/test/GetOption/GetSetOption.py +++ b/test/GetOption/GetSetOption.py @@ -32,7 +32,8 @@ import TestSCons test = TestSCons.TestSCons() test.write('SConstruct', """ -env = Environment() +DefaultEnvironment(tools=[]) +env = Environment(tools=[]) option_list = ['clean', 'implicit_cache', 'max_drift', 'num_jobs'] val = 1 for option in option_list: diff --git a/test/GetOption/help.py b/test/GetOption/help.py index ebca99f..4db4bc8 100644 --- a/test/GetOption/help.py +++ b/test/GetOption/help.py @@ -39,14 +39,14 @@ else: print("no help for you") """) -test.run(arguments = '-q -Q', stdout = "no help for you\n") +test.run(arguments='-q -Q', stdout="no help for you\n") expect = "GetOption('help') set" -test.run(arguments = '-q -Q -h') +test.run(arguments='-q -Q -h') test.fail_test(test.stdout().split('\n')[0] != expect) -test.run(arguments = '-q -Q --help') +test.run(arguments='-q -Q --help') test.fail_test(test.stdout().split('\n')[0] != expect) test.pass_test() -- cgit v0.12