Python bindings

From Nsnam
Revision as of 11:08, 16 July 2008 by GustavoCarneiro (Talk | contribs)

Jump to: navigation, search

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.

If something goes wrong with compiling Python bindings and you just want to ignore them and move on with C++, you can disable Python with:

./waf --python-disable

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.

API of existing module changed or added

So you have been changing existing NS-3 APIs and Python bindings no longer compile? Do not despair, you can manually edit the bindings API definitions to make them reflect the new changed API.

The API definitions are organized as follows. For each ns-3 module <name>, the file bindings/python/ns3_module_<name>.py describes its API. Each of those files have 3 toplevel functions:

  1. def register_types(module): this function takes care of registering new types (e.g. C++ classes, enums) that are defined in tha module;
  2. def register_methods(module): this function calls, for each class <name>, another function register_methods_Ns3<name>(module). These latter functions add method definitions for each class;
  3. def register_functions(module): this function registers ns-3 functions that belong to that module.

New module

If you are adding a new module, Python bindings will continue to compile but will not cover the new module. To cover a new module, you have to create a bindings/python/ns3_module_<name>.py file, similar to the what is described in the previous section, and register it in the variable LOCAL_MODULES in bindings/python/ns3modulegen.py


The semi-automatic way

It is possible to use GCC-XML and PyGccXml to scan API definitions automatically. The API scanner is not perfect, but it gets most of the job done.

First you need to install the necessary tools:

  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. Not, as with all CVS versions, stability may vary. This CVS snapshot is known to work: cvs up -D "2008-04-20".
  3. Download and install pygccxml, version 0.9.5; (To install: python setup.py install --prefix /usr/local);

Next step, run "./waf" just for a while to make sure the 'everything.h' file is generated (this file will be scanned). You can interrupt the build as soon as all 'blue' tasks are finished and compilation starts.

Finally, run "./waf --python-scan". If all goes well, the files in bindings/python/* should have been updated with new API definitions. Now you can build ns-3 as usual, and new Python bindings are compiled.

Known Problems