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