nsnam / ns-3-dev-git

The Network Simulator, Version 3 License This software is licensed under the terms of the GNU General Public License v2.0 only (GPL-2.0-only). See the LICENSE file for more details. Table of Contents • Overview • Software overview • Getting ns-3 • Building ns-3 • Testing ns-3 • Running ns-3 • ns-3 Documentation • Working with the Development Version of ns-3 • Contributing to ns-3 • Reporting Issues • Asking Questions • ns-3 App Store > **NOTE**: Much more substantial information about ns-3 can be found at Overview: An Open Source Project ns-3 is a free open source project aiming to build a discrete-event network simulator targeted for simulation research and education. This is a collaborative project; we hope that the missing pieces of the models we have not yet implemented will be contributed by the community in an open collaboration process. If you would like to contribute to ns-3, please check the Contributing to ns-3 section below. This README excerpts some details from a more extensive tutorial that is maintained at: Software overview From a software perspective, ns-3 consists of a number of C++ libraries organized around different topics and technologies. Programs that actually run simulations can be written in either C++ or Python; the use of Python is enabled by runtime C++/Python bindings. Simulation programs will typically link or import the ns library and any additional libraries that they need. ns-3 requires a modern C++ compiler installation (g++ or clang++) and the CMake build system. Most ns-3 programs are single-threaded; there is some limited support for parallelization using the MPI framework. ns-3 can also run in a real-time emulation mode by binding to an Ethernet device on the host machine and generating and consuming packets on an actual network. The ns-3 APIs are documented using Doxygen. The code for the framework and the default models provided by ns-3 is built as a set of libraries. The libraries maintained by the open source project can be found in the directory. Users may extend ns-3 by adding libraries to the build; third-party libraries can be found on the ns-3 App Store or elsewhere in public Git repositories, and are usually added to the directory. Getting ns-3 ns-3 can be obtained by either downloading a released source archive, or by cloning the project's Git repository. Starting with ns-3 release version 3.45, there are two versions of source archives that are published with each release: • ns-3.##.tar.bz2 • ns-allinone-3.##.tar.bz2 The first archive is simply a compressed archive of the same code that one can obtain by checking out the release tagged code from the ns-3-dev Git repository. The second archive consists of ns-3 plus additional contributed modules that are maintained outside of the main ns-3 open source project but that have been reviewed by maintainers and lightly tested for compatibility with the release. The contributed modules included in the release will change over time as new third-party libraries emerge while others may lose compatibility with the ns-3 mainline (e.g., if they become unmaintained). Building ns-3 As mentioned above, ns-3 uses the CMake build system, but the project maintains a customized wrapper around CMake called the tool. This tool provides a Waf-like API to the underlying CMake build manager. To build the set of default libraries and the example programs included in this package, you need to use the tool. This tool provides a Waf-like API to the underlying CMake build manager. Detailed information on how to use is included in the quick start guide. Before building ns-3, you must configure it. This step allows the configuration of the build options, such as whether to enable the examples, tests and more. To configure ns-3 with examples and tests enabled, run the following command on the ns-3 main directory: Then, build ns-3 by running the following command: By default, the build artifacts will be stored in the directory. Supported Platforms The current codebase is expected to build and run on the set of platforms listed in the release notes file. Other platforms may or may not work: we welcome patches to improve the portability of the code to these other platforms. Testing ns-3 ns-3 contains test suites to validate the models and detect regressions. To run the test suite, run the following command on the ns-3 main directory: More information about ns-3 tests is available in the test framework section of the manual. Running ns-3 On recent Linux systems, once you have built ns-3 (with examples enabled), it should be easy to run the sample programs with the following command, such as: That program should generate a text trace file and a set of binary PCAP trace files, which can be read by . The program source can be found in the directory. Running ns-3 from Python If you do not plan to modify ns-3 upstream modules, you can get a pre-built version of the ns-3 python bindings. It is recommended to create a python virtual environment to isolate different application packages from system-wide packages (installable via the OS package managers). If you do not have , check their documents on how to install it. After installing the package, you can then create your simulation python script. Below is a trivial demo script to get you started. The simulation will take a while to start, while the bindings are loaded. The script above will print the logging messages for the called commands. Use to check the prototypes for all functions defined in the ns3 namespace. To get more useful results, query specific classes of interest and their functions e.g., . Smart pointers can be differentiated from objects by checking if is listed in . To dereference the pointer, use . Most ns-3 simulations are written in C++ and the documentation is oriented towards C++ users. The ns-3 tutorial programs ( , , etc.) have Python equivalents, if you are looking for some initial guidance on how to use the Python A…