diff options
Diffstat (limited to 'doc/generated/functions.gen')
| -rw-r--r-- | doc/generated/functions.gen | 269 |
1 files changed, 164 insertions, 105 deletions
diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 5a74fc6..90d263d 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -248,9 +248,9 @@ to be performed after the specified <parameter>target</parameter> has been built. -The specified action(s) may be +<parameter>action</parameter> may be an Action object, or anything that -can be converted into an Action object +can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. </para> @@ -261,6 +261,13 @@ the action may be called multiple times, once after each action that generates one or more targets in the list. </para> + +<example_commands> +foo = Program('foo.c') +# remove execute permission from binary: +AddPostAction(foo, Chmod('$TARGET', "a-x")) +</example_commands> + </listitem> </varlistentry> <varlistentry id="f-AddPreAction"> @@ -273,9 +280,9 @@ to be performed before the specified <parameter>target</parameter> is built. -The specified action(s) may be +<parameter>action</parameter> may be an Action object, or anything that -can be converted into an Action object +can be converted into an Action object. See the manpage section "Action Objects" for a complete explanation. </para> @@ -318,20 +325,34 @@ file into an object file. </listitem> </varlistentry> <varlistentry id="f-Alias"> - <term><function>Alias</function>(<parameter>alias, [targets, [action]]</parameter>)</term> - <term><replaceable>env</replaceable>.<methodname>Alias</methodname>(<parameter>alias, [targets, [action]]</parameter>)</term> + <term><function>Alias</function>(<parameter>alias, [source, [action]]</parameter>)</term> + <term><replaceable>env</replaceable>.<methodname>Alias</methodname>(<parameter>alias, [source, [action]]</parameter>)</term> <listitem><para> -Creates one or more phony targets that -expand to one or more other targets. -An optional +Creates a phony target (or targets) that +can be used as references to zero or more other targets, +as specified by the optional <parameter>source</parameter> +parameter. +<parameter>alias</parameter> and +<parameter>source</parameter> +may each be a string or Node object, +or a list of strings or Node objects; +if Nodes are used for +<parameter>alias</parameter> +they must be Alias nodes. +The optional <parameter>action</parameter> -(command) -or list of actions -can be specified that will be executed +parameter specifies an action or list of actions +that will be executed whenever the any of the alias targets are out-of-date. -Returns the Node object representing the alias, -which exists outside of any file system. -This Node object, or the alias name, +</para> + +<para> +Returns a list of Alias Node objects representing the alias(es), +which exist outside of any physical file system. +</para> + +<para> +The alias name, or an Alias Node object, may be used as a dependency of any other target, including another alias. &f-Alias; @@ -519,7 +540,7 @@ giving an easy way to enter multiple macros in one addition. Use an <literal>=</literal> to specify a valued macro.</para> </listitem> <listitem> -<para>A tuple is treated as a valued macro. +<para>A tuple is treated as a valued macro. Use the value <constant>None</constant> if the macro should not have a value. It is an error to supply more than two elements in such a tuple.</para> </listitem> @@ -1117,13 +1138,25 @@ so you normally don't need to create directories by hand. <term><function>Configure</function>(<parameter>env, [custom_tests, conf_dir, log_file, config_h]</parameter>)</term> <term><replaceable>env</replaceable>.<methodname>Configure</methodname>(<parameter>[custom_tests, conf_dir, log_file, config_h]</parameter>)</term> <listitem><para> -Creates a Configure object for integrated -functionality similar to GNU autoconf. +Creates a &Configure; object for integrated +functionality similar to GNU <command>autoconf</command>. See the manpage section "Configure Contexts" for a complete explanation of the arguments and behavior. </para> </listitem> </varlistentry> + <varlistentry id="f-DebugOptions"> + <term><function>DebugOptions</function>(<parameter>[json]</parameter>)</term> + <listitem><para> +Allows setting options for SCons debug options. Currently the only supported value is + <emphasis>json</emphasis> which sets the path to the json file created when + <literal>--debug=json</literal> is set. +</para> + <example_commands> +DebugOptions(json='#/build/output/scons_stats.json') +</example_commands> +</listitem> + </varlistentry> <varlistentry id="f-Decider"> <term><function>Decider</function>(<parameter>function</parameter>)</term> <term><replaceable>env</replaceable>.<methodname>Decider</methodname>(<parameter>function</parameter>)</term> @@ -1141,50 +1174,24 @@ that will be applied: <para> <variablelist> <varlistentry> -<term><literal>"timestamp-newer"</literal></term> -<listitem> -<para> -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is newer than the target file's timestamp. -This is the behavior of the classic Make utility, -and -<literal>make</literal> -can be used a synonym for -<literal>timestamp-newer</literal>. -</para> -</listitem> -</varlistentry> -<varlistentry> -<term><literal>"timestamp-match"</literal></term> -<listitem> -<para> -Specifies that a target shall be considered out of date and rebuilt -if the dependency's timestamp is different than the -timestamp recorded the last time the target was built. -This provides behavior very similar to the classic Make utility -(in particular, files are not opened up so that their -contents can be checksummed) -except that the target will also be rebuilt if a -dependency file has been restored to a version with an -<emphasis>earlier</emphasis> -timestamp, such as can happen when restoring files from backup archives. -</para> -</listitem> -</varlistentry> -<varlistentry> <term><literal>"content"</literal></term> <listitem> <para> Specifies that a target shall be considered out of date and rebuilt if the dependency's content has changed since the last time the target was built, -as determined be performing an checksum -on the dependency's contents +as determined by performing a checksum +on the dependency's contents using the selected hash function, and comparing it to the checksum recorded the last time the target was built. -<literal>MD5</literal> -can be used as a synonym for -<literal>content</literal>, but it is deprecated. +<literal>content</literal> is the default decider. +</para> +<para> +<emphasis>Changed in version 4.1:</emphasis> +The decider was renamed to <literal>content</literal> +since the hash function is now selectable. +The former name, <literal>MD5</literal>, +can still be used as a synonym, but is deprecated. </para> </listitem> </varlistentry> @@ -1215,9 +1222,44 @@ that runs a build, updates a file, and runs the build again, all within a single second. -<literal>MD5-timestamp</literal> -can be used as a synonym for -<literal>content-timestamp</literal>, but it is deprecated. +</para> +<para> +<emphasis>Changed in version 4.1:</emphasis> +The decider was renamed to <literal>content-timestamp</literal> +since the hash function is now selectable. +The former name, <literal>MD5-timestamp</literal>, +can still be used as a synonym, but is deprecated. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>"timestamp-newer"</literal></term> +<listitem> +<para> +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is newer than the target file's timestamp. +This is the behavior of the classic Make utility, +and +<literal>make</literal> +can be used a synonym for +<literal>timestamp-newer</literal>. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><literal>"timestamp-match"</literal></term> +<listitem> +<para> +Specifies that a target shall be considered out of date and rebuilt +if the dependency's timestamp is different than the +timestamp recorded the last time the target was built. +This provides behavior very similar to the classic Make utility +(in particular, files are not opened up so that their +contents can be checksummed) +except that the target will also be rebuilt if a +dependency file has been restored to a version with an +<emphasis>earlier</emphasis> +timestamp, such as can happen when restoring files from backup archives. </para> </listitem> </varlistentry> @@ -3973,7 +4015,7 @@ Sets &scons; option variable <parameter>name</parameter> to <parameter>value</parameter>. These options are all also settable via command-line options but the variable name -may differ from the command-line option name - +may differ from the command-line option name - see the table for correspondences. A value set via command-line option will take precedence over one set with &f-SetOption;, which @@ -4481,57 +4523,74 @@ gltool(env) # adds 'opengl' to the TOOLS variable <varlistentry id="f-ValidateOptions"> <term><function>ValidateOptions</function>(<parameter>[throw_exception=False]</parameter>)</term> <listitem><para> - Check that all the options specified on the command line are either defined by SCons itself - or defined by calls to &f-link-AddOption;. - </para> - <para> - This function should only be called after the last &f-link-AddOption; call in your &SConscript; - logic. - </para> - <para> - Be aware that some tools call &f-link-AddOption;, if you are getting error messages for arguments - that they add, you will need to ensure that you load those tools before you call &f-ValidateOptions;. - </para> - <para> - If there are any command line options not defined, calling this function will cause SCons to issue an - error message and then exit with an error exit - status.</para> - <para>If the optional <parameter>throw_exception</parameter> is <literal>True</literal>, &f-ValidateOptions; will raise a - <exceptionname>SConsBadOptionError</exceptionname> - exception. This would allow the calling - &SConscript; logic can catch that exception and handle invalid options itself. - </para> - - <para> - Example: - </para> - - <example_commands> + Check that all the options specified on the command line are either + &SCons; built-in options or defined via calls to &f-link-AddOption;. + &SCons; will eventually fail on unknown options anyway, but calling + this function allows the build to "fail fast" before executing + expensive logic later in the build. + </para> + + <para> + This function should only be called after the last &f-AddOption; + call in your &SConscript; logic. + Be aware that some tools call &f-AddOption;, if you are getting + error messages for arguments that they add, you will need to ensure + that those tools are loaded before calling &f-ValidateOptions;. + </para> + + <para> + If there are any unknown command line options, &f-ValidateOptions; + prints an error message and exits with an error exit status. + If the optional <parameter>throw_exception</parameter> argument is + <literal>True</literal> (default is <literal>False</literal>), + a <exceptionname>SConsBadOptionError</exceptionname> is raised, + giving an opportunity for the &SConscript; logic to catch that + exception and handle invalid options appropriately. Note that + this exception name needs to be imported (see the example below). + </para> + + <para> + A common build problem is typos (or thinkos) - a user enters an option + that is just a little off the expected value, or perhaps a different + word with a similar meaning. It may be useful to abort the build + before going too far down the wrong path. For example: + </para> + + <screen> +$ <userinput>scons --compilers=mingw</userinput> # the correct flag is --compiler + </screen> + + <para> + Here &SCons; could go off and run a bunch of configure steps with + the default value of <literal>--compiler</literal>, since the + incorrect command line did not actually supply a value to it, + costing developer time to track down why the configure logic + made the "wrong" choices. This example shows catching this: + </para> + + <programlisting language="python"> +from SCons.Script.SConsOptions import SConsBadOptionError + +AddOption( + '--compiler', + dest='compiler', + action='store', + default='gcc', + type='string', +) + +# ... other SConscript logic ... + try: ValidateOptions(throw_exception=True) except SConsBadOptionError as e: - print("Parser is SConsOptionParser:%s" % (isinstance(e.parser, SConsOptionParser))) - print("Message is :%s" % e.opt_str) + print(f"ValidateOptions detects a fail: ", e.opt_str) Exit(3) - </example_commands> - - <para> - This function is useful to force SCons to fail fast before you execute any expensive logic later in your - build logic. - For example if you specify build options via any flags, a simple typo could yield the incorrect build - option throughout your entire build. - </para> - <example_commands> -scons --compilers=mingw (the correct flag is --compiler) - </example_commands> - <para> - Could cause SCons to run configure steps with the incorrect compiler. Costing developer time trying to - track down why the configure logic failed with a compiler which should work. - </para> - <para> - <emphasis>New in version 4.5.0</emphasis> - </para> - </listitem> + </programlisting> + + <para><emphasis>New in version 4.5.0</emphasis></para> + + </listitem> </varlistentry> <varlistentry id="f-Value"> <term><function>Value</function>(<parameter>value, [built_value], [name]</parameter>)</term> |