swapping in all of tutorial would be better
This commit is contained in:
Craig Dowell
49
doc/tutorial/Makefile
Normal file
49
doc/tutorial/Makefile
Normal file
@@ -0,0 +1,49 @@
|
||||
TEXI2HTML = texi2html
|
||||
TEXI2PDF = texi2dvi --pdf
|
||||
EPSTOPDF = epstopdf
|
||||
TGIF = tgif
|
||||
DIA = dia
|
||||
CONVERT = convert
|
||||
CSS = --css-include=tutorial.css
|
||||
SPLIT = --split section
|
||||
|
||||
DIA_SOURCES = pp.dia dumbbell.dia star.dia
|
||||
TGIF_SOURCES = helpers.obj
|
||||
|
||||
DIA_EPS = ${DIA_SOURCES:.dia=.eps}
|
||||
DIA_PNG = ${DIA_SOURCES:.dia=.png}
|
||||
DIA_PDF = ${DIA_SOURCES:.dia=.pdf}
|
||||
|
||||
TGIF_EPS = ${TGIF_SOURCES:.obj=.eps}
|
||||
TGIF_PNG = ${TGIF_SOURCES:.obj=.png}
|
||||
TGIF_PDF = ${TGIF_SOURCES:.obj=.pdf}
|
||||
|
||||
all: html split-html pdf
|
||||
|
||||
# Note: tgif requires a valid x display to convert from .obj to .png.
|
||||
# If running this makefile on a remote console, the X virtual frame
|
||||
# buffer may be needed (xorg-x11-server-Xvfb) to provide a "fake"
|
||||
# display
|
||||
images:
|
||||
cd figures/; $(DIA) -t png $(DIA_SOURCES)
|
||||
cd figures/; $(DIA) -t eps $(DIA_SOURCES)
|
||||
cd figures/; $(foreach FILE,$(DIA_EPS),$(EPSTOPDF) $(FILE);)
|
||||
cd figures/; $(TGIF) -print -png $(TGIF_SOURCES)
|
||||
cd figures/; $(TGIF) -print -eps $(TGIF_SOURCES)
|
||||
cd figures/; $(foreach FILE,$(TGIF_EPS),$(EPSTOPDF) $(FILE);)
|
||||
|
||||
html:
|
||||
$(TEXI2HTML) ${CSS} tutorial.texi
|
||||
|
||||
split-html:
|
||||
$(TEXI2HTML) ${CSS} ${SPLIT} tutorial.texi
|
||||
|
||||
pdf:
|
||||
$(TEXI2PDF) tutorial.texi
|
||||
|
||||
figures-clean:
|
||||
cd figures/; rm -rf $(DIA_EPS); rm -rf $(DIA_PNG); rm -rf $(DIA_PDF)
|
||||
cd figures/; rm -rf $(TGIF_EPS); rm -rf $(TGIF_PNG); rm -rf $(TGIF_PDF)
|
||||
|
||||
clean: figures-clean
|
||||
rm -rf tutorial.aux tutorial.cp tutorial.cps tutorial.fn tutorial.ky tutorial.pg tutorial.tp tutorial.vr tutorial.toc tutorial.log tutorial.pdf tutorial.html tutorial/
|
||||
360
doc/tutorial/introduction.texi
Normal file
360
doc/tutorial/introduction.texi
Normal file
@@ -0,0 +1,360 @@
|
||||
|
||||
@c ========================================================================
|
||||
@c Begin document body here
|
||||
@c ========================================================================
|
||||
|
||||
@c ========================================================================
|
||||
@c PART: Introduction
|
||||
@c ========================================================================
|
||||
@c The below chapters are under the major heading "Introduction"
|
||||
@c This is similar to the Latex \part command
|
||||
@c
|
||||
@c ========================================================================
|
||||
@c Introduction
|
||||
@c ========================================================================
|
||||
@node Introduction
|
||||
@chapter Introduction
|
||||
|
||||
@menu
|
||||
* For ns-2 Users::
|
||||
* Contributing::
|
||||
* Tutorial Organization::
|
||||
@end menu
|
||||
|
||||
The ns-3 simulator is a discrete-event network simulator targeted primarily
|
||||
for research and educational use. The
|
||||
@uref{http://www.nsnam.org,,ns-3 project},
|
||||
started in 2006, is an open-source project. The goal of the project is to
|
||||
build a new network simulator primarily for research and educational use.
|
||||
|
||||
Primary documentation for the ns-3 project is available in three forms:
|
||||
@itemize @bullet
|
||||
@item @uref{http://www.nsnam.org/doxygen/index.html,,ns-3 Doxygen/Manual}:
|
||||
Documentation of the public APIs of the simulator
|
||||
@item Tutorial (this document)
|
||||
@item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki}
|
||||
@end itemize
|
||||
|
||||
The purpose of this tutorial is to introduce new ns-3 users to the
|
||||
system in a structured way. It is sometimes difficult for new users to
|
||||
glean essential information from detailed manuals and to convert this
|
||||
information into working simulations. In this tutorial, we will build
|
||||
several example simulations, introducing and explaining key concepts and
|
||||
features as we go.
|
||||
|
||||
As the tutorial unfolds, we will introduce the full ns-3 documentation
|
||||
and provide pointers to source code for those interested in delving deeper
|
||||
into the workings of the system.
|
||||
|
||||
A few key points are worth noting at the onset:
|
||||
@itemize @bullet
|
||||
@item ns-3 is not an extension of @uref{http://www.isi.edu/nsnam/ns,,ns-2};
|
||||
it is a new simulator. The two simulators are both written in C++ but ns-3
|
||||
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 ns-3. The project will continue to
|
||||
maintain ns-2 while ns-3 is being built, and will study transition and
|
||||
integration mechanisms.
|
||||
@item ns-3 is open-source, and the project strives to maintain an open
|
||||
environment for researchers to contribute and share their software.
|
||||
@end itemize
|
||||
|
||||
@node For ns-2 Users
|
||||
@section For ns-2 Users
|
||||
|
||||
For those familiar with ns-2, the most visible outward change when moving to
|
||||
ns-3 is the choice of scripting language. ns-2 is typically scripted in Tcl
|
||||
and results of simulations can be visualized using the Network Animator
|
||||
@command{nam}. In ns-3 there is currently no visualization module, and Python
|
||||
bindings have been developed (Tcl bindings have been prototyped
|
||||
using @uref{http://www.swig.org,,SWIG}, but are not supported by the
|
||||
current development team). In this tutorial, we will 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 ns-3). We will try to highlight differences between ns-2 and ns-3
|
||||
as we proceed in this tutorial.
|
||||
|
||||
@node Contributing
|
||||
@section Contributing
|
||||
|
||||
@cindex contributing
|
||||
ns-3 is a research and educational simulator, by and for the 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 ns-3
|
||||
like they have for ns-2:
|
||||
@itemize @bullet
|
||||
@item open source licensing based on GNU GPLv2 compatibility
|
||||
@item @uref{http://www.nsnam.org/wiki/index.php,,wiki}
|
||||
@item @uref{http://www.nsnam.org/wiki/index.php/Contributed_Code,,Contributed Code} page, similar to ns-2's popular
|
||||
@uref{http://nsnam.isi.edu/nsnam/index.php/Contributed_Code,,Contributed Code}
|
||||
page
|
||||
@item @code{src/contrib} directory (we will host your contributed code)
|
||||
@item open @uref{http://www.nsnam.org/bugzilla,,bug tracker}
|
||||
@item ns-3 developers will gladly help potential contributors to get
|
||||
started with the simulator (please contact @uref{http://www.nsnam.org/people.html,,one of us})
|
||||
@end itemize
|
||||
|
||||
If you are an ns user, please consider providing your feedback, bug fixes, or
|
||||
code to the project.
|
||||
|
||||
@node Tutorial Organization
|
||||
@section Tutorial Organization
|
||||
|
||||
The tutorial assumes that new users might initially follow a path such as the
|
||||
following:
|
||||
|
||||
@itemize @bullet
|
||||
@item Browse the source code and documentation, to get a feel for
|
||||
the simulator and what it might be like to use;
|
||||
@item Try to download and build a copy;
|
||||
@item Try to run a few sample programs, and perhaps change some configurations;
|
||||
@item Look at simulation output, and try to adjust it
|
||||
@end itemize
|
||||
|
||||
As a result, we have tried to organize the tutorial along the above
|
||||
broad sequences of events.
|
||||
|
||||
@c ========================================================================
|
||||
@c Browsing ns-3
|
||||
@c ========================================================================
|
||||
|
||||
@node Browsing ns-3
|
||||
@chapter Browsing ns-3
|
||||
|
||||
@menu
|
||||
* Source Code::
|
||||
* Doxygen::
|
||||
* Other Documentation::
|
||||
@end menu
|
||||
|
||||
@node Source Code
|
||||
@section Source Code
|
||||
|
||||
The most recent code can be browsed on our web server at the following link:
|
||||
@uref{http://code.nsnam.org/?sort=lastchange}. If you click on the bold
|
||||
repository names on the left of the page, you will see @emph{changelogs} for
|
||||
these repositories, and links to the @emph{manifest}. From the manifest
|
||||
links, one can browse the source tree.
|
||||
|
||||
The top-level directory will look something like:
|
||||
@verbatim
|
||||
drwxr-xr-x [up]
|
||||
drwxr-xr-x doc manifest
|
||||
drwxr-xr-x examples manifest
|
||||
drwxr-xr-x ns3 manifest
|
||||
drwxr-xr-x regression manifest
|
||||
drwxr-xr-x samples manifest
|
||||
drwxr-xr-x scratch manifest
|
||||
drwxr-xr-x src manifest
|
||||
drwxr-xr-x tutorial manifest
|
||||
drwxr-xr-x utils manifest
|
||||
-rw-r--r-- 135 .hgignore file | revisions | annotate
|
||||
-rw-r--r-- 891 .hgtags file | revisions | annotate
|
||||
-rw-r--r-- 441 AUTHORS file | revisions | annotate
|
||||
-rw-r--r-- 17987 LICENSE file | revisions | annotate
|
||||
-rw-r--r-- 4948 README file | revisions | annotate
|
||||
-rw-r--r-- 4917 RELEASE_NOTES file | revisions | annotate
|
||||
-rw-r--r-- 7 VERSION file | revisions | annotate
|
||||
-rwxr-xr-x 99143 waf file | revisions | annotate
|
||||
-rwxr-xr-x 28 waf.bat file | revisions | annotate
|
||||
-rw-r--r-- 30584 wscript file | revisions | annotate
|
||||
@end verbatim
|
||||
|
||||
The source code is mainly in the @code{src} directory. You can view source
|
||||
code by clicking on the @code{manifest} link to the right of the directory
|
||||
name. If you click on the @code{manifest} link to the right of the src
|
||||
directory you will find a subdirectory. If you click on the @code{manifest}
|
||||
link next to the @code{core} subdirectory in under @code{src}, you will find
|
||||
a list of files. The first file you will find is @code{assert.h}. If you
|
||||
click on the @code{file} link, you will be sent to the source file for
|
||||
@code{assert.h}.
|
||||
|
||||
Example scripts are in the @code{examples} directory. The @code{examples}
|
||||
directory is a good place to start browsing the code.
|
||||
|
||||
For ns-2 users, who may be familiar with the @code{simple.tcl} example script
|
||||
in the ns-2 documentation, an analogous script is found in
|
||||
@code{examples/simple-point-to-point.cc} with a Python equivalent found
|
||||
in @emph{(pending Python merge)}.
|
||||
|
||||
@node Doxygen
|
||||
@section Doxygen
|
||||
|
||||
We document all of our APIs using @uref{http://www.stack.nl/~dimitri/doxygen/,,Doxygen}. Current builds of this documentation are available at:
|
||||
@uref{http://www.nsnam.org/doxygen/index.html}, which are worth an initial
|
||||
look.
|
||||
|
||||
@node Other Documentation
|
||||
@section Other Documentation
|
||||
|
||||
We provide a large amount of documentation regarding the various components
|
||||
of ns-2 on our website. See: @uref{http://www.nsnam.org/documents.html}.
|
||||
|
||||
@c ========================================================================
|
||||
@c Resources
|
||||
@c ========================================================================
|
||||
|
||||
@node Resources
|
||||
@chapter Resources
|
||||
|
||||
@menu
|
||||
* The Web::
|
||||
* Mercurial::
|
||||
* Waf::
|
||||
* Environment Idioms Design Patterns::
|
||||
* Socket Programming::
|
||||
@end menu
|
||||
|
||||
@node The Web
|
||||
@section The Web
|
||||
|
||||
@cindex www.nsnam.org
|
||||
There are several important resources of which any ns-3 user must be
|
||||
aware. The main web site is located at @uref{http://www.nsnam.org}
|
||||
and provides access to basic information about the ns-3 system.
|
||||
Detailed documentation is available through the main web site at
|
||||
@uref{http://www.nsnam.org/documents.html}.
|
||||
|
||||
@cindex documentation
|
||||
@cindex architecture
|
||||
You can find documents relating to the system architecture from this page,
|
||||
and also gain access to the detailed software documentation. The software
|
||||
system is documented in great detail using
|
||||
@uref{http://www.stack.nl/~dimitri/doxygen/,,Doxygen}. There is a Wiki that
|
||||
complements the main ns-3 web site which you will find at
|
||||
@uref{http://www.nsnam.org/wiki/}.
|
||||
|
||||
You will find user and developer FAQs there as well as troubleshooting guides,
|
||||
third-party contributed code, papers, etc. The source code may be found
|
||||
and browsed at @uref{http://code.nsnam.org/}.
|
||||
|
||||
@cindex repository!ns-3-dev
|
||||
@cindex repository!releases
|
||||
There you will find the current development tree in the repository named
|
||||
@code{ns-3-dev}. Past releases and experimental repositories of the core
|
||||
developers may also be found there.
|
||||
|
||||
@node Mercurial
|
||||
@section Mercurial
|
||||
|
||||
Complex software systems need some way to manage the organization and
|
||||
changes to the underlying code and documentation. There are many ways to
|
||||
perform this feat, and you may have heard of some of the systems that are
|
||||
currently used to do this. The Concurrent Version System (CVS) is probably
|
||||
the most well known.
|
||||
|
||||
@cindex software configuration management
|
||||
@cindex Mercurial
|
||||
The ns-3 project uses Mercurial as its source code management system.
|
||||
Although you do not need to know much about Mercurial in order to complete
|
||||
this tutorial, we recommend becoming familiar with Mercurial and using it
|
||||
to access the source code. Mercurial has a web site at
|
||||
@uref{http://www.selenic.com/mercurial/},
|
||||
from which you can get binary or source releases of this Software
|
||||
Configuration Management (SCM) system. Selenic (the developer of Mercurial)
|
||||
also provides a tutorial at
|
||||
@uref{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial/},
|
||||
and a QuickStart guide at
|
||||
@uref{http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart/}.
|
||||
|
||||
You can also find vital information about using Mercurial and ns-3
|
||||
on the main ns-3 web site.
|
||||
|
||||
@node Waf
|
||||
@section Waf
|
||||
|
||||
@cindex Waf
|
||||
@cindex make
|
||||
@cindex build
|
||||
Once you have source code downloaded to your local system, you will need
|
||||
to compile that source to produce usable programs. Just as in the case of
|
||||
source code management, there are many tools available to perform this
|
||||
function. Probably the most will known of these tools is @code{make}. Along
|
||||
with being the most well known, @code{make} is probably the most difficult to
|
||||
use in a very large and highly configurable system. Because of this, many
|
||||
alternatives have been developed. Recently these systems have been developed
|
||||
using the Python language.
|
||||
|
||||
The build system @code{Waf} is used on the ns-3 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 ns-3 system, and will
|
||||
only have to understand a tiny and intuitively obvious subset of Python in
|
||||
order to extend the system in most cases.
|
||||
|
||||
For those interested in the gory details of Waf, the main web site can be
|
||||
found at @uref{http://freehackers.org/\~tnagy/waf.html}.
|
||||
|
||||
@node Environment Idioms Design Patterns
|
||||
@section Environment, Idioms, and Design Patterns
|
||||
|
||||
@cindex C++
|
||||
As mentioned above, scripting in ns-3 is done in C++. 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
|
||||
possibly unfamiliar language features, idioms and design patterns as they
|
||||
appear. We don't want this tutorial to devolve into a C++ tutorial, though,
|
||||
so we do expect a basic command of the language. There are an almost
|
||||
unimaginable number of sources of information on C++ available on the web or
|
||||
in print.
|
||||
|
||||
If you are new to C++, you may want to find a tutorial- or cookbook-based
|
||||
book or web site and work through at least the basic features of the language
|
||||
before proceeding.
|
||||
|
||||
@subsection Environment
|
||||
|
||||
@cindex toolchain
|
||||
@cindex GNU
|
||||
The ns-3 system uses the GNU ``toolchain'' for development.
|
||||
A software toolchain is the set of programming tools available in the given
|
||||
environment. For a quick review of what is included in the GNU toolchain see,
|
||||
@uref{http://en.wikipedia.org/wiki/GNU_toolchain}.
|
||||
|
||||
@cindex Linux
|
||||
Typically an ns-3 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 ns-3
|
||||
project supports development in the Cygwin and the MinGW environments for
|
||||
these users. See @uref{http://www.cygwin.com/} and
|
||||
@uref{http://www.mingw.org/} for details on downloading and using these
|
||||
systems. 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.
|
||||
|
||||
@cindex Cygwin
|
||||
@cindex MinGW
|
||||
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 @uref{http://www.mingw.org/MinGWiki/index.php/FAQ,,MinGW FAQ}.
|
||||
|
||||
@cindex Logitech
|
||||
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 @code{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.
|
||||
|
||||
@node Socket Programming
|
||||
@section Socket Programming
|
||||
|
||||
@cindex sockets
|
||||
We will assume a basic facility with the Berkeley Sockets API in the examples
|
||||
used in this tutorial. If you are new to sockets, we recommend reviewing the
|
||||
API and some common usage cases. For a good overview of programming TCP/IP
|
||||
sockets we recommend @uref{http://www.elsevier.com/wps/product/cws_home/680765,,Practical TCP/IP Sockets in C, Donahoo and Calvert}.
|
||||
|
||||
There is an associated web site that includes source for the examples in the
|
||||
book, which you can find at:
|
||||
@uref{http://cs.baylor.edu/~donahoo/practical/CSockets/}.
|
||||
|
||||
If you understand the first four chapters of the book (or for those who do
|
||||
not have access to a copy of the book, the echo clients and servers shown in
|
||||
the website above) you will be in good shape to understand the tutorial.
|
||||
There is a similar book on Multicast Sockets,
|
||||
@uref{http://www.elsevier.com/wps/product/cws_home/700736,,Multicast Sockets, Makofske and Almeroth}.
|
||||
that covers material you may need to understand for the multicast examples.
|
||||
|
||||
Reference in New Issue
Block a user