Skip to content

Builder method docs: sources and targets #4766

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+116 −33
Open

Builder method docs: sources and targets #4766

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
45aea2e
Builder method docs: sources and targets
mwichmann Sep 14, 2025
3bec232
builder-paths: address some review comments.
mwichmann Oct 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 116 additions & 33 deletions doc/man/scons.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2881,6 +2881,112 @@ strings of white-space characters as the delimiter
(similar to the &Python; string <function>split</function>
method, but succeeds even if the input isn't a string).</para>

<para>
&SCons; can resolve paths to sources and targets
specified in several different forms.
The <parameter>target</parameter> and
<parameter>source</parameter> arguments
can be scalar (string or Node) or a collection (of strings or Nodes).
</para>
<itemizedlist>
<listitem>
<para>
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.
</para>
</listitem>
<listitem>
<para>
Plain file names (no pathname separators)
are searched for in the current directory.
</para>
</listitem>
<listitem>
<para>
Absolute paths (begin with a pathname separator)
are resolved by walking the path components
starting from root of the filesystem or current volume.
</para>
</listitem>
<listitem>
<para>
Relative paths (no leading pathname separator)
are resolved by walking the path components
starting from the current directory.
</para>
</listitem>
<listitem>
<para>
Top-relative paths are relative paths whose first character
is <emphasis role="bold">#</emphasis>.
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.
</para>
</listitem>
<listitem>
<para>
UNC paths (Windows) start with exactly two pathname separators.
They take the form <literal>\\server_name\share_name\file_path</literal>.
The <varname>file_path</varname> portion is looked up as an
absolute path starting from the root of the
resource described by <literal>\\server_name\share_name</literal>.
Since UNC paths are never relative,
the top-relative path form does not apply.
</para>
</listitem>
<listitem>
<para>
URL-style strings and &Python; <systemitem>pathlib</systemitem>
objects are not recognized.
</para>
</listitem>
</itemizedlist>

<para>
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 <parameter>srcdir</parameter> 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
<link linkend="opt-repository"><option>-Y/--repository</option></link>
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 <parameter>variant_dir=</parameter>
parameter to the &f-link-SConscript; function.
These options do not affect top-relative paths.
</para>

<note>
<para>
On Windows, DOS paths may begin with a volume or drive letter
followed by the volume separator (<literal>:</literal>).
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.
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.
</para>
</note>

<para>
The following are equivalent examples of calling the
&Program; builder method:
Expand All @@ -2896,41 +3002,18 @@ env.Program(target='bar', source=env.Split('bar.c foo.c'))
env.Program('bar', source='bar.c foo.c'.split())
</programlisting>

<para>Additional examples of source and target paths:</para>

<note>
<para>
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.
</para>

<para>
&SCons; also recognizes a third way to specify
path strings: if the string begins with
the <emphasis role="bold">#</emphasis> character it is
<firstterm>top-relative</firstterm> - it works like a relative path, but the
search follows down from the project top directory rather than
from the current directory. The <emphasis role="bold">#</emphasis>
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 <emphasis role="bold">only</emphasis> 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.
</para>

<para>Examples:</para>
</note>

<programlisting language="python">
# The comments describing the targets that will be built
Expand Down
Loading