author | Tom Henderson <tomh@tomh.org> |
Thu, 05 Feb 2015 13:02:44 -0800 | |
changeset 11214 | 103f62fc7d58 |
parent 11213 | eb503c6688a4 |
child 11217 | 3532680a19f5 |
permissions | -rw-r--r-- |
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
1 |
.. include:: replace.txt |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
2 |
.. highlight:: bash |
6754 | 3 |
|
4 |
Getting Started |
|
5 |
--------------- |
|
6 |
||
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
7 |
This section is aimed at getting a user to a working state starting |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
8 |
with a machine that may never have had |ns3| installed. It covers |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
9 |
supported platforms, prerequisites, ways to obtain |ns3|, ways to |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
10 |
build |ns3|, and ways to verify your build and run simple programs. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
11 |
|
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
12 |
Overview |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
13 |
******** |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
14 |
|
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
15 |
|ns3| is built as a system of software libraries that work together. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
16 |
User programs can be written that links with (or imports from) these |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
17 |
libraries. User programs are written in either the C++ or Python |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
18 |
programming languages. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
19 |
|
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
20 |
|ns3| is distributed as source code, meaning that the target system |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
21 |
needs to have a software development environment to build the libraries |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
22 |
first, then build the user program. |ns3| could in principle be |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
23 |
distributed as pre-built libraries for selected systems, and in the |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
24 |
future it may be distributed that way, but at present, many users |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
25 |
actually do their work by editing |ns3| itself, so having the source |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
26 |
code around to rebuild the libraries is useful. If someone would like |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
27 |
to undertake the job of making pre-built libraries and packages for |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
28 |
operating systems, please contact the ns-developers mailing list. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
29 |
|
9749 | 30 |
In the following, we'll look at two ways of downloading and building |
31 |
|ns3|. The first is to download and build an official release |
|
32 |
from the main web site. The second is to fetch and build development |
|
33 |
copies of |ns3|. We'll walk through both examples since the tools |
|
34 |
involved are slightly different. |
|
35 |
||
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
36 |
Downloading |ns3| |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
37 |
***************** |
6754 | 38 |
|
39 |
The |ns3| system as a whole is a fairly complex system and has a |
|
40 |
number of dependencies on other components. Along with the systems you will |
|
8837 | 41 |
most likely deal with every day (the GNU toolchain, Mercurial, a text |
6754 | 42 |
editor) you will need to ensure that a number of additional libraries are |
43 |
present on your system before proceeding. |ns3| provides a wiki |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
44 |
page that includes pages with many useful hints and tips. |
6754 | 45 |
One such page is the "Installation" page, |
10401
6e9d4ceb880b
Update ns-3 wiki URL
Daniel Lertpratchya <nikkipui@gmail.com>
parents:
9960
diff
changeset
|
46 |
http://www.nsnam.org/wiki/Installation. |
6754 | 47 |
|
48 |
The "Prerequisites" section of this wiki page explains which packages are |
|
49 |
required to support common |ns3| options, and also provides the |
|
50 |
commands used to install them for common Linux variants. Cygwin users will |
|
51 |
have to use the Cygwin installer (if you are a Cygwin user, you used it to |
|
52 |
install Cygwin). |
|
53 |
||
54 |
You may want to take this opportunity to explore the |ns3| wiki |
|
55 |
a bit since there really is a wealth of information there. |
|
56 |
||
57 |
From this point forward, we are going to assume that the reader is working in |
|
58 |
Linux or a Linux emulation environment (Linux, Cygwin, etc.) and has the GNU |
|
59 |
toolchain installed and verified along with the prerequisites mentioned |
|
60 |
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
|
61 |
and running on the target system. |
6754 | 62 |
|
63 |
The |ns3| code is available in Mercurial repositories on the server |
|
64 |
http://code.nsnam.org. You can also download a tarball release at |
|
11116 | 65 |
http://www.nsnam.org/release/, or you can work with repositories |
6754 | 66 |
using Mercurial. We recommend using Mercurial unless there's a good reason |
67 |
not to. See the end of this section for instructions on how to get a tarball |
|
68 |
release. |
|
69 |
||
70 |
The simplest way to get started using Mercurial repositories is to use the |
|
71 |
``ns-3-allinone`` environment. This is a set of scripts that manages the |
|
72 |
downloading and building of various subsystems of |ns3| for you. We |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
73 |
recommend that you begin your |ns3| work in this environment. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
74 |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
75 |
One practice is to create a directory called ``workspace`` in one's home |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
76 |
directory under which one can keep local Mercurial repositories. |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
77 |
Any directory name will do, but we'll assume that ``workspace`` is used |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
78 |
herein (note: ``repos`` may also be used in some documentation as |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
79 |
an example directory name). |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
80 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
81 |
Downloading |ns3| Using a Tarball |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
82 |
+++++++++++++++++++++++++++++++++ |
9749 | 83 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
84 |
A tarball is a particular format of software archive where multiple |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
85 |
files are bundled together and the archive possibly compressed. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
86 |
|ns3| software releases are provided via a downloadable tarball. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
87 |
The process for downloading |ns3| via tarball is simple; you just |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
88 |
have to pick a release, download it and decompress it. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
89 |
|
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
90 |
Let's assume that you, as a user, wish to build |ns3| in a local |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
91 |
directory called ``workspace``. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
92 |
If you adopt the ``workspace`` directory approach, you can |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
93 |
get a copy of a release by typing the following into your Linux shell |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
94 |
(substitute the appropriate version numbers, of course):: |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
95 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
96 |
$ cd |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
97 |
$ mkdir workspace |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
98 |
$ cd workspace |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
99 |
$ wget http://www.nsnam.org/release/ns-allinone-3.22.tar.bz2 |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
100 |
$ tar xjf ns-allinone-3.22.tar.bz2 |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
101 |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
102 |
If you change into the directory ``ns-allinone-3.22`` you should see a |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
103 |
number of files:: |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
104 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
105 |
$ ls |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
106 |
bake constants.py ns-3.22 README |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
107 |
build.py netanim-3.105 pybindgen-0.16.0.886 util.py |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
108 |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
109 |
You are now ready to build the base |ns3| distribution. |
6754 | 110 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
111 |
Downloading |ns3| Using Bake |
9749 | 112 |
++++++++++++++++++++++++++++ |
113 |
||
114 |
Bake is a tool for distributed integration and building, |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
115 |
developed for the |ns3| project. Â Bake can be used to fetch development |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
116 |
versions of the |ns3| software, and to download and build extensions to the |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
117 |
base |ns3| distribution, such as the Direct Code Execution environment, |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
118 |
Network Simulation Cradle, ability to create new Python bindings, and |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
119 |
others. |
9749 | 120 |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
121 |
In recent |ns3| releases, Bake has been included in the release |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
122 |
tarball. The configuration file included in the released version |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
123 |
will allow one to download any software that was current at the |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
124 |
time of the release. That is, for example, the version of Bake that |
11214
103f62fc7d58
small edits on previous commit
Tom Henderson <tomh@tomh.org>
parents:
11213
diff
changeset
|
125 |
is distributed with the ``ns-3.21`` release can be used to fetch components |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
126 |
for that |ns3| release or earlier, but can't be used to fetch components |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
127 |
for later releases (unless the ``bakeconf.xml`` file is updated). |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
128 |
|
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
129 |
You can also get the most recent copy of ``bake`` by typing the |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
130 |
following into your Linux shell (assuming you have installed Mercurial):: |
9163
950db74a6484
Minor fixes and corrections to tutorial formatting.
Vedran Miletić <rivanvx@gmail.com>
parents:
9107
diff
changeset
|
131 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
132 |
$ cd |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
133 |
$ mkdir workspace |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
134 |
$ cd workspace |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
135 |
$ hg clone http://code.nsnam.org/bake |
6754 | 136 |
|
137 |
As the hg (Mercurial) command executes, you should see something like the |
|
138 |
following displayed, |
|
139 |
||
140 |
:: |
|
141 |
||
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
142 |
... |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
143 |
destination directory: bake |
6754 | 144 |
requesting all changes |
145 |
adding changesets |
|
146 |
adding manifests |
|
147 |
adding file changes |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
148 |
added 339 changesets with 796 changes to 63 files |
7654 | 149 |
updating to branch default |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
150 |
45 files updated, 0 files merged, 0 files removed, 0 files unresolved |
6754 | 151 |
|
152 |
After the clone command completes, you should have a directory called |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
153 |
``bake``, the contents of which should look something like the following:: |
6754 | 154 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
155 |
$ ls |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
156 |
bake bakeconf.xml doc generate-binary.py TODO |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
157 |
bake.py examples test |
6754 | 158 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
159 |
Notice that you really just downloaded some Python scripts and a Python |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
160 |
module called ``bake``. The next step |
6754 | 161 |
will be to use those scripts to download and build the |ns3| |
162 |
distribution of your choice. |
|
163 |
||
9749 | 164 |
There are a few configuration targets available: |
165 |
||
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
166 |
1. ``ns-3.22``: the module corresponding to the release; it will download |
9749 | 167 |
components similar to the release tarball. |
168 |
2. ``ns-3-dev``: a similar module but using the development code tree |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
169 |
3. ``ns-allinone-3.22``: the module that includes other optional features |
9749 | 170 |
such as click routing, openflow for |ns3|, and the Network Simulation |
171 |
Cradle |
|
172 |
4. ``ns-3-allinone``: similar to the released version of the allinone |
|
173 |
module, but for development code. |
|
6754 | 174 |
|
175 |
The current development snapshot (unreleased) of |ns3| may be found |
|
176 |
at http://code.nsnam.org/ns-3-dev/. The |
|
177 |
developers attempt to keep these repository in consistent, working states but |
|
178 |
they are in a development area with unreleased code present, so you may want |
|
179 |
to consider staying with an official release if you do not need newly- |
|
180 |
introduced features. |
|
181 |
||
9749 | 182 |
You can find the latest version of the |
6754 | 183 |
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
|
184 |
`"ns-3 Releases" |
7162e24118ea
Miscellaneous fixes to Tutorial
Mitch Watrous <watrous@u.washington.edu>
parents:
7275
diff
changeset
|
185 |
<http://www.nsnam.org/releases>`_ |
9749 | 186 |
web page and clicking on the latest release link. We'll proceed in |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
187 |
this tutorial example with ``ns-3.22``. |
9749 | 188 |
|
189 |
We are now going to use the bake tool to pull down the various pieces of |
|
190 |
|ns3| you will be using. First, we'll say a word about running bake. |
|
6754 | 191 |
|
9749 | 192 |
bake works by downloading source packages into a source directory, |
193 |
and installing libraries into a build directory. bake can be run |
|
194 |
by referencing the binary, but if one chooses to run bake from |
|
195 |
outside of the directory it was downloaded into, it is advisable |
|
11077
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
196 |
to put bake into your path, such as follows (Linux bash shell example). |
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
197 |
First, change into the 'bake' directory, and then set the following |
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
198 |
environment variables |
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
199 |
|
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
200 |
:: |
6754 | 201 |
|
11077
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
202 |
$ export BAKE_HOME=`pwd` |
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
203 |
$ export PATH=$PATH:$BAKE_HOME:$BAKE_HOME/build/bin |
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
204 |
$ export PYTHONPATH=$PYTHONPATH:$BAKE_HOME:$BAKE_HOME/build/lib |
9749 | 205 |
|
11077
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
206 |
This will put the bake.py program into the shell's path, and will allow |
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
207 |
other programs to find executables and libraries created by bake. Although |
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
208 |
several bake use cases do not require setting PATH and PYTHONPATH as above, |
5c8dea49a671
update tutorial section on bake environment variables
Tom Henderson <tomh@tomh.org>
parents:
11048
diff
changeset
|
209 |
full builds of ns-3-allinone (with the optional packages) typically do. |
9749 | 210 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
211 |
Step into the workspace directory and type the following into your shell:: |
9749 | 212 |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
213 |
$ ./bake.py configure -e ns-3.22 |
6754 | 214 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
215 |
Next, we'l ask bake to check whether we have enough tools to download |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
216 |
various components. Type:: |
6754 | 217 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
218 |
$ ./bake.py check |
6754 | 219 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
220 |
You should see something like the following, |
6754 | 221 |
|
222 |
:: |
|
223 |
||
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
224 |
> Python - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
225 |
> GNU C++ compiler - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
226 |
> Mercurial - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
227 |
> CVS - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
228 |
> GIT - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
229 |
> Bazaar - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
230 |
> Tar tool - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
231 |
> Unzip tool - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
232 |
> Unrar tool - is missing |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
233 |
> 7z data compression utility - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
234 |
> XZ data compression utility - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
235 |
> Make - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
236 |
> cMake - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
237 |
> patch tool - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
238 |
> autoreconf tool - OK |
6754 | 239 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
240 |
> Path searched for tools: /usr/lib64/qt-3.3/bin /usr/lib64/ccache |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
241 |
/usr/local/bin /bin /usr/bin /usr/local/sbin /usr/sbin /sbin |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
242 |
/home/tomh/bin bin |
6754 | 243 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
244 |
In particular, download tools such as Mercurial, CVS, GIT, and Bazaar |
9749 | 245 |
are our principal concerns at this point, since they allow us to fetch |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
246 |
the code. Please install missing tools at this stage, in the usual |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
247 |
way for your system (if you are able to), or contact your system |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
248 |
administrator as needed to install these tools. |
6754 | 249 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
250 |
Next, try to download the software:: |
6754 | 251 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
252 |
$ ./bake.py download |
6754 | 253 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
254 |
should yield something like:: |
6754 | 255 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
256 |
>> Searching for system dependency pygoocanvas - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
257 |
>> Searching for system dependency python-dev - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
258 |
>> Searching for system dependency pygraphviz - OK |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
259 |
>> Downloading pybindgen-0.16.0.886 - OK |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
260 |
>> Searching for system dependency g++ - OK |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
261 |
>> Searching for system dependency qt4 - OK |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
262 |
>> Downloading netanim-3.105 - OK |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
263 |
>> Downloading ns-3.22 - OK |
6754 | 264 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
265 |
The above suggests that three sources have been downloaded. Check the |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
266 |
``source`` directory now and type ``ls``; one should see:: |
6754 | 267 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
268 |
$ ls |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
269 |
netanim-3.105 ns-3.22 pybindgen-0.16.0.886 |
6754 | 270 |
|
271 |
You are now ready to build the |ns3| distribution. |
|
272 |
||
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
273 |
Building |ns3| |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
274 |
************** |
6754 | 275 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
276 |
Building with ``build.py`` |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
277 |
++++++++++++++++++++++++++ |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
278 |
When working from a released tarball, the first time you build the |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
279 |
|ns3| project you can build using a convenience program found in the |
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
280 |
``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
|
281 |
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
|
282 |
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
|
283 |
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
|
284 |
native |ns3| build system, Waf, to be introduced later in this tutorial. |
6754 | 285 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
286 |
If you downloaded |
6754 | 287 |
using a tarball you should have a directory called something like |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
288 |
``ns-allinone-3.22`` under your ``~/workspace`` directory. |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
289 |
Type the following:: |
6754 | 290 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
291 |
$ ./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
|
292 |
|
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
293 |
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
|
294 |
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
|
295 |
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
|
296 |
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
|
297 |
|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
|
298 |
are not necessary for your work, if you wish. |
6754 | 299 |
|
300 |
You will see lots of typical compiler output messages displayed as the build |
|
301 |
script builds the various pieces you downloaded. Eventually you should see the |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
302 |
following:: |
6754 | 303 |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
304 |
Waf: Leaving directory `/path/to/workspace/ns-allinone-3.22/ns-3.22/build' |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
305 |
'build' finished successfully (6m25.032s) |
7071 | 306 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
307 |
Modules built: |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
308 |
antenna aodv applications |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
309 |
bridge buildings config-store |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
310 |
core csma csma-layout |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
311 |
dsdv dsr energy |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
312 |
fd-net-device flow-monitor internet |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
313 |
lr-wpan lte mesh |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
314 |
mobility mpi netanim (no Python) |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
315 |
network nix-vector-routing olsr |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
316 |
point-to-point point-to-point-layout propagation |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
317 |
sixlowpan spectrum stats |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
318 |
tap-bridge test (no Python) topology-read |
11214
103f62fc7d58
small edits on previous commit
Tom Henderson <tomh@tomh.org>
parents:
11213
diff
changeset
|
319 |
uan virtual-net-device wave |
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
320 |
wifi wimax |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
321 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
322 |
Modules not built (see ns-3 tutorial for explanation): |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
323 |
brite click openflow |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
324 |
visualizer |
6754 | 325 |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
326 |
Leaving directory `./ns-3.22' |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
327 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
328 |
Regarding the portion about modules not built:: |
9169
f8bff624db3c
clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents:
9163
diff
changeset
|
329 |
|
f8bff624db3c
clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents:
9163
diff
changeset
|
330 |
Modules not built (see ns-3 tutorial for explanation): |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
331 |
brite click openflow |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
332 |
visualizer |
9169
f8bff624db3c
clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents:
9163
diff
changeset
|
333 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
334 |
This just means that some |ns3| modules that have dependencies on |
9169
f8bff624db3c
clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents:
9163
diff
changeset
|
335 |
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
|
336 |
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
|
337 |
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
|
338 |
results for the modules listed as being built. |
f8bff624db3c
clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents:
9163
diff
changeset
|
339 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
340 |
Building with bake |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
341 |
++++++++++++++++++ |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
342 |
|
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
343 |
If you used bake above to fetch source code from project repositories, you |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
344 |
may continue to use it to build |ns3|. Type |
6754 | 345 |
|
346 |
:: |
|
347 |
||
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
348 |
$ ./bake.py build |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
349 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
350 |
and you should see something like:: |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
351 |
|
11213
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
352 |
>> Building pybindgen-0.16.0.886 - OK |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
353 |
>> Building netanim-3.105 - OK |
eb503c6688a4
tutorial updates for ns-3.22
Tom Henderson <tomh@tomh.org>
parents:
11123
diff
changeset
|
354 |
>> Building ns-3.22 - OK |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
355 |
|
9749 | 356 |
*Hint: you can also perform both steps, download and build by calling 'bake.py deploy'.* |
357 |
||
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
358 |
If there happens to be a failure, please have a look at what the following |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
359 |
command tells you; it may give a hint as to a missing dependency:: |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
360 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
361 |
$ ./bake.py show |
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
362 |
|
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
363 |
This will list out the various dependencies of the packages you are |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
364 |
trying to build. |
6754 | 365 |
|
366 |
Building with Waf |
|
367 |
+++++++++++++++++ |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
368 |
|
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
369 |
Up to this point, we have used either the `build.py` script, or the |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
370 |
`bake` tool, to get started with building |ns3|. These tools are useful |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
371 |
for building |ns3| and supporting libraries, and they call into |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
372 |
the |ns3| directory to call the Waf build tool to do the actual building. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
373 |
Most users quickly transition to using Waf directly to configure and |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
374 |
build |ns3|. So, to proceed, please change your working directory to |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
375 |
the |ns3| directory that you have initially built. |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
376 |
|
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
377 |
It's not |
6754 | 378 |
strictly required at this point, but it will be valuable to take a slight |
379 |
detour and look at how to make changes to the configuration of the project. |
|
380 |
Probably the most useful configuration change you can make will be to |
|
381 |
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
|
382 |
your project to build the debug version. Let's tell the project to |
6754 | 383 |
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
|
384 |
builds that include the examples and tests, you will need to execute the |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
385 |
following commands:: |
6754 | 386 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
387 |
$ ./waf clean |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
388 |
$ ./waf --build-profile=optimized --enable-examples --enable-tests configure |
6754 | 389 |
|
390 |
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
|
391 |
for you). The first command to clean out the previous build is not |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
392 |
typically strictly necessary but is good practice (but see `Build Profiles`_, |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
393 |
below); it will remove the |
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
394 |
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
|
395 |
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
|
396 |
dependencies, you should see |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
397 |
output that looks similar to the following:: |
6754 | 398 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
399 |
Setting top to : . |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
400 |
Setting out to : build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
401 |
Checking for 'gcc' (c compiler) : /usr/bin/gcc |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
402 |
Checking for cc version : 4.2.1 |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
403 |
Checking for 'g++' (c++ compiler) : /usr/bin/g++ |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
404 |
Checking boost includes : 1_46_1 |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
405 |
Checking boost libs : ok |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
406 |
Checking for boost linkage : ok |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
407 |
Checking for click location : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
408 |
Checking for program pkg-config : /sw/bin/pkg-config |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
409 |
Checking for 'gtk+-2.0' >= 2.12 : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
410 |
Checking for 'libxml-2.0' >= 2.7 : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
411 |
Checking for type uint128_t : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
412 |
Checking for type __uint128_t : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
413 |
Checking high precision implementation : 128-bit integer (default) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
414 |
Checking for header stdint.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
415 |
Checking for header inttypes.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
416 |
Checking for header sys/inttypes.h : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
417 |
Checking for header sys/types.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
418 |
Checking for header sys/stat.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
419 |
Checking for header dirent.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
420 |
Checking for header stdlib.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
421 |
Checking for header signal.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
422 |
Checking for header pthread.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
423 |
Checking for header stdint.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
424 |
Checking for header inttypes.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
425 |
Checking for header sys/inttypes.h : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
426 |
Checking for library rt : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
427 |
Checking for header netpacket/packet.h : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
428 |
Checking for header sys/ioctl.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
429 |
Checking for header net/if.h : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
430 |
Checking for header net/ethernet.h : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
431 |
Checking for header linux/if_tun.h : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
432 |
Checking for header netpacket/packet.h : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
433 |
Checking for NSC location : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
434 |
Checking for 'mpic++' : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
435 |
Checking for 'sqlite3' : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
436 |
Checking for header linux/if_tun.h : not found |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
437 |
Checking for program sudo : /usr/bin/sudo |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
438 |
Checking for program valgrind : /sw/bin/valgrind |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
439 |
Checking for 'gsl' : yes |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
440 |
Checking for compilation flag -Wno-error=deprecated-d... support : ok |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
441 |
Checking for compilation flag -Wno-error=deprecated-d... support : ok |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
442 |
Checking for compilation flag -fstrict-aliasing... support : ok |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
443 |
Checking for compilation flag -fstrict-aliasing... support : ok |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
444 |
Checking for compilation flag -Wstrict-aliasing... support : ok |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
445 |
Checking for compilation flag -Wstrict-aliasing... support : ok |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
446 |
Checking for program doxygen : /usr/local/bin/doxygen |
6754 | 447 |
---- Summary of optional NS-3 features: |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
448 |
Build profile : debug |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
449 |
Build directory : build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
450 |
Python Bindings : enabled |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
451 |
BRITE Integration : not enabled (BRITE not enabled (see option --with-brite)) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
452 |
NS-3 Click Integration : not enabled (nsclick not enabled (see option --with-nsclick)) |
6754 | 453 |
GtkConfigStore : enabled |
454 |
XmlIo : enabled |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
455 |
Threading Primitives : enabled |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
456 |
Real Time Simulator : enabled (librt is not available) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
457 |
Emulated Net Device : enabled (<netpacket/packet.h> include not detected) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
458 |
File descriptor NetDevice : enabled |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
459 |
Tap FdNetDevice : not enabled (needs linux/if_tun.h) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
460 |
Emulation FdNetDevice : not enabled (needs netpacket/packet.h) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
461 |
PlanetLab FdNetDevice : not enabled (PlanetLab operating system not detected (see option --force-planetlab)) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
462 |
Network Simulation Cradle : not enabled (NSC not found (see option --with-nsc)) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
463 |
MPI Support : enabled |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
464 |
NS-3 OpenFlow Integration : not enabled (Required boost libraries not found, missing: system, signals, filesystem) |
6754 | 465 |
SQlite stats data output : enabled |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
466 |
Tap Bridge : not enabled (<linux/if_tun.h> include not detected) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
467 |
PyViz visualizer : enabled |
6754 | 468 |
Use sudo to set suid bit : not enabled (option --enable-sudo not selected) |
7071 | 469 |
Build tests : enabled |
7025
32212c736ab4
Move examples out of samples directory and remove it
Mitch Watrous <watrous@u.washington.edu>
parents:
7024
diff
changeset
|
470 |
Build examples : enabled |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
471 |
GNU Scientific Library (GSL) : enabled |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
472 |
'configure' finished successfully (1.944s) |
6754 | 473 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
474 |
Note the last part of the above output. Some |ns3| options are not enabled by |
6754 | 475 |
default or require support from the underlying system to work properly. |
476 |
For instance, to enable XmlTo, the library libxml-2.0 must be found on the |
|
477 |
system. If this library were not found, the corresponding |ns3| feature |
|
478 |
would not be enabled and a message would be displayed. Note further that there is |
|
479 |
a feature to use the program ``sudo`` to set the suid bit of certain programs. |
|
480 |
This is not enabled by default and so this feature is reported as "not enabled." |
|
481 |
||
7024
4392d52b3536
Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents:
6998
diff
changeset
|
482 |
Now go ahead and switch back to the debug build that includes the examples and tests. |
6754 | 483 |
|
484 |
:: |
|
485 |
||
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
486 |
$ ./waf clean |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
487 |
$ ./waf --build-profile=debug --enable-examples --enable-tests configure |
6754 | 488 |
|
489 |
The build system is now configured and you can build the debug versions of |
|
7654 | 490 |
the |ns3| programs by simply typing |
6754 | 491 |
|
492 |
:: |
|
493 |
||
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
494 |
$ ./waf |
6754 | 495 |
|
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
496 |
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
|
497 |
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
|
498 |
|
11047
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
499 |
The build.py script discussed above supports also the ``--enable-examples`` |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
500 |
and ``enable-tests`` arguments, but in general, does not directly support |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
501 |
other waf options; for example, this will not work: |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
502 |
|
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
503 |
:: |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
504 |
|
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
505 |
$ ./build.py --disable-python |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
506 |
|
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
507 |
will result in |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
508 |
|
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
509 |
:: |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
510 |
|
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
511 |
build.py: error: no such option: --disable-python |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
512 |
|
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
513 |
However, the special operator ``--`` can be used to pass additional |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
514 |
options through to waf, so instead of the above, the following will work: |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
515 |
|
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
516 |
:: |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
517 |
|
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
518 |
$ ./build.py -- --disable-python |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
519 |
|
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
520 |
as it generates the underlying command ``./waf configure --disable-python``. |
259a56c15a37
bug 1326: document the -- operator to build.py
Tom Henderson <tomh@tomh.org>
parents:
10609
diff
changeset
|
521 |
|
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
522 |
Here are a few more introductory tips about Waf. |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
523 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
524 |
Configure vs. Build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
525 |
=================== |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
526 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
527 |
Some Waf commands are only meaningful during the configure phase and some commands are valid |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
528 |
in the build 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
|
529 |
features of |ns3|, you might want to enable setting the suid bit using |
6754 | 530 |
sudo as described above. This turns out to be a configuration-time command, and so |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
531 |
you could reconfigure using the following command that also includes the examples and tests. |
6754 | 532 |
|
533 |
:: |
|
534 |
||
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
535 |
$ ./waf configure --enable-sudo --enable-examples --enable-tests |
6754 | 536 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
537 |
If you do this, Waf will have run sudo to change the socket creator programs of the |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
538 |
emulation code to run as root. |
6754 | 539 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
540 |
There are many other configure- and build-time options |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
541 |
available in Waf. To explore these options, type:: |
6754 | 542 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
543 |
$ ./waf --help |
6754 | 544 |
|
545 |
We'll use some of the testing-related commands in the next section. |
|
546 |
||
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
547 |
Build Profiles |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
548 |
============== |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
549 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
550 |
We already saw how you can configure Waf for ``debug`` or ``optimized`` builds:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
551 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
552 |
$ ./waf --build-profile=debug |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
553 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
554 |
There is also an intermediate build profile, ``release``. ``-d`` is a |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
555 |
synonym for ``--build-profile``. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
556 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
557 |
By default Waf puts the build artifacts in the ``build`` directory. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
558 |
You can specify a different output directory with the ``--out`` |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
559 |
option, e.g. |
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
560 |
|
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
561 |
:: |
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
562 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
563 |
$ ./waf configure --out=foo |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
564 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
565 |
Combining this with build profiles lets you switch between the different |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
566 |
compile options in a clean way:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
567 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
568 |
$ ./waf configure --build-profile=debug --out=build/debug |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
569 |
$ ./waf build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
570 |
... |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
571 |
$ ./waf configure --build-profile=optimized --out=build/optimized |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
572 |
$ ./waf build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
573 |
... |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
574 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
575 |
This allows you to work with multiple builds rather than always |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
576 |
overwriting the last build. When you switch, Waf will only compile |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
577 |
what it has to, instead of recompiling everything. |
7661
9ef562047d3e
some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents:
7654
diff
changeset
|
578 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
579 |
When you do switch build profiles like this, you have to be careful |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
580 |
to give the same configuration parameters each time. It may be convenient |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
581 |
to define some environment variables to help you avoid mistakes:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
582 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
583 |
$ export NS3CONFIG="--enable-examples --enable-tests" |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
584 |
$ export NS3DEBUG="--build-profile=debug --out=build/debug" |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
585 |
$ export NS3OPT=="--build-profile=optimized --out=build/optimized" |
6754 | 586 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
587 |
$ ./waf configure $NS3CONFIG $NS3DEBUG |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
588 |
$ ./waf build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
589 |
... |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
590 |
$ ./waf configure $NS3CONFIG $NS3OPT |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
591 |
$ ./waf build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
592 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
593 |
Compilers |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
594 |
========= |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
595 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
596 |
In the examples above, Waf uses the GCC C++ compiler, ``g++``, for |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
597 |
building |ns3|. However, it's possible to change the C++ compiler used by Waf |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
598 |
by defining the ``CXX`` environment variable. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
599 |
For example, to use the Clang C++ compiler, ``clang++``, |
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
|
600 |
|
b6e9f47c260b
Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents:
9169
diff
changeset
|
601 |
:: |
b6e9f47c260b
Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents:
9169
diff
changeset
|
602 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
603 |
$ CXX="clang++" ./waf configure |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
604 |
$ ./waf build |
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
|
605 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
606 |
One can also set up Waf to do distributed compilation with ``distcc`` in |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
607 |
a similar way:: |
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
|
608 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
609 |
$ CXX="distcc g++" ./waf configure |
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
610 |
$ ./waf build |
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
|
611 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
612 |
More info on ``distcc`` and distributed compilation can be found on it's |
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
|
613 |
`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
|
614 |
<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
|
615 |
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
|
616 |
|
11048
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
617 |
Install |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
618 |
======= |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
619 |
|
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
620 |
Waf may be used to install libraries in various places on the system. |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
621 |
The default location where libraries and executables are built is |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
622 |
in the ``build`` directory, and because Waf knows the location of these |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
623 |
libraries and executables, it is not necessary to install the libraries |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
624 |
elsewhere. |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
625 |
|
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
626 |
If users choose to install things outside of the build directory, users |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
627 |
may issue the ``./waf install`` command. By default, the prefix for |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
628 |
installation is ``/usr/local``, so ``./waf install`` will install programs |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
629 |
into ``/usr/local/bin``, libraries into ``/usr/local/lib``, and headers |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
630 |
into ``/usr/local/include``. Superuser privileges are typically needed |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
631 |
to install to the default prefix, so the typical command would be |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
632 |
``sudo ./waf install``. When running programs with Waf, Waf will |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
633 |
first prefer to use shared libraries in the build directory, then |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
634 |
will look for libraries in the library path configured in the local |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
635 |
environment. So when installing libraries to the system, it is good |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
636 |
practice to check that the intended libraries are being used. |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
637 |
|
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
638 |
Users may choose to install to a different prefix by passing the ``--prefix`` |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
639 |
option at configure time, such as: |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
640 |
|
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
641 |
:: |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
642 |
|
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
643 |
./waf configure --prefix=/opt/local |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
644 |
|
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
645 |
If later after the build the user issues the ``./waf install`` command, the |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
646 |
prefix ``/opt/local`` will be used. |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
647 |
|
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
648 |
The ``./waf clean`` command should be used prior to reconfiguring |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
649 |
the project if Waf will be used to install things at a different prefix. |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
650 |
|
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
651 |
In summary, it is not necessary to call ``./waf install`` to use |ns3|. |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
652 |
Most users will not need this command since Waf will pick up the |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
653 |
current libraries from the ``build`` directory, but some users may find |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
654 |
it useful if their use case involves working with programs outside |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
655 |
of the |ns3| directory. |
8a2ae153d4aa
add coverage of ./waf install to tutorial
Tom Henderson <tomh@tomh.org>
parents:
11047
diff
changeset
|
656 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
657 |
One Waf |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
658 |
======= |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
659 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
660 |
There is only one Waf script, at the top level of the |ns3| source tree. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
661 |
As you work, you may find yourself spending a lot of time in ``scratch/``, |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
662 |
or deep in ``src/...``, and needing to invoke Waf. You could just |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
663 |
remember where you are, and invoke Waf like this:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
664 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
665 |
$ ../../../waf ... |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
666 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
667 |
but that get's tedious, and error prone, and there are better solutions. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
668 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
669 |
If you have the full |ns3| repository this little gem is a start:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
670 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
671 |
$ cd $(hg root) && ./waf ... |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
672 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
673 |
Even better is to define this as a shell function:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
674 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
675 |
$ function waff { cd $(hg root) && ./waf $* ; } |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
676 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
677 |
$ waff build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
678 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
679 |
If you only have the tarball, an environment variable can help:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
680 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
681 |
$ export NS3DIR="$PWD" |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
682 |
$ function waff { cd $NS3DIR && ./waf $* ; } |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
683 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
684 |
$ cd scratch |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
685 |
$ waff build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
686 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
687 |
It might be tempting in a module directory to add a trivial ``waf`` |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
688 |
script along the lines of ``exec ../../waf``. Please don't. It's |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
689 |
confusing to new-comers, and when done poorly it leads to subtle build |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
690 |
errors. The solutions above are the way to go. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
691 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
692 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
693 |
Testing |ns3| |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
694 |
************* |
6754 | 695 |
|
696 |
You can run the unit tests of the |ns3| distribution by running the |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
697 |
``./test.py -c core`` script:: |
6754 | 698 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
699 |
$ ./test.py -c core |
6754 | 700 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
701 |
These tests are run in parallel by Waf. You should eventually |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
702 |
see a report saying that |
6754 | 703 |
|
704 |
:: |
|
705 |
||
7654 | 706 |
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors) |
6754 | 707 |
|
708 |
This is the important message. |
|
709 |
||
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
710 |
You will also see the summary output from Waf and the test runner |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
711 |
executing each test, which will actually look something like:: |
6754 | 712 |
|
9742
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
713 |
Waf: Entering directory `/path/to/workspace/ns-3-allinone/ns-3-dev/build' |
b24738ffa84b
update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents:
9189
diff
changeset
|
714 |
Waf: Leaving directory `/path/to/workspace/ns-3-allinone/ns-3-dev/build' |
6754 | 715 |
'build' finished successfully (1.799s) |
7071 | 716 |
|
717 |
Modules built: |
|
7275 | 718 |
aodv applications bridge |
719 |
click config-store core |
|
720 |
csma csma-layout dsdv |
|
721 |
emu energy flow-monitor |
|
722 |
internet lte mesh |
|
723 |
mobility mpi netanim |
|
724 |
network nix-vector-routing ns3tcp |
|
725 |
ns3wifi olsr openflow |
|
726 |
point-to-point point-to-point-layout propagation |
|
727 |
spectrum stats tap-bridge |
|
728 |
template test tools |
|
729 |
topology-read uan virtual-net-device |
|
730 |
visualizer wifi wimax |
|
7071 | 731 |
|
6754 | 732 |
PASS: TestSuite ns3-wifi-interference |
733 |
PASS: TestSuite histogram |
|
734 |
||
735 |
... |
|
736 |
||
737 |
PASS: TestSuite object |
|
738 |
PASS: TestSuite random-number-generators |
|
7654 | 739 |
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors) |
6754 | 740 |
|
7654 | 741 |
This command is typically run by users to quickly verify that an |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
742 |
|ns3| distribution has built correctly. (Note the order of the ``PASS: ...`` |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
743 |
lines can vary, which is okay. What's important is that the summary line at |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
744 |
the end report that all tests passed; none failed or crashed.) |
6754 | 745 |
|
746 |
Running a Script |
|
747 |
**************** |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
748 |
|
6754 | 749 |
We typically run scripts under the control of Waf. This allows the build |
750 |
system to ensure that the shared library paths are set correctly and that |
|
751 |
the libraries are available at run time. To run a program, simply use the |
|
752 |
``--run`` option in Waf. Let's run the |ns3| equivalent of the |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
753 |
ubiquitous hello world program by typing the following:: |
6754 | 754 |
|
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
755 |
$ ./waf --run hello-simulator |
6754 | 756 |
|
757 |
Waf first checks to make sure that the program is built correctly and |
|
758 |
executes a build if required. Waf then executes the program, which |
|
759 |
produces the following output. |
|
760 |
||
761 |
:: |
|
762 |
||
763 |
Hello Simulator |
|
764 |
||
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
765 |
Congratulations! You are now an ns-3 user! |
6754 | 766 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
767 |
**What do I do if I don't see the output?** |
6754 | 768 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
769 |
If you see Waf messages indicating that the build was |
6754 | 770 |
completed successfully, but do not see the "Hello Simulator" output, |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
771 |
chances are that you have switched your build mode to ``optimized`` in |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
772 |
the `Building with Waf`_ section, but have missed the change back to |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
773 |
``debug`` mode. All of the console output used in this tutorial uses a |
6754 | 774 |
special |ns3| logging component that is useful for printing |
775 |
user messages to the console. Output from this component is |
|
776 |
automatically disabled when you compile optimized code -- it is |
|
777 |
"optimized out." If you don't see the "Hello Simulator" output, |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
778 |
type the following:: |
6754 | 779 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
780 |
$ ./waf configure --build-profile=debug --enable-examples --enable-tests |
6754 | 781 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
782 |
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
|
783 |
programs that includes the examples and tests. You must still build |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
784 |
the actual debug version of the code by typing |
6754 | 785 |
|
786 |
:: |
|
787 |
||
9957
1a4d84a85bad
Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
9749
diff
changeset
|
788 |
$ ./waf |
6754 | 789 |
|
790 |
Now, if you run the ``hello-simulator`` program, you should see the |
|
791 |
expected output. |
|
792 |
||
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
793 |
Program Arguments |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
794 |
+++++++++++++++++ |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
795 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
796 |
To feed command line arguments to an |ns3| program use this pattern:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
797 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
798 |
$ ./waf --run <ns3-program> --command-template="%s <args>" |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
799 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
800 |
Substitute your program name for ``<ns3-program>``, and the arguments |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
801 |
for ``<args>``. The ``--command-template`` argument to Waf is |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
802 |
basically a recipe for constructing the actual command line Waf should use |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
803 |
to execute the program. Waf checks that the build is complete, |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
804 |
sets the shared library paths, then invokes the executable |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
805 |
using the provided command line template, |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
806 |
inserting the program name for the ``%s`` placeholder. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
807 |
(I admit this is a bit awkward, but that's the way it is. Patches welcome!) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
808 |
|
11123
893aa21e059c
[Tutorial] clarify that there is no mytest, and output an error if no test is to be run.
Tommaso Pecorella <tommaso.pecorella@unifi.it>
parents:
11122
diff
changeset
|
809 |
Another particularly useful example is to run a test suite by itself. |
893aa21e059c
[Tutorial] clarify that there is no mytest, and output an error if no test is to be run.
Tommaso Pecorella <tommaso.pecorella@unifi.it>
parents:
11122
diff
changeset
|
810 |
Let's assume that a ``mytest`` test suite exists (it doesn't). |
893aa21e059c
[Tutorial] clarify that there is no mytest, and output an error if no test is to be run.
Tommaso Pecorella <tommaso.pecorella@unifi.it>
parents:
11122
diff
changeset
|
811 |
Above, we used the ``./test.py`` script to run a whole slew of |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
812 |
tests in parallel, by repeatedly invoking the real testing program, |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
813 |
``test-runner``. To invoke ``test-runner`` directly for a single test:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
814 |
|
11122
78b3c90cddcb
[Tutorial] fix missing "s" from argument template
Tommaso Pecorella <tommaso.pecorella@unifi.it>
parents:
11116
diff
changeset
|
815 |
$ ./waf --run test-runner --command-template="%s --suite=mytest --verbose" |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
816 |
|
11123
893aa21e059c
[Tutorial] clarify that there is no mytest, and output an error if no test is to be run.
Tommaso Pecorella <tommaso.pecorella@unifi.it>
parents:
11122
diff
changeset
|
817 |
This passes the arguments to the ``test-runner`` program. |
893aa21e059c
[Tutorial] clarify that there is no mytest, and output an error if no test is to be run.
Tommaso Pecorella <tommaso.pecorella@unifi.it>
parents:
11122
diff
changeset
|
818 |
Since ``mytest`` does not exist, an error message will be generated. |
893aa21e059c
[Tutorial] clarify that there is no mytest, and output an error if no test is to be run.
Tommaso Pecorella <tommaso.pecorella@unifi.it>
parents:
11122
diff
changeset
|
819 |
To print the available ``test-runner`` options:: |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
820 |
|
11122
78b3c90cddcb
[Tutorial] fix missing "s" from argument template
Tommaso Pecorella <tommaso.pecorella@unifi.it>
parents:
11116
diff
changeset
|
821 |
$ ./waf --run test-runner --command-template="%s --help" |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
822 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
823 |
Debugging |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
824 |
+++++++++ |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
825 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
826 |
To run |ns3| programs under the control of another utility, such as |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
827 |
a debugger (*e.g.* ``gdb``) or memory checker (*e.g.* ``valgrind``), |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
828 |
you use a similar ``--command-template="..."`` form. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
829 |
|
11123
893aa21e059c
[Tutorial] clarify that there is no mytest, and output an error if no test is to be run.
Tommaso Pecorella <tommaso.pecorella@unifi.it>
parents:
11122
diff
changeset
|
830 |
For example, to run your |ns3| program ``hello-simulator`` with the arguments |
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
831 |
``<args>`` under the ``gdb`` debugger:: |
6754 | 832 |
|
10609
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
833 |
$ ./waf --run=hello-simulator --command-template="gdb %s --args <args>" |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
834 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
835 |
Notice that the |ns3| program name goes with the ``--run`` argument, |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
836 |
and the control utility (here ``gdb``) is the first token |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
837 |
in the ``--commmand-template`` argument. The ``--args`` tells ``gdb`` |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
838 |
that the remainder of the command line belongs to the "inferior" program. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
839 |
(Some ``gdb``'s don't understand the ``--args`` feature. In this case, |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
840 |
omit the program arguments from the ``--command-template``, |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
841 |
and use the ``gdb`` command ``set args``.) |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
842 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
843 |
We can combine this recipe and the previous one to run a test under the |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
844 |
debugger:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
845 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
846 |
$ ./waf --run test-runner --command-template="gdb %s --args --suite=mytest --verbose" |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
847 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
848 |
Working Directory |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
849 |
+++++++++++++++++ |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
850 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
851 |
Waf needs to run from it's location at the top of the |ns3| tree. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
852 |
This becomes the working directory where output files will be written. |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
853 |
But what if you want to keep those ouf to the |ns3| source tree? Use |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
854 |
the ``--cwd`` argument:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
855 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
856 |
$ ./waf --cwd=... |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
857 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
858 |
It may be more convenient to start with your working directory where |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
859 |
you want the output files, in which case a little indirection can help:: |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
860 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
861 |
$ function waff { |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
862 |
CWD="$PWD" |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
863 |
cd $NS3DIR >/dev/null |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
864 |
./waf --cwd="$CWD" $* |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
865 |
cd - >/dev/null |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
866 |
} |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
867 |
|
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
868 |
This embellishment of the previous version saves the current working directory, |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
869 |
``cd``'s to the Waf directory, then instructs Waf to change the working |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
870 |
directory *back* to the saved current working directory before running the |
4fe4f5afb5f3
[tutorial] Introduce more waf options and best work practices.
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents:
10401
diff
changeset
|
871 |
program. |