From e65ced18e9bc02fdb3c4e3166821f96cf5cf9ff9 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sat, 25 Apr 2020 13:33:22 -0600 Subject: docs: build up description of export/import/return [ci skip] User Guide wording missed some details - one of which is mentioned in an issue. Fixes #798. Signed-off-by: Mats Wichmann --- doc/user/hierarchy.xml | 141 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 97 insertions(+), 44 deletions(-) diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index e5a8470..b54e2a5 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -508,7 +508,7 @@ x In the previous example, each of the subsidiary &SConscript; files created its own construction environment - by calling &Environment; separately. + by calling &f-link-Environment; separately. This obviously works fine, but if each program must be built with the same construction variables, @@ -521,10 +521,10 @@ x - &SCons; supports the ability to export variables - from a parent &SConscript; file - to its subsidiary &SConscript; files, - which allows you to share common initialized + &SCons; supports the ability to export variables + from an &SConscript; file + so they can be imported by other + &SConscript; files, thus allowing you to share common initialized values throughout your build hierarchy. @@ -534,17 +534,13 @@ x - There are two ways to export a variable, - such as a construction environment, - from an &SConscript; file, - so that it may be used by other &SConscript; files. - First, you can call the &Export; - function with a list of variables, - or a string of white-space separated variable names. - Each call to &Export; adds one - or more variables to a global list - of variables that are available for import - by other &SConscript; files. + There are two ways to export a variable + from an &SConscript; file. + The first way is to call the &f-link-Export; function. + &Export; takes one or more arguments that are + string representations of the variable names - that is, + to export the variable env, + you supply the string env to &Export;: @@ -567,9 +563,9 @@ Export('env', 'debug') - Because white space is not legal in Python variable names, - the &Export; function will even automatically split - a string into separate names for you: + Beacuse a Python identifier cannot contain spaces, + &Export; assumes a string containing spaces is multiple + variable names to export and splits it for you: @@ -579,9 +575,42 @@ Export('env debug') - Second, you can specify a list of - variables to export as a second argument - to the &SConscript; function call: + &Export; will also accept arguments in keyword style. + This style can be used, for example, to set variables + that have not been set by name in the SConscript file, + and thus the keys are the intended variable names, + not a string representation: + + + + +Export(MODE="DEBUG", TARGET="arm") + + + + + The styles can be mixed, however note that Python function calling + syntax requires all non-keyword arguments to precede any + keyword arguments in the call. + + + + + + The &Export; function adds the variables to a global + location from which other &SConscript; files can import. + Exporting conceptually works the same as Python assignment + statements - if you assign a name to something, then later assign + the same name to something else, the reference to the original + is lost. + + + + + + The other way to export is you can specify a list of + variables as a second argument + to the &f-link-SConscript; function call: @@ -591,7 +620,7 @@ SConscript('src/SConscript', 'env') - Or as the &exports; keyword argument: + Or (preferably, for readability) as the &exports; keyword argument: @@ -602,7 +631,7 @@ SConscript('src/SConscript', exports='env') These calls export the specified variables - to only the listed &SConscript; files. + to only the listed &SConscript; file. You may, however, specify more than one &SConscript; file in a list: @@ -632,7 +661,7 @@ SConscript(['src1/SConscript', Once a variable has been exported from a calling &SConscript; file, it may be used in other &SConscript; files - by calling the &Import; function: + by calling the &f-link-Import; function: @@ -643,43 +672,66 @@ env.Program('prog', ['prog.c']) - The &Import; call makes the env construction - environment available to the &SConscript; file, - after which the variable can be used to build - programs, libraries, etc. + The &Import; call makes the previously defined env + variable available to the &SConscript; file. + Assuming env is a &consenv;, + after import it can be used to build programs, libraries, etc. + The use case of passing around a &consenv; is extremely common + in larger &scons; builds. Like the &Export; function, - the &Import; function can be used + the &Import; function can be called with multiple variable names: Import('env', 'debug') -env = env.Clone(DEBUG = debug) +env = env.Clone(DEBUG=debug) env.Program('prog', ['prog.c']) + + + + In this example, we pull in the common &consenv; + env, and + use the value of the debug + variable to make a modified copy by passing + that to a &f-link-Clone; call. + + - And the &Import; function will similarly - split a string along white-space + The &Import; function will (like &Export;) + split a string containing white-space into separate variable names: Import('env debug') -env = env.Clone(DEBUG = debug) +env = env.Clone(DEBUG=debug) env.Program('prog', ['prog.c']) + &Import; prefers a local defintion to a global one, + so that if there is a global export of foo, + and the calling SConscript has + exported foo to this SConscript, + the import will find the foo + exported to this SConscript. + + + + + Lastly, as a special case, you may import all of the variables that have been exported by supplying an asterisk @@ -689,7 +741,7 @@ env.Program('prog', ['prog.c']) Import('*') -env = env.Clone(DEBUG = debug) +env = env.Clone(DEBUG=debug) env.Program('prog', ['prog.c']) @@ -713,13 +765,14 @@ env.Program('prog', ['prog.c']) &SConscript; file in some way. For example, suppose that you want to create one - library from source files - scattered throughout a number - of subsidiary &SConscript; files. - You can do this by using the &Return; + library from object files built by + several subsidiary &SConscript; files. + You can do this by using the &f-link-Return; function to return values from the subsidiary &SConscript; files - to the calling file. + to the calling file. Like &Import; and &Export;, + &Return; takes a string representation of the variable + name, not the variable name itself. @@ -727,8 +780,8 @@ env.Program('prog', ['prog.c']) If, for example, we have two subdirectories &foo; and &bar; - that should each contribute a source - file to a Library, + that should each contribute an object + file to a library, what we'd like to be able to do is collect the object files from the subsidiary &SConscript; calls @@ -770,7 +823,7 @@ void bar(void) { printf("bar/bar.c\n"); } We can do this by using the &Return; function in the - foo/SConscript file like this: + foo/SConscript file like this: @@ -780,7 +833,7 @@ void bar(void) { printf("bar/bar.c\n"); } (The corresponding - bar/SConscript + bar/SConscript file should be pretty obvious.) Then when we run &SCons;, the object files from the subsidiary subdirectories -- cgit v0.12