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
|
.. include:: replace.txt
.. highlight:: bash
.. _Quick Start:
Quick Start
-----------
This section is optional, for readers who want to get |ns3| up and running
as quickly as possible. Readers may skip forward to the :ref:`Introduction`
chapter, followed by the :ref:`Getting Started` chapter, for a lengthier
coverage of all of this material.
Brief Summary
*************
|ns3| is a discrete-event simulator typically run from the command line.
It is written directly in C++, not in a high-level modeling language;
simulation events are simply C++ function calls, organized by a scheduler.
An |ns3| user will obtain the |ns3| source code (see below),
compile it into shared (or static) libraries, and link the libraries to
`main()` programs that he or she authors. The `main()` program is where
the specific simulation scenario configuration is performed and where the
simulator is run and stopped. Several example programs are provided, which
can be modified or copied to create new simulation scenarios. Users also
often edit the |ns3| library code (and rebuild the libraries) to change
its behavior.
|ns3| has optional Python bindings for authoring scenario configuration
programs in Python (and using a Python-based workflow); this quick start
does not cover those aspects.
Prerequisites
*************
|ns3| has various optional extensions, but the main features just require
a C++ compiler (g++ or clang++), Python (version 3.8 or above), CMake and
a build-system (e.g. make, ninja, Xcode).
We focus in this chapter only on getting |ns3| up and running on a system
supported by a recent C++ compiler and Python runtime support.
For Linux, use either g++ or clang++ compilers. For macOS, use clang++
(available in Xcode or Xcode Command Line Tools). For Windows, Msys2 tools
with the MinGW64 toolchain can be used (since ns-3.37) for most use
cases. For releases earlier than ns-3.37, or for use of emulation modes
or Python bindings, we recommend
to either use a Linux virtual machine, or the Windows Subsystem for Linux.
Downloading ns-3
****************
|ns3| is distributed in source code only (some binary packages exist but
they are not maintained by the open source project). There are two
main ways to obtain the source code: 1) downloading the latest release
as a source code archive from the main |ns3| web site, or 2) cloning
the Git repository from GitLab.com. These two options are described next;
either one or the other download option (but not both) should be followed.
Downloading the Latest Release
++++++++++++++++++++++++++++++
1) Download the latest release from https://www.nsnam.org/releases/latest
The latest release is available in two versions, as |ns3| by itself (as
maintained by the open source project) or an ``allinone`` archive that
contains |ns3| and additional third-party contributed modules. Note that
the main |ns3| release can always be later extended by adding contributing
modules of your choice
2) Unpack either archive version in a working directory of your choice.
::
$ tar xjf ns-3.45.tar.bz2
or
::
$ tar xjf ns-allinone-3.45.tar.bz2
3) Change into the |ns3| directory directly; e.g.
::
$ cd ns-3.45
Cloning ns-3 from GitLab.com
++++++++++++++++++++++++++++
You can perform a Git clone in the usual way:
::
$ git clone https://gitlab.com/nsnam/ns-3-dev.git
If you are content to work with the tip of the development tree; you need
only to `cd` into ns-3-dev; the `master` branch is checked out by default.
::
$ cd ns-3-dev
If instead you want to try the most recent release (version 3.45 as of this
writing), you can checkout a branch corresponding to that git tag:
::
$ git checkout -b ns-3.45-branch ns-3.45
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
Then, use ``ns3`` to build |ns3|:
::
$ ./ns3 build
Once complete, you can run the unit tests to check your build:
::
$ ./test.py
All tests should either PASS or be SKIPped. At this point, you have a
working |ns3| simulator. From here, you can start to
run programs (look in the examples directory). To run the first tutorial
program, whose source code is located at `examples/tutorial/first.cc`,
use ns3 to run it (by doing so, the |ns3| shared libraries are found
automatically):
::
$ ./ns3 run first
To view possible command-line options, specify the `--PrintHelp` argument:
::
$ ./ns3 run 'first --PrintHelp'
To continue reading about the conceptual model and architecture of |ns3|,
the tutorial chapter :ref:`Conceptual Overview` would be the next natural place
to skip to, or you can learn more about the project and the
various build options by continuing directly with the :ref:`Introduction`
and :ref:`Getting Started` chapters.
|
