Skip to content

Commit 801af4e

Browse files
bdbaddogbdbaddog
committed
Regenerated docs for 4.7.0 release
1 parent 84240a0 commit 801af4e

File tree

6 files changed

+116
-79
lines changed

6 files changed

+116
-79
lines changed

‎doc/generated/builders.gen

Lines changed: 41 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -2216,13 +2216,24 @@ env.RPCGenClient('src/rpcif.x')
22162216
<term><replaceable>env</replaceable>.<methodname>SharedLibrary</methodname>()</term>
22172217
<listitem><para>
22182218
Builds a shared library
2219-
(<filename>.so</filename> on a POSIX system,
2220-
<filename>.dll</filename> on Windows)
22212219
given one or more object files
2222-
or C, C++, D or Fortran source files.
2223-
If any source files are given,
2224-
then they will be automatically
2225-
compiled to object files.
2220+
and/or C, C++, D or Fortran source files.
2221+
Any source files listed in the
2222+
<parameter>source</parameter> parameter
2223+
will be automatically
2224+
compiled to object files suitable
2225+
for use in a shared library.
2226+
Any object files listed in the
2227+
<parameter>source</parameter> parameter
2228+
must have been built for a shared library
2229+
(that is, using the
2230+
&b-SharedObject;
2231+
builder method).
2232+
&scons;
2233+
will raise an error if there is any mismatch.
2234+
</para>
2235+
2236+
<para>
22262237
The target library file prefix,
22272238
specified by the &cv-link-SHLIBPREFIX; &consvar;
22282239
(by default, <filename>lib</filename> on POSIX systems,
@@ -2231,7 +2242,13 @@ and suffix,
22312242
specified by the &cv-link-SHLIBSUFFIX; &consvar;
22322243
(by default, <filename>.dll</filename> on Windows systems,
22332244
<filename>.so</filename> on POSIX systems),
2234-
are automatically added to the target if not already present.
2245+
are automatically added (if not already present)
2246+
to the target name to make up the library filename.
2247+
On a POSIX system, if the &cv-link-SHLIBVERSION; &consvar; is set,
2248+
it is appended (following a period) to the resulting library name.
2249+
</para>
2250+
2251+
<para>
22352252
Example:
22362253
</para>
22372254

@@ -2261,16 +2278,6 @@ if there is not already a <filename>.dll.a</filename> file explicitly
22612278
listed in the targets.
22622279
</para>
22632280

2264-
<para>
2265-
Any object files listed in the
2266-
<parameter>source</parameter>
2267-
must have been built for a shared library
2268-
(that is, using the
2269-
&b-SharedObject;
2270-
builder method).
2271-
&scons;
2272-
will raise an error if there is any mismatch.
2273-
</para>
22742281

22752282
<para>
22762283
On some platforms, there is a distinction between a shared library
@@ -2280,7 +2287,7 @@ For maximum portability, use the &b-link-LoadableModule; builder for the latter.
22802287
</para>
22812288

22822289
<para>
2283-
When the &cv-link-SHLIBVERSION; &consvar; is defined, a versioned
2290+
If &cv-link-SHLIBVERSION; is defined, a versioned
22842291
shared library is created. This modifies &cv-link-SHLINKFLAGS; as required,
22852292
adds the version number to the library name, and creates any
22862293
symbolic links that are needed.
@@ -2291,17 +2298,25 @@ env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
22912298
</example_commands>
22922299

22932300
<para>
2294-
On a POSIX system, versions with a single token create exactly one symlink:
2295-
<filename>libbar.so.6</filename> would have symlink <filename>libbar.so</filename> only.
2296-
On a POSIX system, versions with two or more
2297-
tokens create exactly two symlinks: <filename>libbar.so.2.3.1</filename> would have symlinks
2298-
<filename>libbar.so</filename> and <filename>libbar.so.2</filename>; on a Darwin (OSX) system the library would be
2299-
<filename>libbar.2.3.1.dylib</filename> and the link would be <filename>libbar.dylib</filename>.
2301+
On a POSIX system, supplying a simple version string (no dots)
2302+
creates exactly one symbolic link: <literal>SHLIBVERSION="1"</literal>
2303+
would create (for example) library <filename>libbar.so.1</filename>
2304+
and symbolic link <filename>libbar.so</filename>.
2305+
Supplying a dotted version string will create two symbolic links
2306+
(irrespective of the number of segments in the version):
2307+
<literal>SHLIBVERSION="1.5.2"</literal> for the same library
2308+
would create library <filename>libbar.so.1.5.2</filename>
2309+
and symbolic links <filename>libbar.so</filename> and
2310+
<filename>libbar.so.1</filename>. A Darwin (OSX)
2311+
system creates one symlink in either case,
2312+
for the second example the library would be
2313+
<filename>libbar.1.5.2.dylib</filename>
2314+
and the link would be <filename>libbar.dylib</filename>.
23002315
</para>
23012316

23022317
<para>
2303-
On Windows systems, specifying
2304-
<parameter>register=1</parameter>
2318+
On Windows systems, specifying the
2319+
<parameter>register=1</parameter> keyword argument
23052320
will cause the <filename>.dll</filename> to be
23062321
registered after it is built.
23072322
The command that is run is determined by the &cv-link-REGSVR; &consvar;

‎doc/generated/examples/caching_ex-random_1.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
cc -o f3.o -c f3.c
33
cc -o f5.o -c f5.c
44
cc -o f4.o -c f4.c
5-
cc -o f2.o -c f2.c
65
cc -o f1.o -c f1.c
6+
cc -o f2.o -c f2.c
77
cc -o prog f1.o f2.o f3.o f4.o f5.o
88
</screen>

‎doc/generated/examples/troubleshoot_explain1_3.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,5 @@
22
cp file.in file.oout
33

44
scons: warning: Cannot find target file.out after building
5-
File "/Users/bdbaddog/devel/scons/git/mwichmann/scripts/scons.py", line 97, in &lt;module&gt;
5+
File "/Users/bdbaddog/devel/scons/git/as_scons/scripts/scons.py", line 97, in &lt;module&gt;
66
</screen>

‎doc/generated/examples/troubleshoot_taskmastertrace_1.xml

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
<screen xmlns="http://www.scons.org/dbxsd/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">% <userinput>scons -Q --taskmastertrace=- prog</userinput>
2-
Job.NewParallel._work(): [Thread:8453497088] Gained exclusive access
3-
Job.NewParallel._work(): [Thread:8453497088] Starting search
4-
Job.NewParallel._work(): [Thread:8453497088] Found 0 completed tasks to process
5-
Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks
2+
Job.NewParallel._work(): [Thread:8149967104] Gained exclusive access
3+
Job.NewParallel._work(): [Thread:8149967104] Starting search
4+
Job.NewParallel._work(): [Thread:8149967104] Found 0 completed tasks to process
5+
Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks
66

77
Taskmaster: Looking for a node to evaluate
88
Taskmaster: Considering node &lt;no_state 0 'prog'&gt; and its children:
@@ -18,25 +18,25 @@ Taskmaster: Evaluating &lt;pending 0 'prog.c'&gt;
1818

1919
Task.make_ready_current(): node &lt;pending 0 'prog.c'&gt;
2020
Task.prepare(): node &lt;up_to_date 0 'prog.c'&gt;
21-
Job.NewParallel._work(): [Thread:8453497088] Found internal task
21+
Job.NewParallel._work(): [Thread:8149967104] Found internal task
2222
Task.executed_with_callbacks(): node &lt;up_to_date 0 'prog.c'&gt;
2323
Task.postprocess(): node &lt;up_to_date 0 'prog.c'&gt;
2424
Task.postprocess(): removing &lt;up_to_date 0 'prog.c'&gt;
2525
Task.postprocess(): adjusted parent ref count &lt;pending 1 'prog.o'&gt;
26-
Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks
26+
Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks
2727

2828
Taskmaster: Looking for a node to evaluate
2929
Taskmaster: Considering node &lt;no_state 0 'inc.h'&gt; and its children:
3030
Taskmaster: Evaluating &lt;pending 0 'inc.h'&gt;
3131

3232
Task.make_ready_current(): node &lt;pending 0 'inc.h'&gt;
3333
Task.prepare(): node &lt;up_to_date 0 'inc.h'&gt;
34-
Job.NewParallel._work(): [Thread:8453497088] Found internal task
34+
Job.NewParallel._work(): [Thread:8149967104] Found internal task
3535
Task.executed_with_callbacks(): node &lt;up_to_date 0 'inc.h'&gt;
3636
Task.postprocess(): node &lt;up_to_date 0 'inc.h'&gt;
3737
Task.postprocess(): removing &lt;up_to_date 0 'inc.h'&gt;
3838
Task.postprocess(): adjusted parent ref count &lt;pending 0 'prog.o'&gt;
39-
Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks
39+
Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks
4040

4141
Taskmaster: Looking for a node to evaluate
4242
Taskmaster: Considering node &lt;pending 0 'prog.o'&gt; and its children:
@@ -46,19 +46,19 @@ Taskmaster: Evaluating &lt;pending 0 'prog.o'&gt;
4646

4747
Task.make_ready_current(): node &lt;pending 0 'prog.o'&gt;
4848
Task.prepare(): node &lt;executing 0 'prog.o'&gt;
49-
Job.NewParallel._work(): [Thread:8453497088] Found task requiring execution
50-
Job.NewParallel._work(): [Thread:8453497088] Executing task
49+
Job.NewParallel._work(): [Thread:8149967104] Found task requiring execution
50+
Job.NewParallel._work(): [Thread:8149967104] Executing task
5151
Task.execute(): node &lt;executing 0 'prog.o'&gt;
5252
cc -o prog.o -c -I. prog.c
53-
Job.NewParallel._work(): [Thread:8453497088] Enqueueing executed task results
54-
Job.NewParallel._work(): [Thread:8453497088] Gained exclusive access
55-
Job.NewParallel._work(): [Thread:8453497088] Starting search
56-
Job.NewParallel._work(): [Thread:8453497088] Found 1 completed tasks to process
53+
Job.NewParallel._work(): [Thread:8149967104] Enqueueing executed task results
54+
Job.NewParallel._work(): [Thread:8149967104] Gained exclusive access
55+
Job.NewParallel._work(): [Thread:8149967104] Starting search
56+
Job.NewParallel._work(): [Thread:8149967104] Found 1 completed tasks to process
5757
Task.executed_with_callbacks(): node &lt;executing 0 'prog.o'&gt;
5858
Task.postprocess(): node &lt;executed 0 'prog.o'&gt;
5959
Task.postprocess(): removing &lt;executed 0 'prog.o'&gt;
6060
Task.postprocess(): adjusted parent ref count &lt;pending 0 'prog'&gt;
61-
Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks
61+
Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks
6262

6363
Taskmaster: Looking for a node to evaluate
6464
Taskmaster: Considering node &lt;pending 0 'prog'&gt; and its children:
@@ -67,21 +67,21 @@ Taskmaster: Evaluating &lt;pending 0 'prog'&gt;
6767

6868
Task.make_ready_current(): node &lt;pending 0 'prog'&gt;
6969
Task.prepare(): node &lt;executing 0 'prog'&gt;
70-
Job.NewParallel._work(): [Thread:8453497088] Found task requiring execution
71-
Job.NewParallel._work(): [Thread:8453497088] Executing task
70+
Job.NewParallel._work(): [Thread:8149967104] Found task requiring execution
71+
Job.NewParallel._work(): [Thread:8149967104] Executing task
7272
Task.execute(): node &lt;executing 0 'prog'&gt;
7373
cc -o prog prog.o
74-
Job.NewParallel._work(): [Thread:8453497088] Enqueueing executed task results
75-
Job.NewParallel._work(): [Thread:8453497088] Gained exclusive access
76-
Job.NewParallel._work(): [Thread:8453497088] Starting search
77-
Job.NewParallel._work(): [Thread:8453497088] Found 1 completed tasks to process
74+
Job.NewParallel._work(): [Thread:8149967104] Enqueueing executed task results
75+
Job.NewParallel._work(): [Thread:8149967104] Gained exclusive access
76+
Job.NewParallel._work(): [Thread:8149967104] Starting search
77+
Job.NewParallel._work(): [Thread:8149967104] Found 1 completed tasks to process
7878
Task.executed_with_callbacks(): node &lt;executing 0 'prog'&gt;
7979
Task.postprocess(): node &lt;executed 0 'prog'&gt;
80-
Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks
80+
Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks
8181

8282
Taskmaster: Looking for a node to evaluate
8383
Taskmaster: No candidate anymore.
84-
Job.NewParallel._work(): [Thread:8453497088] Found no task requiring execution, and have no jobs: marking complete
85-
Job.NewParallel._work(): [Thread:8453497088] Gained exclusive access
86-
Job.NewParallel._work(): [Thread:8453497088] Completion detected, breaking from main loop
84+
Job.NewParallel._work(): [Thread:8149967104] Found no task requiring execution, and have no jobs: marking complete
85+
Job.NewParallel._work(): [Thread:8149967104] Gained exclusive access
86+
Job.NewParallel._work(): [Thread:8149967104] Completion detected, breaking from main loop
8787
</screen>

‎doc/generated/functions.gen

Lines changed: 32 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -564,7 +564,7 @@ In this case, space-separated strings are not split.</para>
564564
</listitem>
565565
<listitem>
566566
<para>A dictionary is processed in order,
567-
adding each key:value pair as a valued macro.
567+
adding each key-value pair as a valued macro.
568568
Use the value <constant>None</constant> if the macro should not have a value.
569569
</para>
570570
</listitem>
@@ -649,7 +649,7 @@ Appending a string <parameter>val</parameter>
649649
to a dictonary-typed &consvar; enters
650650
<parameter>val</parameter> as the key in the dictionary,
651651
and <literal>None</literal> as its value.
652-
Using a tuple type to supply a <literal>key, value</literal>
652+
Using a tuple type to supply a key-value pair
653653
only works for the special case of &cv-CPPDEFINES;
654654
described above.
655655
</para>
@@ -2851,35 +2851,38 @@ Returns a list of the target Node or Nodes.
28512851
<listitem><para>
28522852
Merges values from
28532853
<parameter>arg</parameter>
2854-
into &consvars; in the current &consenv;.
2855-
If
2856-
<parameter>arg</parameter>
2854+
into &consvars; in <parameter>env</parameter>.
2855+
If <parameter>arg</parameter> is a dictionary,
2856+
each key-value pair represents a
2857+
&consvar; name and the corresponding flags to merge.
2858+
If <parameter>arg</parameter>
28572859
is not a dictionary,
2858-
it is converted to one by calling
2859-
&f-link-env-ParseFlags;
2860-
on the argument
2860+
&MergeFlags; attempts to convert it to one
28612861
before the values are merged.
2862-
Note that
2862+
&f-link-env-ParseFlags; is used for this,
2863+
so values to be converted are subject to the
2864+
same limitations:
2865+
&ParseFlags; has knowledge of which &consvars; certain
2866+
flags should go to, but not all;
2867+
and only for GCC and compatible compiler chains.
28632868
<parameter>arg</parameter>
2864-
must be a single value,
2865-
so multiple strings must
2866-
be passed in as a list,
2867-
not as separate arguments to
2868-
&f-env-MergeFlags;.
2869+
must be a single object,
2870+
so to pass multiple strings,
2871+
enclose them in a list.
28692872
</para>
28702873

28712874
<para>
28722875
If <literal>unique</literal> is true (the default),
2873-
duplicate values are not stored.
2874-
When eliminating duplicate values,
2875-
any &consvars; that end with
2876-
the string
2876+
duplicate values are not retained.
2877+
In case of duplication,
2878+
any &consvar; names that end in
28772879
<literal>PATH</literal>
2878-
keep the left-most unique value.
2880+
keep the left-most value so the
2881+
path searcb order is not altered.
28792882
All other &consvars; keep
2880-
the right-most unique value.
2883+
the right-most value.
28812884
If <literal>unique</literal> is false,
2882-
values are added even if they are duplicates.
2885+
values are appended even if they are duplicates.
28832886
</para>
28842887

28852888
<para>
@@ -2888,14 +2891,14 @@ Examples:
28882891

28892892
<example_commands>
28902893
# Add an optimization flag to $CCFLAGS.
2891-
env.MergeFlags('-O3')
2894+
env.MergeFlags({'CCFLAGS': '-O3'})
28922895

28932896
# Combine the flags returned from running pkg-config with an optimization
28942897
# flag and merge the result into the construction variables.
28952898
env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
28962899

28972900
# Combine an optimization flag with the flags returned from running pkg-config
2898-
# twice and merge the result into the construction variables.
2901+
# for two distinct packages and merge into the construction variables.
28992902
env.MergeFlags(
29002903
[
29012904
'-O3',
@@ -3633,9 +3636,9 @@ method.
36333636
<term><replaceable>env</replaceable>.<methodname>Requires</methodname>(<parameter>target, prerequisite</parameter>)</term>
36343637
<listitem><para>
36353638
Specifies an order-only relationship
3636-
between the specified target file(s)
3637-
and the specified prerequisite file(s).
3638-
The prerequisite file(s)
3639+
between <parameter>target</parameter>
3640+
and <parameter>prerequisite</parameter>.
3641+
The prerequisites
36393642
will be (re)built, if necessary,
36403643
<emphasis>before</emphasis>
36413644
the target file(s),
@@ -3646,6 +3649,9 @@ the prerequisite file(s) change.
36463649
<parameter>target</parameter> and
36473650
<parameter>prerequisite</parameter> may each
36483651
be a string or Node, or a list of strings or Nodes.
3652+
If there are multiple
3653+
<parameter>target</parameter> values,
3654+
the prerequisite(s) are added to each one.
36493655
Returns a list of the affected target nodes.
36503656
</para>
36513657

‎doc/generated/variables.gen

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -671,6 +671,14 @@ containing the
671671
<filename>SConstruct</filename>
672672
file.
673673
</para>
674+
<para>
675+
If variant directories are in use,
676+
and the configure check results should not be
677+
shared between variants,
678+
you can set &cv-CONFIGUREDIR;
679+
and &cv-link-CONFIGURELOG; so they are
680+
unique per variant directory.
681+
</para>
674682
</listitem>
675683
</varlistentry>
676684
<varlistentry id="cv-CONFIGURELOG">
@@ -686,6 +694,14 @@ containing the
686694
<filename>SConstruct</filename>
687695
file.
688696
</para>
697+
<para>
698+
If variant directories are in use,
699+
and the configure check results should not be
700+
shared between variants,
701+
you can set &cv-link-CONFIGUREDIR;
702+
and &cv-CONFIGURELOG; so they are
703+
unique per variant directory.
704+
</para>
689705
</listitem>
690706
</varlistentry>
691707
<varlistentry id="cv-_CPPDEFFLAGS">

0 commit comments

Comments
 (0)