Article directory
foreword
Recently, due to work needs, I started to contact ns-3. The author has zero foundation and successfully completed the installation of ns-3 from scratch. This article is a record post of ns-3 installation process or a zero-based tutorial for Xiaobai.
The software version information used in this article is as follows: VMware Workstation 16 Pro, Ubuntu 22.10 and ns-3.37. All content is correct.
1. Install virtual machine and Ubuntu
The author first used VMware Workstation 16 Pro to install a virtual machine, and then installed the Ubuntu 22.10 system on this basis. Since there are many tutorials in this area, the author will not repeat them here. For details, please refer to the following articles:
Virtual machine VMware download and installation tutorial (detailed)
VMware installation Ubuntu 18.04 virtual machine (mirror download, hard disk partition, virtual machine creation, installation system, bridged mode network configuration)
After completing the above preparations for installing the virtual machine and Ubuntu, we can install ns-3 through the command line in the Ubuntu terminal (Terminal). ns-3 provides installation instructions in the "Getting Started" chapter of its official tutorial , and provides detailed ns-3 official installation instructions in the official wiki . As long as you are patient and careful, you can complete the ns-3 installation smoothly. The following installation tutorial refers to these official instructions, and the author has translated and summarized and refined to a certain extent. It should be noted that this tutorial is mainly for ns-3.37 version and Ubuntu 22.10 version. If you need to install other versions of Ubuntu and ns-3, please read the ns-3 official installation guide carefully to avoid stepping on the pit.
2. Install dependent libraries
ns-3 is mainly developed in C++ language on GNU/Linux and macOS platforms. Simulation with ns-3 requires at least a C++ compiler (g++ or clang++), a build system (CMake and make or ninja, etc.), and a Python interpreter. This is the minimum requirement for simulation with ns-3.
For ns-3.36 and later versions, it is recommended in the ns-3 official installation guide to install these required libraries through the following command line:
sudo apt install g++ python3 cmake ninja-build git
A few notes:
- Since January 2022 (ns-3.36 version), g++ requires version 8 or above, but the old version of Ubuntu (18.04, 16.04) installs the old version of g++ by default, so users of old versions of Ubuntu should pay attention to the g++ version problem, ns- 3 The solution is also given in the official installation guide (the g++ 12.2.0 version was installed using the above command line in Ubuntu 22.10).
- Since August 2019 (ns-3.30 version), ns-3 uses Python 3 by default, while earlier versions used Python 2, so ns-3 users before ns-3.30 version are recommended to use " python" instead of "python 3" to install the Python 2 interpreter. Moreover, Python 3 of version 3.6 or above is required in the latest version (ns-3.37) of the ns-3 official installation guide .
- If you installed ns-3 by downloading the source archive, you do not need to install git.
In addition, the ns-3 official installation guide also recommends ns-3.37 and later versions to install ccache, the command line is as follows:
sudo apt install ccache
Ccache is a compiler cache optimization tool that speeds up builds across multiple ns-3 directories at the cost of using up to 5 GB of additional disk space in the cache. It should be noted that for Ubuntu 20.04 and earlier versions, the ccache version (3.7.7 or earlier) installed through the apt command may not provide performance advantages, so the ns-3 official installation guide recommends that these users install 4 or 4 The above version of ccache (can be installed through source). For Ubuntu 22.04 and above, you can install ccache directly using the apt command.
In addition to the above-mentioned required libraries, the following optional libraries generally need to be installed to support some of the extended functions and features of ns-3:
- Python visualizer and bindings (ns-3.37 and newer): cppyy Python module and Pyviz dependencies
python3 -m pip install --user cppyy
sudo apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3
If the above command line results in the following error:
/usr/bin/python3: No module named pip
Then you can first install pip through the following command line:
sudo apt install python3-pip
- Additional minimum requirements for Python (development): For using the ns-3-allinone repository (cloned from Git), additional packages need to be fetched and pybindgen and netanim successfully installed
sudo apt install python3-setuptools git
- Netanim: Netanim requires qt5 development tools
sudo apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools
- Support for MPI-based distributed simulation:
sudo apt install openmpi-bin openmpi-common openmpi-doc libopenmpi-dev
- Support for bake build tools:
sudo apt install mercurial unzip
- debugging:
sudo apt install gdb valgrind
- Support for the utils/check-style-clang-format.py code style checker (since ns-3.37):
sudo apt install clang-format
- Doxygen and related inline documentation:
sudo apt install doxygen graphviz imagemagick
sudo apt install texlive texlive-extra-utils texlive-latex-extra texlive-font-utils dvipng latexmk
- ns-3 manuals and tutorials are written in Sphinx, and pictures are generally in dia format:
sudo apt install python3-sphinx dia
- GNU Scientific Library (GSL) (to support a more accurate 802.11b WiFi error model):
sudo apt install gsl-bin libgsl-dev libgslcblas0
- Read pcap packet trace:
sudo apt install tcpdump
- Databases that support the statistical framework:
sudo apt install sqlite sqlite3 libsqlite3-dev
- Xml-based configuration storage version (requires libxml2 >= version 2.7):
sudo apt install libxml2 libxml2-dev
- GTK-based configuration system:
sudo apt install libgtk-3-dev
- Experiment with a virtual machine and ns-3:
sudo apt install vtun lxc uml-utilities
- Support openflow module and Boost development library:
sudo apt install libxml2 libxml2-dev libboost-all-dev
Finally, summarize the above installation commands:
sudo apt install g++ python3 cmake ninja-build git
sudo apt install ccache
sudo apt install python3-pip
python3 -m pip install --user cppyy
sudo apt install gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3
sudo apt install python3-setuptools git
sudo apt install qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools
sudo apt install openmpi-bin openmpi-common openmpi-doc libopenmpi-dev
sudo apt install mercurial unzip
sudo apt install gdb valgrind
sudo apt install clang-format
sudo apt install doxygen graphviz imagemagick
sudo apt install texlive texlive-extra-utils texlive-latex-extra texlive-font-utils dvipng latexmk
sudo apt install python3-sphinx dia
sudo apt install gsl-bin libgsl-dev libgslcblas0
sudo apt install tcpdump
sudo apt install sqlite sqlite3 libsqlite3-dev
sudo apt install libxml2 libxml2-dev
sudo apt install libgtk-3-dev
sudo apt install vtun lxc uml-utilities
sudo apt install libxml2 libxml2-dev libboost-all-dev
The above installation commands have been tested correctly in Ubuntu 22.10, and other distributions or other Debian-based systems may be slightly different. It should be noted that the official ns-3 installation instructions suggest that the Ubuntu 16.04 LTS release may be the oldest release known to be compatible with the latest ns-3 release.
3. Download ns-3
ns-3 is released in source code form. ns-3 officially provides 3 ways to download ns-3 source code:
- Download the source code archive (i.e. tarball) from the ns-3 website
- Clone the git repository from gitlab.com
- Use the source code package management tool bake that comes with ns-3 to download the ns-3 source code
Git is recommended here.
First, create a new directory under the main directory (note that there should be no spaces in the directory name, such as "ns 3") to save the local git warehouse:
cd
mkdir repos # 新建repos目录
cd repos
git clone https://gitlab.com/nsnam/ns-3-allinone.git # 克隆git仓库到本地
When executing the above git command, we will see something like this:
After the above git command is completed, we will find a directory named ns-3-allinone under our ~/repos directory, as shown in the following figure:
Click to enter the ns-3-allinone directory, we will find that it includes the following files:
It should be noted that so far we have actually only downloaded some Python scripts (as shown in the figure above), and have not downloaded the c++ source code of ns-3. Next, we use these scripts to download and build the ns-3 distribution.
Notice that there is a download.py script in the above ns-3-allinone directory, we use it to further obtain ns-3 related source code (need to execute the command in the ns-3-allinone directory), the command line is as follows:
cd ns-3-allinone # 进入ns-3-allinone目录
python3 download.py -n ns-3.37 # 下载ns-3.37源代码（如果想下载其他版本的ns-3，只需指定版本号）
When executing the above command, we see something like this:
After the above command is completed, we will find that there are several more directories under the ns-3-allinone directory, such as ns-3 main project (ns-3.37), ns-3 source code package management tool bake (bake), visual simulation tool NetAnim (netanim):
So far, we have completed the download of ns-3.
Notes :
In addition to the release version of ns-3.37, ns-3 officially provides the development version of ns-3 download, the command line is as follows:
python3 download.py
The development version contains some features that are under development and have not been fully tested. Unless you are planning to submit code to ns-3 or you must use a new feature, it is recommended that readers choose a more stable release version.
4. Build ns-3
The most common way to build the ns-3 project for the first time is to use the build.py script in the ns-3-allinone directory (the command needs to be executed in the ns-3-allinone directory):
./build.py --enable-examples --enable-tests
The "--enable-examples" and "--enable-tests" parameters in the above command line allow build.py to compile the example scripts and test scripts that come with ns-3 at the same time.
After the build is complete, the following information will be displayed:
The "Summary of optional ns-3 features" section lists which features of ns-3 are enabled and which are disabled. "OFF (not requested)" means that the feature is not enabled by default, or requires the underlying system to work properly. "OFF(missing dependency)" indicates that the feature depends on a third-party library, but the third-party library is not found, so it is disabled. The modules configured to be built are listed in the "Modules configured to be built" section. The "Modules that cannot be built" section are uncompiled modules. These modules generally require the support of third-party libraries, which can be added later as needed. If there is a compilation error, there may be a missing dependency package.
In order to allow users to quickly verify whether ns-3 has been built correctly, the ns-3 project comes with a test.py script (under the ns-3.37 directory of the ns main project). By running the test cases that come with ns-3, test.py can test each module of ns-3 one by one:
cd ns-3.37
./test.py
When executing the above command, we see something like this:
After the above command is completed, if the following information is displayed (0 failed, 0 crashed, 0 valgrind errors), it means that ns-3 has been built correctly!
