diff options
| author | William Deegan <bill@baddogconsulting.com> | 2022-03-31 17:27:27 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-03-31 17:27:27 (GMT) |
| commit | 0f6aaa714760f8650f307b0d1e1356a1696e9297 (patch) | |
| tree | 628e831385c1388550a54d6e368173352ec0c184 /doc | |
| parent | 3cb5dabe0339f9380130399d70a5df1848e15c27 (diff) | |
| parent | fb49becabc0cc641eef911473fdabc6c3b8e4788 (diff) | |
| download | SCons-0f6aaa714760f8650f307b0d1e1356a1696e9297.zip SCons-0f6aaa714760f8650f307b0d1e1356a1696e9297.tar.gz SCons-0f6aaa714760f8650f307b0d1e1356a1696e9297.tar.bz2 | |
Merge pull request #4124 from mwichmann/doc/generate-more-info
Add a bit more info to tool "generate" function doc
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/man/scons.xml | 29 |
1 files changed, 22 insertions, 7 deletions
diff --git a/doc/man/scons.xml b/doc/man/scons.xml index be64144..c7ec409 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -7247,23 +7247,38 @@ A tool specification module must include two functions: <varlistentry> <term><function>generate</function>(<parameter>env, **kwargs</parameter>)</term> <listitem> -<para>Modifies the &consenv; <parameter>env</parameter> -to set up necessary &consvars; so that the facilities represented by -the tool can be executed. -It may use any keyword arguments -that the user supplies in <parameter>kwargs</parameter> +<para>Modify the &consenv; <parameter>env</parameter> +to set up necessary &consvars;, Builders, Emitters, etc., +so the facilities represented by the tool can be executed. +Care should be taken not to overwrite &consvars; intended +to be settable by the user. For example: +</para> +<programlisting language="python"> +def generate(env): + ... + if 'MYTOOL' not in env: + env['MYTOOL'] = env.Detect("mytool") + if 'MYTOOLFLAGS' not in env: + env['MYTOOLFLAGS'] = SCons.Util.CLVar('--myarg') + ... +</programlisting> + +<para>The <function>generate</function> function +may use any keyword arguments +that the user supplies via <parameter>kwargs</parameter> to vary its initialization.</para> </listitem> </varlistentry> <varlistentry> <term><function>exists</function>(<parameter>env</parameter>)</term> <listitem> -<para>Returns <constant>True</constant> if the tool can +<para>Return a true value if the tool can be called in the context of <parameter>env</parameter>. +else false. Usually this means looking up one or more known programs using the <varname>PATH</varname> from the supplied <parameter>env</parameter>, but the tool can -make the "exists" decision in any way it chooses. +make the <emphasis>exists</emphasis> decision in any way it chooses. </para> </listitem> </varlistentry> |