F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Freshen the tutorial

Browse Source
This commit is contained in:
Tom Henderson
2011-12-23 12:00:12 -08:00
parent 2cff47cffc
commit b97001e014
4 changed files with 57 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
doc/tutorial/source/conclusion.rst
View File

@@ -7,17 +7,8 @@ Conclusion
Futures
*******
This document is a work in process. We hope and expect it to grow over time
to cover more and more of the nuts and bolts of |ns3|.
We hope to add the following chapters over the next few releases:
* The Callback System
* The Object System and Memory Management
* The Routing System
* Adding a New NetDevice and Channel
* Adding a New Protocol
* Working with Real Networks and Hosts
This document is intended as a living document. We hope and expect it to
grow over time to cover more and more of the nuts and bolts of |ns3|.
Writing manual and tutorial chapters is not something we all get excited about,
but it is very important to the project. If you are an expert in one of these
@@ -28,10 +19,13 @@ Closing
*******
|ns3| is a large and complicated system. It is impossible to cover all
of the things you will need to know in one small tutorial.
of the things you will need to know in one small tutorial. Readers
who want to learn more are encouraged to read the following additional
documentation:
We have really just scratched the surface of |ns3| in this tutorial,
but we hope to have covered enough to get you started doing useful networking
research using our favorite simulator.
* The |ns3| manual
* The |ns3| model library documentatio
* The |ns3| Doxygen (API documentation)
* The |ns3| wiki
-- The |ns3| development team.

36
doc/tutorial/source/getting-started.rst
View File

@@ -53,7 +53,6 @@ that approach, you can get a copy of ``ns-3-allinone`` by typing the
following into your Linux shell (assuming you have installed Mercurial):
::
cd
mkdir repos
cd repos
@@ -69,11 +68,12 @@ following displayed,
adding changesets
adding manifests
adding file changes
added 31 changesets with 45 changes to 7 files
added 47 changesets with 67 changes to 7 files
updating to branch default
7 files updated, 0 files merged, 0 files removed, 0 files unresolved
After the clone command completes, you should have a directory called
``ns-3-allinone`` under your ``~/repos`` directory, the contents of which should
``ns-3-allinone``, the contents of which should
look something like the following:
::
@@ -221,7 +221,7 @@ As mentioned above, one practice is to create a directory called ``repos``
in one's home directory under which one can keep local Mercurial repositories.
One could also keep a ``tarballs`` directory. *Hint: the tutorial
will assume you downloaded into a ``repos`` directory, so remember the
placekeeper.``* If you adopt the ``tarballs`` directory approach, you can
placekeeper.* If you adopt the ``tarballs`` directory approach, you can
get a copy of a release by typing the following into your Linux shell
(substitute the appropriate version numbers, of course):
@@ -230,15 +230,15 @@ get a copy of a release by typing the following into your Linux shell
cd
mkdir tarballs
cd tarballs
wget http://www.nsnam.org/releases/ns-allinone-3.10.tar.bz2
tar xjf ns-allinone-3.10.tar.bz2
wget http://www.nsnam.org/releases/ns-allinone-3.13.tar.bz2
tar xjf ns-allinone-3.13.tar.bz2
If you change into the directory ``ns-allinone-3.10`` you should see a
If you change into the directory ``ns-allinone-3.13`` you should see a
number of files:
::
build.py ns-3.10/ pybindgen-0.15.0/ util.py
build.py ns-3.13/ pybindgen-0.15.0.795/ util.py
constants.py nsc-0.5.2/ README
You are now ready to build the |ns3| distribution.
@@ -256,7 +256,7 @@ Change into the directory you created in the download section above. If you
downloaded using Mercurial you should have a directory called
``ns-3-allinone`` under your ``~/repos`` directory. If you downloaded
using a tarball you should have a directory called something like
``ns-allinone-3.10`` under your ``~/tarballs`` directory. Take a deep
``ns-allinone-3.13`` under your ``~/tarballs`` directory. Take a deep
breath and type the following:
::
@@ -274,7 +274,7 @@ following magic words:
::
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3.13/build'
'build' finished successfully (2m30.586s)
Modules built:
@@ -292,12 +292,12 @@ following magic words:
topology-read uan virtual-net-device
visualizer wifi wimax
Once the project has built you can say goodbye to your old friends, the
Once the project has built, you can stop working with the
``ns-3-allinone`` scripts. You got what you needed from them and will now
interact directly with Waf and we do it in the ``ns-3-dev`` directory,
interact directly with Waf and we do it in the |ns3| directory,
not in the ``ns-3-allinone`` directory. Go ahead and change into the
``ns-3-dev`` directory (or the directory for the appropriate release you
downloaded.
|ns3| directory (or the directory for the appropriate release or
development snapshot that you downloaded; e.g.
::
@@ -399,7 +399,7 @@ Now go ahead and switch back to the debug build that includes the examples and t
./waf -d debug --enable-examples --enable-tests configure
The build system is now configured and you can build the debug versions of
the |ns3| programs by simply typing,
the |ns3| programs by simply typing
::
@@ -443,7 +443,7 @@ see a report saying that,
::
47 of 47 tests passed (47 passed, 0 failed, 0 crashed, 0 valgrind errors)
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)
This is the important message.
@@ -486,9 +486,9 @@ You will also see output from the test runner and the output will actually look
PASS: TestSuite basic-random-number
PASS: TestSuite object
PASS: TestSuite random-number-generators
95 of 95 tests passed (95 passed, 0 failed, 0 crashed, 0 valgrind errors)
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)
This command is typically run by ``users`` to quickly verify that an
This command is typically run by users to quickly verify that an
|ns3| distribution has built correctly.
Running a Script

47
doc/tutorial/source/introduction.rst
View File

@@ -25,48 +25,49 @@ A few key points are worth noting at the onset:
* Ns-3 is not an extension of `ns-2
<http://www.isi.edu/nsnam/ns>`_;
it is a new simulator. The two simulators are both written in C++ but
|ns3| is a new simulator that does not support the ns-2 APIs. Some
models from ns-2 have already been ported from ns-2 to |ns3|. The
project will continue to maintain ns-2 while |ns3| is being built,
|ns3| is a new simulator that does not support the |ns2| APIs. Some
models from |ns2| have already been ported from |ns2| to |ns3|. The
project will continue to maintain |ns2| while |ns3| is being built,
and will study transition and integration mechanisms.
* |ns3| is open-source, and the project strives to maintain an
open environment for researchers to contribute and share their software.
open environment for researchers to contribute and share their software.
For ns-2 Users
For |ns2| Users
**************
For those familiar with ns-2, the most visible outward change when moving to
|ns3| is the choice of scripting language. Ns-2 is
For those familiar with |ns2|, the most visible outward change when moving to
|ns3| is the choice of scripting language. Programs in |ns2| are
scripted in OTcl and results of simulations can be visualized using the
Network Animator nam. It is not possible to run a simulation
in ns-2 purely from C++ (i.e., as a main() program without any OTcl).
Moreover, some components of ns-2 are written in C++ and others in OTcl.
in |ns2| purely from C++ (i.e., as a main() program without any OTcl).
Moreover, some components of |ns2| are written in C++ and others in OTcl.
In |ns3|, the simulator is written entirely in C++, with optional
Python bindings. Simulation scripts can therefore be written in C++
or in Python. The results of some simulations can be visualized by
nam, but new animators are under development. Since |ns3|
or in Python. New animators and visualizers are available and under
current development. Since |ns3|
generates pcap packet trace files, other utilities can be used to
analyze traces as well.
In this tutorial, we will first concentrate on scripting
directly in C++ and interpreting results via trace files.
But there are similarities as well (both, for example, are based on C++
objects, and some code from ns-2 has already been ported to |ns3|).
We will try to highlight differences between ns-2 and |ns3|
objects, and some code from |ns2| has already been ported to |ns3|).
We will try to highlight differences between |ns2| and |ns3|
as we proceed in this tutorial.
A question that we often hear is "Should I still use ns-2 or move to
A question that we often hear is "Should I still use |ns2| or move to
|ns3|?" The answer is that it depends. |ns3| does not have
all of the models that ns-2 currently has, but on the other hand, |ns3|
all of the models that |ns2| currently has, but on the other hand, |ns3|
does have new capabilities (such as handling multiple interfaces on nodes
correctly, use of IP addressing and more alignment with Internet
protocols and designs, more detailed 802.11 models, etc.). ns-2
models can usually be ported to |ns3| (a porting guide is under
development). There is active development on multiple fronts for
|ns3|. The |ns3| developers believe (and certain early users
have proven) that |ns3| is ready for active use, and should be an
attractive alternative for users looking to start new simulation projects.
protocols and designs, more detailed 802.11 models, etc.). |ns2|
models can sometimes be ported to |ns3| (a porting guide is under
development). The support available on the user mailing list, and the
developer and maintainer activity, is higher for |ns3|. A good guideline
would be to look at both simulators, and in particular the models available
for your research, but when in doubt or when starting new simulation
projects, choose the tool that is under more active development (|ns3|).
Contributing
************
@@ -75,13 +76,13 @@ Contributing
research community. It will rely on the ongoing contributions of the
community to develop new models, debug or maintain existing ones, and share
results. There are a few policies that we hope will encourage people to
contribute to |ns3| like they have for ns-2:
contribute to |ns3| like they have for |ns2|:
* Open source licensing based on GNU GPLv2 compatibility
* `wiki
<http://www.nsnam.org/wiki/index.php>`_
* `Contributed Code
<http://www.nsnam.org/wiki/index.php/Contributed_Code>`_ page, similar to ns-2's popular Contributed Code
<http://www.nsnam.org/wiki/index.php/Contributed_Code>`_ page, similar to |ns2|'s popular Contributed Code
`page
<http://nsnam.isi.edu/nsnam/index.php/Contributed_Code>`_
* Open `bug tracker

30
doc/tutorial/source/resources.rst
View File

@@ -10,7 +10,7 @@ There are several important resources of which any |ns3| user must be
aware. The main web site is located at http://www.nsnam.org and
provides access to basic information about the |ns3| system. Detailed
documentation is available through the main web site at
http://www.nsnam.org/documents.html. You can also find documents
http://www.nsnam.org/documentation/. You can also find documents
relating to the system architecture from this page.
There is a Wiki that complements the main |ns3| web site which you will
@@ -61,9 +61,7 @@ using the Python language.
The build system Waf is used on the |ns3| project. It is one
of the new generation of Python-based build systems. You will not need to
understand any Python to build the existing |ns3| system, and will
only have to understand a tiny and intuitively obvious subset of Python in
order to extend the system in most cases.
understand any Python to build the existing |ns3| system.
For those interested in the gory details of Waf, the main web site can be
found at http://code.google.com/p/waf/.
@@ -72,7 +70,7 @@ Development Environment
***********************
As mentioned above, scripting in |ns3| is done in C++ or Python.
As of ns-3.2, most of the |ns3| API is available in Python, but the
Most of the |ns3| API is available in Python, but the
models are written in C++ in either case. A working
knowledge of C++ and object-oriented concepts is assumed in this document.
We will take some time to review some of the more advanced concepts or
@@ -98,26 +96,10 @@ neither make nor autotools. We use Waf for these functions.
Typically an |ns3| author will work in Linux or a Linux-like
environment. For those running under Windows, there do exist environments
which simulate the Linux environment to various degrees. The |ns3|
project supports development in the Cygwin environment for
project has in the past (but not presently) supported development in the Cygwin environment for
these users. See http://www.cygwin.com/
for details on downloading (MinGW is presently not officially supported,
although some of the project maintainers to work with it). Cygwin provides
many of the popular Linux system commands. It can, however, sometimes be
problematic due to the way it actually does its emulation, and sometimes
interactions with other Windows software can cause problems.
If you do use Cygwin or MinGW; and use Logitech products, we will save you
quite a bit of heartburn right off the bat and encourage you to take a look
at the `MinGW FAQ
<http://oldwiki.mingw.org/index.php/FAQ>`_.
Search for "Logitech" and read the FAQ entry, "why does make often
crash creating a sh.exe.stackdump file when I try to compile my source code."
Believe it or not, the ``Logitech Process Monitor`` insinuates itself into
every DLL in the system when it is running. It can cause your Cygwin or
MinGW DLLs to die in mysterious ways and often prevents debuggers from
running. Beware of Logitech software when using Cygwin.
for details on downloading, and visit the |ns3| wiki for more information
about Cygwin and |ns3|. MinGW is presently not officially supported.
Another alternative to Cygwin is to install a virtual machine environment
such as VMware server and install a Linux virtual machine.