doc/tutorial/source/getting-started.rst
author Daniel Lertpratchya <nikkipui@gmail.com>
Wed, 13 Nov 2013 16:06:43 -0500
changeset 10401 6e9d4ceb880b
parent 9960 e03e5de1edc9
child 10609 4fe4f5afb5f3
permissions -rw-r--r--
Update ns-3 wiki URL
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
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    36
Downloading ns-3
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    37
****************
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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
    65
http://www.nsnam.org/releases/, or you can work with repositories
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
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    75
Downloading ns-3 Using a Tarball
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    76
++++++++++++++++++++++++++++++++
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
    77
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    78
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
    79
files are bundled together and the archive possibly compressed.
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    80
|ns3| software releases are provided via a downloadable tarball.
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    81
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
    82
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
    83
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    84
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
    85
directory called ``workspace``. 
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    86
If you adopt the ``workspace`` directory approach, you can 
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    87
get a copy of a release by typing the following into your Linux shell 
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    88
(substitute the appropriate version numbers, of course):
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
::
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    91
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
    92
  $ cd
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
    93
  $ mkdir workspace
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
    94
  $ cd workspace
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
    95
  $ wget http://www.nsnam.org/releases/ns-allinone-3.17.tar.bz2
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
    96
  $ tar xjf ns-allinone-3.17.tar.bz2
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    97
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    98
If you change into the directory ``ns-allinone-3.17`` you should see a
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
    99
number of files:
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   100
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   101
::
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   102
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   103
  bake      constants.py   ns-3.17               README
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   104
  build.py  netanim-3.103  pybindgen-0.16.0.825  util.py
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   105
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   106
You are now ready to build the |ns3| distribution.
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   107
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   108
Downloading ns-3 Using Bake
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   109
++++++++++++++++++++++++++++
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   110
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   111
Bake is a tool for distributed integration and building, 
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   112
developed for the |ns3| project.  First of all, Bake is 
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   113
developed in Python, and should be fetched from the project's 
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   114
master code repositories using a tool called Mercurial, so to 
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   115
run Bake one must have Python and mercurial on one's machine.
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   116
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   117
One practice is to create a directory called ``workspace`` in one's home 
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   118
directory under which one can keep local Mercurial repositories.  
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   119
Any directory name will do, but we'll assume that ``workspace`` is used
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   120
herein (note:  ``repos`` may also be used in some documentation as
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   121
an example directory name).  You can get a copy of ``bake`` by typing the 
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   122
following into your Linux shell (assuming you have installed Mercurial):
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   123
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   124
::
9163
950db74a6484 Minor fixes and corrections to tutorial formatting.
Vedran Miletić <rivanvx@gmail.com>
parents: 9107
diff changeset
   125
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   126
  $ cd
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   127
  $ mkdir workspace
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   128
  $ cd workspace
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   129
  $ hg clone http://code.nsnam.org/bake
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   130
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   131
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
   132
following displayed,
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   133
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   134
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   135
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   136
  destination directory: bake
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   137
  requesting all changes
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   138
  adding changesets
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   139
  adding manifests
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   140
  adding file changes
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   141
  added 252 changesets with 661 changes to 62 files
7654
62ecccd96cad Freshen the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7314
diff changeset
   142
  updating to branch default
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   143
  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
   144
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   145
After the clone command completes, you should have a directory called 
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   146
``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
   147
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   148
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   149
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   150
  bake                  bakeconf.xml  doc       generate-binary.py  TODO
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   151
  bake.py               examples      test
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   152
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   153
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
   154
module called ``bake``.  The next step
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   155
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
   156
distribution of your choice.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   157
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   158
There are a few configuration targets available:
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   159
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   160
1.  ``ns-3.17``:  the module corresponding to the release; it will download
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   161
    components similar to the release tarball.
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   162
2.  ``ns-3-dev``:  a similar module but using the development code tree
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   163
3.  ``ns-allinone-3.17``:  the module that includes other optional features
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   164
    such as click routing, openflow for |ns3|, and the Network Simulation
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   165
    Cradle
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   166
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
   167
    module, but for development code.
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   168
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   169
The current development snapshot (unreleased) of |ns3| may be found 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   170
at http://code.nsnam.org/ns-3-dev/.  The 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   171
developers attempt to keep these repository in consistent, working states but
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   172
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
   173
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
   174
introduced features.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   175
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   176
You can find the latest version  of the
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   177
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
   178
`"ns-3 Releases"
7162e24118ea Miscellaneous fixes to Tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7275
diff changeset
   179
<http://www.nsnam.org/releases>`_
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   180
web page and clicking on the latest release link.  We'll proceed in
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   181
this tutorial example with ``ns-3.17``.
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   182
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   183
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
   184
|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
   185
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   186
bake works by downloading source packages into a source directory,
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   187
and installing libraries into a build directory.  bake can be run
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   188
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
   189
outside of the directory it was downloaded into, it is advisable
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   190
to put bake into your path, such as follows (Linux bash shell example):
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   191
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   192
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   193
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   194
  $ export BAKE_HOME=`pwd`/bake
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   195
  $ export PATH=$PATH:$BAKE_HOME
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   196
  $ export PYTHONPATH=$PYTHONPATH:$BAKE_HOME
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   197
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   198
However, setting environment variables is not strictly necessary to
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   199
complete this tutorial, so we'll call bake directly by specifying the path 
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   200
to it in our shell commands.
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   201
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   202
Step into the workspace directory and type the following into your shell:
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   203
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   204
::
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   205
9960
e03e5de1edc9 Error on the installation doc
daniel
parents: 9957
diff changeset
   206
  $ ./bake.py configure -e ns-3.17
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   207
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   208
Next, we'l ask bake to check whether we have enough tools to download
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   209
various components.  Type:
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   210
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   211
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   212
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   213
  $ ./bake.py check
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
You should see something like the following,
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   216
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   217
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   218
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   219
   > Python - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   220
   > GNU C++ compiler - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   221
   > Mercurial - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   222
   > CVS - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   223
   > GIT - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   224
   > Bazaar - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   225
   > Tar tool - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   226
   > Unzip tool - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   227
   > Unrar tool - is missing
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   228
   > 7z  data compression utility - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   229
   > XZ data compression utility - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   230
   > Make - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   231
   > cMake - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   232
   > patch tool - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   233
   > autoreconf tool - OK
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   234
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   235
   > 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
   236
   /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
   237
   /home/tomh/bin bin
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   238
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   239
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
   240
are our principal concerns at this point, since they allow us to fetch
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   241
the code.  Please install missing tools at this stage if you are able to.
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   242
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   243
Next, try to download the software:
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   244
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   245
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   246
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   247
  ./bake.py download
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   248
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   249
should yield something like:
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   250
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   251
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   252
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   253
   >> Searching for system dependency pygoocanvas - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   254
   >> Searching for system dependency python-dev - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   255
   >> Searching for system dependency pygraphviz - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   256
   >> Downloading pybindgen-0.16.0.825 - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   257
   >> Searching for system dependency g++ - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   258
   >> Searching for system dependency qt4 - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   259
   >> Downloading netanim-3.103 - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   260
   >> Downloading ns-3.17 - OK    
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   261
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   262
The above suggests that three sources have been downloaded.  Check the
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   263
``source`` directory now and type ``ls``; one should see:
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   264
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   265
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   266
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   267
  netanim-3.103  ns-3.17  pybindgen-0.16.0.825
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   268
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   269
You are now ready to build the |ns3| distribution.
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
Building ns-3
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   272
*************
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   273
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   274
Building with build.py
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   275
++++++++++++++++++++++
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   276
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
   277
|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
   278
``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
   279
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
   280
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
   281
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
   282
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
   283
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   284
If you downloaded
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   285
using a tarball you should have a directory called something like 
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   286
``ns-allinone-3.17`` under your ``~/workspace`` directory.  
7661
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   287
Type the following:
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   288
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   289
::
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
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   302
following magic words:
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   303
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   304
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   305
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   306
   Waf: Leaving directory `/path/to/workspace/ns-allinone-3.17/ns-3.17/build'
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   307
   'build' finished successfully (6m25.032s)
7071
24c505cb1c87 Update tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7025
diff changeset
   308
  
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   309
   Modules built:
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   310
   antenna                   aodv                      applications             
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   311
   bridge                    buildings                 config-store             
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   312
   core                      csma                      csma-layout              
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   313
   dsdv                      dsr                       emu                      
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   314
   energy                    fd-net-device             flow-monitor             
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   315
   internet                  lte                       mesh                     
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   316
   mobility                  mpi                       netanim (no Python)      
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   317
   network                   nix-vector-routing        olsr                     
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   318
   point-to-point            point-to-point-layout     propagation              
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   319
   spectrum                  stats                     tap-bridge               
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   320
   test (no Python)          tools                     topology-read            
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   321
   uan                       virtual-net-device        wifi                     
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   322
   wimax                    
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   323
  
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   324
   Modules not built (see ns-3 tutorial for explanation):
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   325
   brite                     click                     openflow                 
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   326
   visualizer               
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   327
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   328
   Leaving directory `./ns-3.17'
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   329
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   330
Regarding the portion about modules not built:
9169
f8bff624db3c clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents: 9163
diff changeset
   331
f8bff624db3c clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents: 9163
diff changeset
   332
::
f8bff624db3c clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents: 9163
diff changeset
   333
f8bff624db3c clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents: 9163
diff changeset
   334
  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
   335
  brite                     click                     openflow                 
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   336
  visualizer               
9169
f8bff624db3c clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents: 9163
diff changeset
   337
f8bff624db3c clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents: 9163
diff changeset
   338
This just means that some ns-3 modules that have dependencies on
f8bff624db3c clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents: 9163
diff changeset
   339
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
   340
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
   341
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
   342
results for the modules listed as being built.
f8bff624db3c clarify 'Modules not built' waf report
Tom Henderson <tomh@tomh.org>
parents: 9163
diff changeset
   343
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   344
Building with bake
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   345
++++++++++++++++++
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   346
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   347
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
   348
may continue to use it to build |ns3|.  Type 
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   349
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   350
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   351
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   352
  $ ./bake.py build
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   353
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   354
and you should see something like:
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   355
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   356
:: 
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   357
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   358
  >> Building pybindgen-0.16.0.825 - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   359
  >> Building netanim-3.103 - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   360
  >> Building ns-3.17 - OK
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   361
9749
ce15c45471d8 more tutorial updates
Tom Henderson <tomh@tomh.org>
parents: 9742
diff changeset
   362
*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
   363
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   364
If there happens to be a failure, please have a look at what the following
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   365
command tells you; it may give a hint as to a missing dependency:
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   366
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   367
::
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   368
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   369
  $ ./bake.py show
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   370
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   371
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
   372
trying to build.
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   373
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   374
Building with Waf
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   375
+++++++++++++++++
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   376
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   377
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
   378
`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
   379
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
   380
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
   381
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
   382
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
   383
the |ns3| directory that you have initially built.
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   384
7661
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   385
It's not 
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   386
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
   387
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
   388
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
   389
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
   390
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
   391
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
   392
builds that include the examples and tests, you will need to execute the 
7661
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   393
following commands,
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   394
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   395
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   396
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   397
  $ ./waf clean
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   398
  $ ./waf -d optimized --enable-examples --enable-tests configure
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   399
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   400
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
   401
for you).  The first command to clean out the previous build is not 
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   402
typically strictly necessary but is good practice; it will remove the
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   403
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
   404
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
   405
dependencies, you should see
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   406
output that looks similar to the following,
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   407
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   408
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   409
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   410
  Checking for program g++                 : ok /usr/bin/g++
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   411
  Checking for program cpp                 : ok /usr/bin/cpp
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   412
  Checking for program ar                  : ok /usr/bin/ar
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   413
  Checking for program ranlib              : ok /usr/bin/ranlib
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   414
  Checking for g++                         : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   415
  Checking for program pkg-config          : ok /usr/bin/pkg-config
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   416
  Checking for -Wno-error=deprecated-declarations support : yes
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   417
  Checking for -Wl,--soname=foo support                   : yes
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   418
  Checking for header stdlib.h                            : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   419
  Checking for header signal.h                            : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   420
  Checking for header pthread.h                           : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   421
  Checking for high precision time implementation         : 128-bit integer
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   422
  Checking for header stdint.h                            : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   423
  Checking for header inttypes.h                          : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   424
  Checking for header sys/inttypes.h                      : not found
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   425
  Checking for library rt                                 : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   426
  Checking for header netpacket/packet.h                  : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   427
  Checking for pkg-config flags for GSL                   : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   428
  Checking for header linux/if_tun.h                      : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   429
  Checking for pkg-config flags for GTK_CONFIG_STORE      : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   430
  Checking for pkg-config flags for LIBXML2               : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   431
  Checking for library sqlite3                            : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   432
  Checking for NSC location                               : ok ../nsc (guessed)
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   433
  Checking for library dl                                 : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   434
  Checking for NSC supported architecture x86_64          : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   435
  Checking for program python                             : ok /usr/bin/python
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   436
  Checking for Python version >= 2.3                      : ok 2.5.2
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   437
  Checking for library python2.5                          : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   438
  Checking for program python2.5-config                   : ok /usr/bin/python2.5-config
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   439
  Checking for header Python.h                            : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   440
  Checking for -fvisibility=hidden support                : yes
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   441
  Checking for pybindgen location                         : ok ../pybindgen (guessed)
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   442
  Checking for Python module pybindgen                    : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   443
  Checking for pybindgen version                          : ok 0.10.0.640
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   444
  Checking for Python module pygccxml                     : ok
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   445
  Checking for pygccxml version                           : ok 0.9.5
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   446
  Checking for program gccxml                             : ok /usr/local/bin/gccxml
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   447
  Checking for gccxml version                             : ok 0.9.0
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   448
  Checking for program sudo                               : ok /usr/bin/sudo
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   449
  Checking for program hg                                 : ok /usr/bin/hg
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   450
  Checking for program valgrind                           : ok /usr/bin/valgrind
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   451
  ---- Summary of optional NS-3 features:
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   452
  Threading Primitives          : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   453
  Real Time Simulator           : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   454
  Emulated Net Device           : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   455
  GNU Scientific Library (GSL)  : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   456
  Tap Bridge                    : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   457
  GtkConfigStore                : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   458
  XmlIo                         : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   459
  SQlite stats data output      : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   460
  Network Simulation Cradle     : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   461
  Python Bindings               : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   462
  Python API Scanning Support   : enabled
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   463
  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
   464
  Build tests                   : enabled
7025
32212c736ab4 Move examples out of samples directory and remove it
Mitch Watrous <watrous@u.washington.edu>
parents: 7024
diff changeset
   465
  Build examples                : enabled
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   466
  Static build                  : not enabled (option --enable-static not selected)
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   467
  'configure' finished successfully (2.870s)
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   468
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   469
Note the last part of the above output.  Some ns-3 options are not enabled by
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   470
default or require support from the underlying system to work properly.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   471
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
   472
system.  If this library were not found, the corresponding |ns3| feature 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   473
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
   474
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
   475
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
   476
7024
4392d52b3536 Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents: 6998
diff changeset
   477
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
   478
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   479
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   480
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   481
  $ ./waf clean
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   482
  $ ./waf -d debug --enable-examples --enable-tests configure
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
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
   485
the |ns3| programs by simply typing
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   486
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   487
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   488
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   489
  $ ./waf
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   490
7661
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   491
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
   492
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
   493
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   494
Here are a few more introductory tips about Waf.
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   495
Some waf commands are meaningful during the build phase and some commands are valid
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   496
in the configuration phase.  For example, if you wanted to use the emulation 
6998
1c2b8cfb71d2 Make tests not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents: 6754
diff changeset
   497
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
   498
sudo as described above.  This turns out to be a configuration-time command, and so 
7024
4392d52b3536 Make examples not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents: 6998
diff changeset
   499
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
   500
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   501
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   502
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   503
  $ ./waf configure -d debug --enable-sudo --enable-examples --enable-tests
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   504
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   505
If you do this, waf will have run sudo to change the socket creator programs of the
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   506
emulation code to run as root.  There are many other configure- and build-time options
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   507
available in waf.  To explore these options, type:
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   508
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   509
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   510
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   511
  $ ./waf --help
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   512
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   513
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
   514
7661
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   515
Finally, as an aside, it is possible to specify that waf builds the 
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   516
project in 
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   517
a directory different than the default ``build/`` directory by passing
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   518
the ``-o`` option to configure; e.g.
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   519
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   520
::
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   521
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   522
  $ ./waf configure -d debug -o build/debug --enable-examples --enable-tests
7661
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   523
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   524
This allows users to work with multiple builds rather than always
9ef562047d3e some clarifications to the use of build.py in the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7654
diff changeset
   525
overwriting the last build.
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   526
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
   527
In the examples above, waf uses GCC C++ compiler, command ``g++``, for
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   528
building ns-3. However, it's possible to change C++ compiler used by waf.
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   529
Say one wants to use Clang C++ compiler, command ``clang++``; it's done by
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   530
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   531
::
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   532
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   533
  $ CXX="clang++" ./waf configure
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   534
  $ ./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
   535
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   536
One can also set up waf to do distributed compilation with ``distcc`` in
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   537
a similar way:
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   538
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   539
::
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   540
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   541
  $ CXX="distcc g++" ./waf configure
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   542
  $ ./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
   543
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   544
More info on distcc and distributed compilation can be found on it's
b6e9f47c260b Document building with distcc in tutorial, add it to RELEASE_NOTES and CHANGES.html.
Vedran Miletić <rivanvx@gmail.com>
parents: 9169
diff changeset
   545
`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
   546
<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
   547
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
   548
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   549
Testing ns-3
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   550
************
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   551
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   552
You can run the unit tests of the |ns3| distribution by running the 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   553
"./test.py -c core" script,
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   554
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   555
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   556
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   557
  $ ./test.py -c core
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   558
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   559
These tests are run in parallel by waf. You should eventually
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   560
see a report saying that,
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   561
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   562
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   563
7654
62ecccd96cad Freshen the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7314
diff changeset
   564
  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
   565
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   566
This is the important message.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   567
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   568
You will also see output from the test runner and the output will actually look something like,
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   569
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   570
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   571
9742
b24738ffa84b update tutorial for bake usage
Tom Henderson <tomh@tomh.org>
parents: 9189
diff changeset
   572
  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
   573
  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
   574
  'build' finished successfully (1.799s)
7071
24c505cb1c87 Update tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7025
diff changeset
   575
  
24c505cb1c87 Update tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7025
diff changeset
   576
  Modules built: 
7275
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   577
  aodv                      applications              bridge
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   578
  click                     config-store              core
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   579
  csma                      csma-layout               dsdv
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   580
  emu                       energy                    flow-monitor
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   581
  internet                  lte                       mesh
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   582
  mobility                  mpi                       netanim
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   583
  network                   nix-vector-routing        ns3tcp
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   584
  ns3wifi                   olsr                      openflow
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   585
  point-to-point            point-to-point-layout     propagation
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   586
  spectrum                  stats                     tap-bridge
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   587
  template                  test                      tools
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   588
  topology-read             uan                       virtual-net-device
83f76a2f8449 documentation fixes
Andrey Mazo <mazo@iitp.ru>
parents: 7099
diff changeset
   589
  visualizer                wifi                      wimax
7071
24c505cb1c87 Update tutorial
Mitch Watrous <watrous@u.washington.edu>
parents: 7025
diff changeset
   590
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   591
  PASS: TestSuite ns3-wifi-interference
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   592
  PASS: TestSuite histogram
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   593
  PASS: TestSuite sample
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   594
  PASS: TestSuite ipv4-address-helper
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   595
  PASS: TestSuite devices-wifi
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   596
  PASS: TestSuite propagation-loss-model
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   597
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   598
  ...
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   599
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   600
  PASS: TestSuite attributes
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   601
  PASS: TestSuite config
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   602
  PASS: TestSuite global-value
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   603
  PASS: TestSuite command-line
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   604
  PASS: TestSuite basic-random-number
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   605
  PASS: TestSuite object
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   606
  PASS: TestSuite random-number-generators
7654
62ecccd96cad Freshen the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7314
diff changeset
   607
  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
   608
7654
62ecccd96cad Freshen the tutorial
Tom Henderson <tomh@tomh.org>
parents: 7314
diff changeset
   609
This command is typically run by users to quickly verify that an 
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   610
|ns3| distribution has built correctly.  
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   611
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   612
Running a Script
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   613
****************
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   614
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
   615
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
   616
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
   617
``--run`` option in Waf.  Let's run the |ns3| equivalent of the
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   618
ubiquitous hello world program by typing the following:
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   619
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   620
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   621
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   622
  $ ./waf --run hello-simulator
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   623
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   624
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
   625
executes a build if required.  Waf then executes the program, which 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   626
produces the following output.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   627
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   628
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   629
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   630
  Hello Simulator
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   631
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   632
*Congratulations.  You are now an ns-3 user.*
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   633
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   634
*What do I do if I don't see the output?*
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   635
9107
97282f9f685b fix small tutorial typo
Tom Henderson <tomh@tomh.org>
parents: 8837
diff changeset
   636
If you see ``waf`` messages indicating that the build was 
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   637
completed successfully, but do not see the "Hello Simulator" output, 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   638
chances are that you have switched your build mode to "optimized" in 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   639
the "Building with Waf" section, but have missed the change back to 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   640
"debug" mode.  All of the console output used in this tutorial uses a 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   641
special |ns3| logging component that is useful for printing 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   642
user messages to the console.  Output from this component is 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   643
automatically disabled when you compile optimized code -- it is 
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   644
"optimized out."  If you don't see the "Hello Simulator" output,
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   645
type the following,
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   646
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   647
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   648
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   649
  $ ./waf configure -d debug --enable-examples --enable-tests
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   650
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   651
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
   652
programs that includes the examples and tests.  You must still build 
6998
1c2b8cfb71d2 Make tests not be built by default
Mitch Watrous <watrous@u.washington.edu>
parents: 6754
diff changeset
   653
the actual debug version of the code by typing,
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   654
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   655
::
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   656
9957
1a4d84a85bad Manual and Tutorial syntax coloring
Peter D. Barnes, Jr. <barnes26@llnl.gov>
parents: 9749
diff changeset
   657
  $ ./waf
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   658
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   659
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
   660
expected output.
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   661
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   662
If you want to run programs under another tool such as gdb or valgrind,
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   663
see this `wiki entry
10401
6e9d4ceb880b Update ns-3 wiki URL
Daniel Lertpratchya <nikkipui@gmail.com>
parents: 9960
diff changeset
   664
<http://www.nsnam.org/wiki/User_FAQ#How_to_run_NS-3_programs_under_another_tool>`_.
6754
7ff69b244b5b Move tutorial to Sphinx
Tom Henderson <tomh@tomh.org>
parents:
diff changeset
   665