[Ns-developers] Status of Python bindings

[Tom Henderson]

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>
>>
>> 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).

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

I think the rest of your proposal sounds reasonable.

Thanks,
Tom