1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
.. include:: replace.txt
.. highlight:: bash
.. heading hierarchy:
------------- Chapter
************* Section (#.#)
============= Subsection (#.#.#)
############# Paragraph (no number)
.. _Quick start:
Quick Start
-----------
This chapter summarizes the |ns3| 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
|ns3| `tutorial <https://www.nsnam.org/docs/tutorial/html/>`_, which also covers similar steps.
The steps are:
1. Download a source archive, or make a git clone, of |ns3| to a location on your file
system (usually somewhere under your home directory).
2. Use a C++ compiler to compile the software into a set of shared libraries, executable example
programs, and tests
|ns3| 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.
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) | No minimum version |
+ + + +
| | or ``tar`` and ``bunzip2`` | No minimum version |
| | (for Web download) | |
+--------------------+--------------------------------------+------------------------------+
| **Compiler** | ``g++`` | >= 10 |
+ + + +
| | or ``clang++`` | >= 11 |
+--------------------+--------------------------------------+------------------------------+
| **Configuration** | ``python3`` | >= 3.8 |
+--------------------+--------------------------------------+------------------------------+
| **Build system** | ``cmake``, | >= 3.13 |
+ + + +
| | and at least one of: | No minimum version |
| | ``make``, ``ninja``, or ``Xcode`` | |
+--------------------+--------------------------------------+------------------------------+
.. 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`` |
+--------------------------------------+------------------------------------+
Download
********
There are two main options:
#. Download a release tarball. This will unpack to a directory such as ``ns-allinone-3.45``
or ``ns-3.45``. Below is a command-line download using ``wget``,
but a browser download will also work::
$ wget https://www.nsnam.org/releases/ns-allinone-3.45.tar.bz2
$ tar xfj ns-allinone-3.45.tar.bz2
$ cd ns-3.45
#. Clone |ns3| from the ``ns-3-dev`` Git repository::
$ 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 |ns3|, your directory will be named ``ns-3-dev``. By default, Git will check out
the |ns3| ``master`` branch, which is a development branch. All |ns3| 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.45-release ns-3.45
In this quick-start, we are omitting download and build instructions for optional |ns3| modules,
the ``NetAnim`` animator, Python bindings, and ``NetSimulyzer``. The
`ns-3 Tutorial <https://www.nsnam.org/docs/tutorial/html/getting-started.html>`_ 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.
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 |ns3| 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
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 |ns3|.
Then, use the ``ns3`` program to build the |ns3| 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 |ns3|. Read further in this manual for instructions about building
optional components, or else consult the |ns3| Tutorial or other documentation to get started
with the base |ns3|.
If you prefer to code with an code editor, consult the documentation in the |ns3| Manual
on `Working with CMake <https://www.nsnam.org/docs/manual/html/working-with-cmake.html>`_,
since CMake enables |ns3| integration with a variety of code editors, including:
* JetBrains's CLion
* Microsoft Visual Studio and Visual Studio Code
* Apple's XCode
* CodeBlocks
* Eclipse CDT4
Installing ns-3
***************
Most users do not install |ns3| 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 |ns3| 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``.
|
