Python bindings

Overview

The goal of Python bindings for NS-3 are two fold:

1. Allow the programmer to write complete simulation scripts in Python;
2. Prototype new models (e.g. routing protocols).

For the time being, the primary focus of the bindings is the first goal, but the second goal will eventually be supported as well. Python bindings for NS-3 are being developed using a new tool called PyBindGen.

The process by which Python bindings are handled is the following:

1. Periodically a developer uses a GCC-XML based API scanning script, which saves the scanned API definition as bindings/python/ns3_module_*.py files. These files are kept under version control in the main NS-3 repository;
2. Other developers clone the repository and use the already scanned API definitions;
3. When configuring NS-3, pybindgen will be automatically downloaded if not already installed. Released NS-3 tarballs will ship a copy of pybindgen.

Build instructions

Just make sure Python development headers are installed (e.g., in debian/ubuntu: sudo apt-get install python-dev), then waf configure and waf build ns-3 as usual.

Testing

"./waf check" now also runs some Python unit tests, at the end.

To run example programs:

./waf --shell
python examples/mixed-wireless.py

or:

./waf --pyrun examples/mixed-wireless.py

Instructions for wrapping new or changed APIs

The manual way

You will need to read some PyBindGen documentation.

The semi-automatic way

FIXME: this section is not finished.

1. Get CMake (can either build from source or download binaries for windows, linux i386);
2. Get GCC-XML (must download from CVS). Instructions are to be found here;
3. Download and install pygccxml, version 0.9.5 or greater; (To install: python setup.py install);
4. Get the PyBindGen bzr branch; instructions here.
   • Note: the bzr branch does not come with a waf script, but the one from NS-3 (1.3.2) works fine (waf trunk may or not work);
   • Download specific version of waf into PyBindGen trunk;
   • ./waf configure; ./waf; ./waf check; ./waf install;
5. Finally, get the ns-3-pybindgen-notracing branch: http://code.nsnam.org/gjc/ns-3-pybindgen-notracing/
   • ./waf configure; ./waf