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

Run utils/trim-trailing-whitespace.py on codebase

Browse Source
This commit is contained in:
Tom Henderson
2022-06-05 21:01:11 -07:00
parent 7c47d8af08
commit b6a5ee8151
1385 changed files with 16008 additions and 16008 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -35,11 +35,11 @@ regenerated by an automated scanning process.
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.
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
involving a development installation of the Clang compiler, a program called
CastXML (https://github.com/CastXML/CastXML), and a program called
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.
@@ -67,42 +67,42 @@ Here is some example code that is written in Python and that runs |ns3|, which i
import ns.internet
import ns.network
import ns.point_to_point
ns.core.LogComponentEnable("UdpEchoClientApplication", ns.core.LOG_LEVEL_INFO)
ns.core.LogComponentEnable("UdpEchoServerApplication", ns.core.LOG_LEVEL_INFO)
nodes = ns.network.NodeContainer()
nodes.Create(2)
pointToPoint = ns.point_to_point.PointToPointHelper()
pointToPoint.SetDeviceAttribute("DataRate", ns.core.StringValue("5Mbps"))
pointToPoint.SetChannelAttribute("Delay", ns.core.StringValue("2ms"))
devices = pointToPoint.Install(nodes)
stack = ns.internet.InternetStackHelper()
stack.Install(nodes)
address = ns.internet.Ipv4AddressHelper()
address.SetBase(ns.network.Ipv4Address("10.1.1.0"), ns.network.Ipv4Mask("255.255.255.0"))
interfaces = address.Assign (devices);
echoServer = ns.applications.UdpEchoServerHelper(9)
serverApps = echoServer.Install(nodes.Get(1))
serverApps.Start(ns.core.Seconds(1.0))
serverApps.Stop(ns.core.Seconds(10.0))
echoClient = ns.applications.UdpEchoClientHelper(interfaces.GetAddress(1), 9)
echoClient.SetAttribute("MaxPackets", ns.core.UintegerValue(1))
echoClient.SetAttribute("Interval", ns.core.TimeValue(ns.core.Seconds (1.0)))
echoClient.SetAttribute("PacketSize", ns.core.UintegerValue(1024))
clientApps = echoClient.Install(nodes.Get(0))
clientApps.Start(ns.core.Seconds(2.0))
clientApps.Stop(ns.core.Seconds(10.0))
ns.core.Simulator.Run()
ns.core.Simulator.Destroy()
@@ -164,7 +164,7 @@ First of all, keep in mind that not 100% of the API is supported in Python. Som
#. some of the APIs involve pointers, which require knowledge of what kind of memory passing semantics (who owns what memory). Such knowledge is not part of the function signatures, and is either documented or sometimes not even documented. Annotations are needed to bind those functions;
#. 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.
#. 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 the project does not have maintainers to maintain every API.
@@ -232,7 +232,7 @@ There is one caveat: you must not allow the file object to be garbage collected
Working with Python Bindings
****************************
Python bindings are built on a module-by-module basis, and can be found in each module's ``bindings`` directory.
Python bindings are built on a module-by-module basis, and can be found in each module's ``bindings`` directory.
Overview
========
@@ -283,7 +283,7 @@ Process Overview
|ns3| has an automated process to regenerate Python bindings from the C++
header files. The process is only supported for Linux at the moment
because the project has not found a contributor yet to test and
document the capability on macOS. In short, the process currently
document the capability on macOS. In short, the process currently
requires the following steps on a Linux machine.
1. Prepare the system for scanning by installing the prerequisites,
@@ -332,7 +332,7 @@ Perform a configuration at the bake level:
$ ./bake.py configure -e ns-3-dev -e pygccxml
The output of ``./bake.py show`` should show something like this:
The output of ``./bake.py show`` should show something like this:
.. sourcecode:: bash
@@ -363,7 +363,7 @@ report as Missing. For Python bindings, the important
prerequisites are clang-dev, cmake, cxxfilt, llvm-dev, python3-dev,
and python3-setuptools. In the following process, the following programs
and libraries will be locally installed: castxml, pybindgen, pygccxml,
and |ns3|.
and |ns3|.
Note also that the `ns-3-allinone` target for bake will also include the
`pygccxml` and `ns-3-dev` targets (among other libraries) and can be
@@ -386,38 +386,38 @@ is present or missing on your system.
>> Searching for system dependency clang-dev - OK
>> Searching for system dependency qt - Problem
> Problem: Optional dependency, module "qt" not available
This may reduce the functionality of the final build.
This may reduce the functionality of the final build.
However, bake will continue since "qt" is not an essential dependency.
For more information call bake with -v or -vvv, for full verbose mode.
>> Searching for system dependency g++ - OK
>> Searching for system dependency cxxfilt - OK
>> Searching for system dependency setuptools - OK
>> Searching for system dependency python3-setuptools - OK
>> Searching for system dependency gi-cairo - Problem
> Problem: Optional dependency, module "gi-cairo" not available
This may reduce the functionality of the final build.
This may reduce the functionality of the final build.
However, bake will continue since "gi-cairo" is not an essential dependency.
For more information call bake with -v or -vvv, for full verbose mode.
>> Searching for system dependency gir-bindings - Problem
> Problem: Optional dependency, module "gir-bindings" not available
This may reduce the functionality of the final build.
This may reduce the functionality of the final build.
However, bake will continue since "gir-bindings" is not an essential dependency.
For more information call bake with -v or -vvv, for full verbose mode.
>> Searching for system dependency pygobject - Problem
> Problem: Optional dependency, module "pygobject" not available
This may reduce the functionality of the final build.
This may reduce the functionality of the final build.
However, bake will continue since "pygobject" is not an essential dependency.
For more information call bake with -v or -vvv, for full verbose mode.
>> Searching for system dependency pygraphviz - Problem
> Problem: Optional dependency, module "pygraphviz" not available
This may reduce the functionality of the final build.
This may reduce the functionality of the final build.
However, bake will continue since "pygraphviz" is not an essential dependency.
For more information call bake with -v or -vvv, for full verbose mode.
>> Searching for system dependency python3-dev - OK
>> Searching for system dependency cmake - OK
>> Downloading castxml - OK
@@ -425,7 +425,7 @@ is present or missing on your system.
>> Downloading pybindgen - OK
>> Downloading pygccxml - OK
>> Downloading ns-3-dev - OK
Build
#####
@@ -451,7 +451,7 @@ C++ code), it will report a failure instead:
::
>> Building ns-3-dev - Problem
> Error: Critical dependency, module "ns-3-dev" failed
> Error: Critical dependency, module "ns-3-dev" failed
For more information call Bake with --debug and/or -v, -vvv, for full verbose mode (bake --help)
At this point, it is recommended to change into the ns-3-dev directory and
@@ -483,15 +483,15 @@ data models, as explained here: https://www.ibm.com/support/knowledgecenter/en/
Linux uses the LP64 model, and MacOS (as well as 32-bit Linux) use the ILP32
model. Users will note that there are two versions of bindings files in
each ns-3 module directory; one with an ILP32.py suffix and one with
each ns-3 module directory; one with an ILP32.py suffix and one with
an LP64.py suffix. Only one is used on any given platform. The main
difference is in the representation of the 64 bit integer type as either
a 'long' (LP64) or 'long long' (ILP32).
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 CMake scripts.
Rescanning a module
###################
@@ -532,7 +532,7 @@ Generating bindings on MacOS
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.
We would welcome suggestions on how to enable scanning for MacOS.
Regenerating the Python bindings using gitlab-ci-local
======================================================
@@ -570,10 +570,10 @@ To allow an unprivileged user to use Docker, perform the following:
$ sudo chmod 666 /var/run/docker.sock
The following command will obtain a raw shell for an Ubuntu 20.04 image:
The following command will obtain a raw shell for an Ubuntu 20.04 image:
.. sourcecode:: bash
$ docker run -it ubuntu:20.04
However, if you prefer to work on your current directory from the container
@@ -620,7 +620,7 @@ The ``src/<module>/bindings`` directory may contain the following files, some of
* ``modulegen_customizations.py``: you may optionally add this file in order to customize the pybindgen code generation
* ``scan-header.h``: you may optionally add this file to customize what header file is scanned for the module. Basically this file is scanned instead of ns3/<module>-module.h. Typically, the first statement is #include "ns3/<module>-module.h", plus some other stuff to force template instantiations;
* ``module_helpers.cc``: you may add additional files, such as this, to be linked to python extension module. They will be automatically scanned;
* ``<module>.py``: if this file exists, it becomes the "frontend" python module for the ns3 module, and the extension module (.so file) becomes _<module>.so instead of <module>.so. The <module>.py file has to import all symbols from the module _<module> (this is more tricky than it sounds, see src/core/bindings/core.py for an example), and then can add some additional pure-python definitions.
* ``<module>.py``: if this file exists, it becomes the "frontend" python module for the ns3 module, and the extension module (.so file) becomes _<module>.so instead of <module>.so. The <module>.py file has to import all symbols from the module _<module> (this is more tricky than it sounds, see src/core/bindings/core.py for an example), and then can add some additional pure-python definitions.
Historical Information
**********************