3. System Prerequisites¶
This chapter describes the various required, recommended, and optional system prerequisites for installing and using ns-3. Optional prerequisites depend on whether an optional feature of ns-3 is desired by the user. The chapter is written to be generally applicable to all operating systems, and subsequent chapters describe the specific packages for different operating systems.
The list of requirements depends on which version of ns-3 you are trying to build, and on which extensions you need.
Note
“Do I need to install all of these packages?” Some users want to install everything so that their configuration output shows that every feature is enabled. However, there is no real need to install prerequisites related to features you are not yet using; you can always come back later and install more prerequisites as needed. The build system should warn you if you are missing a prerequisite.
In the following, we have classified the prerequisites as either being required, recommended for all users, or optional depending on use cases.
Note
“Is there a maintained list of all prerequisites?” We use GitLab.com’s continuous
integration system for testing; the configuration YAML files for these jobs can be found
in the directory utils/tests/. So, for instance, if you want to look at what packages
the CI is installing for Alpine Linux, look at utils/tests/gitlab-ci-alpine.yml. The
default CI (Arch Linux) pacman commands are in utils/tests/gitlab-ci.yml.
3.1. Requirements¶
3.1.1. Minimal requirements for release 3.36 and later¶
A C++ compiler (g++ or clang++), Python 3, the CMake build
system, and a separate C++ building tool such as make, ninja-build, or Xcode are
the minimal requirements for compiling the software.
The tar and bunzip2 utilities are needed to unpack source file archives.
If you want to instead use Git to fetch code, rather than downloading
a source archive, then git is required instead.
3.1.2. Minimal requirements for release 3.30-3.35¶
If you are not using Python bindings, since the Waf build system is provided as part of ns-3, there are only two build requirements (a C++ compiler, and Python3) for a minimal install of these older ns-3 releases.
The tar and bunzip2 utilities are needed to unpack source file archives.
If you want to instead use Git to fetch code, rather than downloading
a source archive, then git is required instead.
3.1.3. Minimal requirements for release 3.29 and earlier¶
Similarly, only a C++ compiler and Python2 were strictly required for building the ns-3 releases 3.29 and earlier.
The tar and bunzip2 utilities are needed to unpack source file archives.
If you want to instead use Git to fetch code, rather than downloading
a source archive, then git is required instead.
3.2. Recommended¶
The following are recommended for most users of ns-3.
3.2.1. compiler cache optimization (for ns-3.37 and later)¶
Ccache is a compiler cache optimization that will speed up builds across multiple ns-3 directories, at the cost of up to an extra 5 GB of disk space used in the cache.
3.2.2. Code linting¶
Since ns-3.37 release, Clang-Format and Clang-Tidy are used to enforce the coding-style adopted by ns-3.
Users can invoke these tools directly from the command-line or through the
(utils/check-style-clang-format.py) check program.
Moreover, clang-tidy is integrated with CMake, enabling code scanning during the build phase.
Note
clang-format-14 through clang-format-16 version is required.
clang-format is strongly recommended to write code that follows the ns-3 code conventions, but might be skipped for simpler tasks (e.g., writing a simple simulation script for yourself).
clang-tidy is recommended when writing a module, to both follow code conventions and to provide hints on possible bugs in code.
Both are used in the CI system, and a merge request will likely fail if you did not use them.
3.3. Optional¶
The remaining prerequisites listed below are only needed for optional ns-3 components.
Note
As of ns-3.30 release (August 2019), ns-3 uses Python 3 by default, but earlier releases depend on Python 2 packages, and at least a Python 2 interpreter is recommended. If installing the below prerequisites for an earlier release, one may in general substitute ‘python’ where ‘python3’ is found in the below (e.g., install ‘python-dev’ instead of ‘python3-dev’).
3.3.1. To read pcap packet traces¶
Many ns-3 examples generate pcap files that can be viewed by pcap analyzers such as Tcpdump and Wireshark.
3.3.2. Database support¶
SQLite is recommended if you are using the statistics framework or if you are running LTE or NR simulations (which make use of SQLite databases):
3.3.3. Python bindings (ns-3.37 and newer)¶
ns-3 Python support now uses cppyy. Version 3.1.2 is the most recent supported cppyy release since ns-3.42.
Cppyy version 2.4.2 should be used from ns-3.37 up to 3.41.
Due to an upstream limitation with cppyy, Python bindings do not work on macOS machines with Apple silicon (M1 and M2 processors).
3.3.4. Using Python bindings (release 3.30 to ns-3.36)¶
This pertains to the use of existing Python bindings shipped with ns-3; for updating or generating new bindings, see further below.
Python bindings used pybindgen in the past, which
can usually be found in the ns-3-allinone directory. Python3 development packages, and
setup tools, are typically needed.
3.3.5. NetAnim animator¶
The Qt qt5 development tools are needed for NetAnim animator; qt4 will also work but we have migrated to qt5. qt6 compatibility is not tested.
3.3.6. PyViz visualizer¶
The PyViz visualizer uses a variety of Python packages supporting GraphViz. In general, to enable Python support in ns-3, cppyy is required.
3.3.7. MPI-based distributed simulation¶
Open MPI support is needed if you intend to run large, parallel ns-3 simulations.
3.3.8. Doxygen¶
Doxygen is only needed if you intend to write new Doxygen documentation for header files.
3.3.9. Sphinx documentation¶
The ns-3 manual (doc/manual), tutorial (doc/tutorial) and others are written in
reStructuredText for Sphinx, and figures are typically in dia. To build PDF versions,
texlive packages are needed.
3.3.10. Eigen3 support¶
Eigen3 is used to support more efficient calculations when using the 3GPP propagation loss models in LTE and NR simulations.
3.3.11. GNU Scientific Library (GSL)¶
GNU Scientific Library (GSL) is is only used for more accurate 802.11b (legacy) WiFi error models (not needed for more modern OFDM-based Wi-Fi).
3.3.12. XML-based version of the config store¶
Libxml2 is needed for the XML-based Config Store feature.
3.3.13. A GTK-based configuration system¶
GTK development libraries are also related to the (optional) config store, for graphical desktop support.
3.3.14. Generating modified python bindings (ns-3.36 and earlier)¶
To modify the Python bindings found in release 3.36 and earlier (not needed for modern releases, or if you do not use Python, the LLVM toolchain and cxxfilt are needed.
You will also need to install castxml and pygccxml as per the instructions for Python bindings (or through the bake build tool as described in the ns-3 tutorial). If you plan to work with bindings or rescan them for any ns-3 C++ changes you might make, please read the chapter in the manual (corresponding to the release) on this topic.
3.3.15. To experiment with virtual machines and ns-3¶
Linux systems can use LXC and TUN/TAP device drivers for emulation support.
3.3.16. Support for openflow module¶
OpenFlow switch support requires XML and Boost development libraries.