diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index ea9f64072..666dce5a9 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -27,7 +27,7 @@ requirements (Note: not all ns-3 features are available on all systems): - (macOS only) Xcode 11 or later - (Windows only) Msys2/MinGW64 toolchain or WSL2 -Python API requires [Cppyy](https://cppyy.readthedocs.io/en/latest/installation.html). +Python API requires [Cppyy](https://cppyy.readthedocs.io/en/latest/installation.html). Specifically, avoid Cppyy version 3; stay with version 2.4.2 for this release. ### New user-visible features diff --git a/doc/installation/source/linux.rst b/doc/installation/source/linux.rst index 0f1cf65a8..a8482c528 100644 --- a/doc/installation/source/linux.rst +++ b/doc/installation/source/linux.rst @@ -106,9 +106,11 @@ Please see below subsections for Python-related package requirements. Python bindings =============== +Python requires `Cppyy, ` and specifically, version 2.4.2 is the latest version known to work with ns-3 at this time. + ns-3.37 and newer:: - python3 -m pip install --user cppyy + python3 -m pip install --user cppyy==2.4.2 ns-3.30-3.36 (also requires pybindgen, found in the ``allinone`` directory):: diff --git a/doc/installation/source/overview.rst b/doc/installation/source/overview.rst index 02c01f5ce..30a5e7adc 100644 --- a/doc/installation/source/overview.rst +++ b/doc/installation/source/overview.rst @@ -51,11 +51,9 @@ choose to use a subset of the available libraries; only the ``core`` library is |ns3| uses the CMake build system (until release 3.36, the Waf build system was used). It can be built from command-line or via a code editor program. -Most users write C++ ns-3 programs; Python support is less frequently used and is not officially -maintained as of this writing. As of *ns-3.37*, |ns3| uses `cppyy` to generate runtime Python -bindings. Officially, Python3 support is only lightly maintained, and the `cppyy` support was -contributed by Gabriel Ferreira as a proof-of-concept (hint: the project is seeking a full-time -maintainer to develop this further). +Most users write C++ ns-3 programs; Python support is less frequently used. +As of *ns-3.37*, |ns3| uses `cppyy` to generate runtime Python +bindings, and |ns3| is available in the Pip repositories as of ns-3.39 release. Many users may be familiar with how software is packaged and installed on Linux and other systems using package managers. For example, to install a given Linux development library such as diff --git a/doc/installation/source/system.rst b/doc/installation/source/system.rst index a4c8731ba..a458d6510 100644 --- a/doc/installation/source/system.rst +++ b/doc/installation/source/system.rst @@ -140,7 +140,8 @@ if you are running LTE or NR simulations (which make use of SQLite databases): Python bindings (ns-3.37 and newer) =================================== -|ns3| Python support now uses `cppyy `_. +|ns3| Python support now uses `cppyy `_. Version 2.4.2 +is the most recent supported cppyy release; version 3.0.0 is not currently supported. Using Python bindings (release 3.30 to ns-3.36) =============================================== diff --git a/doc/manual/source/python.rst b/doc/manual/source/python.rst index 26f39cf52..6ad5ec803 100644 --- a/doc/manual/source/python.rst +++ b/doc/manual/source/python.rst @@ -115,10 +115,11 @@ simple modules in python, jump to the `Using the pip wheel`_ section. Using the bindings from the ns-3 source ======================================= -The main prerequisite is to install `cppyy`. Depending on how you may manage +The main prerequisite is to install `cppyy`, with version no later than 2.4.2. +Depending on how you may manage Python extensions, the installation instructions may vary, but you can first check if it installed by seeing if the `cppyy` module can be -successfully imported: +successfully imported and the version is no later than 2.4.2: .. sourcecode:: bash @@ -127,6 +128,8 @@ successfully imported: [GCC 9.4.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import cppyy + >>> print("%s" % cppyy.__version) + 2.4.2 >>> If not, you may try to install via `pip` or whatever other manager you are @@ -134,7 +137,7 @@ using; e.g.: .. sourcecode:: bash - $ python3 -m pip install --user cppyy + $ python3 -m pip install --user cppyy==2.4.2 First, we need to enable the build of Python bindings: @@ -149,13 +152,13 @@ To run example programs, there are two ways to use ns3 to take care of this. On .. sourcecode:: bash $ ./ns3 shell - $ python3 examples/wireless/mixed-wireless.py + $ python3 examples/wireless/mixed-wired-wireless.py and the other is to use the 'run' option to ns3: .. sourcecode:: bash - $ ./ns3 run examples/wireless/mixed-wireless.py + $ ./ns3 run examples/wireless/mixed-wired-wireless.py Use the ``--no-build`` option to run the program without invoking a project rebuild. This option may be useful to improve execution time when running the same program @@ -163,14 +166,14 @@ repeatedly but with different arguments, such as from scripts. .. sourcecode:: bash - $ ./ns3 run --no-build examples/wireless/mixed-wireless.py + $ ./ns3 run --no-build examples/wireless/mixed-wired-wireless.py To run a python script under the C debugger: .. sourcecode:: bash $ ./ns3 shell - $ gdb --args python3 examples/wireless/mixed-wireless.py + $ gdb --args python3 examples/wireless/mixed-wired-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: