[Ns-developers] Status of Python bindings

[Gustavo Carneiro]

2008/6/5 Tom Henderson <tomh at tomh.org>:

> Gustavo Carneiro wrote:
>
>> 2008/5/19 Gustavo Carneiro <gjcarneiro at gmail.com>:
>>
>>  The PyBindGen API changes are more or less complete:
>>>
>>> https://code.launchpad.net/~gjc/pybindgen/trunk<https://code.launchpad.net/%7Egjc/pybindgen/trunk>
>>> <https://code.launchpad.net/%7Egjc/pybindgen/trunk>
>>>
>>>
>>> If nothing else comes up API-wise, next steps are:
>>>
>>>  1. Generate NS-3 API definitions as a single Python file and make it
>>> work;
>>>
>>>  2. Split the above file into several files, and support local
>>> modification
>>> files;
>>>
>>>  3. Figure out issues related to splitting python bindings into a
>>> separate
>>> repository;
>>>
>>
>>
>> === Facts ===
>>
>> We should come to a decision regarding how to deploy python bindings after
>> 3.1.
>>
>> Looking at the obtained result, I see that the ns-3-pybindgen-notracing
>> dist
>> tarball is 748 KiB, versus the no-python normal tarball which is 720 KiB.
>> That is, only 4% increase.  If I also add the pybindgen source tree, the
>> total goes to 800KiB, or 11% increase.  In any case, API definitions in
>> this
>> new format are much smaller than I had expected.
>>
>> === Proposal ===
>>
>> That being said, I think it will be vastly simpler and less painful if:
>>
>>  1. Python API definitions are kept in the main ns-3-dev branch;
>>
>>  2. For logistic reasons, and because pybindgen is an independent project
>> useful to other people, I would prefer to pull the pybindgen source tree
>> from a bzr branch hosted in code.launchpad.net, the same way regression
>> traces are pulled from another branch;
>>
>>  3. The released ns-3 tarballs would ship both a pybindgen tree and API
>> definitions.  This means that whoever receives the tarball can:
>>
>>    a) Build the python bindings easily, only needing Python (>= 2.3) with
>> Python headers as external dependency;
>>
>>    b) Add extra API definitions using the simplified pybindgen API (I
>> already added support for this and an example, missing documentation
>> only).
>>
>> === Problems Likely To Occur ===
>>
>> Problems that may occur regarding python bindings are:
>>
>>  1. A user that receives the tarball hacks NS-3 away, changing APIs in the
>> process.  The user will then see a compiler error message in the Python
>> bindings, which may be blocking her work;
>>
>>        a) I don't see any magical solution here.  Needs documentation
>> explaining to the user she needs to update the API definition or disable
>> python bindings;
>>
>>  2. A NS-3 developer changes the API (I hope this will become rare!).  If
>> Python bindings are enabled, they will stop compiling and block further
>> work
>> until they are fixed.  New we can decide whether Python bindings are
>> enabled
>> by default in development trees (read: branch checkout):
>>
>>    a) Python bindings are enabled by default.  This means that developers
>> that change existing APIs will have to fix the corresponding pybindgen API
>> definition or comment it out;
>>
>>    b) Python bindings are disabled by default.  This means that Python
>> bindings will often not be compilable during development periods, but most
>> developers are free from worrying about bindings.  Some other developers
>> will have to do the extra work.
>>        i) In this case we would need to discuss how to detect developer
>> trees vs release trees...
>>
>> Please comment.
>>
>
> I would favor 2a), and also a regression environment to find these faults
> as they occur (to the extent that we have API coverage in examples).


Sounds good.

I am thinking a combination of (additional?) regression tests coded in
python, and python unit tests, should do the trick.


>
>
> I'm guessing you will add some flag during the ./waf configure process to
> disable bindings, if needed.


Yes.  The option --python-disable is already there for that.  Works with waf
configure and also on a per build basis (waf configure --python-disable
remembers the option, while ./waf --python-disable only takes effect for
that build run).


>
>
> I think the rest of your proposal sounds reasonable.


I should also warn that pybindgen is emitting tons of warnings and
incomprehensible warnings, at the moment.  In time, and with feedback, I can
fix the warnings to make them more useful.  But this is an evolutionary
process and takes time to get right, much like ns-3 logging keeps
evolving...

-- 
Gustavo J. A. M. Carneiro
INESC Porto, Telecommunications and Multimedia Unit
"The universe is always one step beyond logic." -- Frank Herbert