From 801af4e979311c960d6b7611c001f885f43e5ed4 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Sun, 17 Mar 2024 17:29:44 -0700 Subject: Regenerated docs for 4.7.0 release --- doc/generated/builders.gen | 67 +++++++++++++--------- doc/generated/examples/caching_ex-random_1.xml | 2 +- doc/generated/examples/troubleshoot_explain1_3.xml | 2 +- .../examples/troubleshoot_taskmastertrace_1.xml | 50 ++++++++-------- doc/generated/functions.gen | 58 ++++++++++--------- doc/generated/variables.gen | 16 ++++++ 6 files changed, 116 insertions(+), 79 deletions(-) diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen index 0515377..45b4711 100644 --- a/doc/generated/builders.gen +++ b/doc/generated/builders.gen @@ -2216,13 +2216,24 @@ env.RPCGenClient('src/rpcif.x') env.SharedLibrary() Builds a shared library -(.so on a POSIX system, -.dll on Windows) given one or more object files -or C, C++, D or Fortran source files. -If any source files are given, -then they will be automatically -compiled to object files. +and/or C, C++, D or Fortran source files. +Any source files listed in the +source parameter +will be automatically +compiled to object files suitable +for use in a shared library. +Any object files listed in the +source parameter +must have been built for a shared library +(that is, using the +&b-SharedObject; +builder method). +&scons; +will raise an error if there is any mismatch. + + + The target library file prefix, specified by the &cv-link-SHLIBPREFIX; &consvar; (by default, lib on POSIX systems, @@ -2231,7 +2242,13 @@ and suffix, specified by the &cv-link-SHLIBSUFFIX; &consvar; (by default, .dll on Windows systems, .so on POSIX systems), -are automatically added to the target if not already present. +are automatically added (if not already present) +to the target name to make up the library filename. +On a POSIX system, if the &cv-link-SHLIBVERSION; &consvar; is set, +it is appended (following a period) to the resulting library name. + + + Example: @@ -2261,16 +2278,6 @@ if there is not already a .dll.a file explicitly listed in the targets. - -Any object files listed in the -source -must have been built for a shared library -(that is, using the -&b-SharedObject; -builder method). -&scons; -will raise an error if there is any mismatch. - 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. -When the &cv-link-SHLIBVERSION; &consvar; is defined, a versioned +If &cv-link-SHLIBVERSION; is defined, a versioned shared library is created. This modifies &cv-link-SHLINKFLAGS; as required, adds the version number to the library name, and creates any symbolic links that are needed. @@ -2291,17 +2298,25 @@ env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2') -On a POSIX system, versions with a single token create exactly one symlink: -libbar.so.6 would have symlink libbar.so only. -On a POSIX system, versions with two or more -tokens create exactly two symlinks: libbar.so.2.3.1 would have symlinks -libbar.so and libbar.so.2; on a Darwin (OSX) system the library would be -libbar.2.3.1.dylib and the link would be libbar.dylib. +On a POSIX system, supplying a simple version string (no dots) +creates exactly one symbolic link: SHLIBVERSION="1" +would create (for example) library libbar.so.1 +and symbolic link libbar.so. +Supplying a dotted version string will create two symbolic links +(irrespective of the number of segments in the version): +SHLIBVERSION="1.5.2" for the same library +would create library libbar.so.1.5.2 +and symbolic links libbar.so and +libbar.so.1. A Darwin (OSX) +system creates one symlink in either case, +for the second example the library would be +libbar.1.5.2.dylib +and the link would be libbar.dylib. -On Windows systems, specifying -register=1 +On Windows systems, specifying the +register=1 keyword argument will cause the .dll to be registered after it is built. The command that is run is determined by the &cv-link-REGSVR; &consvar; diff --git a/doc/generated/examples/caching_ex-random_1.xml b/doc/generated/examples/caching_ex-random_1.xml index a1f68fe..00041ee 100644 --- a/doc/generated/examples/caching_ex-random_1.xml +++ b/doc/generated/examples/caching_ex-random_1.xml @@ -2,7 +2,7 @@ cc -o f3.o -c f3.c cc -o f5.o -c f5.c cc -o f4.o -c f4.c -cc -o f2.o -c f2.c cc -o f1.o -c f1.c +cc -o f2.o -c f2.c cc -o prog f1.o f2.o f3.o f4.o f5.o diff --git a/doc/generated/examples/troubleshoot_explain1_3.xml b/doc/generated/examples/troubleshoot_explain1_3.xml index 76e4b79..e658d89 100644 --- a/doc/generated/examples/troubleshoot_explain1_3.xml +++ b/doc/generated/examples/troubleshoot_explain1_3.xml @@ -2,5 +2,5 @@ cp file.in file.oout scons: warning: Cannot find target file.out after building -File "/Users/bdbaddog/devel/scons/git/mwichmann/scripts/scons.py", line 97, in <module> +File "/Users/bdbaddog/devel/scons/git/as_scons/scripts/scons.py", line 97, in <module> diff --git a/doc/generated/examples/troubleshoot_taskmastertrace_1.xml b/doc/generated/examples/troubleshoot_taskmastertrace_1.xml index fe821ba..70f3fbb 100644 --- a/doc/generated/examples/troubleshoot_taskmastertrace_1.xml +++ b/doc/generated/examples/troubleshoot_taskmastertrace_1.xml @@ -1,8 +1,8 @@ % scons -Q --taskmastertrace=- prog -Job.NewParallel._work(): [Thread:8453497088] Gained exclusive access -Job.NewParallel._work(): [Thread:8453497088] Starting search -Job.NewParallel._work(): [Thread:8453497088] Found 0 completed tasks to process -Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks +Job.NewParallel._work(): [Thread:8149967104] Gained exclusive access +Job.NewParallel._work(): [Thread:8149967104] Starting search +Job.NewParallel._work(): [Thread:8149967104] Found 0 completed tasks to process +Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks Taskmaster: Looking for a node to evaluate Taskmaster: Considering node <no_state 0 'prog'> and its children: @@ -18,12 +18,12 @@ Taskmaster: Evaluating <pending 0 'prog.c'> Task.make_ready_current(): node <pending 0 'prog.c'> Task.prepare(): node <up_to_date 0 'prog.c'> -Job.NewParallel._work(): [Thread:8453497088] Found internal task +Job.NewParallel._work(): [Thread:8149967104] Found internal task Task.executed_with_callbacks(): node <up_to_date 0 'prog.c'> Task.postprocess(): node <up_to_date 0 'prog.c'> Task.postprocess(): removing <up_to_date 0 'prog.c'> Task.postprocess(): adjusted parent ref count <pending 1 'prog.o'> -Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks +Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks Taskmaster: Looking for a node to evaluate Taskmaster: Considering node <no_state 0 'inc.h'> and its children: @@ -31,12 +31,12 @@ Taskmaster: Evaluating <pending 0 'inc.h'> Task.make_ready_current(): node <pending 0 'inc.h'> Task.prepare(): node <up_to_date 0 'inc.h'> -Job.NewParallel._work(): [Thread:8453497088] Found internal task +Job.NewParallel._work(): [Thread:8149967104] Found internal task Task.executed_with_callbacks(): node <up_to_date 0 'inc.h'> Task.postprocess(): node <up_to_date 0 'inc.h'> Task.postprocess(): removing <up_to_date 0 'inc.h'> Task.postprocess(): adjusted parent ref count <pending 0 'prog.o'> -Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks +Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks Taskmaster: Looking for a node to evaluate Taskmaster: Considering node <pending 0 'prog.o'> and its children: @@ -46,19 +46,19 @@ Taskmaster: Evaluating <pending 0 'prog.o'> Task.make_ready_current(): node <pending 0 'prog.o'> Task.prepare(): node <executing 0 'prog.o'> -Job.NewParallel._work(): [Thread:8453497088] Found task requiring execution -Job.NewParallel._work(): [Thread:8453497088] Executing task +Job.NewParallel._work(): [Thread:8149967104] Found task requiring execution +Job.NewParallel._work(): [Thread:8149967104] Executing task Task.execute(): node <executing 0 'prog.o'> cc -o prog.o -c -I. prog.c -Job.NewParallel._work(): [Thread:8453497088] Enqueueing executed task results -Job.NewParallel._work(): [Thread:8453497088] Gained exclusive access -Job.NewParallel._work(): [Thread:8453497088] Starting search -Job.NewParallel._work(): [Thread:8453497088] Found 1 completed tasks to process +Job.NewParallel._work(): [Thread:8149967104] Enqueueing executed task results +Job.NewParallel._work(): [Thread:8149967104] Gained exclusive access +Job.NewParallel._work(): [Thread:8149967104] Starting search +Job.NewParallel._work(): [Thread:8149967104] Found 1 completed tasks to process Task.executed_with_callbacks(): node <executing 0 'prog.o'> Task.postprocess(): node <executed 0 'prog.o'> Task.postprocess(): removing <executed 0 'prog.o'> Task.postprocess(): adjusted parent ref count <pending 0 'prog'> -Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks +Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks Taskmaster: Looking for a node to evaluate Taskmaster: Considering node <pending 0 'prog'> and its children: @@ -67,21 +67,21 @@ Taskmaster: Evaluating <pending 0 'prog'> Task.make_ready_current(): node <pending 0 'prog'> Task.prepare(): node <executing 0 'prog'> -Job.NewParallel._work(): [Thread:8453497088] Found task requiring execution -Job.NewParallel._work(): [Thread:8453497088] Executing task +Job.NewParallel._work(): [Thread:8149967104] Found task requiring execution +Job.NewParallel._work(): [Thread:8149967104] Executing task Task.execute(): node <executing 0 'prog'> cc -o prog prog.o -Job.NewParallel._work(): [Thread:8453497088] Enqueueing executed task results -Job.NewParallel._work(): [Thread:8453497088] Gained exclusive access -Job.NewParallel._work(): [Thread:8453497088] Starting search -Job.NewParallel._work(): [Thread:8453497088] Found 1 completed tasks to process +Job.NewParallel._work(): [Thread:8149967104] Enqueueing executed task results +Job.NewParallel._work(): [Thread:8149967104] Gained exclusive access +Job.NewParallel._work(): [Thread:8149967104] Starting search +Job.NewParallel._work(): [Thread:8149967104] Found 1 completed tasks to process Task.executed_with_callbacks(): node <executing 0 'prog'> Task.postprocess(): node <executed 0 'prog'> -Job.NewParallel._work(): [Thread:8453497088] Searching for new tasks +Job.NewParallel._work(): [Thread:8149967104] Searching for new tasks Taskmaster: Looking for a node to evaluate Taskmaster: No candidate anymore. -Job.NewParallel._work(): [Thread:8453497088] Found no task requiring execution, and have no jobs: marking complete -Job.NewParallel._work(): [Thread:8453497088] Gained exclusive access -Job.NewParallel._work(): [Thread:8453497088] Completion detected, breaking from main loop +Job.NewParallel._work(): [Thread:8149967104] Found no task requiring execution, and have no jobs: marking complete +Job.NewParallel._work(): [Thread:8149967104] Gained exclusive access +Job.NewParallel._work(): [Thread:8149967104] Completion detected, breaking from main loop diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index b93fa8d..6fd0bb1 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -564,7 +564,7 @@ In this case, space-separated strings are not split. A dictionary is processed in order, -adding each key:value pair as a valued macro. +adding each key-value pair as a valued macro. Use the value None if the macro should not have a value. @@ -649,7 +649,7 @@ Appending a string val to a dictonary-typed &consvar; enters val as the key in the dictionary, and None as its value. -Using a tuple type to supply a key, value +Using a tuple type to supply a key-value pair only works for the special case of &cv-CPPDEFINES; described above. @@ -2851,35 +2851,38 @@ Returns a list of the target Node or Nodes. Merges values from arg -into &consvars; in the current &consenv;. -If -arg +into &consvars; in env. +If arg is a dictionary, +each key-value pair represents a +&consvar; name and the corresponding flags to merge. +If arg is not a dictionary, -it is converted to one by calling -&f-link-env-ParseFlags; -on the argument +&MergeFlags; attempts to convert it to one before the values are merged. -Note that +&f-link-env-ParseFlags; is used for this, +so values to be converted are subject to the +same limitations: +&ParseFlags; has knowledge of which &consvars; certain +flags should go to, but not all; +and only for GCC and compatible compiler chains. arg -must be a single value, -so multiple strings must -be passed in as a list, -not as separate arguments to -&f-env-MergeFlags;. +must be a single object, +so to pass multiple strings, +enclose them in a list. If unique is true (the default), -duplicate values are not stored. -When eliminating duplicate values, -any &consvars; that end with -the string +duplicate values are not retained. +In case of duplication, +any &consvar; names that end in PATH -keep the left-most unique value. +keep the left-most value so the +path searcb order is not altered. All other &consvars; keep -the right-most unique value. +the right-most value. If unique is false, -values are added even if they are duplicates. +values are appended even if they are duplicates. @@ -2888,14 +2891,14 @@ Examples: # Add an optimization flag to $CCFLAGS. -env.MergeFlags('-O3') +env.MergeFlags({'CCFLAGS': '-O3'}) # Combine the flags returned from running pkg-config with an optimization # flag and merge the result into the construction variables. env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3']) # Combine an optimization flag with the flags returned from running pkg-config -# twice and merge the result into the construction variables. +# for two distinct packages and merge into the construction variables. env.MergeFlags( [ '-O3', @@ -3633,9 +3636,9 @@ method. env.Requires(target, prerequisite) Specifies an order-only relationship -between the specified target file(s) -and the specified prerequisite file(s). -The prerequisite file(s) +between target +and prerequisite. +The prerequisites will be (re)built, if necessary, before the target file(s), @@ -3646,6 +3649,9 @@ the prerequisite file(s) change. target and prerequisite may each be a string or Node, or a list of strings or Nodes. +If there are multiple +target values, +the prerequisite(s) are added to each one. Returns a list of the affected target nodes. diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen index 3f42b49..4d5e1e3 100644 --- a/doc/generated/variables.gen +++ b/doc/generated/variables.gen @@ -671,6 +671,14 @@ containing the SConstruct file. + +If variant directories are in use, +and the configure check results should not be +shared between variants, +you can set &cv-CONFIGUREDIR; +and &cv-link-CONFIGURELOG; so they are +unique per variant directory. + @@ -686,6 +694,14 @@ containing the SConstruct file. + +If variant directories are in use, +and the configure check results should not be +shared between variants, +you can set &cv-link-CONFIGUREDIR; +and &cv-CONFIGURELOG; so they are +unique per variant directory. + -- cgit v0.12