author | Tom Henderson <tomh@tomh.org> |
Tue, 09 Oct 2012 12:47:50 -0700 | |
changeset 9107 | 97282f9f685b |
parent 8837 | b769bed02bc2 |
child 9163 | 950db74a6484 |
permissions | -rw-r--r-- |
6754 | 1 |
.. include:: replace.txt |
2 |
||
3 |
||
4 |
Getting Started |
|
5 |
--------------- |
|
6 |
||
7 |
Downloading ns-3 |
|
8 |
**************** |
|
9 |
||
10 |
The |ns3| system as a whole is a fairly complex system and has a |
|
11 |
number of dependencies on other components. Along with the systems you will |
|
8837 | 12 |
most likely deal with every day (the GNU toolchain, Mercurial, a text |
6754 | 13 |
editor) you will need to ensure that a number of additional libraries are |
14 |
present on your system before proceeding. |ns3| provides a wiki |
|
15 |
for your reading pleasure that includes pages with many useful hints and tips. |
|
16 |
One such page is the "Installation" page, |
|
17 |
http://www.nsnam.org/wiki/index.php/Installation. |
|
18 |
||
19 |
The "Prerequisites" section of this wiki page explains which packages are |
|
20 |
required to support common |ns3| options, and also provides the |
|
21 |
commands used to install them for common Linux variants. Cygwin users will |
|
22 |
have to use the Cygwin installer (if you are a Cygwin user, you used it to |
|
23 |
install Cygwin). |
|
24 |
||
25 |
You may want to take this opportunity to explore the |ns3| wiki |
|
26 |
a bit since there really is a wealth of information there. |
|
27 |
||
28 |
From this point forward, we are going to assume that the reader is working in |
|
29 |
Linux or a Linux emulation environment (Linux, Cygwin, etc.) and has the GNU |
|
30 |
toolchain installed and verified along with the prerequisites mentioned |
|
31 |
above. We are also going to assume that you have Mercurial and Waf installed |
|
7314
7162e24118ea
Miscellaneous fixes to Tutorial
Mitch Watrous <watrous@u.washington.edu>
parents:
7275
diff
changeset
|
32 |
and running on the target system. |
6754 | 33 |
|
34 |
The |ns3| code is available in Mercurial repositories on the server |
|
35 |
http://code.nsnam.org. You can also download a tarball release at |
|
36 |
http://www.nsnam.org/releases/, or you can work with repositories |
|
37 |
using Mercurial. We recommend using Mercurial unless there's a good reason |
|
38 |
not to. See the end of this section for instructions on how to get a tarball |
|
39 |
release. |
|
40 |
||
41 |
The simplest way to get started using Mercurial repositories is to use the |
|
42 |
``ns-3-allinone`` environment. This is a set of scripts that manages the |
|
43 |
downloading and building of various subsystems of |ns3| for you. We |
|
44 |
recommend that you begin your |ns3| adventures in this environment |
|
45 |
as it can really simplify your life at this point. |
|
46 |
||
47 |
Downloading ns-3 Using Mercurial |
|
48 |
++++++++++++++++++++++++++++++++ |
|
49 |
One practice is to create a directory called ``repos`` in one's home |
|
50 |
directory under which one can keep local Mercurial repositories. |
|
51 |
*Hint: we will assume you do this later in the tutorial.* If you adopt |
|
52 |
that approach, you can get a copy of ``ns-3-allinone`` by typing the |
|
53 |
following into your Linux shell (assuming you have installed Mercurial): |
|
54 |
||
55 |
:: |
|
56 |
cd |
|
57 |
mkdir repos |
|
58 |
cd repos |
|
59 |
hg clone http://code.nsnam.org/ns-3-allinone |
|
60 |
||
61 |
As the hg (Mercurial) command executes, you should see something like the |
|
62 |
following displayed, |
|
63 |
||
64 |
:: |
|
65 |
||
66 |
destination directory: ns-3-allinone |
|
67 |
requesting all changes |
|
68 |
adding changesets |
|
69 |
adding manifests |
|
70 |
adding file changes |
|
7654 | 71 |
added 47 changesets with 67 changes to 7 files |
72 |
updating to branch default |
|
6754 | 73 |
7 files updated, 0 files merged, 0 files removed, 0 files unresolved |
74 |
||
75 |
After the clone command completes, you should have a directory called |
|
7654 | 76 |
``ns-3-allinone``, the contents of which should |
6754 | 77 |
look something like the following: |
78 |
||
79 |
:: |
|
80 |
||
81 |
build.py* constants.py dist.py* download.py* README util.py |
|
82 |
||
83 |
Notice that you really just downloaded some Python scripts. The next step |
|
84 |
will be to use those scripts to download and build the |ns3| |
|
85 |
distribution of your choice. |
|
86 |
||
87 |
If you go to the following link: http://code.nsnam.org/, |
|
88 |
you will see a number of repositories. Many are the private repositories of |
|
89 |
the |ns3| development team. The repositories of interest to you will |
|
90 |
be prefixed with "ns-3". Official releases of |ns3| will be |
|
91 |
numbered as ``ns-3.<release>.<hotfix>``. For example, a second hotfix to a |
|
7275 | 92 |
still hypothetical release forty two of |ns3| would be numbered as |
93 |
``ns-3.42.2``. |
|
6754 | 94 |
|
95 |
The current development snapshot (unreleased) of |ns3| may be found |
|
96 |
at http://code.nsnam.org/ns-3-dev/. The |
|
97 |
developers attempt to keep these repository in consistent, working states but |
|
98 |
they are in a development area with unreleased code present, so you may want |
|
99 |
to consider staying with an official release if you do not need newly- |
|
100 |
introduced features. |
|
101 |
||
102 |
Since the release numbers are going to be changing, I will stick with |
|
103 |
the more constant ns-3-dev here in the tutorial, but you can replace the |
|
104 |
string "ns-3-dev" with your choice of release (e.g., ns-3.10) in the |
|
105 |
text below. You can find the latest version of the |
|
106 |
code either by inspection of the repository list or by going to the |
|
7314
7162e24118ea
Miscellaneous fixes to Tutorial
Mitch Watrous <watrous@u.washington.edu>
parents:
7275
diff
changeset
|
107 |
`"ns-3 Releases" |
7162e24118ea
Miscellaneous fixes to Tutorial
Mitch Watrous <watrous@u.washington.edu>
parents:
7275
diff
changeset
|
108 |
<http://www.nsnam.org/releases>`_ |
7162e24118ea
Miscellaneous fixes to Tutorial
Mitch Watrous <watrous@u.washington.edu>
parents:
7275
diff
changeset
|
109 |
web page and clicking on the latest release link. |
6754 | 110 |
|
111 |
Go ahead and change into the ``ns-3-allinone`` directory you created when |
|
112 |
you cloned that repository. We are now going to use the ``download.py`` |
|
113 |
script to pull down the various pieces of |ns3| you will be using. |
|
114 |
||
115 |
Go ahead and type the following into your shell (remember you can substitute |
|
116 |
the name of your chosen release number instead of ``ns-3-dev`` -- like |
|
117 |
``"ns-3.10"`` if you want to work with a |
|
118 |
stable release). |
|
119 |
||
120 |
:: |
|
121 |
||
122 |
./download.py -n ns-3-dev |
|
123 |
||
124 |
Note that the default for the ``-n`` option is ``ns-3-dev`` and so the |
|
125 |
above is actually redundant. We provide this example to illustrate how to |
|
126 |
specify alternate repositories. In order to download ``ns-3-dev`` you |
|
127 |
can actually use the defaults and simply type, |
|
128 |
||
129 |
:: |
|
130 |
||
131 |
./download.py |
|
132 |
||
133 |
As the hg (Mercurial) command executes, you should see something like the |
|
134 |
following, |
|
135 |
||
136 |
:: |
|
137 |
||
138 |
# |
|
139 |
# Get NS-3 |
|
140 |
# |
|
141 |
||
142 |
Cloning ns-3 branch |
|
143 |
=> hg clone http://code.nsnam.org/ns-3-dev ns-3-dev |
|
144 |
requesting all changes |
|
145 |
adding changesets |
|
146 |
adding manifests |
|
147 |
adding file changes |
|
148 |
added 4634 changesets with 16500 changes to 1762 files |
|
149 |
870 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
150 |
||
151 |
This is output by the download script as it fetches the actual ``ns-3`` |
|
152 |
code from the repository. |
|
153 |
||
154 |
The download script is smart enough to know that on some platforms various |
|
155 |
pieces of ns-3 are not supported. On your platform you may not see some |
|
156 |
of these pieces come down. However, on most platforms, the process should |
|
157 |
continue with something like, |
|
158 |
||
159 |
:: |
|
160 |
||
161 |
# |
|
162 |
# Get PyBindGen |
|
163 |
# |
|
164 |
||
165 |
Required pybindgen version: 0.10.0.640 |
|
166 |
Trying to fetch pybindgen; this will fail if no network connection is available. Hit Ctrl-C to skip. |
|
167 |
=> bzr checkout -rrevno:640 https://launchpad.net/pybindgen pybindgen |
|
168 |
Fetch was successful. |
|
169 |
||
170 |
This was the download script getting the Python bindings generator for you. |
|
171 |
Note that you will need bazaar (bzr), a version control system, to download |
|
172 |
PyBindGen. Next you should see (modulo platform variations) something along |
|
173 |
the lines of, |
|
174 |
||
175 |
:: |
|
176 |
||
177 |
# |
|
178 |
# Get NSC |
|
179 |
# |
|
180 |
||
181 |
Required NSC version: nsc-0.5.0 |
|
182 |
Retrieving nsc from https://secure.wand.net.nz/mercurial/nsc |
|
183 |
=> hg clone https://secure.wand.net.nz/mercurial/nsc nsc |
|
184 |
requesting all changes |
|
185 |
adding changesets |
|
186 |
adding manifests |
|
187 |
adding file changes |
|
188 |
added 273 changesets with 17565 changes to 15175 files |
|
189 |
10622 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
190 |
||
191 |
This part of the process is the script downloading the Network Simulation |
|
192 |
Cradle for you. Note that NSC is not supported on OSX or Cygwin and works |
|
193 |
best with gcc-3.4 or gcc-4.2 or greater series. |
|
194 |
||
195 |
After the download.py script completes, you should have several new directories |
|
196 |
under ``~/repos/ns-3-allinone``: |
|
197 |
||
198 |
:: |
|
199 |
||
200 |
build.py* constants.pyc download.py* nsc/ README util.pyc |
|
201 |
constants.py dist.py* ns-3-dev/ pybindgen/ util.py |
|
202 |
||
203 |
Go ahead and change into ``ns-3-dev`` under your ``~/repos/ns-3-allinone`` |
|
204 |
directory. You should see something like the following there: |
|
205 |
||
206 |
:: |
|
207 |
||
7275 | 208 |
AUTHORS doc ns3 scratch testpy.supp VERSION waf-tools |
209 |
bindings examples README src utils waf* wscript |
|
210 |
CHANGES.html LICENSE RELEASE_NOTES test.py* utils.py waf.bat* wutils.py |
|
6754 | 211 |
|
212 |
You are now ready to build the |ns3| distribution. |
|
213 |
||
214 |
Downloading ns-3 Using a Tarball |
|
215 |
++++++++++++++++++++++++++++++++ |
|
216 |
The process for downloading |ns3| via tarball is simpler than the |
|
217 |
Mercurial process since all of the pieces are pre-packaged for you. You just |
|
218 |
have to pick a release, download it and decompress it. |
|
219 |
||
220 |
As mentioned above, one practice is to create a directory called ``repos`` |
|
221 |
in one's home directory under which one can keep local Mercurial repositories. |
|
222 |
One could also keep a ``tarballs`` directory. *Hint: the tutorial |
|
223 |
will assume you downloaded into a ``repos`` directory, so remember the |
|
7654 | 224 |
placekeeper.* If you adopt the ``tarballs`` directory approach, you can |
6754 | 225 |
get a copy of a release by typing the following into your Linux shell |
226 |
(substitute the appropriate version numbers, of course): |
|
227 |
||
228 |
:: |
|
229 |
||
230 |
cd |
|
231 |
mkdir tarballs |
|
232 |
cd tarballs |
|
7654 | 233 |
wget http://www.nsnam.org/releases/ns-allinone-3.13.tar.bz2 |
234 |
tar xjf ns-allinone-3.13.tar.bz2 |
|
6754 | 235 |
|
7654 | 236 |
If you change into the directory ``ns-allinone-3.13`` you should see a |
6754 | 237 |
number of files: |
238 |
||
239 |
:: |
|
240 |
||
7654 | 241 |
build.py ns-3.13/ pybindgen-0.15.0.795/ util.py |
6754 | 242 |
constants.py nsc-0.5.2/ README |
243 |
||
244 |
You are now ready to build the |ns3| distribution. |
|
245 |
||
246 |
Building ns-3 |
|
247 |
************* |
|
248 |
||
249 |
Building with build.py |
|
250 |
++++++++++++++++++++++ |
|
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
251 |
The first time you build the |ns3| project you can build using a |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
252 |
convenience program found in the |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
253 |
``allinone`` directory. This program is called ``build.py``. This |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
254 |
program will get the project configured for you |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
255 |
in the most commonly useful way. However, please note that more advanced |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
256 |
configuration and work with |ns3| will typically involve using the |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
257 |
native |ns3| build system, Waf, to be introduced later in this tutorial. |
6754 | 258 |
|
259 |
Change into the directory you created in the download section above. If you |
|
260 |
downloaded using Mercurial you should have a directory called |
|
261 |
``ns-3-allinone`` under your ``~/repos`` directory. If you downloaded |
|
262 |
using a tarball you should have a directory called something like |
|
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
263 |
``ns-allinone-3.13`` under your ``~/tarballs`` directory. |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
264 |
Type the following: |
6754 | 265 |
|
266 |
:: |
|
267 |
||
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
268 |
./build.py --enable-examples --enable-tests |
6998
1c2b8cfb71d2
Make tests not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6754
diff
changeset
|
269 |
|
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
270 |
Because we are working with examples and tests in this tutorial, and |
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
271 |
because they are not built by default in |ns3|, the arguments for |
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
272 |
build.py tells it to build them for us. The program also defaults to |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
273 |
building all available modules. Later, you can build |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
274 |
|ns3| without examples and tests, or eliminate the modules that |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
275 |
are not necessary for your work, if you wish. |
6754 | 276 |
|
277 |
You will see lots of typical compiler output messages displayed as the build |
|
278 |
script builds the various pieces you downloaded. Eventually you should see the |
|
279 |
following magic words: |
|
280 |
||
281 |
:: |
|
282 |
||
7654 | 283 |
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3.13/build' |
6754 | 284 |
'build' finished successfully (2m30.586s) |
7071 | 285 |
|
286 |
Modules built: |
|
7275 | 287 |
aodv applications bridge |
288 |
click config-store core |
|
289 |
csma csma-layout dsdv |
|
290 |
emu energy flow-monitor |
|
291 |
internet lte mesh |
|
292 |
mobility mpi netanim |
|
293 |
network nix-vector-routing ns3tcp |
|
294 |
ns3wifi olsr openflow |
|
295 |
point-to-point point-to-point-layout propagation |
|
296 |
spectrum stats tap-bridge |
|
297 |
template test tools |
|
298 |
topology-read uan virtual-net-device |
|
299 |
visualizer wifi wimax |
|
6754 | 300 |
|
7654 | 301 |
Once the project has built, you can stop working with the |
6754 | 302 |
``ns-3-allinone`` scripts. You got what you needed from them and will now |
7654 | 303 |
interact directly with Waf and we do it in the |ns3| directory, |
6754 | 304 |
not in the ``ns-3-allinone`` directory. Go ahead and change into the |
7654 | 305 |
|ns3| directory (or the directory for the appropriate release or |
306 |
development snapshot that you downloaded; e.g. |
|
6754 | 307 |
|
308 |
:: |
|
309 |
||
310 |
cd ns-3-dev |
|
311 |
||
312 |
Building with Waf |
|
313 |
+++++++++++++++++ |
|
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
314 |
Most users directly use Waf to configure and build the |ns3| project. |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
315 |
It's not |
6754 | 316 |
strictly required at this point, but it will be valuable to take a slight |
317 |
detour and look at how to make changes to the configuration of the project. |
|
318 |
Probably the most useful configuration change you can make will be to |
|
319 |
build the optimized version of the code. By default you have configured |
|
6998
1c2b8cfb71d2
Make tests not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6754
diff
changeset
|
320 |
your project to build the debug version. Let's tell the project to |
6754 | 321 |
make an optimized build. To explain to Waf that it should do optimized |
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
322 |
builds that include the examples and tests, you will need to execute the |
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
323 |
following commands, |
6754 | 324 |
|
325 |
:: |
|
326 |
||
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
327 |
./waf clean |
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
328 |
./waf -d optimized --enable-examples --enable-tests configure |
6754 | 329 |
|
330 |
This runs Waf out of the local directory (which is provided as a convenience |
|
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
331 |
for you). The first command to clean out the previous build is not |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
332 |
typically strictly necessary but is good practice; it will remove the |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
333 |
previously built libraries and object files found in directory ``build/``. |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
334 |
When the project is reconfigured and the build system checks for various |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
335 |
dependencies, you should see |
6754 | 336 |
output that looks similar to the following, |
337 |
||
338 |
:: |
|
339 |
||
340 |
Checking for program g++ : ok /usr/bin/g++ |
|
341 |
Checking for program cpp : ok /usr/bin/cpp |
|
342 |
Checking for program ar : ok /usr/bin/ar |
|
343 |
Checking for program ranlib : ok /usr/bin/ranlib |
|
344 |
Checking for g++ : ok |
|
345 |
Checking for program pkg-config : ok /usr/bin/pkg-config |
|
346 |
Checking for -Wno-error=deprecated-declarations support : yes |
|
347 |
Checking for -Wl,--soname=foo support : yes |
|
348 |
Checking for header stdlib.h : ok |
|
349 |
Checking for header signal.h : ok |
|
350 |
Checking for header pthread.h : ok |
|
351 |
Checking for high precision time implementation : 128-bit integer |
|
352 |
Checking for header stdint.h : ok |
|
353 |
Checking for header inttypes.h : ok |
|
354 |
Checking for header sys/inttypes.h : not found |
|
355 |
Checking for library rt : ok |
|
356 |
Checking for header netpacket/packet.h : ok |
|
357 |
Checking for pkg-config flags for GSL : ok |
|
358 |
Checking for header linux/if_tun.h : ok |
|
359 |
Checking for pkg-config flags for GTK_CONFIG_STORE : ok |
|
360 |
Checking for pkg-config flags for LIBXML2 : ok |
|
361 |
Checking for library sqlite3 : ok |
|
362 |
Checking for NSC location : ok ../nsc (guessed) |
|
363 |
Checking for library dl : ok |
|
364 |
Checking for NSC supported architecture x86_64 : ok |
|
365 |
Checking for program python : ok /usr/bin/python |
|
366 |
Checking for Python version >= 2.3 : ok 2.5.2 |
|
367 |
Checking for library python2.5 : ok |
|
368 |
Checking for program python2.5-config : ok /usr/bin/python2.5-config |
|
369 |
Checking for header Python.h : ok |
|
370 |
Checking for -fvisibility=hidden support : yes |
|
371 |
Checking for pybindgen location : ok ../pybindgen (guessed) |
|
372 |
Checking for Python module pybindgen : ok |
|
373 |
Checking for pybindgen version : ok 0.10.0.640 |
|
374 |
Checking for Python module pygccxml : ok |
|
375 |
Checking for pygccxml version : ok 0.9.5 |
|
376 |
Checking for program gccxml : ok /usr/local/bin/gccxml |
|
377 |
Checking for gccxml version : ok 0.9.0 |
|
378 |
Checking for program sudo : ok /usr/bin/sudo |
|
379 |
Checking for program hg : ok /usr/bin/hg |
|
380 |
Checking for program valgrind : ok /usr/bin/valgrind |
|
381 |
---- Summary of optional NS-3 features: |
|
382 |
Threading Primitives : enabled |
|
383 |
Real Time Simulator : enabled |
|
384 |
Emulated Net Device : enabled |
|
385 |
GNU Scientific Library (GSL) : enabled |
|
386 |
Tap Bridge : enabled |
|
387 |
GtkConfigStore : enabled |
|
388 |
XmlIo : enabled |
|
389 |
SQlite stats data output : enabled |
|
390 |
Network Simulation Cradle : enabled |
|
391 |
Python Bindings : enabled |
|
392 |
Python API Scanning Support : enabled |
|
393 |
Use sudo to set suid bit : not enabled (option --enable-sudo not selected) |
|
7071 | 394 |
Build tests : enabled |
7025
32212c736ab4
Move examples out of samples directory and remove it
Mitch Watrous <watrous@u.washington.edu>
parents:
7024
diff
changeset
|
395 |
Build examples : enabled |
6754 | 396 |
Static build : not enabled (option --enable-static not selected) |
397 |
'configure' finished successfully (2.870s) |
|
398 |
||
399 |
Note the last part of the above output. Some ns-3 options are not enabled by |
|
400 |
default or require support from the underlying system to work properly. |
|
401 |
For instance, to enable XmlTo, the library libxml-2.0 must be found on the |
|
402 |
system. If this library were not found, the corresponding |ns3| feature |
|
403 |
would not be enabled and a message would be displayed. Note further that there is |
|
404 |
a feature to use the program ``sudo`` to set the suid bit of certain programs. |
|
405 |
This is not enabled by default and so this feature is reported as "not enabled." |
|
406 |
||
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
407 |
Now go ahead and switch back to the debug build that includes the examples and tests. |
6754 | 408 |
|
409 |
:: |
|
410 |
||
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
411 |
./waf clean |
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
412 |
./waf -d debug --enable-examples --enable-tests configure |
6754 | 413 |
|
414 |
The build system is now configured and you can build the debug versions of |
|
7654 | 415 |
the |ns3| programs by simply typing |
6754 | 416 |
|
417 |
:: |
|
418 |
||
419 |
./waf |
|
420 |
||
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
421 |
Okay, sorry, I made you build the |ns3| part of the system twice, |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
422 |
but now you know how to change the configuration and build optimized code. |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
423 |
|
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
424 |
Here are a few more introductory tips about Waf. |
6754 | 425 |
Some waf commands are meaningful during the build phase and some commands are valid |
426 |
in the configuration phase. For example, if you wanted to use the emulation |
|
6998
1c2b8cfb71d2
Make tests not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6754
diff
changeset
|
427 |
features of |ns3|, you might want to enable setting the suid bit using |
6754 | 428 |
sudo as described above. This turns out to be a configuration-time command, and so |
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
429 |
you could reconfigure using the following command that also includes the examples and tests |
6754 | 430 |
|
431 |
:: |
|
432 |
||
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
433 |
./waf -d debug --enable-sudo --enable-examples --enable-tests configure |
6754 | 434 |
|
435 |
If you do this, waf will have run sudo to change the socket creator programs of the |
|
436 |
emulation code to run as root. There are many other configure- and build-time options |
|
437 |
available in waf. To explore these options, type: |
|
438 |
||
439 |
:: |
|
440 |
||
441 |
./waf --help |
|
442 |
||
443 |
We'll use some of the testing-related commands in the next section. |
|
444 |
||
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
445 |
Finally, as an aside, it is possible to specify that waf builds the |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
446 |
project in |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
447 |
a directory different than the default ``build/`` directory by passing |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
448 |
the ``-o`` option to configure; e.g. |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
449 |
|
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
450 |
:: |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
451 |
|
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
452 |
./waf -d debug -o build/debug --enable-examples --enable-tests configure |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
453 |
|
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
454 |
This allows users to work with multiple builds rather than always |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
455 |
overwriting the last build. |
6754 | 456 |
|
457 |
Testing ns-3 |
|
458 |
************ |
|
459 |
||
460 |
You can run the unit tests of the |ns3| distribution by running the |
|
461 |
"./test.py -c core" script, |
|
462 |
||
463 |
:: |
|
464 |
||
465 |
./test.py -c core |
|
466 |
||
467 |
These tests are run in parallel by waf. You should eventually |
|
468 |
see a report saying that, |
|
469 |
||
470 |
:: |
|
471 |
||
7654 | 472 |
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors) |
6754 | 473 |
|
474 |
This is the important message. |
|
475 |
||
476 |
You will also see output from the test runner and the output will actually look something like, |
|
477 |
||
478 |
:: |
|
479 |
||
480 |
Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build' |
|
481 |
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build' |
|
482 |
'build' finished successfully (1.799s) |
|
7071 | 483 |
|
484 |
Modules built: |
|
7275 | 485 |
aodv applications bridge |
486 |
click config-store core |
|
487 |
csma csma-layout dsdv |
|
488 |
emu energy flow-monitor |
|
489 |
internet lte mesh |
|
490 |
mobility mpi netanim |
|
491 |
network nix-vector-routing ns3tcp |
|
492 |
ns3wifi olsr openflow |
|
493 |
point-to-point point-to-point-layout propagation |
|
494 |
spectrum stats tap-bridge |
|
495 |
template test tools |
|
496 |
topology-read uan virtual-net-device |
|
497 |
visualizer wifi wimax |
|
7071 | 498 |
|
6754 | 499 |
PASS: TestSuite ns3-wifi-interference |
500 |
PASS: TestSuite histogram |
|
501 |
PASS: TestSuite sample |
|
502 |
PASS: TestSuite ipv4-address-helper |
|
503 |
PASS: TestSuite devices-wifi |
|
504 |
PASS: TestSuite propagation-loss-model |
|
505 |
||
506 |
... |
|
507 |
||
508 |
PASS: TestSuite attributes |
|
509 |
PASS: TestSuite config |
|
510 |
PASS: TestSuite global-value |
|
511 |
PASS: TestSuite command-line |
|
512 |
PASS: TestSuite basic-random-number |
|
513 |
PASS: TestSuite object |
|
514 |
PASS: TestSuite random-number-generators |
|
7654 | 515 |
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors) |
6754 | 516 |
|
7654 | 517 |
This command is typically run by users to quickly verify that an |
6754 | 518 |
|ns3| distribution has built correctly. |
519 |
||
520 |
Running a Script |
|
521 |
**************** |
|
522 |
We typically run scripts under the control of Waf. This allows the build |
|
523 |
system to ensure that the shared library paths are set correctly and that |
|
524 |
the libraries are available at run time. To run a program, simply use the |
|
525 |
``--run`` option in Waf. Let's run the |ns3| equivalent of the |
|
526 |
ubiquitous hello world program by typing the following: |
|
527 |
||
528 |
:: |
|
529 |
||
530 |
./waf --run hello-simulator |
|
531 |
||
532 |
Waf first checks to make sure that the program is built correctly and |
|
533 |
executes a build if required. Waf then executes the program, which |
|
534 |
produces the following output. |
|
535 |
||
536 |
:: |
|
537 |
||
538 |
Hello Simulator |
|
539 |
||
540 |
*Congratulations. You are now an ns-3 user.* |
|
541 |
||
542 |
*What do I do if I don't see the output?* |
|
543 |
||
9107 | 544 |
If you see ``waf`` messages indicating that the build was |
6754 | 545 |
completed successfully, but do not see the "Hello Simulator" output, |
546 |
chances are that you have switched your build mode to "optimized" in |
|
547 |
the "Building with Waf" section, but have missed the change back to |
|
548 |
"debug" mode. All of the console output used in this tutorial uses a |
|
549 |
special |ns3| logging component that is useful for printing |
|
550 |
user messages to the console. Output from this component is |
|
551 |
automatically disabled when you compile optimized code -- it is |
|
552 |
"optimized out." If you don't see the "Hello Simulator" output, |
|
553 |
type the following, |
|
554 |
||
555 |
:: |
|
556 |
||
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
557 |
./waf -d debug --enable-examples --enable-tests configure |
6754 | 558 |
|
559 |
to tell ``waf`` to build the debug versions of the |ns3| |
|
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
560 |
programs that includes the examples and tests. You must still build |
6998
1c2b8cfb71d2
Make tests not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6754
diff
changeset
|
561 |
the actual debug version of the code by typing, |
6754 | 562 |
|
563 |
:: |
|
564 |
||
565 |
./waf |
|
566 |
||
567 |
Now, if you run the ``hello-simulator`` program, you should see the |
|
568 |
expected output. |
|
569 |
||
570 |
If you want to run programs under another tool such as gdb or valgrind, |
|
571 |
see this `wiki entry |
|
572 |
<http://www.nsnam.org/wiki/index.php/User_FAQ#How_to_run_NS-3_programs_under_another_tool>`_. |
|
573 |