Created attachment 1291 [details]
Patch for tutorial to show changes required if build.py handles waf configure options

This is the second attached patch for this bug. 

It show changes that need to be made to the tutorial. It doesn't show changes that need to be made to the other ns-3 documents like the manual and model library document.

Note, I had some discussion with Mitch about whether we want to be doing this.  I'm reluctant to start adding features to build.py and then having to maintain the build functions of both build.py and waf.

Presently, build.py is handled in the tutorial only as a way to quickly get up and running, but then it is abandoned in favor of using waf directly.  Do we want to encourage users to be always managing their builds via build.py?

Also, this suggested tutorial change:

-  ./build.py --enable-examples --enable-tests
+  ./build.py --enable-examples --enable-tests --configure-options="-d debug -o build/debug"

seems to just unnecessarily make things more complicated for the first-time user.

So, I would probably -1 on the tutorial patch, and am neutral on adding the --configure-options (that is, I would be OK with adding it or with not adding it and removing the --build-options while we are at it).

Other opinions?

Hi, the bug report is not correct, build.py already supported passing configure options to waf for a long time.  All options after -- are passed verbatim to waf configure.  E.g.

./build.py -- --enable-nsc

Perhaps we need to document this better, that's all.

The documentation should state something along these lines:
"""
The build.py script allows passing arbitrary options to ns-3's waf configure by preceding these options with a double dash token (--).  For example:

./build.py -- --enable-mpi
[...]
 =>  /usr/bin/python waf configure --enable-mpi
"""

(In reply to comment #4)
> The documentation should state something along these lines:
> """
> The build.py script allows passing arbitrary options to ns-3's waf configure by
> preceding these options with a double dash token (--).  For example:
> 
> ./build.py -- --enable-mpi
> [...]
>  =>  /usr/bin/python waf configure --enable-mpi
> """

I believe that we need to document that -- is greedy and needs to be the last option provided; e.g. this will work:
./build.py --disable-nsc --build-options="-j1" -- --disable-python

but other orderings will generally not work.  What do you think?

(In reply to comment #5)
> (In reply to comment #4)
> > The documentation should state something along these lines:
> > """
> > The build.py script allows passing arbitrary options to ns-3's waf configure by
> > preceding these options with a double dash token (--).  For example:
> > 
> > ./build.py -- --enable-mpi
> > [...]
> >  =>  /usr/bin/python waf configure --enable-mpi
> > """
> 
> I believe that we need to document that -- is greedy and needs to be the last
> option provided; e.g. this will work:
> ./build.py --disable-nsc --build-options="-j1" -- --disable-python
> 
> but other orderings will generally not work.  What do you think?

What happens is that -- is a special token.  When it is found, the command-line option parser library stops interpreting argv elements starting with a dash as options and simply gives them to the application programmer in the end.  This is typically used to allow programs to support --xxx options but also support file names starting with --.  It is a standard feature of GNU programs to allow this interpretation of the '--' token.  I don't know yet where it is well explained, but if I find out I'll comment here.

The getopt man page[1] says only this:

The special argument "--" forces an end of option-scanning regardless of the scanning mode.

[1] http://linux.die.net/man/3/getopt

I added documentation to the tutorial about this in changeset 11047:259a56c15a37