F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Update manual for Python API scanning

Browse Source
This commit is contained in:
Tom Henderson
2022-04-17 15:46:35 -07:00
parent 9ac351202b
commit 72c64cd500
1 changed files with 79 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
doc/manual/source/python.rst
View File

@@ -32,8 +32,9 @@ C++ API of that ns-3 module. If the C++ API changes, the Python bindings file
must either be modified by hand accordingly, or the bindings must be
regenerated by an automated scanning process.
If a user is not interested in Python, he or she may disable the use of
Python bindings at CMake configure time. In this case, changes to the C++
If a user is not interested in Python, no action is needed; by default, Python
bindings are disabled (and must be explicitly enabled at
CMake configure time). In this case, changes to the C++
API of a provided module will not cause the module to fail to compile.
The process for automatically generating Python bindings relies on a toolchain
@@ -42,6 +43,18 @@ CastXML (https://github.com/CastXML/CastXML), and a program called
pygccxml (https://github.com/gccxml/pygccxml). The toolchain can be installed
using the ns-3 ``bake`` build tool.
As of ns-3.36, the Python bindings framework (including many of its
constituent tools) has lacked active maintainers for several years, and there
are constraints on the compatible Python version and on the C++ language
features that may be used in the C++ header files. The API scanning framework
(in particular, pygccxml) requires Python 3.6 through 3.8 but is
not compatible with Python 3.9 or 3.10. Compiling the existing bindings
should work through Python 3.10. Additionally, many newer C++ language features
beyond C++11 may not be supported by pybindgen.
Python bindings may be removed from future ns-3 releases if new maintainers
are not found.
An Example Python Script that Runs |ns3|
****************************************
@@ -96,18 +109,19 @@ Here is some example code that is written in Python and that runs |ns3|, which i
Running Python Scripts
**********************
First, we need to enable the build of python bindings:
First, we need to enable the build of Python bindings:
.. sourcecode:: bash
$ ./ns3 configure --enable-python-bindings
Other options such as ``--enable-examples`` may be passed to the above command.
ns3 contains some options that automatically update the python path to find the ns3 module. To run example programs, there are two ways to use ns3 to take care of this. One is to run a ns3 shell; e.g.:
.. sourcecode:: bash
$ ./ns3 shell
$ python examples/wireless/mixed-wireless.py
$ python3 examples/wireless/mixed-wireless.py
and the other is to use the 'run' option to ns3:
@@ -121,26 +135,27 @@ repeatedly but with different arguments, such as from scripts.
.. sourcecode:: bash
$ ./ns3 run examples/wireless/mixed-wireless.py --no-build
$ ./ns3 run --no-build examples/wireless/mixed-wireless.py
To run a python script under the C debugger:
.. sourcecode:: bash
$ ./ns3 shell
$ gdb --args python examples/wireless/mixed-wireless.py
$ gdb --args python3 examples/wireless/mixed-wireless.py
To run your own Python script that calls |ns3| and that has this path, ``/path/to/your/example/my-script.py``, do the following:
.. sourcecode:: bash
$ ./ns3 shell
$ python /path/to/your/example/my-script.py
$ python3 /path/to/your/example/my-script.py
Caveats
*******
Python bindings for |ns3| are a work in progress, and some limitations are known by developers. Some of these limitations (not all) are listed here.
In addition to limitations in Python and C++ versions supported (as discussed
above), some additional limitations are listed here.
Incomplete Coverage
===================
@@ -151,7 +166,7 @@ First of all, keep in mind that not 100% of the API is supported in Python. Som
#. Sometimes a unusual fundamental data type or C++ construct is used which is not yet supported by PyBindGen;
#. CastXML does not report template based classes unless they are instantiated.
Most of the missing APIs can be wrapped, given enough time, patience, and expertise, and will likely be wrapped if bug reports are submitted. However, don't file a bug report saying "bindings are incomplete", because we do not have manpower to complete 100% of the bindings.
Most of the missing APIs can be wrapped, given enough time, patience, and expertise, and will likely be wrapped if bug reports are submitted. However, don't file a bug report saying "bindings are incomplete", because the project does not have maintainers to maintain every API.
Conversion Constructors
=======================
@@ -164,7 +179,7 @@ Conversion Constructors
ipAddrs.SetBase ("192.168.0.0", "255.255.255.0");
ipAddrs.Assign (backboneDevices);
In Python, for the time being you have to do:
In Python, you have to do:
::
@@ -251,14 +266,7 @@ The process by which Python bindings are handled is the following:
#. Other developers clone the repository and use the already scanned API definitions;
#. When configuring |ns3|, pybindgen will be automatically downloaded if not already installed. Released |ns3| tarballs will ship a copy of pybindgen.
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:
.. sourcecode:: bash
$ ./ns3 configure --disable-python-bindings ...
One must also provide the bindings files (usually by running the scanning
framework).
If something goes wrong with compiling Python bindings and you just want to ignore them and move on with C++, you can disable Python by configuring |ns3| without Python bindings enabled.
Regenerating the Python bindings
================================
@@ -526,6 +534,59 @@ In principle, this should work (and should generate the 32-bit bindings).
However, maintainers have not been available to complete this port to date.
We would welcome suggestions on how to enable scanning for MacOS.
Regenerating the Python bindings using Docker
=============================================
An alternative to the above Bake install is to use a Docker container.
The following steps are used by the |ns3| CI system on an Ubuntu 20.04 image.
As a prerequisite, install Docker using a package manager; on Ubuntu, use:
.. sourcecode bash
$ apt install docker.io
To allow an unprivileged user to use Docker, perform the following
.. sourcecode bash
$ apt install docker.io
Then execute the following steps to get a shell:
.. sourcecode bash
$ docker run -it ubuntu:20.04
If you prefer to work on your current directory from the container shell,
instead do:
.. sourcecode bash
$ docker run -it -v /path/to/your/current/directory:/path/to/container/mount ubuntu:20.04
$ cd /path/to/container/mount
where ``/path/to/container/mount`` can be something like ``/ns-3-dev``.
Then, from within a directory that contains ns-3, perform the following
steps to rescan the APIs and test them:
.. sourcecode bash
$ apt-get update
$ apt-get install -y g++ cmake ninja-build ccache libgsl-dev libgtk-3-dev libboost-dev wget git python3 python3-pip
$ pip install cxxfilt pygccxml pybindgen castxml
$ ./ns3 clean
$ ./ns3 configure -G Ninja -- -DNS3_SCAN_PYTHON_BINDINGS=ON
$ ./ns3 build apiscan-all
$ ./ns3 configure --enable-python-bindings
$ ./ns3 build
$ ./ns3 run ./utils/python-unit-tests.py
If you exit the container, the package state will be lost, but from another
terminal window, you may be able to further test and evaluate the new bindings.
Note that the new bindings and build files will have root file ownership.
Organization of the Modular Python Bindings
===========================================