From 45aea2e73cf995dd6ff7578fcfd2502f046ebc19 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Sun, 14 Sep 2025 09:32:09 -0600 Subject: [PATCH 1/2] Builder method docs: sources and targets More harvesting of ideas from withdawn PR revising the manpage Builder Method section. This rewords the description of acceptable forms for the source and target arguments. Review of #4671 indicated that removing details the topic of absolute and relative paths unwanted, so this restores and expands on that section. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 149 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 116 insertions(+), 33 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 98544de2e..90b8e9b8e 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2881,6 +2881,112 @@ strings of white-space characters as the delimiter (similar to the &Python; string split method, but succeeds even if the input isn't a string). + +&SCons; can resolve paths to sources and targets +specified in several different forms. +The target and +source arguments +can be scalar (string or Node) or a collection (of strings or Nodes). + + + + +Nodes always work, +as they are the result of a previous successful path resolution; +if a path string is resolved correctly it is stored +internally as a Node in the dependency graph. + + + + +Plain file names (no pathname separators) +are searched for in the current directory. + + + + +Absolute paths (begin with a pathname separator) +are resolved by walking the path components +starting from root of the filesystem or current volume. + + + + +Relative paths (no leading pathname separator) +are resolved by walking the path components +starting from the current directory. + + + + +Top-relative paths are relative paths whose first character +is #. +They are walked starting from the project top-level directory +(usually, the directory where the &SConstruct; file is found). +Top-relative paths are always relative paths, +so the initial character can be followed by a pathname separator, +which is ignored and does not affect resolution. + + + + +UNC paths (Windows) start with exactly two pathname separators. +They take the form \\server_name\share_name\file_path. +The file_path portion is looked up as an +absolute path starting from the root of the +resource described by \\server_name\share_name. +Since UNC paths are never relative, +the top-relative path form does not apply. + + + + +URL-style strings and &Python; pathlib +objects are not recognized. + + + + + +The "current directory" for relative path resolution has options. +&SCons; by default changes to the directory containing the +&SConscript; file (including &SConstruct;) it is currently processing. +Use of the &f-link-SConscriptChdir; function toggles the +default behavior off/on. +The srcdir builder argument +affects where source file paths are looked for +(see details below). +Specifying one or more source code repositories via +the &f-link-Repository; function or the + +option tells &SCons; to look additional places +after the actual current directory. +The concept of current directory changes for targets +(and in some cases sources) if a variant directory is set up using +the &f-link-VariantDir; function or the variant_dir= +parameter to the &f-link-SConscript; function. +These options do not affect top-relative paths. + + + + +On Windows, DOS paths may beging with a volume or drive letter +followed by the volume separator (:). +The remainder of the path is absolute or relative; +if the volume specifier is present, +resolution starts at the root of the specified drive for absolute paths +and the current directory on the specified drive for relative paths. +The combination of a drive letter different from the +current drive and a relative path is ambiguous: +depending on context the current directory on +that drive may have been saved from outside the &SCons; process, +and is unknown to the &Python; interpreter, +so that form should be avoided. +Use of a drive letter in the path also precludes +the use of the top-relative form. + + + The following are equivalent examples of calling the &Program; builder method: @@ -2896,41 +3002,18 @@ env.Program(target='bar', source=env.Split('bar.c foo.c')) env.Program('bar', source='bar.c foo.c'.split()) +Additional examples of source and target paths: + + -Sources and targets can be specified as a scalar or as a list, -composed of either strings or nodes (more on nodes below). -When specifying path strings, -&Python; follows the POSIX pathname convention: -if a string begins with the operating system pathname separator -(on Windows both the slash and backslash separator are accepted, -and any leading drive specifier is ignored for -the determination) it is considered an absolute path, -otherwise it is a relative path. -If the path string contains no separator characters, -it is searched for as a file in the current directory. If it -contains separator characters, the search follows down -from the starting point, which is the top of the directory tree for -an absolute path and the current directory for a relative path. -The "current directory" in this context is the directory -of the &SConscript; file currently being processed. - - - -&SCons; also recognizes a third way to specify -path strings: if the string begins with -the # character it is -top-relative - it works like a relative path, but the -search follows down from the project top directory rather than -from the current directory. The # -can optionally be followed by a pathname separator, -which is ignored if found in that position. -Top-relative paths only work in places where &scons; will -interpret the path (see some examples below). To be -used in other contexts the string will need to be converted -to a relative or absolute path first. +Top-relative paths only work +where &SCons; will interpret the path (see examples). +To be used in other contexts the string must first be converted +to a relative or absolute path. +A suitable string can be extracted from the Node +created from the top-relative path. - -Examples: + # The comments describing the targets that will be built From 3bec232121c301034035176567ccb683e43bbc51 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 2 Oct 2025 13:26:01 -0600 Subject: [PATCH 2/2] builder-paths: address some review comments. Signed-off-by: Mats Wichmann --- doc/man/scons.xml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index 90b8e9b8e..43380292a 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -2970,18 +2970,18 @@ These options do not affect top-relative paths. -On Windows, DOS paths may beging with a volume or drive letter +On Windows, DOS paths may begin with a volume or drive letter followed by the volume separator (:). The remainder of the path is absolute or relative; if the volume specifier is present, resolution starts at the root of the specified drive for absolute paths and the current directory on the specified drive for relative paths. -The combination of a drive letter different from the -current drive and a relative path is ambiguous: -depending on context the current directory on -that drive may have been saved from outside the &SCons; process, -and is unknown to the &Python; interpreter, -so that form should be avoided. +If the specified drive letter is different than the +current drive, a relative path is missing context: +since &SCons; is a console (command-line) application, +it may inherit state from the terminal it was started in, +including saved current directories for other drives; +&SCons; has no way of knowing what those would be. Use of a drive letter in the path also precludes the use of the top-relative form.