doc/tutorial/source/getting-started.rst
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--
small edits on previous commit
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
     3
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
     4
Getting Started
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
     5
---------------
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
     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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
    30
In the following, we'll look at two ways of downloading and building
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
    31
|ns3|.  The first is to download and build an official release
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
    32
from the main web site.  The second is to fetch and build development
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
    33
copies of |ns3|.  We'll walk through both examples since the tools
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
    34
involved are slightly different.
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
    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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    38
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    39
The |ns3| system as a whole is a fairly complex system and has a
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    40
number of dependencies on other components.  Along with the systems you will
8837
b769bed02bc2 two small tutorial typos
Tom Henderson <tomh@tomh.org>
parents: 7661
diff changeset
    41
most likely deal with every day (the GNU toolchain, Mercurial, a text
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    42
editor) you will need to ensure that a number of additional libraries are
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    47
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    48
The "Prerequisites" section of this wiki page explains which packages are 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    49
required to support common |ns3| options, and also provides the 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    50
commands used to install them for common Linux variants.  Cygwin users will
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    51
have to use the Cygwin installer (if you are a Cygwin user, you used it to
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    52
install Cygwin). 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    53
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    54
You may want to take this opportunity to explore the |ns3| wiki 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    55
a bit since there really is a wealth of information there. 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    56
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    57
From this point forward, we are going to assume that the reader is working in
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    58
Linux or a Linux emulation environment (Linux, Cygwin, etc.) and has the GNU
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    59
toolchain installed and verified along with the prerequisites mentioned 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    62
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    63
The |ns3| code is available in Mercurial repositories on the server
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    64
http://code.nsnam.org.  You can also download a tarball release at
11116
d4baad1975de fix URL
Tom Henderson <tomh@tomh.org>
parents: 11077
diff changeset
    65
http://www.nsnam.org/release/, or you can work with repositories
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    66
using Mercurial.  We recommend using Mercurial unless there's a good reason
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    67
not to.  See the end of this section for instructions on how to get a tarball
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    68
release.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    69
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    70
The simplest way to get started using Mercurial repositories is to use the
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    71
``ns-3-allinone`` environment.  This is a set of scripts that manages the 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
    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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   112
++++++++++++++++++++++++++++
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   113
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   136
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   137
As the hg (Mercurial) command executes, you should see something like the 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   138
following displayed,
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   139
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   140
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   144
  requesting all changes
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   145
  adding changesets
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   146
  adding manifests
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
62ecccd96cad Freshen the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7314
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   151
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   161
will be to use those scripts to download and build the |ns3|
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   162
distribution of your choice.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   163
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   164
There are a few configuration targets available:
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   167
    components similar to the release tarball.
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   170
    such as click routing, openflow for |ns3|, and the Network Simulation
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   171
    Cradle
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   172
4.  ``ns-3-allinone``:  similar to the released version of the allinone
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   173
    module, but for development code.
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   174
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   175
The current development snapshot (unreleased) of |ns3| may be found 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   176
at http://code.nsnam.org/ns-3-dev/.  The 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   177
developers attempt to keep these repository in consistent, working states but
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   178
they are in a development area with unreleased code present, so you may want 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   179
to consider staying with an official release if you do not need newly-
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   180
introduced features.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   181
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   182
You can find the latest version  of the
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   188
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   189
We are now going to use the bake tool to pull down the various pieces of 
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   190
|ns3| you will be using.  First, we'll say a word about running bake.
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   191
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   192
bake works by downloading source packages into a source directory,
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   193
and installing libraries into a build directory.  bake can be run
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   194
by referencing the binary, but if one chooses to run bake from
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   217
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   218
  $ ./bake.py check
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   221
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   222
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   270
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   271
You are now ready to build the |ns3| distribution.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   285
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   286
If you downloaded
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   299
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   300
You will see lots of typical compiler output messages displayed as the build
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
24c505cb1c87 Update tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7025
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   345
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   346
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   356
*Hint:  you can also perform both steps, download and build by calling 'bake.py deploy'.*
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   365
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   366
Building with Waf
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   378
strictly required at this point, but it will be valuable to take a slight
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   379
detour and look at how to make changes to the configuration of the project.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   380
Probably the most useful configuration change you can make will be to 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   389
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   453
  GtkConfigStore                : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   468
  Use sudo to set suid bit      : not enabled (option --enable-sudo not selected)
7071
24c505cb1c87 Update tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7025
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   475
default or require support from the underlying system to work properly.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   476
For instance, to enable XmlTo, the library libxml-2.0 must be found on the
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   477
system.  If this library were not found, the corresponding |ns3| feature 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   478
would not be enabled and a message would be displayed.  Note further that there is 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   479
a feature to use the program ``sudo`` to set the suid bit of certain programs.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   480
This is not enabled by default and so this feature is reported as "not enabled."
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   483
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   484
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   488
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   489
The build system is now configured and you can build the debug versions of 
7654
62ecccd96cad Freshen the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7314
diff changeset
   490
the |ns3| programs by simply typing
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   491
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   492
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   493
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   494
  $ ./waf
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   532
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   533
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   542
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   543
  $ ./waf --help
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   544
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   545
We'll use some of the testing-related commands in the next section.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   695
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   703
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   704
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   705
7654
62ecccd96cad Freshen the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7314
diff changeset
   706
  92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   707
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   708
This is the important message.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   715
  'build' finished successfully (1.799s)
7071
24c505cb1c87 Update tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7025
diff changeset
   716
  
24c505cb1c87 Update tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7025
diff changeset
   717
  Modules built: 
7275
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   718
  aodv                      applications              bridge
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   719
  click                     config-store              core
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   720
  csma                      csma-layout               dsdv
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   721
  emu                       energy                    flow-monitor
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   722
  internet                  lte                       mesh
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   723
  mobility                  mpi                       netanim
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   724
  network                   nix-vector-routing        ns3tcp
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   725
  ns3wifi                   olsr                      openflow
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   726
  point-to-point            point-to-point-layout     propagation
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   727
  spectrum                  stats                     tap-bridge
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   728
  template                  test                      tools
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   729
  topology-read             uan                       virtual-net-device
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   730
  visualizer                wifi                      wimax
7071
24c505cb1c87 Update tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7025
diff changeset
   731
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   732
  PASS: TestSuite ns3-wifi-interference
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   733
  PASS: TestSuite histogram
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   734
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   735
  ...
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   736
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   737
  PASS: TestSuite object
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   738
  PASS: TestSuite random-number-generators
7654
62ecccd96cad Freshen the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7314
diff changeset
   739
  92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   740
7654
62ecccd96cad Freshen the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7314
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   745
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   746
Running a Script
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   749
We typically run scripts under the control of Waf.  This allows the build 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   750
system to ensure that the shared library paths are set correctly and that
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   751
the libraries are available at run time.  To run a program, simply use the
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   756
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   757
Waf first checks to make sure that the program is built correctly and 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   758
executes a build if required.  Waf then executes the program, which 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   759
produces the following output.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   760
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   761
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   762
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   763
  Hello Simulator
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   774
special |ns3| logging component that is useful for printing 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   775
user messages to the console.  Output from this component is 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   776
automatically disabled when you compile optimized code -- it is 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   785
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   786
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   787
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   788
  $ ./waf
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   789
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   790
Now, if you run the ``hello-simulator`` program, you should see the 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   791
expected output.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   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.