diff options
| -rw-r--r-- | doc/user/command-line.xml | 34 | ||||
| -rw-r--r-- | doc/user/depends.xml | 1 | ||||
| -rw-r--r-- | src/engine/SCons/Script/Main.xml | 15 |
3 files changed, 50 insertions, 0 deletions
diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index d129d2e..8b8949a 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -608,6 +608,7 @@ foo.in of the <classname>optparse.OptionParser</classname>. </para> </footnote> + Once you have added a custom command-line option with the &AddOption; function, the value of the option (if any) is immediately available @@ -678,6 +679,39 @@ foo.in <scons_output_command>scons -Q -n --prefix=/tmp/install</scons_output_command> </scons_output> + <note> + <para> + Long options and option-arguments separated by a space, rather than + by <literal>=</literal>, are ambiguous. + While <literal>--input=ARG</literal> + has a clear meaning, for <literal>--input ARG</literal> it is not + possible to tell without instructions whether + <parameter>ARG</parameter> is an argument belonging to the + <parameter>input</parameter> option or a positional argument + (that is, an argument that does not start with a single or double dash). + In <command>scons</command>, positional arguments are treated as either + command-line build options or command-line targets + (see the immediately following sections for details), + which are made available for use in the &SConscript;. + This means they have to be collected before &SConscript; processing + takes place. Since &AddOption; calls, which provide + the necessary processing instructions, happen in the &SConscript;, + <command>scons</command> cannot resolve the ambiguity in time + for options added this way, and unexpected things will happen. + As a result, this usage style should be avoided when invoking + <command>scons</command>. For single-argument + options, use the <literal>--input=ARG</literal> style on the + command line. For multiple-argument options + (<parameter>nargs</parameter> greater than one), + set <parameter>nargs</parameter> to one in + &AddOption; and combine the option-arguments into one word + with a separator, and parse the result in your own code. + See the built-in <parameter>--debug</parameter> option, which + allows specifying multiple arguments as a single comma-separated + word, for an example of such usage. + </para> + </footnote> + </section> </section> diff --git a/doc/user/depends.xml b/doc/user/depends.xml index 5a78eb5..cd5094a 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -764,6 +764,7 @@ int main() { printf("Hello, world!\n"); } encounter them in older &SConscript; files. </para> + </section> <section> <title>Implicit Dependencies: The &cv-CPPPATH; Construction Variable</title> diff --git a/src/engine/SCons/Script/Main.xml b/src/engine/SCons/Script/Main.xml index e95afbc..13ad336 100644 --- a/src/engine/SCons/Script/Main.xml +++ b/src/engine/SCons/Script/Main.xml @@ -133,6 +133,21 @@ AddOption('--prefix', help='installation prefix') env = Environment(PREFIX = GetOption('prefix')) </example_commands> + +<note> +<para> +While &AddOption; behaves like +<function>optparse.add_option</function>, +the behavior of options added by &AddOption; +which take arguments is underfined in +<command>scons</command> if a space +(rather than <literal>=</literal> sign) is used as +the separator on the command line when +the option is invoked. +Such usage should be avoided. +</para> +</note> + </summary> </scons_function> |