--- a/doc/tutorial/introduction.texi Sun Jan 02 22:57:04 2011 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,310 +0,0 @@
-
-@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 @command{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 developing @command{ns-3}.
-
-Primary documentation for the @command{ns-3} project is available in four
-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/docs/manual.html,,Reference Manual}: Reference Manual
-@item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki}
-@end itemize
-
-The purpose of this tutorial is to introduce new @command{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 @command{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
-@command{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 @command{ns-3}. The
-project will continue to maintain ns-2 while @command{ns-3} is being built,
-and will study transition and integration mechanisms.
-@item @command{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
-@command{ns-3} is the choice of scripting language. Ns-2 is
-scripted in OTcl and results of simulations can be visualized using the
-Network Animator @command{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 @command{ns-3}, 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
-@command{nam}, but new animators are under development. Since @command{ns-3}
-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 @command{ns-3}).
-We will try to highlight differences between ns-2 and @command{ns-3}
-as we proceed in this tutorial.
-
-A question that we often hear is "Should I still use ns-2 or move to
-@command{ns-3}?" The answer is that it depends. @command{ns-3} does not have
-all of the models that ns-2 currently has, but on the other hand, @command{ns-3}
-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 @command{ns-3} (a porting guide is under
-development). There is active development on multiple fronts for
-@command{ns-3}. The @command{ns-3} developers believe (and certain early users
-have proven) that @command{ns-3} is ready for active use, and should be an
-attractive alternative for users looking to start new simulation projects.
-
-@node Contributing
-@section Contributing
-
-@cindex contributing
-@command{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 @command{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 @command{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
-
-We realize that if you are reading this document, contributing back to
-the project is probably not your foremost concern at this point, but
-we want you to be aware that contributing is in the spirit of the project and
-that even the act of dropping us a note about your early experience
-with @command{ns-3} (e.g. "this tutorial section was not clear..."),
-reports of stale documentation, etc. are much appreciated.
-
-@node Tutorial Organization
-@section Tutorial Organization
-
-The tutorial assumes that new users might initially follow a path such as the
-following:
-
-@itemize @bullet
-@item Try to download and build a copy;
-@item Try to run a few sample programs;
-@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 Resources
-@c ========================================================================
-
-@node Resources
-@chapter Resources
-
-@menu
-* The Web::
-* Mercurial::
-* Waf::
-* Development Environment::
-* Socket Programming::
-@end menu
-
-@node The Web
-@section The Web
-
-@cindex www.nsnam.org
-@cindex documentation
-@cindex architecture
-There are several important resources of which any @command{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 @command{ns-3} system. Detailed
-documentation is available through the main web site at
-@uref{http://www.nsnam.org/documents.html}. You can also find documents
-relating to the system architecture from this page.
-
-There is a Wiki that complements the main @command{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.
-
-@cindex mercurial repository
-@cindex ns-3-dev repository
-@cindex release repository
-The source code may be found and browsed at @uref{http://code.nsnam.org/}.
-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 @command{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 @command{ns-3}
-on the main @command{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 well 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 @command{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 @command{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://code.google.com/p/waf/}.
-
-@node Development Environment
-@section Development Environment
-
-@cindex C++
-@cindex Python
-As mentioned above, scripting in @command{ns-3} is done in C++ or Python.
-As of ns-3.2, most of the @command{ns-3} 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
-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. For instance,
-@uref{http://www.cplusplus.com/doc/tutorial/,,this tutorial}.
-
-@cindex toolchain
-@cindex GNU
-The @command{ns-3} system uses several components of 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}. @command{ns-3} uses gcc,
-GNU binutils, and gdb. However, we do not use the GNU build system tools,
-neither make nor autotools. We use Waf for these functions.
-
-@cindex Linux
-Typically an @command{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 @command{ns-3}
-project supports development in the Cygwin environment for
-these users. See @uref{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.
-
-@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://oldwiki.mingw.org/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 software when using Cygwin.
-
-Another alternative to Cygwin is to install a virtual machine environment
-such as VMware server and install a Linux virtual machine.
-
-@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/find/bookdescription.cws_home/717656/description#description,,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/find/bookdescription.cws_home/700736/description#description,,Multicast Sockets, Makofske and Almeroth}.
-that covers material you may need to understand if you look at the multicast
-examples in the distribution.