From 57960ac7fa2e1cab770a834a386719f21947d558 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 7 Jan 2022 11:02:35 -0700 Subject: Add some info to User Guide on #/paths [skip appveyor] Signed-off-by: Mats Wichmann --- doc/generated/examples/hierarchy_hash_1.xml | 5 +++ doc/user/hierarchy.xml | 54 ++++++++++++++++++++++++++--- doc/user/separate.xml | 12 +++---- 3 files changed, 60 insertions(+), 11 deletions(-) create mode 100644 doc/generated/examples/hierarchy_hash_1.xml diff --git a/doc/generated/examples/hierarchy_hash_1.xml b/doc/generated/examples/hierarchy_hash_1.xml new file mode 100644 index 0000000..371746d --- /dev/null +++ b/doc/generated/examples/hierarchy_hash_1.xml @@ -0,0 +1,5 @@ +% scons -Q +path = #/include +force-interpreted path = include +scons: `.' is up to date. + diff --git a/doc/user/hierarchy.xml b/doc/user/hierarchy.xml index ec1864c..e63d230 100644 --- a/doc/user/hierarchy.xml +++ b/doc/user/hierarchy.xml @@ -303,8 +303,7 @@ SConscript(['display/SConscript', -SConscript(['prog1/SConscript', - 'prog2/SConscript']) +SConscript(['prog1/SConscript', 'prog2/SConscript']) env = Environment() @@ -384,7 +383,7 @@ x
- Top-Level Path Names in Subsidiary &SConscript; Files + Top-Relative Path Names in Subsidiary &SConscript; Files @@ -397,8 +396,7 @@ x You can tell &SCons; to interpret a path name as relative to the top-level &SConstruct; directory, not the local directory of the &SConscript; file, - by appending a &hash; (hash mark) - to the beginning of the path name: + by prepending a &hash; (hash mark) in front of the path name: @@ -446,6 +444,52 @@ x + + + A couple of notes on top-relative paths: + + + + + &SCons; doesn't care whether you add a slash after the &hash;. + Some people consider '#/lib/foo1.c' + more readable than '#lib/foo1.c', + but they're functionally equivalent. + + + + + + The top-relative syntax is only + evaluated by &SCons;, the &Python; language itself does not + understand about it. This becomes immediately obvious + if you like to use print for debugging, + or write a Python function that wants to evaluate a path. + You can force &SCons; to evaluate a top-relative path by + creating a Node object from it: + + + + + + + + +path = "#/include" + +print("path =", path) +print("force-interpreted path =", Entry(path)) + + + + Which shows: + + + scons -Q + + + +
diff --git a/doc/user/separate.xml b/doc/user/separate.xml index 236556d..cfb7c8b 100644 --- a/doc/user/separate.xml +++ b/doc/user/separate.xml @@ -55,12 +55,12 @@ and header files differ. If you build "Controller A" first, then "Controller B", on the second build everything would have to be rebuilt, because &SCons; sees that the build - instructions differ, and thus the targets that depend on those - different instructions are not valid for the current build. + instructions are different to the ones used to build the + existing targets, and thus the existing targets are invalid. Now when you go back and build for "Controller A", things have to be rebuilt from scratch again for the same reason. - However, if you can separate the places the output files - go, this problem can be avoided. + However, if you can separate the places the output files go, + this problem can be avoided. You can even set up to do both builds in one invocation of &SCons;. @@ -69,8 +69,8 @@ You can enable this separation by creating one or more variant directory trees - that are used to hold the built objects files, libraries, - and executable programs, etc. + that are used to perform the build in, and thus provide a unique + home for object files, libraries, and executable programs, etc. for a specific flavor, or variant, of build. &SCons; provides two ways to do this, one through the &f-link-SConscript; function that we've already seen, -- cgit v0.12 From 44f2157541e1ea5f1caa10a2bb089baeb164edcd Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Mon, 10 Jan 2022 07:40:51 -0700 Subject: Refine Uguide variantdir description [skip appveyor] Responding to review comment - and going a bit further. Signed-off-by: Mats Wichmann --- doc/user/separate.xml | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/doc/user/separate.xml b/doc/user/separate.xml index cfb7c8b..3b609f0 100644 --- a/doc/user/separate.xml +++ b/doc/user/separate.xml @@ -53,13 +53,14 @@ lot of code, so it makes sense to keep them in the same source tree, but certain build options in the source code and header files differ. If you build "Controller A" first, - then "Controller B", on the second build everything would - have to be rebuilt, because &SCons; sees that the build - instructions are different to the ones used to build the - existing targets, and thus the existing targets are invalid. + then "Controller B", on the "Controller B" build everything would + have to be rebuilt, because &SCons; recognizes that the build + instructions are different from those used in the "Controller A" + build for each target - the build instructions are part of + &SCons;'s out-of-date calculation. Now when you go back and build for "Controller A", things have to be rebuilt from scratch again for the same reason. - However, if you can separate the places the output files go, + However, if you can separate the locations of the output files, this problem can be avoided. You can even set up to do both builds in one invocation of &SCons;. @@ -67,11 +68,20 @@ - You can enable this separation by creating one or more + You can enable this separation by establishing one or more variant directory trees that are used to perform the build in, and thus provide a unique home for object files, libraries, and executable programs, etc. - for a specific flavor, or variant, of build. + for a specific flavor, or variant, of build. &SCons; tracks + targets by their path, so when the variant directory is included, + objects belonging to "Controller A" can have different + build instructions than those belonging to "Controller B" without + triggering ping-ponging rebuilds. + + + + + &SCons; provides two ways to do this, one through the &f-link-SConscript; function that we've already seen, and the second through a more flexible &f-link-VariantDir; function. -- cgit v0.12