.. include:: replace.txt

Resources

---------

The Web

*******

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 

relating to the system architecture from this page.

There is a Wiki that complements the main |ns3| web site which you will

find at 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 http://code.nsnam.org/. 

There you will find the current development tree in the repository named

``ns-3-dev``. Past releases and experimental repositories of the core

developers may also be found there.

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.

The |ns3| 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 

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 

http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial/,

and a QuickStart guide at

http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart/.

You can also find vital information about using Mercurial and |ns3|

on the main |ns3| web site.

Waf

***

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 ``make``.  Along

with being the most well known, ``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 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.

For those interested in the gory details of Waf, the main web site can be 

found at http://code.google.com/p/waf/.

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 

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, `this tutorial

<http://www.cplusplus.com/doc/tutorial/>`_.

The |ns3| 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,

http://en.wikipedia.org/wiki/GNU_toolchain.  |ns3| 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.

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 

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.

Another alternative to Cygwin is to install a virtual machine environment

such as VMware server and install a Linux virtual machine.

Socket Programming

******************

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 `TCP/IP Sockets in C, Donahoo and Calvert

<http://www.elsevier.com/wps/find/bookdescription.cws_home/717656/description#description>`_.

There is an associated web site that includes source for the examples in the

book, which you can find at:

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,

`Multicast Sockets, Makofske and Almeroth

<http://www.elsevier.com/wps/find/bookdescription.cws_home/700736/description#description>`_.

that covers material you may need to understand if you look at the multicast 

examples in the distribution.