2. Quick Start¶
This chapter summarizes the ns-3 installation process for C++ users interested in trying a generic install of the main simulator. Python bindings installation is not covered.
Some of this chapter is redundant with the ns-3 tutorial, which also covers similar steps.
The steps are:
Download a source archive, or make a git clone, of ns-3 to a location on your file system (usually somewhere under your home directory).
Use a C++ compiler to compile the software into a set of shared libraries, executable example programs, and tests
ns-3 uses the CMake build system to manage the C++ compilation, and CMake itself calls on
a lower-level build system such as make
to perform the actual compilation.
2.1. Prerequisites¶
Make sure that your system has these prerequisites. Download can be via either git
or via
source archive download (via a web browser, wget
, or curl
).
Purpose
Tool
Minimum Version
Download
git
(for Git download)or
tar
andbunzip2
(for Web download)No minimum version
No minimum version
Compiler
g++
or
clang++
>= 10
>= 11
Configuration
python3
>= 3.8
Build system
cmake
,and at least one of:
make
,ninja
, orXcode
>= 3.13
No minimum version
Note
If you are using an older version of ns-3, other tools may be needed (such as
python2
instead of python3
and Waf
instead of cmake
). Check the file
RELEASE_NOTES
in the top-level directory for requirements for older releases.
From the command line, you can check the version of each of the above tools with version requirements as follows:
Tool
Version check command
g++
$ g++ --version
clang++
$ clang++ --version
python3
$ python3 -V
cmake
$ cmake --version
2.2. Download¶
There are two main options:
1. Download a release tarball. This will unpack to a directory such as ns-allinone-3.43
containing ns-3 and some other programs. Below is a command-line download using wget
,
but a browser download will also work:
$ wget https://www.nsnam.org/releases/ns-allinone-3.43.tar.bz2
$ tar xfj ns-allinone-3.43.tar.bz2
$ cd ns-allinone-3.43/ns-3.43
2. Clone ns-3 from the Git repository. The ns-3-allinone
can be cloned, as well as
ns-3-dev
by itself. Below, we illustrate the latter:
$ git clone https://gitlab.com/nsnam/ns-3-dev.git
$ cd ns-3-dev
Note that if you select option 1), your directory name will contain the release number. If
you clone ns-3, your directory will be named ns-3-dev
. By default, Git will check out
the ns-3 master
branch, which is a development branch. All ns-3 releases are tagged
in Git, so if you would then like to check out a past release, you can do so as follows:
$ git checkout -b ns-3.43-release ns-3.43
In this quick-start, we are omitting download and build instructions for optional ns-3 modules,
the NetAnim
animator, Python bindings, and NetSimulyzer
. The
ns-3 Tutorial has some
instructions on optional components, or else the documentation associated with the extension
should be consulted.
Moreover, in this guide we will assume that you are using ns-3.36 or later. Earlier versions had different configuration, build, and run command and options.
2.3. Building and testing ns-3¶
Once you have obtained the source either by downloading a release or by cloning a Git repository,
the next step is to configure the build using the CMake build system. The below commands
make use of a Python wrapper around CMake, called ns3
, that simplifies the command-line
syntax, resembling Waf syntax. There are several options to control the build, but enabling
the example programs and the tests, for a default build profile (with asserts enabled and
and support for ns-3 logging) is what is usually done at first:
$ ./ns3 configure --enable-examples --enable-tests
Depending on how fast your CPU is, the configuration command can take anywhere from a few seconds to a minute.
You should see some output such as below, if successful:
Modules configured to be built:
antenna aodv applications
bridge buildings config-store
core csma csma-layout
dsdv dsr energy
fd-net-device flow-monitor internet
internet-apps lr-wpan lte
mesh mobility netanim
network nix-vector-routing olsr
point-to-point point-to-point-layout propagation
sixlowpan spectrum stats
tap-bridge test topology-read
traffic-control uan virtual-net-device
wifi wimax
Modules that cannot be built:
brite click mpi
openflow visualizer
Do not be concerned about the list of modules that cannot be built; these modules are all optional and require some extra dependencies, but are not needed for initial exploration of ns-3.
Then, use the ns3
program to build the ns-3 module libraries and executables:
$ ./ns3 build
Build times vary based on the number of CPU cores, the speed of the CPU and memory, and the mode
of the build (whether debug mode, which is faster, or the default or optimized modes, which are
slower). Additional configuration (not covered here) can be used to limit the scope of the
build, and the ccache
, if installed, can speed things up. In general, plan on the build
taking a few minutes on faster workstations.
At the end of the build, if successful, the output will report on the underlying cmake
build command that was invoked by the ns3
program. Once the build is complete, you can
run the unit tests to check your build:
$ ./test.py
This command should run several hundred unit tests. If they pass, you have made a successful initial build of ns-3. Read further in this manual for instructions about building optional components, or else consult the ns-3 Tutorial or other documentation to get started with the base ns-3.
If you prefer to code with an code editor, consult the documentation in the ns-3 Manual on Working with CMake, since CMake enables ns-3 integration with a variety of code editors, including:
JetBrains’s CLion
Microsoft Visual Studio and Visual Studio Code
Apple’s XCode
CodeBlocks
Eclipse CDT4
2.4. Installing ns-3¶
Most users do not install ns-3 libraries to typical system library directories; they instead
just leave the libraries in the build
directory, and the ns3
Python program will
find these libraries. However, it is possible to perform an installation step– ns3 install
–
with the following caveats.
The location of the installed libraries is set by the --prefix
option specified at the
configure step. The prefix defaults to /usr/local
. For a given --prefix=$PREFIX
,
the installation step will install headers to a $PREFIX/include
directory, libraries
and pkgconfig files to a $PREFIX/lib
directory, and a few binaries to a
$PREFIX/libexec
directory. For example, ./ns3 configure --prefix=/tmp
, followed
by ./ns3 build
and ./ns3 install
, will lead to files being installed in
/tmp/include
, /tmp/lib
, and /tmp/libexec
.
Note that the ns3
script prevents running the script as root (or as a sudo user). As a
result, with the default prefix of /usr/local
, the installation will fail unless the
user has write privileges in that directory. Attempts to force this with
sudo ./ns3 install
will fail due to a check in the ns3
program that prevents running
as root. This check was installed by ns-3 maintainers for the safety of novice users who may
run ./ns3
in a root shell and later in a normal shell, and become confused about errors
resulting in lack of privileges to modify files. For users who know what they are doing and
who want to install to a privileged directory, users can comment out the statement
refuse_run_as_root()
in the ns3
program (around line 1400), and then run
sudo ./ns3 install
.