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

Update docs with CMake and ns3 wrapper

Browse Source
This commit is contained in:
Gabriel Ferreira
2021-11-29 21:58:30 -03:00
committed by Tom Henderson
parent 314c02b234
commit 3c604d5b2e
145 changed files with 960 additions and 676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -25,15 +25,15 @@ Python, to allow integration of |ns3| with other Python tools and workflows.
The intent is not to provide a different language choice to author new
|ns3| models implemented in Python.
Python bindings for |ns3| use a tool called PyBindGen (https://github.com/gjcarneiro/pybindgen) to create Python modules from the C++ libraries built by
Waf. The Python bindings that PyBindGen uses are maintained in a
``bindings`` directory in each module, and must be maintained to match the
Python bindings for |ns3| use a tool called PyBindGen (https://github.com/gjcarneiro/pybindgen)
to create Python modules from the C++ libraries built by CMake. The Python bindings that PyBindGen
uses are maintained in a ``bindings`` directory in each module, and must be maintained to match the
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 Waf configure time. In this case, changes to the C++
Python bindings 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
@@ -96,18 +96,18 @@ Here is some example code that is written in Python and that runs |ns3|, which i
Running Python Scripts
**********************
waf contains some options that automatically update the python path to find the ns3 module. To run example programs, there are two ways to use waf to take care of this. One is to run a waf shell; e.g.:
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
$ ./waf shell
$ ./ns3 shell
$ python examples/wireless/mixed-wireless.py
and the other is to use the --pyrun option to waf:
and the other is to use the --pyrun option to ns3:
.. sourcecode:: bash
$ ./waf --pyrun examples/wireless/mixed-wireless.py
$ ./ns3 --pyrun examples/wireless/mixed-wireless.py
As of ns-3.30, a --pyrun-no-build option was added to allow the running of
a program without invoking a project rebuild. This option may be useful
@@ -117,20 +117,20 @@ different arguments, such as from scripts. It can be used in place of
.. sourcecode:: bash
$ ./waf --pyrun-no-build examples/wireless/mixed-wireless.py
$ ./ns3 --pyrun-no-build examples/wireless/mixed-wireless.py
To run a python script under the C debugger:
.. sourcecode:: bash
$ ./waf shell
$ ./ns3 shell
$ gdb --args python 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
$ ./waf shell
$ ./ns3 shell
$ python /path/to/your/example/my-script.py
Caveats
@@ -251,7 +251,7 @@ If something goes wrong with compiling Python bindings and you just want to igno
.. sourcecode:: bash
$ ./waf configure --disable-python ...
$ ./ns3 configure --disable-python ...
To add support for modular bindings to an existing or new |ns3| module, simply add the following line to its wscript build() function:
@@ -451,7 +451,7 @@ C++ code), it will report a failure instead:
At this point, it is recommended to change into the ns-3-dev directory and
work further from there, because the API scanning dependencies have been
built and installed successfully into the `build` directory.
The output of './waf configure' can be inspected to see if Python API scanning
The output of './ns3 configure' can be inspected to see if Python API scanning
support is enabled:
.. sourcecode:: text
@@ -484,7 +484,7 @@ a 'long' (LP64) or 'long long' (ILP32).
The process (only supported on Linux at present) generates the LP64
bindings using the toolchain and then copies the LP64 bindings to the
ILP32 bindings with some type substitutions automated by Waf scripts.
ILP32 bindings with some type substitutions automated by CMake scripts.
Rescanning a module
###################
@@ -494,14 +494,14 @@ To re-scan a module:
.. sourcecode:: bash
$ cd source/ns-3-dev
$ ./waf --apiscan=wifi
$ ./ns3 --apiscan=wifi
To re-scan all modules:
.. sourcecode:: bash
$ cd source/ns-3-dev
$ ./waf --apiscan=all
$ ./ns3 --apiscan=all
Generating bindings on MacOS
############################