Nsnam - User contributions [en]

Ns-3.19-errata

2014-03-31T08:51:43Z

Hippo: bug 1170

{{TOC}}

This page is an [[Errata]] page for the ns-3.19 release.

* After the release, it was discovered (reported in [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1823 bug 1823]) that IPv6 fails to work properly over point-to-point NetDevice types. This [http://code.nsnam.org/ns-3-dev/rev/b8c9ece3ae63 patch], which will be included in future releases, can fix the problem.
* After the release, it was discovered (reported in [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1170#c56 bug 1170]) that optimized build fails on clang-3.4 (Xcode 5.1) due to unused function warnings. This [http://code.nsnam.org/ns-3-dev/rev/1330d4ee94e8 patch], which will be included in future releases, can fix the problem.

Sprints

2013-11-11T10:31:33Z

Hippo: s/Djanjo/Django/g

{{TOC}}

= What is a sprint? =

A sprint is a scheduled time for ns-3 contributors to gather and focus their undivided attention on improving the code, documentation, or tests.

Sprints are open to anyone, and are conducted on IRC, and if needed, other virtual meeting technologies.
* IRC channel is '''#ns-3''' at irc.freenode.net

The [https://code.djangoproject.com/wiki/Sprints Django project] has a good reference and links to some presentations all about coding sprints.

A summary of the results of sprints will be shared with other developers on the ns-developers mailing list.

= Upcoming sprints =

* Friday November 15, 14h00-20h00 UTC ('''note:''' attendees are welcome to attend a subset of the 6-hour slot, if so desired)
** '''Topic:''' Documentation improvement. https://www.nsnam.org/bugzilla/show_bug.cgi?id=938. In particular, we will work on reducing the number of doxygen warnings that are generated due to missing Doxygen. This is a long-standing issue that just requires group effort to resolve.
** '''Organizer:''' [mailto:tomhend@u.washington.edu Tom Henderson]
** '''Preparation:'''
**# Read the general preparation below
**# Make sure you have Doxygen installed on your system, and can run the shell script 'doc/doxygen.warnings.report.sh' (it may take a while to run, and should generate a lot of warnings)
**# Contact ns-3-users mailing list or the organizer for help if you have trouble with the above
** '''Tasks:''' Fix as many of the doxygen warnings as we can. The current count of warnings (by module) can be seen here: http://mailman.isi.edu/pipermail/ns-commits/2013-November/014304.html. There is a full log generated that can be used to identify what is the error, and then it can be fixed with a text editor. How this is planned to work is that contributors who show up will be assigned a file or set of files (that they are comfortable with documenting) and will try to clear the errors in that file, producing a patch that can be merged to ns-3-dev.
** '''Coordination:''' We will use IRC and [http://etherpad.org Etherpad] to coordinate the work (make sure multiple people do not work on the same file).

== General preparation ==

* Make sure that you can join the IRC channel in advance
* Make sure you can checkout the development version of ns-3 (we will use ns-3-dev)
* Familiarize yourself with how to [http://www.nsnam.org/developers/contributing-code/submit/ generate a patch] against ns-3-dev. Patches you write can be uploaded to Bugzilla or sent to one of the maintainers.

== Once you're there ==

* Check in by letting others know that you've joined and are ready to contribute, and a maintainer will go from there

DevelMeetingOct2011

2011-10-10T10:49:42Z

Hippo: /* Participants */

{{TOC}}

= Location and Schedule =

Virtual, Thursday October 27 (19h00-21h00 UTC). For North American participants, this is 3pm-5pm EDT.

= Participants =

(please add your name/email here if you plan to attend)

* Tom Henderson
* Mitch Watrous
* George Riley
* John Abraham
* Felipe Perrone
* Vedran Miletic
* Mathieu Lacage
* Lalith Suresh
* Andrey Mazo

= Agenda =

This is our first try at a virtual meeting. We will aim to hold discussion to two hours only. If we have more topics or more discussion needed, we can schedule another one.

Please list suggested topics below:

* next steps in modular build system

= Logistics =

We will use an audio bridge and desktop sharing solution such as Webex, Adobe Connect, or Cisco MeetingPlace. Details will be provided when they are sorted out.

= Suggested agenda/topics =

Topology Generator

2010-11-16T15:10:29Z

Hippo: /* Installation */

{{TOC}}

The ns-3 topology generator project aims to provide a quick and easy way to create ns-3 topology.
It provides intuitive GUI so you can add nodes, link, applications, ... and generates C++ simulation
code for ns-3.

This tool has been written by Pierre Weiss and Sebastien Vincent, University of Strasbourg.

== Prerequisites ==

You need Qt 4 libraries to compile and use ns-3 topology generator.

== Installation ==

To download the project:
$ hg clone http://svnet.u-strasbg.fr/hg/ns-3-generator

To build the project:
$ qmake
$ make

== Usage ==

To use it, simply run:
$ ./ns-3-generator

To generate the API documentation (you need doxygen tool):
$ doxygen Doxyfile

The HTML generated documentation is located in doc/html/ directory of sources.

Configurations may be saved to an XML file and later loaded.

== Example screenshot ==

[[File:Ns-3-generator-test.png]]

[[File:Ns-3-generator-test.cc.patch]]: C++ code generated from the above screenshot. Python code can also be generated. The configuration can be saved in XML and reloaded. '''Note:''' two applications were added and can be sen in the generated code (not visible in the screenshot).

== Feature requests ==

* Ability to configure tracing
* (others go here)

Direct Code Execution portability

2010-08-26T17:36:17Z

Hippo: Initial template

This page is intended to track [http://code.nsnam.org/mathieu/ns-3-simu ns-3-simu] portability issues.

Currently it's very sensitive to libc version used.

{| border=1
|-
! Distribution
! Architecture
! glibc
! Last checked revision
! ./test.py -s process-manager
! Workarounds
|-
| Fedora 12
| x86-64
| 2.11.1
| ???
| PASS
|-
| Fedora 13
| x86-64
| 2.12.?
| ???
| FAIL
|-
| Ubuntu 10.04
| x86-64
| ???
| ???
| FAIL
|-
| Ubuntu 9.10
| x86
| ???
| ???
| FAIL
|-
| Gentoo (as of 2010-08-26)
| x86
| 2.11.2
| ???
| FAIL
|}

Installation

2010-06-08T16:55:49Z

Hippo: uncrustify dependency

{{TOC}}

This is a detailed installation guide for ns-3. Basic installation instructions can be found at the [http://www.nsnam.org/getting_started.html Getting Started] page or in the [http://www.nsnam.org/docs/release/tutorial/tutorial.html ns-3 tutorial].

== Supported platforms ==

ns-3 is primarily developed on GNU/Linux platforms, and the minimal requirements to run basic simulations are a gcc installation of gcc-3.4/g++-3.4 or greater, and python 2.4 or greater.

ns-3 is supported on the following primary platforms:

# Linux x86 gcc 4.2, 4.1, and, 3.4.6.
# Linux x86_64 gcc 4.4.0, 4.3.2, 4.2.3, 4.2.1, 4.1.3, 3.4.6
# MacOS X ppc and x86 (gcc 4.0.x and 4.2.x)
# [http://www.cygwin.com Cygwin] gcc 3.4.4 (debug only), gcc 4.3.2 (debug and optimized)

By supported, we mean that the project tries to support most or all of the build options on these platforms unless there is a good reason to exclude the option; and at least the debug build will compile. If you intend to do serious work using ns-3, and are forced by circumstances to use a Windows platform, consider virtualization of a popular Linux platform. This may be more time-consuming than installing a minimal Cygwin, for example, but you end up with a fully functional Linux system and ns-3 distribution. Some quick performance comparisons between Cygwin and VirtualBoxed Fedora 11 indicate that examples can actually run faster under VirtualBox.

We provide HOWTO documents describing the process for installing Linux support and getting ns-3 running using two popular virtualization products: VirtualBox ([[HOWTO use VirtualBox to run simulations on Windows machines]]) and VMware ([[HOWTO use VMware to set up virtual networks (Windows)]]).

ns-3 may also run on currently unsupported platforms. For example, an alternative Windows platform is MinGW. There are maintainers who attempt to keep a subset of ns-3 running on MinGW, but it is not "officially" suppported. This means that bugs filed against MinGW will be addressed as time permits. Additionally, the Eclipse IDE is used by some developers, but the project does not actively support this environment.

Additional maintainers are invited to make more platforms, compilers and environments supported.

=== ns-3 options ===

There are a few options that are not enabled by default and are not available on all platforms. At the end of the configuration process (explained below), the status of these options are shown as detected by a '''waf''' script:

<pre>
---- Summary of optional NS-3 features:
Threading Primitives : enabled
Real Time Simulator : enabled
Emulated Net Device : enabled
Tap Bridge : enabled
GtkConfigStore : enabled
XmlIo : not enabled (library 'libxml-2.0 >= 2.7' not found)
SQlite stats data output : enabled
Network Simulation Cradle : enabled
Python Bindings : not enabled (disabled by user request)
Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
Static build : not enabled (option --enable-static not selected)
</pre>

Generally if the platform is missing some requirement for an option it is marked as "not enabled." Note that "disabled by user request" will be shown when the user explicitly disables a feature (such as "--disable-python"); and if a feature defaults to disabled this will also be noted (e.g., option --enable-sudo not selected).

The table below is meant to help sort out the different features and on which platforms they are supported. This table reflects the status of the most recent release version (ns-3.6):

{| border=1 cellspacing=0 cellpadding=3

|+ Option status
! Option !! Linux gcc-4.x,gcc-3.4.x !! OS X !! Cygwin
|-
! Optimized build
| || || X 1
|-
! Python bindings
| || || X 2
|-
! Threading
| || ||
|-
! Real-time simulator
| || X || X
|-
! Emulated Net Device
| || X || X
|-
! Tap Bridge
| || X || X
|-
! Network simulation cradle
| note3 || X || X
|-
! Static builds
| || ||

|}

''Key:'' '''( )'''(empty space) = supported; '''X''' = not supported; '''?''' = unknown; '''dev''' = support in ns-3-dev (next release)

''Notes:''
# Works with gcc4
# Cygwin limitation explained [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings#Cygwin_limitation here]
# NSC works best with gcc-3.4 or gcc-4.2 or greater series. Try to avoid gcc-4.0 and gcc-4.1 series; some build problems have been found with these versions of compilers.

== Prerequisites ==

The core of ns-3 requires a gcc/g++ installation of 3.4 or greater, and python 2.4 or greater. As mentioned above, different options require additional support. This is a list of packages (for Debian/Ubuntu systems) that are needed to support different ns-3 options. Note that other distributions (e.g., Fedora, FreeBSD) may have different package names or capitalization (e.g. ImageMagik). Installation should be similar for Red Hat/Fedora based systems, with "yum" replacing "apt-get", but some differences exist, so below is a guide for both Ubuntu (should generally apply to Debian) and Fedora/RedHat-based systems:

=== Ubuntu/Debian ===

The following list of packages should be accurate for Ubuntu 9.10 release; other releases or other Debian-based systems may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

sudo apt-get install gcc g++ python

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

sudo apt-get install gcc g++ python python-dev

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

sudo apt-get install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

sudo apt-get install bzr

* A GTK-based configuration system

sudo apt-get install libgtk2.0-0 libgtk2.0-dev

* Debugging:

sudo apt-get install gdb valgrind

* Doxygen and related inline documentation:

sudo apt-get install doxygen graphviz imagemagick
sudo apt-get install texlive texlive-pdf texlive-latex-extra texlive-generic-extra texlive-generic-recommended

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

sudo apt-get install texinfo dia texlive texlive-pdf texlive-latex-extra texlive-extra-utils texlive-generic-recommended texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

sudo apt-get install flex bison

* Some basic mobility visualization tests require goocanvas:

sudo apt-get install libgoocanvas-dev

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

sudo apt-get install g++-3.4 gcc-3.4

* To read pcap packet traces

sudo apt-get install tcpdump

* Database support for statistics framework

sudo apt-get install sqlite sqlite3 libsqlite3-dev

* Xml-based version of the config store (requires libxml2 >= version 2.7)

sudo apt-get install libxml2 libxml2-dev

* Support for Gustavo's ns-3-pyviz visualizer

sudo apt-get install python-pygraphviz python-kiwi python-pygoocanvas

* Support for utils/check-style.py style check program

sudo apt-get install uncrustify

=== Fedora/RedHat ===

The following list of packages should be accurate for Fedora 12/CentOS 5.4 release; other releases may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

yum install gcc gcc-c++ python

* '''Note:''' If you are using CentOS 5.4 or RHEL 5, you may want to also get and use the gcc44 packages; see the [[Troubleshooting]] page.

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

yum install gcc gcc-c++ python python-devel

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories. You may want to install mercurial from rpmforge repository (instructions [http://www.trinitycore.org/forum/mercurial-centos-t3113.html here]) or EPEL.

yum install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar. You may need EPEL repository for this.

yum install bzr

* An optional but recommended package (for improving some wireless model fidelity) is GNU scientific library:

yum install gsl gsl-devel

* A GTK-based configuration system

yum install gtk2 gtk2-devel

* Debugging:

yum install gdb valgrind

* Doxygen and related inline documentation:

yum install doxygen graphviz ImageMagick
yum install texinfo texinfo-tex

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

yum install texinfo dia texinfo-tex texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

yum install flex bison

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

yum install compat-gcc-34

* To read pcap packet traces

yum install tcpdump

* Database support for statistics framework

yum install sqlite sqlite-devel

* Xml-based version of the config store (requires libxml2 >= version 2.7)

yum install libxml2 libxml2-devel

* Support for utils/check-style.py style check program

yum install uncrustify

=== Gentoo ===

The following list of packages should be accurate for Gentoo as of 04/22/2010; due to possible changes in USE-flags or package names the list may slightly vary.
First of all, become root as usual.

* '''minimal requirements for C++ or Python (release):''' This is the minimal set of packages needed to run ns-3 or to work with Python bindings from a released tarball.

USE="threads -nocxx nptl" emerge -uavN gcc python

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

emerge -av --noreplace mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

USE="curl" emerge -uavN bzr

* A GTK-based configuration system

emerge -av --noreplace gtk+:2

* Debugging:

emerge -av --noreplace gdb valgrind

* Doxygen and related inline documentation; also ns-3 manual and tutorial (written in Texinfo):

USE="extra graphics png" emerge -uavN texlive
USE="cairo graphviz latex png svg" emerge -uavN doxygen imagemagick dia

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

emerge -av --noreplace flex bison

* Some basic mobility visualization tests require goocanvas:

emerge -av --noreplace goocanvas

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

USE="-nocxx nptl" emerge -uavN gcc:3.4

* To read pcap packet traces

emerge -av --noreplace tcpdump

or you may prefer

emerge -av --noreplace wireshark

* Database support for statistics framework

USE="threadsafe" emerge -uavN sqlite:3

* Xml-based version of the config store (requires libxml2 >= version 2.7)

emerge -av --noreplace libxml2

* Support for Gustavo's ns-3-pyviz visualizer (following packages have no stable version as of day of writing, so ~arch for ACCEPT_KEYWORDS)

ACCEPT_KEYWORDS="~x86" emerge -av --noreplace pygraphviz kiwi pygoocanvas

* Support for utils/check-style.py style check program

ACCEPT_KEYWORDS="~x86" emerge -av --noreplace uncrustify

* To summarize all of above up (without not yet stable pygraphviz, kiwi, pygoocanvas, uncrustify):
USE="cairo curl extra graphics graphviz latex -nocxx nptl png svg threads threadsafe" emerge -uavN bison bzr dia doxygen flex gcc gcc:3.4 goocanvas gtk+:2 imagemagick libxml2 mercurial python sqlite:3 tcpdump texlive valgrind wireshark

=== Mac OS X (Snow Leopard) ===

Please see [[HOWTO_get_ns-3_running_on_Mac_OS_X_(10.6.2_Intel)]] and follow steps 1 and 2 (prerequisites) and continue reading below if you want to work with a released version, and follow all steps if you want to work with a development version of ns-3.

== Installation ==

The ns-3 code is available in Mercurial repositories on the server http://code.nsnam.org (look for the latest release e.g., "ns-3.4"). You can download a tarball of the latest release at http://www.nsnam.org/releases or you can work with our repositories using Mercurial. We recommend using Mercurial unless there's a good reason not to (See the end of this section for instructions on how to get a tarball release).

The simplest way to get started using Mercurial repositories is to use the '''ns-3-allinone''' environment. This is a set of scripts that manages the downloading and building of various subystems of ns-3 for you. We recommend that you begin your ns-3 adventures in this environment as it can really simplify your life at this point.

=== Downloading ns-3 Using Mercurial ===
One practice is to create a directory called '''repos''' in one's home directory under which one can keep local Mercurial repositories. If you adopt 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
hg clone http://code.nsnam.org/ns-3-allinone

As the hg (Mercurial) command executes, you should see something like the following displayed,

destination directory: ns-3-allinone
requesting all changes
adding changesets
adding manifests
adding file changes
added 26 changesets with 40 changes to 7 files
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 look something like the following:

build.py* constants.py dist.py* download.py* README util.py

Notice that you really just downloaded some Python scripts. The next step will be to use those scripts to download and build the ns-3 distribution of your choice.

If you go to the following link: http://code.nsnam.org/ you will see a number of repositories. Many are the private repositories of the ns-3 development team. The repositories of interest to you will be prefixed with '''ns-3'''. Official releases of ns-3 will be numbered as ns-3.release.hotfix. For example, a second hotfix to a still hypothetical release nine of ns-3 would be numbered as ns-3.9.2 on this page.

We have had a regression testing framework in place since the first release. For each release, a set of output files that define ''good behavior'' are saved. These known good output files are called reference traces and are associated with a given release by name. For example, in http://code.nsnam.org/ you will find a repository named ns-3.1 which is the first stable release of ns-3. You will also find a separate repository named ns-3.1-ref-traces that holds the reference traces for the ns-3.1 release. It is crucial to keep these
files consistent if you want to do any regression testing of your repository. This is a good idea to do at least once to verify everything has built correctly.

The current development snapshot (unreleased) of ns-3 may be found at http://code.nsnam.org/ns-3-dev/ and the associated reference traces may be found http://code.nsnam.org/ns-3-dev-ref-traces/ . The developers attempt to keep these repository in consistent, working states but they are in a development area with unreleased code present, so you may want to consider staying with an official release if you do not need newly-introduced features.

Since the release numbers are going to be changing, we will stick with the more constant ns-3-dev here, but you can replace the string ''ns-3-dev'' with your choice of release (e.g., ns-3.4 and ns-3.4-ref-traces) in the text below. You can find the latest version of the code either by inspection of the repository list or by going to the ''Getting Started'' web page and looking for the latest release identifier.

To download the most common options type the following into your shell (remember you can substitute the name of your chosen release number instead of ns-3-dev)

./download.py -n ns-3-dev -r ns-3-dev-ref-traces

After download process completes, you should have several new directories under ~/repos/ns-3-allinone:

build.py* constants.pyc download.py* ns-3-dev-ref-traces/ pybindgen/ util.py
constants.py dist.py* ns-3-dev/ nsc/ README util.pyc

Go ahead and change into ns-3-dev under your ~/repos/ns-3-allinone directory. You should see something like the following there:

AUTHORS examples/ regression/ scratch/ waf*
bindings/ LICENSE regression.py src/ waf.bat*
CHANGES.html ns3/ RELEASE_NOTES utils/ wscript
doc/ README samples/ VERSION wutils.py

You are now ready to build the ns-3 distribution.

=== Downloading ns-3 Using a Tarball ===

The process for downloading ns-3 via tarball is simpler than the Mercurial process since all of the pieces are pre-packaged for you. You just have to pick a release, download it and decompress it.

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. 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):

cd
mkdir tarballs
cd tarballs
wget http://www.nsnam.org/releases/ns-allinone-3.6.tar.bz2
tar xjf ns-allinone-3.6.tar.bz2

If you change into the directory '''ns-allinone-3.6''' you should see a number of files:

build.py* ns-3.6/ nsc-0.5.1/ README
constants.py ns-3.6-ref-traces/ pybindgen-0.12.0.703/ util.py

You are now ready to build the ns-3 distribution.

== Building ns-3 with ns-3-allinone ==

The first time you build the ns-3 project you should build using the allinone environment. This will get the project configured for you
in the most commonly useful way.

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-3-allinone-3.4 under your ~/tarballs directory. Type the following:

./build.py

You will see lots of typical compiler output messages displayed as the build script builds the various pieces you downloaded. Eventually you should see the following magic words:

Build finished successfully (00:02:37)
Leaving directory `./ns-3-dev'

Once the project has built you typically will not use ns-3-allinone scripts. You will now interact directly with Waf and we '''do it in the ns-3-dev directory and not in the ns-3-allinone directory'''.

=== Configuration with Waf ===

To see valid configure options, type ./waf --help. The most important option is -d <debug level>. Valid debug levels (which are listed in waf --help) are: "debug" or "optimized". It is also possible to change the flags used for compilation with (e.g.):

CXXFLAGS="-O3" ./waf configure

or, alternately, the gcc compiler

CXX=g++-3.4 ./waf configure

'''Note:''' Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than
the build stage (i.e., "./waf -d optimized" will not work; instead, do

./waf -d optimized configure; ./waf

The resulting binaries are placed in build/<debuglevel>/srcpath. For example, in a debug build you can find the executable for the first.cc example as build/debug/examples/first. You can debug the executable directly by:

./waf --shell
cd build/debug/examples
gdb first

Of course, you can run gdb in emacs, or use your favorite debugger such as ddd or insight just as easily. In an optimized build you can find the executable for the first.cc example as build/optimized/examples/first.

In order to forcibly disable python bindings, you can provide the following option:

./waf --disable-python configure

In order to tell the build system to use the sudo program to set the suid bit if required, you can provide the following option:

./waf --enable-sudo configure

To start over a configuration from scratch, type:

./waf distclean

Or if you get stuck and all else fails:

rm -rf build

followed by changing back into ns-3-allinone and doing:

./build.py

will basically reset your build state.

To see all waf options:

./waf --help

== Validating ==

ns-3 has unit tests that can be run to verify the installation:

./test.py

which should produce output like:
<pre>
PASS: TestSuite histogram
PASS: TestSuite ns3-wifi-interference
PASS: TestSuite ns3-tcp-cwnd
PASS: TestSuite ns3-tcp-interoperability
PASS: TestSuite sample
...
</pre>

To run the regression tests mentioned above:

./waf --regression

== Using Python ==

See [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings this page].

== Troubleshooting ==

See [http://www.nsnam.org/wiki/index.php/Troubleshooting this page].

----
[[User:Craigdo|Craigdo]] 04:40, 5 November 2009 (UTC)

Emulation and Realtime Scheduler

2010-05-02T18:15:32Z

Hippo:

==Emulation and Realtime Scheduler==
There are two large pieces to the emulation and realtime scheduler project. Not too surprisingly they are the emulation part and the realtime scheduler part.

===Realtime Scheduler===
The purpose of the realtime scheduler is to cause the progression of the simulation clock to occur synchronously with respect to some external time base. Without the presence of an external time base (wall clock), simulation time jumps instantly from one simulated time to the next.

In order to create a realtime scheduler, to a first approximation you just want to cause simulation time jumps to consume real time. We propose doing this using a combination of sleep- and busy- waits. Sleep-waits cause the calling process (thread) to yield the processor for some amount of time. Even though this specified amount of time can be passed to nanosecond resolution, it is actually converted to an OS-specific granularity. In Linux, the granularity is called a ''Jiffy''. Typically this resolution is insufficient for our needs (on the order of a ten milliseconds), so we round down and sleep for some smaller number of Jiffies. The process is then awakened after the specified number of Jiffies has passed. At this time, we have some residual time to wait. This time is generally smaller than the minimum sleep time, so we busy-wait for the remainder of the time. This means that the thread just sits in a for loop consuming cycles until the desired time arrives. After the combination of sleep- and busy-waits, the elapsed realtime (wall) clock should agree with the simulation time of the next event and the simulation proceeds.

===Emulation===
Using the realtime scheduler you can create an N second simulation that will consume N seconds of real time. This is not a terrifically useful feature by itself. To make it useful you need to connect the simulation to the real world that is proceeding according to that realtime clock. In the case of network emulation, this means connecting ns-3 to a at least one real device.

We are providing ns-3 net devices that will look like a usual ns-3 simulated device from the top, but will connect to a real physical network underneath using a packet (raw) socket. By itself this presents little challenge, but one are of concern is the requirement that a process be running as suid root in order to read and write the required sockets. The brute force and awkwardness solution is to simply run the simulation as root. Another option is to use chown and chmod the executable to suid root. This doesn't require the root login, but you still have a rather large application running as root. If one is concerned primarily with limiting the amount of code running as root, but not security, we could provide a net-device smaller process that can read and write raw sockets that runs as root, to which the larger simulation connects. This has the drawback of opening a giant security hole. If you have any opinions or strong requirements in this respect, please let me know.

===Emulation plus Realtime Scheduler===
If you consider how an ns-3 simulation might drive a physical net device, it is straightforward. When you want the physical net device to drive the simulation, you need to be able to allow the net device to schedule events in the simulator. Since the basic model for sockets is synchronous, we will need to have a thread reading data from a physical net device in real time. We also want to have at least one thread executing the simulation. It seems clear that we are going to have a multithreaded solution. This means we needed to serialize the scheduler.

Also. since there is going to be a need for the net device thread to affect the main scheduler thread we are going to have some form of inter-thread communication. Typically, the scheduler will be sleeping waiting to synchronize with real time. IF a net device receives a packet, we need to be able to schedule a new packet reception event and to wake the scheduler and force it to re-evaluate what it needs to do. This will most likely mean the scheduler will have to execute the newly scheduled event (and derived events) and then go back to sleep waiting for the next event time.

A useful OS construct for doing exactly this kind of wait is a timed conditional wait. ''Posix Threads'' (pthreads) implements this functionality as ''pthread_cond_timedwait''. We use the ''condition'' as a request for interruption by a realtime device. If a pthread_cond_timedwait is requested, a sleep-wait is performed for a specified time. If the condition does not become true during that time (a timeout) then the function call will return and we will have accomplished our needed sleep-wait. If an external (to the simulation proper) device sets the condition, then the sleep-wait will return early. The scheduler then wakes up and re-evaluates its next action.

Since multiple threads are wandering around in the scheduler, we need to be careful about protecting shared data structures of course.

We have added the required kernel thread and synchronization classes to ns-3-dev as of July, 2008.

===Higher Order Effects===
Since we are attempting to run our simulations at realtime, and have already committed to a multithreaded environment, we have plenty of need and new opportunity for performance optimizations. Others (Mahrenholz et al.) have considered the kinds of optimizations that can be done so I won't duplicate this here, but at this stage of the game we consider them higher order effects that we'll worry about when the time comes.

===Current Status===
The basic project is complete. The realtime simulator was part of the ns-3.2 release. The EmuNetDevice was part of the ns-3.3 release. The TapBridge was part of the ns-3.4 release. We did a demo of the EmuNetDevice at Sigcomm in 2008 with this topology:

[[Image:Sigcomm08-demo-figure.png]]

There is a HOWTO describing how to set up the virtual machines [http://www.nsnam.org/wiki/index.php/HOWTO_use_VMware_to_set_up_virtual_networks_%28Windows%29 here]. You can find the sigcomm demo repository [http://code.nsnam.org/ns-3-sigcomm/ here].

There are two use cases we've defined so far: using ns-3 nodes and stacks but substituting real net devices and real networks in a simulation; and the converse which is using an ns-3 simulated network between real nodes and stacks.

----
[[User:Craigdo|Craigdo]] 23:53, 27 March 2009 (UTC)

Installation

2010-04-22T18:35:45Z

Hippo: /* Gentoo */

{{TOC}}

This is a detailed installation guide for ns-3. Basic installation instructions can be found at the [http://www.nsnam.org/getting_started.html Getting Started] page or in the [http://www.nsnam.org/docs/release/tutorial/tutorial.html ns-3 tutorial].

== Supported platforms ==

ns-3 is primarily developed on GNU/Linux platforms, and the minimal requirements to run basic simulations are a gcc installation of gcc-3.4/g++-3.4 or greater, and python 2.4 or greater.

ns-3 is supported on the following primary platforms:

# Linux x86 gcc 4.2, 4.1, and, 3.4.6.
# Linux x86_64 gcc 4.4.0, 4.3.2, 4.2.3, 4.2.1, 4.1.3, 3.4.6
# MacOS X ppc and x86 (gcc 4.0.x and 4.2.x)
# [http://www.cygwin.com Cygwin] gcc 3.4.4 (debug only), gcc 4.3.2 (debug and optimized)

By supported, we mean that the project tries to support most or all of the build options on these platforms unless there is a good reason to exclude the option; and at least the debug build will compile. If you intend to do serious work using ns-3, and are forced by circumstances to use a Windows platform, consider virtualization of a popular Linux platform. This may be more time-consuming than installing a minimal Cygwin, for example, but you end up with a fully functional Linux system and ns-3 distribution. Some quick performance comparisons between Cygwin and VirtualBoxed Fedora 11 indicate that examples can actually run faster under VirtualBox.

We provide HOWTO documents describing the process for installing Linux support and getting ns-3 running using two popular virtualization products: VirtualBox ([[HOWTO use VirtualBox to run simulations on Windows machines]]) and VMware ([[HOWTO use VMware to set up virtual networks (Windows)]]).

ns-3 may also run on currently unsupported platforms. For example, an alternative Windows platform is MinGW. There are maintainers who attempt to keep a subset of ns-3 running on MinGW, but it is not "officially" suppported. This means that bugs filed against MinGW will be addressed as time permits. Additionally, the Eclipse IDE is used by some developers, but the project does not actively support this environment.

Additional maintainers are invited to make more platforms, compilers and environments supported.

=== ns-3 options ===

There are a few options that are not enabled by default and are not available on all platforms. At the end of the configuration process (explained below), the status of these options are shown as detected by a '''waf''' script:

<pre>
---- Summary of optional NS-3 features:
Threading Primitives : enabled
Real Time Simulator : enabled
Emulated Net Device : enabled
Tap Bridge : enabled
GtkConfigStore : enabled
XmlIo : not enabled (library 'libxml-2.0 >= 2.7' not found)
SQlite stats data output : enabled
Network Simulation Cradle : enabled
Python Bindings : not enabled (disabled by user request)
Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
Static build : not enabled (option --enable-static not selected)
</pre>

Generally if the platform is missing some requirement for an option it is marked as "not enabled." Note that "disabled by user request" will be shown when the user explicitly disables a feature (such as "--disable-python"); and if a feature defaults to disabled this will also be noted (e.g., option --enable-sudo not selected).

The table below is meant to help sort out the different features and on which platforms they are supported. This table reflects the status of the most recent release version (ns-3.6):

{| border=1 cellspacing=0 cellpadding=3

|+ Option status
! Option !! Linux gcc-4.x,gcc-3.4.x !! OS X !! Cygwin
|-
! Optimized build
| || || X 1
|-
! Python bindings
| || || X 2
|-
! Threading
| || ||
|-
! Real-time simulator
| || X || X
|-
! Emulated Net Device
| || X || X
|-
! Tap Bridge
| || X || X
|-
! Network simulation cradle
| note3 || X || X
|-
! Static builds
| || ||

|}

''Key:'' '''( )'''(empty space) = supported; '''X''' = not supported; '''?''' = unknown; '''dev''' = support in ns-3-dev (next release)

''Notes:''
# Works with gcc4
# Cygwin limitation explained [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings#Cygwin_limitation here]
# NSC works best with gcc-3.4 or gcc-4.2 or greater series. Try to avoid gcc-4.0 and gcc-4.1 series; some build problems have been found with these versions of compilers.

== Prerequisites ==

The core of ns-3 requires a gcc/g++ installation of 3.4 or greater, and python 2.4 or greater. As mentioned above, different options require additional support. This is a list of packages (for Debian/Ubuntu systems) that are needed to support different ns-3 options. Note that other distributions (e.g., Fedora, FreeBSD) may have different package names or capitalization (e.g. ImageMagik). Installation should be similar for Red Hat/Fedora based systems, with "yum" replacing "apt-get", but some differences exist, so below is a guide for both Ubuntu (should generally apply to Debian) and Fedora/RedHat-based systems:

=== Ubuntu/Debian ===

The following list of packages should be accurate for Ubuntu 9.10 release; other releases or other Debian-based systems may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

sudo apt-get install gcc g++ python

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

sudo apt-get install gcc g++ python python-dev

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

sudo apt-get install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

sudo apt-get install bzr

* A GTK-based configuration system

sudo apt-get install libgtk2.0-0 libgtk2.0-dev

* Debugging:

sudo apt-get install gdb valgrind

* Doxygen and related inline documentation:

sudo apt-get install doxygen graphviz imagemagick
sudo apt-get install texlive texlive-pdf texlive-latex-extra texlive-generic-extra texlive-generic-recommended

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

sudo apt-get install texinfo dia texlive texlive-pdf texlive-latex-extra texlive-extra-utils texlive-generic-recommended texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

sudo apt-get install flex bison

* Some basic mobility visualization tests require goocanvas:

sudo apt-get install libgoocanvas-dev

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

sudo apt-get install g++-3.4 gcc-3.4

* To read pcap packet traces

sudo apt-get install tcpdump

* Database support for statistics framework

sudo apt-get install sqlite sqlite3 libsqlite3-dev

* Xml-based version of the config store (requires libxml2 >= version 2.7)

sudo apt-get install libxml2 libxml2-dev

* Support for Gustavo's ns-3-pyviz visualizer

sudo apt-get install python-pygraphviz python-kiwi python-pygoocanvas

=== Fedora/RedHat ===

The following list of packages should be accurate for Fedora 12/CentOS 5.4 release; other releases may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

yum install gcc gcc-c++ python

* '''Note:''' If you are using CentOS 5.4 or RHEL 5, you may want to also get and use the gcc44 packages; see the [[Troubleshooting]] page.

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

yum install gcc gcc-c++ python python-devel

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories. You may want to install mercurial from rpmforge repository (instructions [http://www.trinitycore.org/forum/mercurial-centos-t3113.html here]) or EPEL.

yum install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar. You may need EPEL repository for this.

yum install bzr

* An optional but recommended package (for improving some wireless model fidelity) is GNU scientific library:

yum install gsl gsl-devel

* A GTK-based configuration system

yum install gtk2 gtk2-devel

* Debugging:

yum install gdb valgrind

* Doxygen and related inline documentation:

yum install doxygen graphviz ImageMagick
yum install texinfo texinfo-tex

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

yum install texinfo dia texinfo-tex texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

yum install flex bison

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

yum install compat-gcc-34

* To read pcap packet traces

yum install tcpdump

* Database support for statistics framework

yum install sqlite sqlite-devel

* Xml-based version of the config store (requires libxml2 >= version 2.7)

yum install libxml2 libxml2-devel

=== Gentoo ===

The following list of packages should be accurate for Gentoo as of 04/22/2010; due to possible changes in USE-flags or package names the list may slightly vary.
First of all, become root as usual.

* '''minimal requirements for C++ or Python (release):''' This is the minimal set of packages needed to run ns-3 or to work with Python bindings from a released tarball.

USE="threads -nocxx nptl" emerge -uavN gcc python

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

emerge -av --noreplace mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

USE="curl" emerge -uavN bzr

* A GTK-based configuration system

emerge -av --noreplace gtk+:2

* Debugging:

emerge -av --noreplace gdb valgrind

* Doxygen and related inline documentation; also ns-3 manual and tutorial (written in Texinfo):

USE="extra graphics png" emerge -uavN texlive
USE="cairo graphviz latex png svg" emerge -uavN doxygen imagemagick dia

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

emerge -av --noreplace flex bison

* Some basic mobility visualization tests require goocanvas:

emerge -av --noreplace goocanvas

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

USE="-nocxx nptl" emerge -uavN gcc:3.4

* To read pcap packet traces

emerge -av --noreplace tcpdump

or you may prefer

emerge -av --noreplace wireshark

* Database support for statistics framework

USE="threadsafe" emerge -uavN sqlite:3

* Xml-based version of the config store (requires libxml2 >= version 2.7)

emerge -av --noreplace libxml2

* Support for Gustavo's ns-3-pyviz visualizer (following packages have no stable version as of day of writing, so ~arch for ACCEPT_KEYWORDS)

ACCEPT_KEYWORDS="~x86" emerge -av --noreplace pygraphviz kiwi pygoocanvas

* To summarize all of above up (without not yet stable pygraphviz, kiwi, pygoocanvas):
USE="cairo curl extra graphics graphviz latex -nocxx nptl png svg threads threadsafe" emerge -uavN bison bzr dia doxygen flex gcc gcc:3.4 goocanvas gtk+:2 imagemagick libxml2 mercurial python sqlite:3 tcpdump texlive valgrind wireshark

=== Mac OS X (Snow Leopard) ===

Please see [[HOWTO_get_ns-3_running_on_Mac_OS_X_(10.6.2_Intel)]] and follow steps 1 and 2 (prerequisites) and continue reading below if you want to work with a released version, and follow all steps if you want to work with a development version of ns-3.

== Installation ==

The ns-3 code is available in Mercurial repositories on the server http://code.nsnam.org (look for the latest release e.g., "ns-3.4"). You can download a tarball of the latest release at http://www.nsnam.org/releases or you can work with our repositories using Mercurial. We recommend using Mercurial unless there's a good reason not to (See the end of this section for instructions on how to get a tarball release).

The simplest way to get started using Mercurial repositories is to use the '''ns-3-allinone''' environment. This is a set of scripts that manages the downloading and building of various subystems of ns-3 for you. We recommend that you begin your ns-3 adventures in this environment as it can really simplify your life at this point.

=== Downloading ns-3 Using Mercurial ===
One practice is to create a directory called '''repos''' in one's home directory under which one can keep local Mercurial repositories. If you adopt 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
hg clone http://code.nsnam.org/ns-3-allinone

As the hg (Mercurial) command executes, you should see something like the following displayed,

destination directory: ns-3-allinone
requesting all changes
adding changesets
adding manifests
adding file changes
added 26 changesets with 40 changes to 7 files
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 look something like the following:

build.py* constants.py dist.py* download.py* README util.py

Notice that you really just downloaded some Python scripts. The next step will be to use those scripts to download and build the ns-3 distribution of your choice.

If you go to the following link: http://code.nsnam.org/ you will see a number of repositories. Many are the private repositories of the ns-3 development team. The repositories of interest to you will be prefixed with '''ns-3'''. Official releases of ns-3 will be numbered as ns-3.release.hotfix. For example, a second hotfix to a still hypothetical release nine of ns-3 would be numbered as ns-3.9.2 on this page.

We have had a regression testing framework in place since the first release. For each release, a set of output files that define ''good behavior'' are saved. These known good output files are called reference traces and are associated with a given release by name. For example, in http://code.nsnam.org/ you will find a repository named ns-3.1 which is the first stable release of ns-3. You will also find a separate repository named ns-3.1-ref-traces that holds the reference traces for the ns-3.1 release. It is crucial to keep these
files consistent if you want to do any regression testing of your repository. This is a good idea to do at least once to verify everything has built correctly.

The current development snapshot (unreleased) of ns-3 may be found at http://code.nsnam.org/ns-3-dev/ and the associated reference traces may be found http://code.nsnam.org/ns-3-dev-ref-traces/ . The developers attempt to keep these repository in consistent, working states but they are in a development area with unreleased code present, so you may want to consider staying with an official release if you do not need newly-introduced features.

Since the release numbers are going to be changing, we will stick with the more constant ns-3-dev here, but you can replace the string ''ns-3-dev'' with your choice of release (e.g., ns-3.4 and ns-3.4-ref-traces) in the text below. You can find the latest version of the code either by inspection of the repository list or by going to the ''Getting Started'' web page and looking for the latest release identifier.

To download the most common options type the following into your shell (remember you can substitute the name of your chosen release number instead of ns-3-dev)

./download.py -n ns-3-dev -r ns-3-dev-ref-traces

After download process completes, you should have several new directories under ~/repos/ns-3-allinone:

build.py* constants.pyc download.py* ns-3-dev-ref-traces/ pybindgen/ util.py
constants.py dist.py* ns-3-dev/ nsc/ README util.pyc

Go ahead and change into ns-3-dev under your ~/repos/ns-3-allinone directory. You should see something like the following there:

AUTHORS examples/ regression/ scratch/ waf*
bindings/ LICENSE regression.py src/ waf.bat*
CHANGES.html ns3/ RELEASE_NOTES utils/ wscript
doc/ README samples/ VERSION wutils.py

You are now ready to build the ns-3 distribution.

=== Downloading ns-3 Using a Tarball ===

The process for downloading ns-3 via tarball is simpler than the Mercurial process since all of the pieces are pre-packaged for you. You just have to pick a release, download it and decompress it.

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. 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):

cd
mkdir tarballs
cd tarballs
wget http://www.nsnam.org/releases/ns-allinone-3.6.tar.bz2
tar xjf ns-allinone-3.6.tar.bz2

If you change into the directory '''ns-allinone-3.6''' you should see a number of files:

build.py* ns-3.6/ nsc-0.5.1/ README
constants.py ns-3.6-ref-traces/ pybindgen-0.12.0.703/ util.py

You are now ready to build the ns-3 distribution.

== Building ns-3 with ns-3-allinone ==

The first time you build the ns-3 project you should build using the allinone environment. This will get the project configured for you
in the most commonly useful way.

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-3-allinone-3.4 under your ~/tarballs directory. Type the following:

./build.py

You will see lots of typical compiler output messages displayed as the build script builds the various pieces you downloaded. Eventually you should see the following magic words:

Build finished successfully (00:02:37)
Leaving directory `./ns-3-dev'

Once the project has built you typically will not use ns-3-allinone scripts. You will now interact directly with Waf and we '''do it in the ns-3-dev directory and not in the ns-3-allinone directory'''.

=== Configuration with Waf ===

To see valid configure options, type ./waf --help. The most important option is -d <debug level>. Valid debug levels (which are listed in waf --help) are: "debug" or "optimized". It is also possible to change the flags used for compilation with (e.g.):

CXXFLAGS="-O3" ./waf configure

or, alternately, the gcc compiler

CXX=g++-3.4 ./waf configure

'''Note:''' Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than
the build stage (i.e., "./waf -d optimized" will not work; instead, do

./waf -d optimized configure; ./waf

The resulting binaries are placed in build/<debuglevel>/srcpath. For example, in a debug build you can find the executable for the first.cc example as build/debug/examples/first. You can debug the executable directly by:

./waf --shell
cd build/debug/examples
gdb first

Of course, you can run gdb in emacs, or use your favorite debugger such as ddd or insight just as easily. In an optimized build you can find the executable for the first.cc example as build/optimized/examples/first.

In order to forcibly disable python bindings, you can provide the following option:

./waf --disable-python configure

In order to tell the build system to use the sudo program to set the suid bit if required, you can provide the following option:

./waf --enable-sudo configure

To start over a configuration from scratch, type:

./waf distclean

Or if you get stuck and all else fails:

rm -rf build

followed by changing back into ns-3-allinone and doing:

./build.py

will basically reset your build state.

To see all waf options:

./waf --help

== Validating ==

ns-3 has unit tests that can be run to verify the installation:

./test.py

which should produce output like:
<pre>
PASS: TestSuite histogram
PASS: TestSuite ns3-wifi-interference
PASS: TestSuite ns3-tcp-cwnd
PASS: TestSuite ns3-tcp-interoperability
PASS: TestSuite sample
...
</pre>

To run the regression tests mentioned above:

./waf --regression

== Using Python ==

See [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings this page].

== Troubleshooting ==

See [http://www.nsnam.org/wiki/index.php/Troubleshooting this page].

----
[[User:Craigdo|Craigdo]] 04:40, 5 November 2009 (UTC)

Installation

2010-04-22T18:34:27Z

Hippo: /* Gentoo */

{{TOC}}

This is a detailed installation guide for ns-3. Basic installation instructions can be found at the [http://www.nsnam.org/getting_started.html Getting Started] page or in the [http://www.nsnam.org/docs/release/tutorial/tutorial.html ns-3 tutorial].

== Supported platforms ==

ns-3 is primarily developed on GNU/Linux platforms, and the minimal requirements to run basic simulations are a gcc installation of gcc-3.4/g++-3.4 or greater, and python 2.4 or greater.

ns-3 is supported on the following primary platforms:

# Linux x86 gcc 4.2, 4.1, and, 3.4.6.
# Linux x86_64 gcc 4.4.0, 4.3.2, 4.2.3, 4.2.1, 4.1.3, 3.4.6
# MacOS X ppc and x86 (gcc 4.0.x and 4.2.x)
# [http://www.cygwin.com Cygwin] gcc 3.4.4 (debug only), gcc 4.3.2 (debug and optimized)

By supported, we mean that the project tries to support most or all of the build options on these platforms unless there is a good reason to exclude the option; and at least the debug build will compile. If you intend to do serious work using ns-3, and are forced by circumstances to use a Windows platform, consider virtualization of a popular Linux platform. This may be more time-consuming than installing a minimal Cygwin, for example, but you end up with a fully functional Linux system and ns-3 distribution. Some quick performance comparisons between Cygwin and VirtualBoxed Fedora 11 indicate that examples can actually run faster under VirtualBox.

We provide HOWTO documents describing the process for installing Linux support and getting ns-3 running using two popular virtualization products: VirtualBox ([[HOWTO use VirtualBox to run simulations on Windows machines]]) and VMware ([[HOWTO use VMware to set up virtual networks (Windows)]]).

ns-3 may also run on currently unsupported platforms. For example, an alternative Windows platform is MinGW. There are maintainers who attempt to keep a subset of ns-3 running on MinGW, but it is not "officially" suppported. This means that bugs filed against MinGW will be addressed as time permits. Additionally, the Eclipse IDE is used by some developers, but the project does not actively support this environment.

Additional maintainers are invited to make more platforms, compilers and environments supported.

=== ns-3 options ===

There are a few options that are not enabled by default and are not available on all platforms. At the end of the configuration process (explained below), the status of these options are shown as detected by a '''waf''' script:

<pre>
---- Summary of optional NS-3 features:
Threading Primitives : enabled
Real Time Simulator : enabled
Emulated Net Device : enabled
Tap Bridge : enabled
GtkConfigStore : enabled
XmlIo : not enabled (library 'libxml-2.0 >= 2.7' not found)
SQlite stats data output : enabled
Network Simulation Cradle : enabled
Python Bindings : not enabled (disabled by user request)
Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
Static build : not enabled (option --enable-static not selected)
</pre>

Generally if the platform is missing some requirement for an option it is marked as "not enabled." Note that "disabled by user request" will be shown when the user explicitly disables a feature (such as "--disable-python"); and if a feature defaults to disabled this will also be noted (e.g., option --enable-sudo not selected).

The table below is meant to help sort out the different features and on which platforms they are supported. This table reflects the status of the most recent release version (ns-3.6):

{| border=1 cellspacing=0 cellpadding=3

|+ Option status
! Option !! Linux gcc-4.x,gcc-3.4.x !! OS X !! Cygwin
|-
! Optimized build
| || || X 1
|-
! Python bindings
| || || X 2
|-
! Threading
| || ||
|-
! Real-time simulator
| || X || X
|-
! Emulated Net Device
| || X || X
|-
! Tap Bridge
| || X || X
|-
! Network simulation cradle
| note3 || X || X
|-
! Static builds
| || ||

|}

''Key:'' '''( )'''(empty space) = supported; '''X''' = not supported; '''?''' = unknown; '''dev''' = support in ns-3-dev (next release)

''Notes:''
# Works with gcc4
# Cygwin limitation explained [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings#Cygwin_limitation here]
# NSC works best with gcc-3.4 or gcc-4.2 or greater series. Try to avoid gcc-4.0 and gcc-4.1 series; some build problems have been found with these versions of compilers.

== Prerequisites ==

The core of ns-3 requires a gcc/g++ installation of 3.4 or greater, and python 2.4 or greater. As mentioned above, different options require additional support. This is a list of packages (for Debian/Ubuntu systems) that are needed to support different ns-3 options. Note that other distributions (e.g., Fedora, FreeBSD) may have different package names or capitalization (e.g. ImageMagik). Installation should be similar for Red Hat/Fedora based systems, with "yum" replacing "apt-get", but some differences exist, so below is a guide for both Ubuntu (should generally apply to Debian) and Fedora/RedHat-based systems:

=== Ubuntu/Debian ===

The following list of packages should be accurate for Ubuntu 9.10 release; other releases or other Debian-based systems may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

sudo apt-get install gcc g++ python

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

sudo apt-get install gcc g++ python python-dev

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

sudo apt-get install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

sudo apt-get install bzr

* A GTK-based configuration system

sudo apt-get install libgtk2.0-0 libgtk2.0-dev

* Debugging:

sudo apt-get install gdb valgrind

* Doxygen and related inline documentation:

sudo apt-get install doxygen graphviz imagemagick
sudo apt-get install texlive texlive-pdf texlive-latex-extra texlive-generic-extra texlive-generic-recommended

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

sudo apt-get install texinfo dia texlive texlive-pdf texlive-latex-extra texlive-extra-utils texlive-generic-recommended texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

sudo apt-get install flex bison

* Some basic mobility visualization tests require goocanvas:

sudo apt-get install libgoocanvas-dev

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

sudo apt-get install g++-3.4 gcc-3.4

* To read pcap packet traces

sudo apt-get install tcpdump

* Database support for statistics framework

sudo apt-get install sqlite sqlite3 libsqlite3-dev

* Xml-based version of the config store (requires libxml2 >= version 2.7)

sudo apt-get install libxml2 libxml2-dev

* Support for Gustavo's ns-3-pyviz visualizer

sudo apt-get install python-pygraphviz python-kiwi python-pygoocanvas

=== Fedora/RedHat ===

The following list of packages should be accurate for Fedora 12/CentOS 5.4 release; other releases may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

yum install gcc gcc-c++ python

* '''Note:''' If you are using CentOS 5.4 or RHEL 5, you may want to also get and use the gcc44 packages; see the [[Troubleshooting]] page.

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

yum install gcc gcc-c++ python python-devel

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories. You may want to install mercurial from rpmforge repository (instructions [http://www.trinitycore.org/forum/mercurial-centos-t3113.html here]) or EPEL.

yum install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar. You may need EPEL repository for this.

yum install bzr

* An optional but recommended package (for improving some wireless model fidelity) is GNU scientific library:

yum install gsl gsl-devel

* A GTK-based configuration system

yum install gtk2 gtk2-devel

* Debugging:

yum install gdb valgrind

* Doxygen and related inline documentation:

yum install doxygen graphviz ImageMagick
yum install texinfo texinfo-tex

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

yum install texinfo dia texinfo-tex texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

yum install flex bison

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

yum install compat-gcc-34

* To read pcap packet traces

yum install tcpdump

* Database support for statistics framework

yum install sqlite sqlite-devel

* Xml-based version of the config store (requires libxml2 >= version 2.7)

yum install libxml2 libxml2-devel

=== Gentoo ===

The following list of packages should be accurate for Gentoo as of 04/22/2010; due to possible changes in USE-flags or package names the list may slightly vary.
First of all, become root as usual.

* '''minimal requirements for C++ or Python (release):''' This is the minimal set of packages needed to run ns-3 or to work with Python bindings from a released tarball.

USE="threads -nocxx nptl" emerge -uavN gcc python

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

emerge -av --noreplace mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

USE="curl" emerge -uavN bzr

* A GTK-based configuration system

emerge -av --noreplace gtk+:2

* Debugging:

emerge -av --noreplace gdb valgrind

* Doxygen and related inline documentation; also ns-3 manual and tutorial (written in Texinfo):

USE="extra graphics png" emerge -uavN texlive
USE="cairo graphviz latex png svg" emerge -uavN doxygen imagemagick dia

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

emerge -av --noreplace flex bison

* Some basic mobility visualization tests require goocanvas:

emerge -av --noreplace goocanvas

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

USE="-nocxx nptl" emerge -uavN gcc:3.4

* To read pcap packet traces

emerge -av --noreplace tcpdump

or you may prefer

emerge -av --noreplace wireshark

* Database support for statistics framework

USE="threadsafe" emerge -uavN sqlite:3

* Xml-based version of the config store (requires libxml2 >= version 2.7)

emerge -av --noreplace libxml2

* Support for Gustavo's ns-3-pyviz visualizer (following packages have no stable version as of day of writing, so ~arch for ACCEPT_KEYWORDS)

ACCEPT_KEYWORDS="~x86" emerge -av --noreplace pygraphviz kiwi pygoocanvas

* To summarize all of above up (with not yet stable pygraphviz, kiwi, pygoocanvas):
USE="cairo curl extra graphics graphviz latex -nocxx nptl png svg threads threadsafe" emerge -uavN bison bzr dia doxygen flex gcc gcc:3.4 goocanvas gtk+:2 imagemagick libxml2 mercurial python sqlite:3 tcpdump texlive valgrind wireshark

=== Mac OS X (Snow Leopard) ===

Please see [[HOWTO_get_ns-3_running_on_Mac_OS_X_(10.6.2_Intel)]] and follow steps 1 and 2 (prerequisites) and continue reading below if you want to work with a released version, and follow all steps if you want to work with a development version of ns-3.

== Installation ==

The ns-3 code is available in Mercurial repositories on the server http://code.nsnam.org (look for the latest release e.g., "ns-3.4"). You can download a tarball of the latest release at http://www.nsnam.org/releases or you can work with our repositories using Mercurial. We recommend using Mercurial unless there's a good reason not to (See the end of this section for instructions on how to get a tarball release).

The simplest way to get started using Mercurial repositories is to use the '''ns-3-allinone''' environment. This is a set of scripts that manages the downloading and building of various subystems of ns-3 for you. We recommend that you begin your ns-3 adventures in this environment as it can really simplify your life at this point.

=== Downloading ns-3 Using Mercurial ===
One practice is to create a directory called '''repos''' in one's home directory under which one can keep local Mercurial repositories. If you adopt 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
hg clone http://code.nsnam.org/ns-3-allinone

As the hg (Mercurial) command executes, you should see something like the following displayed,

destination directory: ns-3-allinone
requesting all changes
adding changesets
adding manifests
adding file changes
added 26 changesets with 40 changes to 7 files
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 look something like the following:

build.py* constants.py dist.py* download.py* README util.py

Notice that you really just downloaded some Python scripts. The next step will be to use those scripts to download and build the ns-3 distribution of your choice.

If you go to the following link: http://code.nsnam.org/ you will see a number of repositories. Many are the private repositories of the ns-3 development team. The repositories of interest to you will be prefixed with '''ns-3'''. Official releases of ns-3 will be numbered as ns-3.release.hotfix. For example, a second hotfix to a still hypothetical release nine of ns-3 would be numbered as ns-3.9.2 on this page.

We have had a regression testing framework in place since the first release. For each release, a set of output files that define ''good behavior'' are saved. These known good output files are called reference traces and are associated with a given release by name. For example, in http://code.nsnam.org/ you will find a repository named ns-3.1 which is the first stable release of ns-3. You will also find a separate repository named ns-3.1-ref-traces that holds the reference traces for the ns-3.1 release. It is crucial to keep these
files consistent if you want to do any regression testing of your repository. This is a good idea to do at least once to verify everything has built correctly.

The current development snapshot (unreleased) of ns-3 may be found at http://code.nsnam.org/ns-3-dev/ and the associated reference traces may be found http://code.nsnam.org/ns-3-dev-ref-traces/ . The developers attempt to keep these repository in consistent, working states but they are in a development area with unreleased code present, so you may want to consider staying with an official release if you do not need newly-introduced features.

Since the release numbers are going to be changing, we will stick with the more constant ns-3-dev here, but you can replace the string ''ns-3-dev'' with your choice of release (e.g., ns-3.4 and ns-3.4-ref-traces) in the text below. You can find the latest version of the code either by inspection of the repository list or by going to the ''Getting Started'' web page and looking for the latest release identifier.

To download the most common options type the following into your shell (remember you can substitute the name of your chosen release number instead of ns-3-dev)

./download.py -n ns-3-dev -r ns-3-dev-ref-traces

After download process completes, you should have several new directories under ~/repos/ns-3-allinone:

build.py* constants.pyc download.py* ns-3-dev-ref-traces/ pybindgen/ util.py
constants.py dist.py* ns-3-dev/ nsc/ README util.pyc

Go ahead and change into ns-3-dev under your ~/repos/ns-3-allinone directory. You should see something like the following there:

AUTHORS examples/ regression/ scratch/ waf*
bindings/ LICENSE regression.py src/ waf.bat*
CHANGES.html ns3/ RELEASE_NOTES utils/ wscript
doc/ README samples/ VERSION wutils.py

You are now ready to build the ns-3 distribution.

=== Downloading ns-3 Using a Tarball ===

The process for downloading ns-3 via tarball is simpler than the Mercurial process since all of the pieces are pre-packaged for you. You just have to pick a release, download it and decompress it.

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. 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):

cd
mkdir tarballs
cd tarballs
wget http://www.nsnam.org/releases/ns-allinone-3.6.tar.bz2
tar xjf ns-allinone-3.6.tar.bz2

If you change into the directory '''ns-allinone-3.6''' you should see a number of files:

build.py* ns-3.6/ nsc-0.5.1/ README
constants.py ns-3.6-ref-traces/ pybindgen-0.12.0.703/ util.py

You are now ready to build the ns-3 distribution.

== Building ns-3 with ns-3-allinone ==

The first time you build the ns-3 project you should build using the allinone environment. This will get the project configured for you
in the most commonly useful way.

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-3-allinone-3.4 under your ~/tarballs directory. Type the following:

./build.py

You will see lots of typical compiler output messages displayed as the build script builds the various pieces you downloaded. Eventually you should see the following magic words:

Build finished successfully (00:02:37)
Leaving directory `./ns-3-dev'

Once the project has built you typically will not use ns-3-allinone scripts. You will now interact directly with Waf and we '''do it in the ns-3-dev directory and not in the ns-3-allinone directory'''.

=== Configuration with Waf ===

To see valid configure options, type ./waf --help. The most important option is -d <debug level>. Valid debug levels (which are listed in waf --help) are: "debug" or "optimized". It is also possible to change the flags used for compilation with (e.g.):

CXXFLAGS="-O3" ./waf configure

or, alternately, the gcc compiler

CXX=g++-3.4 ./waf configure

'''Note:''' Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than
the build stage (i.e., "./waf -d optimized" will not work; instead, do

./waf -d optimized configure; ./waf

The resulting binaries are placed in build/<debuglevel>/srcpath. For example, in a debug build you can find the executable for the first.cc example as build/debug/examples/first. You can debug the executable directly by:

./waf --shell
cd build/debug/examples
gdb first

Of course, you can run gdb in emacs, or use your favorite debugger such as ddd or insight just as easily. In an optimized build you can find the executable for the first.cc example as build/optimized/examples/first.

In order to forcibly disable python bindings, you can provide the following option:

./waf --disable-python configure

In order to tell the build system to use the sudo program to set the suid bit if required, you can provide the following option:

./waf --enable-sudo configure

To start over a configuration from scratch, type:

./waf distclean

Or if you get stuck and all else fails:

rm -rf build

followed by changing back into ns-3-allinone and doing:

./build.py

will basically reset your build state.

To see all waf options:

./waf --help

== Validating ==

ns-3 has unit tests that can be run to verify the installation:

./test.py

which should produce output like:
<pre>
PASS: TestSuite histogram
PASS: TestSuite ns3-wifi-interference
PASS: TestSuite ns3-tcp-cwnd
PASS: TestSuite ns3-tcp-interoperability
PASS: TestSuite sample
...
</pre>

To run the regression tests mentioned above:

./waf --regression

== Using Python ==

See [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings this page].

== Troubleshooting ==

See [http://www.nsnam.org/wiki/index.php/Troubleshooting this page].

----
[[User:Craigdo|Craigdo]] 04:40, 5 November 2009 (UTC)

Installation

2010-04-22T18:24:28Z

Hippo: /* Gentoo */

{{TOC}}

This is a detailed installation guide for ns-3. Basic installation instructions can be found at the [http://www.nsnam.org/getting_started.html Getting Started] page or in the [http://www.nsnam.org/docs/release/tutorial/tutorial.html ns-3 tutorial].

== Supported platforms ==

ns-3 is primarily developed on GNU/Linux platforms, and the minimal requirements to run basic simulations are a gcc installation of gcc-3.4/g++-3.4 or greater, and python 2.4 or greater.

ns-3 is supported on the following primary platforms:

# Linux x86 gcc 4.2, 4.1, and, 3.4.6.
# Linux x86_64 gcc 4.4.0, 4.3.2, 4.2.3, 4.2.1, 4.1.3, 3.4.6
# MacOS X ppc and x86 (gcc 4.0.x and 4.2.x)
# [http://www.cygwin.com Cygwin] gcc 3.4.4 (debug only), gcc 4.3.2 (debug and optimized)

By supported, we mean that the project tries to support most or all of the build options on these platforms unless there is a good reason to exclude the option; and at least the debug build will compile. If you intend to do serious work using ns-3, and are forced by circumstances to use a Windows platform, consider virtualization of a popular Linux platform. This may be more time-consuming than installing a minimal Cygwin, for example, but you end up with a fully functional Linux system and ns-3 distribution. Some quick performance comparisons between Cygwin and VirtualBoxed Fedora 11 indicate that examples can actually run faster under VirtualBox.

We provide HOWTO documents describing the process for installing Linux support and getting ns-3 running using two popular virtualization products: VirtualBox ([[HOWTO use VirtualBox to run simulations on Windows machines]]) and VMware ([[HOWTO use VMware to set up virtual networks (Windows)]]).

ns-3 may also run on currently unsupported platforms. For example, an alternative Windows platform is MinGW. There are maintainers who attempt to keep a subset of ns-3 running on MinGW, but it is not "officially" suppported. This means that bugs filed against MinGW will be addressed as time permits. Additionally, the Eclipse IDE is used by some developers, but the project does not actively support this environment.

Additional maintainers are invited to make more platforms, compilers and environments supported.

=== ns-3 options ===

There are a few options that are not enabled by default and are not available on all platforms. At the end of the configuration process (explained below), the status of these options are shown as detected by a '''waf''' script:

<pre>
---- Summary of optional NS-3 features:
Threading Primitives : enabled
Real Time Simulator : enabled
Emulated Net Device : enabled
Tap Bridge : enabled
GtkConfigStore : enabled
XmlIo : not enabled (library 'libxml-2.0 >= 2.7' not found)
SQlite stats data output : enabled
Network Simulation Cradle : enabled
Python Bindings : not enabled (disabled by user request)
Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
Static build : not enabled (option --enable-static not selected)
</pre>

Generally if the platform is missing some requirement for an option it is marked as "not enabled." Note that "disabled by user request" will be shown when the user explicitly disables a feature (such as "--disable-python"); and if a feature defaults to disabled this will also be noted (e.g., option --enable-sudo not selected).

The table below is meant to help sort out the different features and on which platforms they are supported. This table reflects the status of the most recent release version (ns-3.6):

{| border=1 cellspacing=0 cellpadding=3

|+ Option status
! Option !! Linux gcc-4.x,gcc-3.4.x !! OS X !! Cygwin
|-
! Optimized build
| || || X 1
|-
! Python bindings
| || || X 2
|-
! Threading
| || ||
|-
! Real-time simulator
| || X || X
|-
! Emulated Net Device
| || X || X
|-
! Tap Bridge
| || X || X
|-
! Network simulation cradle
| note3 || X || X
|-
! Static builds
| || ||

|}

''Key:'' '''( )'''(empty space) = supported; '''X''' = not supported; '''?''' = unknown; '''dev''' = support in ns-3-dev (next release)

''Notes:''
# Works with gcc4
# Cygwin limitation explained [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings#Cygwin_limitation here]
# NSC works best with gcc-3.4 or gcc-4.2 or greater series. Try to avoid gcc-4.0 and gcc-4.1 series; some build problems have been found with these versions of compilers.

== Prerequisites ==

The core of ns-3 requires a gcc/g++ installation of 3.4 or greater, and python 2.4 or greater. As mentioned above, different options require additional support. This is a list of packages (for Debian/Ubuntu systems) that are needed to support different ns-3 options. Note that other distributions (e.g., Fedora, FreeBSD) may have different package names or capitalization (e.g. ImageMagik). Installation should be similar for Red Hat/Fedora based systems, with "yum" replacing "apt-get", but some differences exist, so below is a guide for both Ubuntu (should generally apply to Debian) and Fedora/RedHat-based systems:

=== Ubuntu/Debian ===

The following list of packages should be accurate for Ubuntu 9.10 release; other releases or other Debian-based systems may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

sudo apt-get install gcc g++ python

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

sudo apt-get install gcc g++ python python-dev

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

sudo apt-get install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

sudo apt-get install bzr

* A GTK-based configuration system

sudo apt-get install libgtk2.0-0 libgtk2.0-dev

* Debugging:

sudo apt-get install gdb valgrind

* Doxygen and related inline documentation:

sudo apt-get install doxygen graphviz imagemagick
sudo apt-get install texlive texlive-pdf texlive-latex-extra texlive-generic-extra texlive-generic-recommended

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

sudo apt-get install texinfo dia texlive texlive-pdf texlive-latex-extra texlive-extra-utils texlive-generic-recommended texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

sudo apt-get install flex bison

* Some basic mobility visualization tests require goocanvas:

sudo apt-get install libgoocanvas-dev

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

sudo apt-get install g++-3.4 gcc-3.4

* To read pcap packet traces

sudo apt-get install tcpdump

* Database support for statistics framework

sudo apt-get install sqlite sqlite3 libsqlite3-dev

* Xml-based version of the config store (requires libxml2 >= version 2.7)

sudo apt-get install libxml2 libxml2-dev

* Support for Gustavo's ns-3-pyviz visualizer

sudo apt-get install python-pygraphviz python-kiwi python-pygoocanvas

=== Fedora/RedHat ===

The following list of packages should be accurate for Fedora 12/CentOS 5.4 release; other releases may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

yum install gcc gcc-c++ python

* '''Note:''' If you are using CentOS 5.4 or RHEL 5, you may want to also get and use the gcc44 packages; see the [[Troubleshooting]] page.

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

yum install gcc gcc-c++ python python-devel

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories. You may want to install mercurial from rpmforge repository (instructions [http://www.trinitycore.org/forum/mercurial-centos-t3113.html here]) or EPEL.

yum install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar. You may need EPEL repository for this.

yum install bzr

* An optional but recommended package (for improving some wireless model fidelity) is GNU scientific library:

yum install gsl gsl-devel

* A GTK-based configuration system

yum install gtk2 gtk2-devel

* Debugging:

yum install gdb valgrind

* Doxygen and related inline documentation:

yum install doxygen graphviz ImageMagick
yum install texinfo texinfo-tex

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

yum install texinfo dia texinfo-tex texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

yum install flex bison

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

yum install compat-gcc-34

* To read pcap packet traces

yum install tcpdump

* Database support for statistics framework

yum install sqlite sqlite-devel

* Xml-based version of the config store (requires libxml2 >= version 2.7)

yum install libxml2 libxml2-devel

=== Gentoo ===

The following list of packages should be accurate for Gentoo as of 04/22/2010; due to possible changes in USE-flags or package names the list may slightly vary.
First of all, become root as usual.

* '''minimal requirements for C++ or Python (release):''' This is the minimal set of packages needed to run ns-3 or to work with Python bindings from a released tarball.

USE="threads -nocxx nptl" emerge -uavN gcc python

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

emerge -av --noreplace mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

USE="curl" emerge -uavN bzr

* A GTK-based configuration system

emerge -av --noreplace gtk+:2

* Debugging:

emerge -av --noreplace gdb valgrind

* Doxygen and related inline documentation; also ns-3 manual and tutorial (written in Texinfo):

USE="extra graphics png" emerge -uavN texlive
USE="cairo graphviz latex png svg" emerge -uavN doxygen imagemagick dia

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

emerge -av --noreplace flex bison

* Some basic mobility visualization tests require goocanvas:

emerge -av --noreplace goocanvas

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

USE="-nocxx nptl" emerge -uavN gcc:3.4

* To read pcap packet traces

emerge -av --noreplace tcpdump

or you may prefer

emerge -av --noreplace wireshark

* Database support for statistics framework

USE="threadsafe" emerge -uavN sqlite:3

* Xml-based version of the config store (requires libxml2 >= version 2.7)

emerge -av --noreplace libxml2

* Support for Gustavo's ns-3-pyviz visualizer (following packages have no stable version as of day of writing, so ~arch for ACCEPT_KEYWORDS)

ACCEPT_KEYWORDS="~x86" emerge -av --noreplace pygraphviz kiwi pygoocanvas

=== Mac OS X (Snow Leopard) ===

Please see [[HOWTO_get_ns-3_running_on_Mac_OS_X_(10.6.2_Intel)]] and follow steps 1 and 2 (prerequisites) and continue reading below if you want to work with a released version, and follow all steps if you want to work with a development version of ns-3.

== Installation ==

The ns-3 code is available in Mercurial repositories on the server http://code.nsnam.org (look for the latest release e.g., "ns-3.4"). You can download a tarball of the latest release at http://www.nsnam.org/releases or you can work with our repositories using Mercurial. We recommend using Mercurial unless there's a good reason not to (See the end of this section for instructions on how to get a tarball release).

The simplest way to get started using Mercurial repositories is to use the '''ns-3-allinone''' environment. This is a set of scripts that manages the downloading and building of various subystems of ns-3 for you. We recommend that you begin your ns-3 adventures in this environment as it can really simplify your life at this point.

=== Downloading ns-3 Using Mercurial ===
One practice is to create a directory called '''repos''' in one's home directory under which one can keep local Mercurial repositories. If you adopt 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
hg clone http://code.nsnam.org/ns-3-allinone

As the hg (Mercurial) command executes, you should see something like the following displayed,

destination directory: ns-3-allinone
requesting all changes
adding changesets
adding manifests
adding file changes
added 26 changesets with 40 changes to 7 files
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 look something like the following:

build.py* constants.py dist.py* download.py* README util.py

Notice that you really just downloaded some Python scripts. The next step will be to use those scripts to download and build the ns-3 distribution of your choice.

If you go to the following link: http://code.nsnam.org/ you will see a number of repositories. Many are the private repositories of the ns-3 development team. The repositories of interest to you will be prefixed with '''ns-3'''. Official releases of ns-3 will be numbered as ns-3.release.hotfix. For example, a second hotfix to a still hypothetical release nine of ns-3 would be numbered as ns-3.9.2 on this page.

We have had a regression testing framework in place since the first release. For each release, a set of output files that define ''good behavior'' are saved. These known good output files are called reference traces and are associated with a given release by name. For example, in http://code.nsnam.org/ you will find a repository named ns-3.1 which is the first stable release of ns-3. You will also find a separate repository named ns-3.1-ref-traces that holds the reference traces for the ns-3.1 release. It is crucial to keep these
files consistent if you want to do any regression testing of your repository. This is a good idea to do at least once to verify everything has built correctly.

The current development snapshot (unreleased) of ns-3 may be found at http://code.nsnam.org/ns-3-dev/ and the associated reference traces may be found http://code.nsnam.org/ns-3-dev-ref-traces/ . The developers attempt to keep these repository in consistent, working states but they are in a development area with unreleased code present, so you may want to consider staying with an official release if you do not need newly-introduced features.

Since the release numbers are going to be changing, we will stick with the more constant ns-3-dev here, but you can replace the string ''ns-3-dev'' with your choice of release (e.g., ns-3.4 and ns-3.4-ref-traces) in the text below. You can find the latest version of the code either by inspection of the repository list or by going to the ''Getting Started'' web page and looking for the latest release identifier.

To download the most common options type the following into your shell (remember you can substitute the name of your chosen release number instead of ns-3-dev)

./download.py -n ns-3-dev -r ns-3-dev-ref-traces

After download process completes, you should have several new directories under ~/repos/ns-3-allinone:

build.py* constants.pyc download.py* ns-3-dev-ref-traces/ pybindgen/ util.py
constants.py dist.py* ns-3-dev/ nsc/ README util.pyc

Go ahead and change into ns-3-dev under your ~/repos/ns-3-allinone directory. You should see something like the following there:

AUTHORS examples/ regression/ scratch/ waf*
bindings/ LICENSE regression.py src/ waf.bat*
CHANGES.html ns3/ RELEASE_NOTES utils/ wscript
doc/ README samples/ VERSION wutils.py

You are now ready to build the ns-3 distribution.

=== Downloading ns-3 Using a Tarball ===

The process for downloading ns-3 via tarball is simpler than the Mercurial process since all of the pieces are pre-packaged for you. You just have to pick a release, download it and decompress it.

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. 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):

cd
mkdir tarballs
cd tarballs
wget http://www.nsnam.org/releases/ns-allinone-3.6.tar.bz2
tar xjf ns-allinone-3.6.tar.bz2

If you change into the directory '''ns-allinone-3.6''' you should see a number of files:

build.py* ns-3.6/ nsc-0.5.1/ README
constants.py ns-3.6-ref-traces/ pybindgen-0.12.0.703/ util.py

You are now ready to build the ns-3 distribution.

== Building ns-3 with ns-3-allinone ==

The first time you build the ns-3 project you should build using the allinone environment. This will get the project configured for you
in the most commonly useful way.

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-3-allinone-3.4 under your ~/tarballs directory. Type the following:

./build.py

You will see lots of typical compiler output messages displayed as the build script builds the various pieces you downloaded. Eventually you should see the following magic words:

Build finished successfully (00:02:37)
Leaving directory `./ns-3-dev'

Once the project has built you typically will not use ns-3-allinone scripts. You will now interact directly with Waf and we '''do it in the ns-3-dev directory and not in the ns-3-allinone directory'''.

=== Configuration with Waf ===

To see valid configure options, type ./waf --help. The most important option is -d <debug level>. Valid debug levels (which are listed in waf --help) are: "debug" or "optimized". It is also possible to change the flags used for compilation with (e.g.):

CXXFLAGS="-O3" ./waf configure

or, alternately, the gcc compiler

CXX=g++-3.4 ./waf configure

'''Note:''' Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than
the build stage (i.e., "./waf -d optimized" will not work; instead, do

./waf -d optimized configure; ./waf

The resulting binaries are placed in build/<debuglevel>/srcpath. For example, in a debug build you can find the executable for the first.cc example as build/debug/examples/first. You can debug the executable directly by:

./waf --shell
cd build/debug/examples
gdb first

Of course, you can run gdb in emacs, or use your favorite debugger such as ddd or insight just as easily. In an optimized build you can find the executable for the first.cc example as build/optimized/examples/first.

In order to forcibly disable python bindings, you can provide the following option:

./waf --disable-python configure

In order to tell the build system to use the sudo program to set the suid bit if required, you can provide the following option:

./waf --enable-sudo configure

To start over a configuration from scratch, type:

./waf distclean

Or if you get stuck and all else fails:

rm -rf build

followed by changing back into ns-3-allinone and doing:

./build.py

will basically reset your build state.

To see all waf options:

./waf --help

== Validating ==

ns-3 has unit tests that can be run to verify the installation:

./test.py

which should produce output like:
<pre>
PASS: TestSuite histogram
PASS: TestSuite ns3-wifi-interference
PASS: TestSuite ns3-tcp-cwnd
PASS: TestSuite ns3-tcp-interoperability
PASS: TestSuite sample
...
</pre>

To run the regression tests mentioned above:

./waf --regression

== Using Python ==

See [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings this page].

== Troubleshooting ==

See [http://www.nsnam.org/wiki/index.php/Troubleshooting this page].

----
[[User:Craigdo|Craigdo]] 04:40, 5 November 2009 (UTC)

Installation

2010-04-22T18:23:10Z

Hippo: /* Fedora/RedHat */

{{TOC}}

This is a detailed installation guide for ns-3. Basic installation instructions can be found at the [http://www.nsnam.org/getting_started.html Getting Started] page or in the [http://www.nsnam.org/docs/release/tutorial/tutorial.html ns-3 tutorial].

== Supported platforms ==

ns-3 is primarily developed on GNU/Linux platforms, and the minimal requirements to run basic simulations are a gcc installation of gcc-3.4/g++-3.4 or greater, and python 2.4 or greater.

ns-3 is supported on the following primary platforms:

# Linux x86 gcc 4.2, 4.1, and, 3.4.6.
# Linux x86_64 gcc 4.4.0, 4.3.2, 4.2.3, 4.2.1, 4.1.3, 3.4.6
# MacOS X ppc and x86 (gcc 4.0.x and 4.2.x)
# [http://www.cygwin.com Cygwin] gcc 3.4.4 (debug only), gcc 4.3.2 (debug and optimized)

By supported, we mean that the project tries to support most or all of the build options on these platforms unless there is a good reason to exclude the option; and at least the debug build will compile. If you intend to do serious work using ns-3, and are forced by circumstances to use a Windows platform, consider virtualization of a popular Linux platform. This may be more time-consuming than installing a minimal Cygwin, for example, but you end up with a fully functional Linux system and ns-3 distribution. Some quick performance comparisons between Cygwin and VirtualBoxed Fedora 11 indicate that examples can actually run faster under VirtualBox.

We provide HOWTO documents describing the process for installing Linux support and getting ns-3 running using two popular virtualization products: VirtualBox ([[HOWTO use VirtualBox to run simulations on Windows machines]]) and VMware ([[HOWTO use VMware to set up virtual networks (Windows)]]).

ns-3 may also run on currently unsupported platforms. For example, an alternative Windows platform is MinGW. There are maintainers who attempt to keep a subset of ns-3 running on MinGW, but it is not "officially" suppported. This means that bugs filed against MinGW will be addressed as time permits. Additionally, the Eclipse IDE is used by some developers, but the project does not actively support this environment.

Additional maintainers are invited to make more platforms, compilers and environments supported.

=== ns-3 options ===

There are a few options that are not enabled by default and are not available on all platforms. At the end of the configuration process (explained below), the status of these options are shown as detected by a '''waf''' script:

<pre>
---- Summary of optional NS-3 features:
Threading Primitives : enabled
Real Time Simulator : enabled
Emulated Net Device : enabled
Tap Bridge : enabled
GtkConfigStore : enabled
XmlIo : not enabled (library 'libxml-2.0 >= 2.7' not found)
SQlite stats data output : enabled
Network Simulation Cradle : enabled
Python Bindings : not enabled (disabled by user request)
Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
Static build : not enabled (option --enable-static not selected)
</pre>

Generally if the platform is missing some requirement for an option it is marked as "not enabled." Note that "disabled by user request" will be shown when the user explicitly disables a feature (such as "--disable-python"); and if a feature defaults to disabled this will also be noted (e.g., option --enable-sudo not selected).

The table below is meant to help sort out the different features and on which platforms they are supported. This table reflects the status of the most recent release version (ns-3.6):

{| border=1 cellspacing=0 cellpadding=3

|+ Option status
! Option !! Linux gcc-4.x,gcc-3.4.x !! OS X !! Cygwin
|-
! Optimized build
| || || X 1
|-
! Python bindings
| || || X 2
|-
! Threading
| || ||
|-
! Real-time simulator
| || X || X
|-
! Emulated Net Device
| || X || X
|-
! Tap Bridge
| || X || X
|-
! Network simulation cradle
| note3 || X || X
|-
! Static builds
| || ||

|}

''Key:'' '''( )'''(empty space) = supported; '''X''' = not supported; '''?''' = unknown; '''dev''' = support in ns-3-dev (next release)

''Notes:''
# Works with gcc4
# Cygwin limitation explained [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings#Cygwin_limitation here]
# NSC works best with gcc-3.4 or gcc-4.2 or greater series. Try to avoid gcc-4.0 and gcc-4.1 series; some build problems have been found with these versions of compilers.

== Prerequisites ==

The core of ns-3 requires a gcc/g++ installation of 3.4 or greater, and python 2.4 or greater. As mentioned above, different options require additional support. This is a list of packages (for Debian/Ubuntu systems) that are needed to support different ns-3 options. Note that other distributions (e.g., Fedora, FreeBSD) may have different package names or capitalization (e.g. ImageMagik). Installation should be similar for Red Hat/Fedora based systems, with "yum" replacing "apt-get", but some differences exist, so below is a guide for both Ubuntu (should generally apply to Debian) and Fedora/RedHat-based systems:

=== Ubuntu/Debian ===

The following list of packages should be accurate for Ubuntu 9.10 release; other releases or other Debian-based systems may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

sudo apt-get install gcc g++ python

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

sudo apt-get install gcc g++ python python-dev

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

sudo apt-get install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

sudo apt-get install bzr

* A GTK-based configuration system

sudo apt-get install libgtk2.0-0 libgtk2.0-dev

* Debugging:

sudo apt-get install gdb valgrind

* Doxygen and related inline documentation:

sudo apt-get install doxygen graphviz imagemagick
sudo apt-get install texlive texlive-pdf texlive-latex-extra texlive-generic-extra texlive-generic-recommended

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

sudo apt-get install texinfo dia texlive texlive-pdf texlive-latex-extra texlive-extra-utils texlive-generic-recommended texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

sudo apt-get install flex bison

* Some basic mobility visualization tests require goocanvas:

sudo apt-get install libgoocanvas-dev

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

sudo apt-get install g++-3.4 gcc-3.4

* To read pcap packet traces

sudo apt-get install tcpdump

* Database support for statistics framework

sudo apt-get install sqlite sqlite3 libsqlite3-dev

* Xml-based version of the config store (requires libxml2 >= version 2.7)

sudo apt-get install libxml2 libxml2-dev

* Support for Gustavo's ns-3-pyviz visualizer

sudo apt-get install python-pygraphviz python-kiwi python-pygoocanvas

=== Fedora/RedHat ===

The following list of packages should be accurate for Fedora 12/CentOS 5.4 release; other releases may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

yum install gcc gcc-c++ python

* '''Note:''' If you are using CentOS 5.4 or RHEL 5, you may want to also get and use the gcc44 packages; see the [[Troubleshooting]] page.

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

yum install gcc gcc-c++ python python-devel

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories. You may want to install mercurial from rpmforge repository (instructions [http://www.trinitycore.org/forum/mercurial-centos-t3113.html here]) or EPEL.

yum install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar. You may need EPEL repository for this.

yum install bzr

* An optional but recommended package (for improving some wireless model fidelity) is GNU scientific library:

yum install gsl gsl-devel

* A GTK-based configuration system

yum install gtk2 gtk2-devel

* Debugging:

yum install gdb valgrind

* Doxygen and related inline documentation:

yum install doxygen graphviz ImageMagick
yum install texinfo texinfo-tex

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

yum install texinfo dia texinfo-tex texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

yum install flex bison

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

yum install compat-gcc-34

* To read pcap packet traces

yum install tcpdump

* Database support for statistics framework

yum install sqlite sqlite-devel

* Xml-based version of the config store (requires libxml2 >= version 2.7)

yum install libxml2 libxml2-devel

=== Gentoo ===

The following list of packages should be accurate for Gentoo as of 04/22/2010; due to possible changes in USE-flags or package names the list may slightly vary.
First of all, become root as usual.

* '''minimal requirements for C++ or Python (release):''' This is the minimal set of packages needed to run ns-3 or to work with Python bindings from a released tarball.

USE="threads -nocxx nptl" emerge -uavN gcc python

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

emerge -av --noreplace mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

USE="curl" emerge -uavN bzr

* A GTK-based configuration system

emerge -av --noreplace gtk+:2

* Debugging:

emerge -av --noreplace gdb valgrind

* Doxygen and related inline documentation; also ns-3 manual and tutorial (written in Texinfo):

USE="graphics png extra" emerge -uavN texlive
USE="latex graphviz png svg cairo" emerge -uavN doxygen imagemagick dia

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

emerge -av --noreplace flex bison

* Some basic mobility visualization tests require goocanvas:

emerge -av --noreplace goocanvas

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

USE="-nocxx nptl" emerge -uavN gcc:3.4

* To read pcap packet traces

emerge -av --noreplace tcpdump

or you may prefer

emerge -av --noreplace wireshark

* Database support for statistics framework

USE="threadsafe" emerge -uavN sqlite:3

* Xml-based version of the config store (requires libxml2 >= version 2.7)

emerge -av --noreplace libxml2

* Support for Gustavo's ns-3-pyviz visualizer (following packages have no stable version as of day of writing, so ~arch for ACCEPT_KEYWORDS)

ACCEPT_KEYWORDS="~x86" emerge -av --noreplace pygraphviz kiwi pygoocanvas

=== Mac OS X (Snow Leopard) ===

Please see [[HOWTO_get_ns-3_running_on_Mac_OS_X_(10.6.2_Intel)]] and follow steps 1 and 2 (prerequisites) and continue reading below if you want to work with a released version, and follow all steps if you want to work with a development version of ns-3.

== Installation ==

The ns-3 code is available in Mercurial repositories on the server http://code.nsnam.org (look for the latest release e.g., "ns-3.4"). You can download a tarball of the latest release at http://www.nsnam.org/releases or you can work with our repositories using Mercurial. We recommend using Mercurial unless there's a good reason not to (See the end of this section for instructions on how to get a tarball release).

The simplest way to get started using Mercurial repositories is to use the '''ns-3-allinone''' environment. This is a set of scripts that manages the downloading and building of various subystems of ns-3 for you. We recommend that you begin your ns-3 adventures in this environment as it can really simplify your life at this point.

=== Downloading ns-3 Using Mercurial ===
One practice is to create a directory called '''repos''' in one's home directory under which one can keep local Mercurial repositories. If you adopt 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
hg clone http://code.nsnam.org/ns-3-allinone

As the hg (Mercurial) command executes, you should see something like the following displayed,

destination directory: ns-3-allinone
requesting all changes
adding changesets
adding manifests
adding file changes
added 26 changesets with 40 changes to 7 files
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 look something like the following:

build.py* constants.py dist.py* download.py* README util.py

Notice that you really just downloaded some Python scripts. The next step will be to use those scripts to download and build the ns-3 distribution of your choice.

If you go to the following link: http://code.nsnam.org/ you will see a number of repositories. Many are the private repositories of the ns-3 development team. The repositories of interest to you will be prefixed with '''ns-3'''. Official releases of ns-3 will be numbered as ns-3.release.hotfix. For example, a second hotfix to a still hypothetical release nine of ns-3 would be numbered as ns-3.9.2 on this page.

We have had a regression testing framework in place since the first release. For each release, a set of output files that define ''good behavior'' are saved. These known good output files are called reference traces and are associated with a given release by name. For example, in http://code.nsnam.org/ you will find a repository named ns-3.1 which is the first stable release of ns-3. You will also find a separate repository named ns-3.1-ref-traces that holds the reference traces for the ns-3.1 release. It is crucial to keep these
files consistent if you want to do any regression testing of your repository. This is a good idea to do at least once to verify everything has built correctly.

The current development snapshot (unreleased) of ns-3 may be found at http://code.nsnam.org/ns-3-dev/ and the associated reference traces may be found http://code.nsnam.org/ns-3-dev-ref-traces/ . The developers attempt to keep these repository in consistent, working states but they are in a development area with unreleased code present, so you may want to consider staying with an official release if you do not need newly-introduced features.

Since the release numbers are going to be changing, we will stick with the more constant ns-3-dev here, but you can replace the string ''ns-3-dev'' with your choice of release (e.g., ns-3.4 and ns-3.4-ref-traces) in the text below. You can find the latest version of the code either by inspection of the repository list or by going to the ''Getting Started'' web page and looking for the latest release identifier.

To download the most common options type the following into your shell (remember you can substitute the name of your chosen release number instead of ns-3-dev)

./download.py -n ns-3-dev -r ns-3-dev-ref-traces

After download process completes, you should have several new directories under ~/repos/ns-3-allinone:

build.py* constants.pyc download.py* ns-3-dev-ref-traces/ pybindgen/ util.py
constants.py dist.py* ns-3-dev/ nsc/ README util.pyc

Go ahead and change into ns-3-dev under your ~/repos/ns-3-allinone directory. You should see something like the following there:

AUTHORS examples/ regression/ scratch/ waf*
bindings/ LICENSE regression.py src/ waf.bat*
CHANGES.html ns3/ RELEASE_NOTES utils/ wscript
doc/ README samples/ VERSION wutils.py

You are now ready to build the ns-3 distribution.

=== Downloading ns-3 Using a Tarball ===

The process for downloading ns-3 via tarball is simpler than the Mercurial process since all of the pieces are pre-packaged for you. You just have to pick a release, download it and decompress it.

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. 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):

cd
mkdir tarballs
cd tarballs
wget http://www.nsnam.org/releases/ns-allinone-3.6.tar.bz2
tar xjf ns-allinone-3.6.tar.bz2

If you change into the directory '''ns-allinone-3.6''' you should see a number of files:

build.py* ns-3.6/ nsc-0.5.1/ README
constants.py ns-3.6-ref-traces/ pybindgen-0.12.0.703/ util.py

You are now ready to build the ns-3 distribution.

== Building ns-3 with ns-3-allinone ==

The first time you build the ns-3 project you should build using the allinone environment. This will get the project configured for you
in the most commonly useful way.

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-3-allinone-3.4 under your ~/tarballs directory. Type the following:

./build.py

You will see lots of typical compiler output messages displayed as the build script builds the various pieces you downloaded. Eventually you should see the following magic words:

Build finished successfully (00:02:37)
Leaving directory `./ns-3-dev'

Once the project has built you typically will not use ns-3-allinone scripts. You will now interact directly with Waf and we '''do it in the ns-3-dev directory and not in the ns-3-allinone directory'''.

=== Configuration with Waf ===

To see valid configure options, type ./waf --help. The most important option is -d <debug level>. Valid debug levels (which are listed in waf --help) are: "debug" or "optimized". It is also possible to change the flags used for compilation with (e.g.):

CXXFLAGS="-O3" ./waf configure

or, alternately, the gcc compiler

CXX=g++-3.4 ./waf configure

'''Note:''' Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than
the build stage (i.e., "./waf -d optimized" will not work; instead, do

./waf -d optimized configure; ./waf

The resulting binaries are placed in build/<debuglevel>/srcpath. For example, in a debug build you can find the executable for the first.cc example as build/debug/examples/first. You can debug the executable directly by:

./waf --shell
cd build/debug/examples
gdb first

Of course, you can run gdb in emacs, or use your favorite debugger such as ddd or insight just as easily. In an optimized build you can find the executable for the first.cc example as build/optimized/examples/first.

In order to forcibly disable python bindings, you can provide the following option:

./waf --disable-python configure

In order to tell the build system to use the sudo program to set the suid bit if required, you can provide the following option:

./waf --enable-sudo configure

To start over a configuration from scratch, type:

./waf distclean

Or if you get stuck and all else fails:

rm -rf build

followed by changing back into ns-3-allinone and doing:

./build.py

will basically reset your build state.

To see all waf options:

./waf --help

== Validating ==

ns-3 has unit tests that can be run to verify the installation:

./test.py

which should produce output like:
<pre>
PASS: TestSuite histogram
PASS: TestSuite ns3-wifi-interference
PASS: TestSuite ns3-tcp-cwnd
PASS: TestSuite ns3-tcp-interoperability
PASS: TestSuite sample
...
</pre>

To run the regression tests mentioned above:

./waf --regression

== Using Python ==

See [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings this page].

== Troubleshooting ==

See [http://www.nsnam.org/wiki/index.php/Troubleshooting this page].

----
[[User:Craigdo|Craigdo]] 04:40, 5 November 2009 (UTC)

Installation

2010-04-22T18:22:19Z

Hippo: added Gentoo installation instructions

{{TOC}}

This is a detailed installation guide for ns-3. Basic installation instructions can be found at the [http://www.nsnam.org/getting_started.html Getting Started] page or in the [http://www.nsnam.org/docs/release/tutorial/tutorial.html ns-3 tutorial].

== Supported platforms ==

ns-3 is primarily developed on GNU/Linux platforms, and the minimal requirements to run basic simulations are a gcc installation of gcc-3.4/g++-3.4 or greater, and python 2.4 or greater.

ns-3 is supported on the following primary platforms:

# Linux x86 gcc 4.2, 4.1, and, 3.4.6.
# Linux x86_64 gcc 4.4.0, 4.3.2, 4.2.3, 4.2.1, 4.1.3, 3.4.6
# MacOS X ppc and x86 (gcc 4.0.x and 4.2.x)
# [http://www.cygwin.com Cygwin] gcc 3.4.4 (debug only), gcc 4.3.2 (debug and optimized)

By supported, we mean that the project tries to support most or all of the build options on these platforms unless there is a good reason to exclude the option; and at least the debug build will compile. If you intend to do serious work using ns-3, and are forced by circumstances to use a Windows platform, consider virtualization of a popular Linux platform. This may be more time-consuming than installing a minimal Cygwin, for example, but you end up with a fully functional Linux system and ns-3 distribution. Some quick performance comparisons between Cygwin and VirtualBoxed Fedora 11 indicate that examples can actually run faster under VirtualBox.

We provide HOWTO documents describing the process for installing Linux support and getting ns-3 running using two popular virtualization products: VirtualBox ([[HOWTO use VirtualBox to run simulations on Windows machines]]) and VMware ([[HOWTO use VMware to set up virtual networks (Windows)]]).

ns-3 may also run on currently unsupported platforms. For example, an alternative Windows platform is MinGW. There are maintainers who attempt to keep a subset of ns-3 running on MinGW, but it is not "officially" suppported. This means that bugs filed against MinGW will be addressed as time permits. Additionally, the Eclipse IDE is used by some developers, but the project does not actively support this environment.

Additional maintainers are invited to make more platforms, compilers and environments supported.

=== ns-3 options ===

There are a few options that are not enabled by default and are not available on all platforms. At the end of the configuration process (explained below), the status of these options are shown as detected by a '''waf''' script:

<pre>
---- Summary of optional NS-3 features:
Threading Primitives : enabled
Real Time Simulator : enabled
Emulated Net Device : enabled
Tap Bridge : enabled
GtkConfigStore : enabled
XmlIo : not enabled (library 'libxml-2.0 >= 2.7' not found)
SQlite stats data output : enabled
Network Simulation Cradle : enabled
Python Bindings : not enabled (disabled by user request)
Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
Static build : not enabled (option --enable-static not selected)
</pre>

Generally if the platform is missing some requirement for an option it is marked as "not enabled." Note that "disabled by user request" will be shown when the user explicitly disables a feature (such as "--disable-python"); and if a feature defaults to disabled this will also be noted (e.g., option --enable-sudo not selected).

The table below is meant to help sort out the different features and on which platforms they are supported. This table reflects the status of the most recent release version (ns-3.6):

{| border=1 cellspacing=0 cellpadding=3

|+ Option status
! Option !! Linux gcc-4.x,gcc-3.4.x !! OS X !! Cygwin
|-
! Optimized build
| || || X 1
|-
! Python bindings
| || || X 2
|-
! Threading
| || ||
|-
! Real-time simulator
| || X || X
|-
! Emulated Net Device
| || X || X
|-
! Tap Bridge
| || X || X
|-
! Network simulation cradle
| note3 || X || X
|-
! Static builds
| || ||

|}

''Key:'' '''( )'''(empty space) = supported; '''X''' = not supported; '''?''' = unknown; '''dev''' = support in ns-3-dev (next release)

''Notes:''
# Works with gcc4
# Cygwin limitation explained [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings#Cygwin_limitation here]
# NSC works best with gcc-3.4 or gcc-4.2 or greater series. Try to avoid gcc-4.0 and gcc-4.1 series; some build problems have been found with these versions of compilers.

== Prerequisites ==

The core of ns-3 requires a gcc/g++ installation of 3.4 or greater, and python 2.4 or greater. As mentioned above, different options require additional support. This is a list of packages (for Debian/Ubuntu systems) that are needed to support different ns-3 options. Note that other distributions (e.g., Fedora, FreeBSD) may have different package names or capitalization (e.g. ImageMagik). Installation should be similar for Red Hat/Fedora based systems, with "yum" replacing "apt-get", but some differences exist, so below is a guide for both Ubuntu (should generally apply to Debian) and Fedora/RedHat-based systems:

=== Ubuntu/Debian ===

The following list of packages should be accurate for Ubuntu 9.10 release; other releases or other Debian-based systems may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

sudo apt-get install gcc g++ python

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

sudo apt-get install gcc g++ python python-dev

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

sudo apt-get install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

sudo apt-get install bzr

* A GTK-based configuration system

sudo apt-get install libgtk2.0-0 libgtk2.0-dev

* Debugging:

sudo apt-get install gdb valgrind

* Doxygen and related inline documentation:

sudo apt-get install doxygen graphviz imagemagick
sudo apt-get install texlive texlive-pdf texlive-latex-extra texlive-generic-extra texlive-generic-recommended

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

sudo apt-get install texinfo dia texlive texlive-pdf texlive-latex-extra texlive-extra-utils texlive-generic-recommended texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

sudo apt-get install flex bison

* Some basic mobility visualization tests require goocanvas:

sudo apt-get install libgoocanvas-dev

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

sudo apt-get install g++-3.4 gcc-3.4

* To read pcap packet traces

sudo apt-get install tcpdump

* Database support for statistics framework

sudo apt-get install sqlite sqlite3 libsqlite3-dev

* Xml-based version of the config store (requires libxml2 >= version 2.7)

sudo apt-get install libxml2 libxml2-dev

* Support for Gustavo's ns-3-pyviz visualizer

sudo apt-get install python-pygraphviz python-kiwi python-pygoocanvas

=== Fedora/RedHat ===

The following list of packages should be accurate for Fedora 12/CentOS 5.4 release; other releases or other Debian-based systems may slightly vary.

* '''minimal requirements for C++ (release):''' This is the minimal set of packages needed to run ns-3 from a released tarball.

yum install gcc gcc-c++ python

* '''Note:''' If you are using CentOS 5.4 or RHEL 5, you may want to also get and use the gcc44 packages; see the [[Troubleshooting]] page.

* '''minimal requirements for Python (release):''' This is the minimal set of packages needed to work with Python bindings from a released tarball.

yum install gcc gcc-c++ python python-devel

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories. You may want to install mercurial from rpmforge repository (instructions [http://www.trinitycore.org/forum/mercurial-centos-t3113.html here]) or EPEL.

yum install mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar. You may need EPEL repository for this.

yum install bzr

* An optional but recommended package (for improving some wireless model fidelity) is GNU scientific library:

yum install gsl gsl-devel

* A GTK-based configuration system

yum install gtk2 gtk2-devel

* Debugging:

yum install gdb valgrind

* Doxygen and related inline documentation:

yum install doxygen graphviz ImageMagick
yum install texinfo texinfo-tex

* The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):

yum install texinfo dia texinfo-tex texi2html

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

yum install flex bison

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

yum install compat-gcc-34

* To read pcap packet traces

yum install tcpdump

* Database support for statistics framework

yum install sqlite sqlite-devel

* Xml-based version of the config store (requires libxml2 >= version 2.7)

yum install libxml2 libxml2-devel

=== Gentoo ===

The following list of packages should be accurate for Gentoo as of 04/22/2010; due to possible changes in USE-flags or package names the list may slightly vary.
First of all, become root as usual.

* '''minimal requirements for C++ or Python (release):''' This is the minimal set of packages needed to run ns-3 or to work with Python bindings from a released tarball.

USE="threads -nocxx nptl" emerge -uavN gcc python

* Running regression tests requires mercurial to fetch the trace repositories. mercurial is also needed in general to work with ns-3 development repositories.

emerge -av --noreplace mercurial

* Running python bindings from the ns-3 development tree (ns-3-dev) requires bazaar

USE="curl" emerge -uavN bzr

* A GTK-based configuration system

emerge -av --noreplace gtk+:2

* Debugging:

emerge -av --noreplace gdb valgrind

* Doxygen and related inline documentation; also ns-3 manual and tutorial (written in Texinfo):

USE="graphics png extra" emerge -uavN texlive
USE="latex graphviz png svg cairo" emerge -uavN doxygen imagemagick dia

* The Network Simulation Cradle (nsc) requires the flex lexical analyzer and bison parser generator:

emerge -av --noreplace flex bison

* Some basic mobility visualization tests require goocanvas:

emerge -av --noreplace goocanvas

* To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:

USE="-nocxx nptl" emerge -uavN gcc:3.4

* To read pcap packet traces

emerge -av --noreplace tcpdump

or you may prefer

emerge -av --noreplace wireshark

* Database support for statistics framework

USE="threadsafe" emerge -uavN sqlite:3

* Xml-based version of the config store (requires libxml2 >= version 2.7)

emerge -av --noreplace libxml2

* Support for Gustavo's ns-3-pyviz visualizer (following packages have no stable version as of day of writing, so ~arch for ACCEPT_KEYWORDS)

ACCEPT_KEYWORDS="~x86" emerge -av --noreplace pygraphviz kiwi pygoocanvas

=== Mac OS X (Snow Leopard) ===

Please see [[HOWTO_get_ns-3_running_on_Mac_OS_X_(10.6.2_Intel)]] and follow steps 1 and 2 (prerequisites) and continue reading below if you want to work with a released version, and follow all steps if you want to work with a development version of ns-3.

== Installation ==

The ns-3 code is available in Mercurial repositories on the server http://code.nsnam.org (look for the latest release e.g., "ns-3.4"). You can download a tarball of the latest release at http://www.nsnam.org/releases or you can work with our repositories using Mercurial. We recommend using Mercurial unless there's a good reason not to (See the end of this section for instructions on how to get a tarball release).

The simplest way to get started using Mercurial repositories is to use the '''ns-3-allinone''' environment. This is a set of scripts that manages the downloading and building of various subystems of ns-3 for you. We recommend that you begin your ns-3 adventures in this environment as it can really simplify your life at this point.

=== Downloading ns-3 Using Mercurial ===
One practice is to create a directory called '''repos''' in one's home directory under which one can keep local Mercurial repositories. If you adopt 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
hg clone http://code.nsnam.org/ns-3-allinone

As the hg (Mercurial) command executes, you should see something like the following displayed,

destination directory: ns-3-allinone
requesting all changes
adding changesets
adding manifests
adding file changes
added 26 changesets with 40 changes to 7 files
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 look something like the following:

build.py* constants.py dist.py* download.py* README util.py

Notice that you really just downloaded some Python scripts. The next step will be to use those scripts to download and build the ns-3 distribution of your choice.

If you go to the following link: http://code.nsnam.org/ you will see a number of repositories. Many are the private repositories of the ns-3 development team. The repositories of interest to you will be prefixed with '''ns-3'''. Official releases of ns-3 will be numbered as ns-3.release.hotfix. For example, a second hotfix to a still hypothetical release nine of ns-3 would be numbered as ns-3.9.2 on this page.

We have had a regression testing framework in place since the first release. For each release, a set of output files that define ''good behavior'' are saved. These known good output files are called reference traces and are associated with a given release by name. For example, in http://code.nsnam.org/ you will find a repository named ns-3.1 which is the first stable release of ns-3. You will also find a separate repository named ns-3.1-ref-traces that holds the reference traces for the ns-3.1 release. It is crucial to keep these
files consistent if you want to do any regression testing of your repository. This is a good idea to do at least once to verify everything has built correctly.

The current development snapshot (unreleased) of ns-3 may be found at http://code.nsnam.org/ns-3-dev/ and the associated reference traces may be found http://code.nsnam.org/ns-3-dev-ref-traces/ . The developers attempt to keep these repository in consistent, working states but they are in a development area with unreleased code present, so you may want to consider staying with an official release if you do not need newly-introduced features.

Since the release numbers are going to be changing, we will stick with the more constant ns-3-dev here, but you can replace the string ''ns-3-dev'' with your choice of release (e.g., ns-3.4 and ns-3.4-ref-traces) in the text below. You can find the latest version of the code either by inspection of the repository list or by going to the ''Getting Started'' web page and looking for the latest release identifier.

To download the most common options type the following into your shell (remember you can substitute the name of your chosen release number instead of ns-3-dev)

./download.py -n ns-3-dev -r ns-3-dev-ref-traces

After download process completes, you should have several new directories under ~/repos/ns-3-allinone:

build.py* constants.pyc download.py* ns-3-dev-ref-traces/ pybindgen/ util.py
constants.py dist.py* ns-3-dev/ nsc/ README util.pyc

Go ahead and change into ns-3-dev under your ~/repos/ns-3-allinone directory. You should see something like the following there:

AUTHORS examples/ regression/ scratch/ waf*
bindings/ LICENSE regression.py src/ waf.bat*
CHANGES.html ns3/ RELEASE_NOTES utils/ wscript
doc/ README samples/ VERSION wutils.py

You are now ready to build the ns-3 distribution.

=== Downloading ns-3 Using a Tarball ===

The process for downloading ns-3 via tarball is simpler than the Mercurial process since all of the pieces are pre-packaged for you. You just have to pick a release, download it and decompress it.

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. 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):

cd
mkdir tarballs
cd tarballs
wget http://www.nsnam.org/releases/ns-allinone-3.6.tar.bz2
tar xjf ns-allinone-3.6.tar.bz2

If you change into the directory '''ns-allinone-3.6''' you should see a number of files:

build.py* ns-3.6/ nsc-0.5.1/ README
constants.py ns-3.6-ref-traces/ pybindgen-0.12.0.703/ util.py

You are now ready to build the ns-3 distribution.

== Building ns-3 with ns-3-allinone ==

The first time you build the ns-3 project you should build using the allinone environment. This will get the project configured for you
in the most commonly useful way.

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-3-allinone-3.4 under your ~/tarballs directory. Type the following:

./build.py

You will see lots of typical compiler output messages displayed as the build script builds the various pieces you downloaded. Eventually you should see the following magic words:

Build finished successfully (00:02:37)
Leaving directory `./ns-3-dev'

Once the project has built you typically will not use ns-3-allinone scripts. You will now interact directly with Waf and we '''do it in the ns-3-dev directory and not in the ns-3-allinone directory'''.

=== Configuration with Waf ===

To see valid configure options, type ./waf --help. The most important option is -d <debug level>. Valid debug levels (which are listed in waf --help) are: "debug" or "optimized". It is also possible to change the flags used for compilation with (e.g.):

CXXFLAGS="-O3" ./waf configure

or, alternately, the gcc compiler

CXX=g++-3.4 ./waf configure

'''Note:''' Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than
the build stage (i.e., "./waf -d optimized" will not work; instead, do

./waf -d optimized configure; ./waf

The resulting binaries are placed in build/<debuglevel>/srcpath. For example, in a debug build you can find the executable for the first.cc example as build/debug/examples/first. You can debug the executable directly by:

./waf --shell
cd build/debug/examples
gdb first

Of course, you can run gdb in emacs, or use your favorite debugger such as ddd or insight just as easily. In an optimized build you can find the executable for the first.cc example as build/optimized/examples/first.

In order to forcibly disable python bindings, you can provide the following option:

./waf --disable-python configure

In order to tell the build system to use the sudo program to set the suid bit if required, you can provide the following option:

./waf --enable-sudo configure

To start over a configuration from scratch, type:

./waf distclean

Or if you get stuck and all else fails:

rm -rf build

followed by changing back into ns-3-allinone and doing:

./build.py

will basically reset your build state.

To see all waf options:

./waf --help

== Validating ==

ns-3 has unit tests that can be run to verify the installation:

./test.py

which should produce output like:
<pre>
PASS: TestSuite histogram
PASS: TestSuite ns3-wifi-interference
PASS: TestSuite ns3-tcp-cwnd
PASS: TestSuite ns3-tcp-interoperability
PASS: TestSuite sample
...
</pre>

To run the regression tests mentioned above:

./waf --regression

== Using Python ==

See [http://www.nsnam.org/wiki/index.php/NS-3_Python_Bindings this page].

== Troubleshooting ==

See [http://www.nsnam.org/wiki/index.php/Troubleshooting this page].

----
[[User:Craigdo|Craigdo]] 04:40, 5 November 2009 (UTC)

Ns-3.8

2010-03-09T18:09:59Z

Hippo: /* Matrix propagation loss model */

{{TOC}}

This page summarizes the ongoing release planning for ns-3.8. The release manager is Josh Pelkey <jpelkey@gatech.edu>.

== Tentative ns-3.8 Release Schedule ==

# <s>January 27 -- ns-3.7 posted</s>
# <s>January 27 -- ns-3.8 '''''Open phase begins'''''</s>
# <s>March 8 -- Deadline for new feature merge</s>
# March 8 -- Begin the phase of small feature development and bug fixing
# March 27 -- Small feature development and bug fixing ends
# March 27 -- '''''Open phase ends'''''
# March 27 -- '''''Maintenance phase begins'''''
# April 13 -- '''''Maintenance phase ends'''''
# April 13 -- '''''Code freeze phase begins'''''
# April 13 -- ns-3.8-RC1
# April 15 -- ns-3.8-RC2
# April 19 -- ns-3.8-RC3
# April 22 -- ns-3.8-RC4
# April 27 -- ns-3.8 posted
# April 27 -- '''''Code freeze phase ends'''''
# April 27 -- ns-3.9 Open phase begins

As described in the [[Roadmap]] there are three broad sections in the release schedule. During the open phase, people wanting to include a new feature in ns-3.8 should contact Josh and arrange to have their features merged into ns-3-dev. You will be expected to provide the following:

* A mercurial patch, bundle or repo against the current version of ns-3-dev that contains your proposed feature addition. You need to make sure that we can apply this patch and build and run (debug and optimized as appropriate) all unit and regression tests successfully on all of our target machines
* A summary of the additions you are proposing and an explanation of any changes to existing code that had to be done in order to support your feature (this will be used to generate release notes and will be provided to maintainers if a code review is indicated)
* Some kind of unit or system test that can be used to determine if your feature is actually working at each stage of the integration

One of us will take a quick look at your proposed addition and determine if a code review is required. According to the ''book of instructions'' a code review requiring positive acknowledgment by maintainers is indicated if:

* Your proposed feature does not work with all models or on all platforms
* Your feature changes pre-existing APIs
* Your feature crosses maintainer boundaries

Just to be safe, we will probably run a feature submission by at least one maintainer according to the general area of applicability of the feature. For example, if you submit an entirely new device driver model, as a courtesy we will run this submission by the maintainers of the current devices. The maintainers won't have any responsibility to positively ack the submission, but we will take some time to allow a reasonable review.

The open phase is divided into two parts: new feature merge period and small feature development and bug fixing.

During the new feature merge period we can:
* Review the code that might be merged
* Clean up the bug tracker: solve as much bugs as possible
* Merge the new features that has +1 and from maintainers

After March 8th, the new feature merge period ends and small feature development and bug fixes begins. During the latter, no more merges are accepted and we can:
* Accept limited, small, self contained changes/features to ns-3-dev and to merged new features. As specified before, no more merges are accepted
* Review the code to be merged for next releases
* Cleanup the ns-3-dev bug tracker, solve as much bugs as possible

The end of the small feature development and bug fixes coincides (March 27th) with the beginning of the maintenance phase. No new features may be added, but the maintainers may check in fixes to bugs; and people with new features that have been accepted and previously merged may fix bugs in existing features. Please don't try to sneak in more new features or you may have your whole feature set removed at the release manager's discretion. You can ask if you want to add small, self-contained features, but there are no guarantees that we will okay them.

On April 13th, 2010, we are going to enter the code freeze phase. This indicates that we are in the final stages of the release and our primary goal is stability. During the code freeze phase, only P1 bugfixes will be allowed to be checked in. Our ''goal'' will be to reduce the number of P1 bugs to zero before the release of ns-3.8.

'''''We will reserve the right to veto (and remove) any new feature addition if it begins to cause problems and looks like it threatens the stability of the release at any time in the release process.'''''

== Candidate Contributions for Inclusion in ns-3.8 ==

=== Underwater Acoustic Network Device ===

* ''review location'': http://codereview.appspot.com/87043
* ''reviewer(s)'': Craig Dowell, Faker Moatamri
* ''status'': postponed to NS-3.8
* ''Developer'': Leonard Tracy
* ''background'': http://mailman.isi.edu/pipermail/ns-developers/2009-June/006148.html

=== NHDP ===
* ''Code'': No available code for the moment
* ''Developer'': Tom Wambold
* ''Status'': waiting to the code to be ready to review

=== Internet stack roadmap ===
* Work on various parts of the TCP/IP stack is tracked [[Internet-stack-maintenance | on this wiki page]]

=== NAT traversal ===
* ''background'': http://www.nsnam.org/wiki/index.php/GSOC2009NetworkAddressTranslation

=== Topology read system (Inet/Orbis) ===
* ''Review location'': http://codereview.appspot.com/204055/show
* ''Reviewers'': Pavel Boyko
* ''Developer'': Tommaso Pecorella
* ''Status'': Waiting for +1 from Mathieu
* ''background'':http://mailman.isi.edu/pipermail/ns-developers/2010-January/007314.html

== ns-3.8 Features Merged ==

=== Matrix propagation loss model ===
* ''Review location'': http://codereview.appspot.com/207104/show
* ''Reviewers'': Mathieu Lacage, Nicola Baldo
* ''Developer'': Pavel Boyko

=== MPI-based parallelization ===

* ''review location'': http://codereview.appspot.com/109068
* ''code location'': http://code.nsnam.org/jpelkey3/ns-3-distributed
* ''reviewers'': Faker Moatamri, Craig Dowell, Tom Henderson, Mathieu Lacage
* ''Developer'': George Riley and Josh Pelkey
* ''background'': http://mailman.isi.edu/pipermail/ns-developers/2009-November/006927.html

=== WiMAX ===

* ''code location'': http://code.nsnam.org/iamine/ns-3-wimax
* ''reviewers'': Faker Moatamri, Mathieu Lacage, Tom Henderson
* ''Developer'': Amine Ismail
* ''background'': http://mailman.isi.edu/pipermail/ns-developers/2009-August/006329.html

=== Redo ASCII and pcap Traces ===

* ''review location'': http://codereview.appspot.com/196058
* ''reviewer(s)'': Mathieu Lacage
* ''Developer'': Craig Dowell
* ''background'': http://mailman.isi.edu/pipermail/ns-developers/2010-January/007352.html

=== Gauss-Markov Mobility Model ===
* ''Review location'': http://codereview.appspot.com/223048
* ''Reviewers'': Josh Pelkey, Mathieu Lacage
* ''Developer'': Dan Broyles

=== Steady state random waypoint mobility model ===
* ''Review location'': http://codereview.appspot.com/193105/show
* ''Reviewers'': Mathieu Lacage
* ''Developer'': Denis Fakhriev
* ''Background'': http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.2.7557

=== 802.11n block ack ===
* ''Review location'': http://codereview.appspot.com/144050
* ''Reviewers'': Faker Moatamri, Nicola Baldo, Andrey Mazo, Andreev Kirill, Mathieu Lacage
* ''Developer'': Mirko Blanchi

=== Enhancements to src/core/random-variable.cc/h ===
* ''Review location'': http://www.nsnam.org/bugzilla/show_bug.cgi?id=797
* ''Reviewers'': Michele Weigle
* ''Developer'': Tommaso Pecorella

=== Two ray ground radio propagation model ===
* ''Review location'': http://www.nsnam.org/bugzilla/show_bug.cgi?id=787
* ''Reviewers'': Pavel Boyko, Mathieu Lacage
* ''Developer'': Tom Hewer
* ''Background'': http://en.wikipedia.org/wiki/2-Ray_Ground_Reflection_Model

=== Move propagation models to src/common ===
* ''Developer'': Amine Ismail
* ''Background'': http://mailman.isi.edu/pipermail/ns-developers/2010-January/007354.html

=== Pareto rng constructors using scale and shape instead of mean and shape ===
* ''Review location'': http://codereview.appspot.com/207098/show
* ''Reviewers'': Mathieu Lacage, Tom Henderson
* ''Developer'': Tommaso Pecorella

== The ns-3.8 Bug List ==

== High Priority Blockers ==

[http://www.nsnam.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=ns-3&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&deadlinefrom=&deadlineto=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&priority=P1&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= blockers list]

=== P1 Bugs ===
<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=806 Bug 806] - TCP doesn't work over a CSMA link</s>
* <s>Assigned to: ns-bugs</s>
* <s>Probably only affects ns-3.7 release</s>
* <s>Tom is working on a small test suite for this case</s>

== High Priority Non-Blockers ==

[http://www.nsnam.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=ns-3&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&deadlinefrom=&deadlineto=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&priority=P2&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= High priority non blockers]

=== P2 Bugs with patches ===

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=772 Bug 772] - AODV is unable to correctly buffer packets waiting for route reply</s>
* <s>Assigned to: Pavel Boyko</s>
* <s>Patch available, needs review</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=810 Bug 810] - In TCP, Socket::GetSockName() does not return the local socket address</s>
* <s>Assigned to: Josh Pelkey</s>
* <s>Patch available, looks ready to go</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=341 Bug 341] - Get unexpected dropped packets when using SetSendCallback with heavy traffic
* Assigned to: Craig Dowell
* Patch available, but old and possibly untested (from 2008!)
* submitter isn't using ns-3 anymore
* Mathieu has suggested (back in 2008) that this could be tricky
* Craig thinks this is invalid

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=794 Bug 794] - Ipv4Mask constructor for "/yy"-notation is wrong</s>
* <s>Assigned to: Craig Dowell</s>
* <s>+1 from Tom and Craig, looks ready to go</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=231 Bug 231] - SocketAddressTag needs to be removed from a packet before forwarding the packet to the user
* Assigned to: Faker Moatamri
* Possibly trivial now with RemovePacketTag API

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=778 Bug 778] - OLSR ignores specified outgoing interface in RouteOutput()</s>
* <s>Assigned to: Gustavo J. A. M. Carneiro</s>
* <s>Patch from Tom, Gustavo pretty much +1</s>
* <s>looks ready to go</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=788 Bug 788] - OLSR_NEIGH_HOLD_TIME should be 3 times OLSR_REFRESH_INTERVAL</s>
* <s>Assigned to: Gustavo J. A. M. Carneiro</s>
* <s>looks ready to go</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=747 Bug 747] - Listening TCP socket closes on RST</s>
* <s>Assigned to: Josh Pelkey</s>
* <s>+1 from me, looks ready to go</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=748 Bug 748] - Cloned TCP socket uses wrong source address</s>
* <s>Assigned to: Josh Pelkey</s>
* <s>Patch proposal from Fabian Mauchle</s>
* <s>need to look at this</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=555 Bug 555] - DCF immediate access bug
* Assigned to: Mathieu Lacage
* patch needs review

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=602 Bug 602] - WifiRemoteStation lacks information about the access class of outgoing packets</s>
* <s>Assigned to: Mathieu Lacage</s>
* <s>patch needs review</s>
* <s>possibly fixed in changeset 0f012e7d9128</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=521 Bug 521] - Ipv4 global routing inefficient
* Assigned to: Tom Henderson
* I think this one was re-opened, and not sure if the patch is still valid
* I know that Tom has mentioned he is working on this one

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=385 Bug 385] - Add a generic "sequence number" class
* Assigned to: Mathieu Lacage
* patch exists, but there is still some issues about implementation
* tracing is important for this one

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=184 Bug 184] - GtkConfigStore do not support ConfigureDefault</s>
* <s>Assigned to: Faker Moatamri</s>
* <s>another oldie</s>
* <s>Mathieu says, "This bug is now really about making GtkConfigStore do what ConfigStore already does and provide a GUI for the 'default' + 'global' values."</s>
* <s>Faker just updated the patch (Feb. 16, 2010), needs review</s>

=== P2 Bugs without patches ===

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=818 Bug 818] - TCP Socket implementation does not set ACK flag on retransmits
* Assigned to: Josh Pelkey
* Possible fix mentioned, but it causes crash in tcp test suite

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=822 Bug 822] - Default attributes in abstract base classes not working
* Assigned to: Mathieu Lacage
* Has test case to show bug
* Possibly two bugs

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=812 Bug 812] - Assert when getting socket in RecvReply for AODV</s>
* <s>Assigned to: Pavel Boyko</s>
* <s>changed to P2 crit, as this is blocking some people's research</s>
* <s>has example showing assert</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=796 Bug 796] - TCP bug in ns-3-dev branch : Crash detected during retesting of Chord on ns-3-dev branch</s>
* <s>Assigned to: Craig Dowell</s>
* <s>logs attached to this one</s>
* <s>worked in ns-3.6 but not ns-3.7</s>
* <s>possibly bug 806 fix fixed this</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=409 Bug 409] - Routing messages can exceed MTU, and fragmentation not supported
* Assigned to: Mathieu Lacage
* Quick fix available
* IP fragmentation support for UDP is needed

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=631 Bug 631] - RealtimeSimulatorImpl not compatible with python bindings
* Assigned to: Mathieu Lacage
* lots of discussion here, no consensus it seems

Ns-3.8

2010-03-09T18:08:29Z

Hippo: matrix propagation loss model merged

{{TOC}}

This page summarizes the ongoing release planning for ns-3.8. The release manager is Josh Pelkey <jpelkey@gatech.edu>.

== Tentative ns-3.8 Release Schedule ==

# <s>January 27 -- ns-3.7 posted</s>
# <s>January 27 -- ns-3.8 '''''Open phase begins'''''</s>
# <s>March 8 -- Deadline for new feature merge</s>
# March 8 -- Begin the phase of small feature development and bug fixing
# March 27 -- Small feature development and bug fixing ends
# March 27 -- '''''Open phase ends'''''
# March 27 -- '''''Maintenance phase begins'''''
# April 13 -- '''''Maintenance phase ends'''''
# April 13 -- '''''Code freeze phase begins'''''
# April 13 -- ns-3.8-RC1
# April 15 -- ns-3.8-RC2
# April 19 -- ns-3.8-RC3
# April 22 -- ns-3.8-RC4
# April 27 -- ns-3.8 posted
# April 27 -- '''''Code freeze phase ends'''''
# April 27 -- ns-3.9 Open phase begins

As described in the [[Roadmap]] there are three broad sections in the release schedule. During the open phase, people wanting to include a new feature in ns-3.8 should contact Josh and arrange to have their features merged into ns-3-dev. You will be expected to provide the following:

* A mercurial patch, bundle or repo against the current version of ns-3-dev that contains your proposed feature addition. You need to make sure that we can apply this patch and build and run (debug and optimized as appropriate) all unit and regression tests successfully on all of our target machines
* A summary of the additions you are proposing and an explanation of any changes to existing code that had to be done in order to support your feature (this will be used to generate release notes and will be provided to maintainers if a code review is indicated)
* Some kind of unit or system test that can be used to determine if your feature is actually working at each stage of the integration

One of us will take a quick look at your proposed addition and determine if a code review is required. According to the ''book of instructions'' a code review requiring positive acknowledgment by maintainers is indicated if:

* Your proposed feature does not work with all models or on all platforms
* Your feature changes pre-existing APIs
* Your feature crosses maintainer boundaries

Just to be safe, we will probably run a feature submission by at least one maintainer according to the general area of applicability of the feature. For example, if you submit an entirely new device driver model, as a courtesy we will run this submission by the maintainers of the current devices. The maintainers won't have any responsibility to positively ack the submission, but we will take some time to allow a reasonable review.

The open phase is divided into two parts: new feature merge period and small feature development and bug fixing.

During the new feature merge period we can:
* Review the code that might be merged
* Clean up the bug tracker: solve as much bugs as possible
* Merge the new features that has +1 and from maintainers

After March 8th, the new feature merge period ends and small feature development and bug fixes begins. During the latter, no more merges are accepted and we can:
* Accept limited, small, self contained changes/features to ns-3-dev and to merged new features. As specified before, no more merges are accepted
* Review the code to be merged for next releases
* Cleanup the ns-3-dev bug tracker, solve as much bugs as possible

The end of the small feature development and bug fixes coincides (March 27th) with the beginning of the maintenance phase. No new features may be added, but the maintainers may check in fixes to bugs; and people with new features that have been accepted and previously merged may fix bugs in existing features. Please don't try to sneak in more new features or you may have your whole feature set removed at the release manager's discretion. You can ask if you want to add small, self-contained features, but there are no guarantees that we will okay them.

On April 13th, 2010, we are going to enter the code freeze phase. This indicates that we are in the final stages of the release and our primary goal is stability. During the code freeze phase, only P1 bugfixes will be allowed to be checked in. Our ''goal'' will be to reduce the number of P1 bugs to zero before the release of ns-3.8.

'''''We will reserve the right to veto (and remove) any new feature addition if it begins to cause problems and looks like it threatens the stability of the release at any time in the release process.'''''

== Candidate Contributions for Inclusion in ns-3.8 ==

=== Underwater Acoustic Network Device ===

* ''review location'': http://codereview.appspot.com/87043
* ''reviewer(s)'': Craig Dowell, Faker Moatamri
* ''status'': postponed to NS-3.8
* ''Developer'': Leonard Tracy
* ''background'': http://mailman.isi.edu/pipermail/ns-developers/2009-June/006148.html

=== NHDP ===
* ''Code'': No available code for the moment
* ''Developer'': Tom Wambold
* ''Status'': waiting to the code to be ready to review

=== Internet stack roadmap ===
* Work on various parts of the TCP/IP stack is tracked [[Internet-stack-maintenance | on this wiki page]]

=== NAT traversal ===
* ''background'': http://www.nsnam.org/wiki/index.php/GSOC2009NetworkAddressTranslation

=== Topology read system (Inet/Orbis) ===
* ''Review location'': http://codereview.appspot.com/204055/show
* ''Reviewers'': Pavel Boyko
* ''Developer'': Tommaso Pecorella
* ''Status'': Waiting for +1 from Mathieu
* ''background'':http://mailman.isi.edu/pipermail/ns-developers/2010-January/007314.html

== ns-3.8 Features Merged ==

=== Matrix propagation loss model ===
* ''Review location'': http://codereview.appspot.com/207104/show
* ''Reviewers'': Mathieu Lacage, Nicola Baldo
* ''Developer'': Pavel Boyko
* ''Status'': Ready to go, just needs to be merged

=== MPI-based parallelization ===

* ''review location'': http://codereview.appspot.com/109068
* ''code location'': http://code.nsnam.org/jpelkey3/ns-3-distributed
* ''reviewers'': Faker Moatamri, Craig Dowell, Tom Henderson, Mathieu Lacage
* ''Developer'': George Riley and Josh Pelkey
* ''background'': http://mailman.isi.edu/pipermail/ns-developers/2009-November/006927.html

=== WiMAX ===

* ''code location'': http://code.nsnam.org/iamine/ns-3-wimax
* ''reviewers'': Faker Moatamri, Mathieu Lacage, Tom Henderson
* ''Developer'': Amine Ismail
* ''background'': http://mailman.isi.edu/pipermail/ns-developers/2009-August/006329.html

=== Redo ASCII and pcap Traces ===

* ''review location'': http://codereview.appspot.com/196058
* ''reviewer(s)'': Mathieu Lacage
* ''Developer'': Craig Dowell
* ''background'': http://mailman.isi.edu/pipermail/ns-developers/2010-January/007352.html

=== Gauss-Markov Mobility Model ===
* ''Review location'': http://codereview.appspot.com/223048
* ''Reviewers'': Josh Pelkey, Mathieu Lacage
* ''Developer'': Dan Broyles

=== Steady state random waypoint mobility model ===
* ''Review location'': http://codereview.appspot.com/193105/show
* ''Reviewers'': Mathieu Lacage
* ''Developer'': Denis Fakhriev
* ''Background'': http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.2.7557

=== 802.11n block ack ===
* ''Review location'': http://codereview.appspot.com/144050
* ''Reviewers'': Faker Moatamri, Nicola Baldo, Andrey Mazo, Andreev Kirill, Mathieu Lacage
* ''Developer'': Mirko Blanchi

=== Enhancements to src/core/random-variable.cc/h ===
* ''Review location'': http://www.nsnam.org/bugzilla/show_bug.cgi?id=797
* ''Reviewers'': Michele Weigle
* ''Developer'': Tommaso Pecorella

=== Two ray ground radio propagation model ===
* ''Review location'': http://www.nsnam.org/bugzilla/show_bug.cgi?id=787
* ''Reviewers'': Pavel Boyko, Mathieu Lacage
* ''Developer'': Tom Hewer
* ''Background'': http://en.wikipedia.org/wiki/2-Ray_Ground_Reflection_Model

=== Move propagation models to src/common ===
* ''Developer'': Amine Ismail
* ''Background'': http://mailman.isi.edu/pipermail/ns-developers/2010-January/007354.html

=== Pareto rng constructors using scale and shape instead of mean and shape ===
* ''Review location'': http://codereview.appspot.com/207098/show
* ''Reviewers'': Mathieu Lacage, Tom Henderson
* ''Developer'': Tommaso Pecorella

== The ns-3.8 Bug List ==

== High Priority Blockers ==

[http://www.nsnam.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=ns-3&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&deadlinefrom=&deadlineto=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&priority=P1&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= blockers list]

=== P1 Bugs ===
<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=806 Bug 806] - TCP doesn't work over a CSMA link</s>
* <s>Assigned to: ns-bugs</s>
* <s>Probably only affects ns-3.7 release</s>
* <s>Tom is working on a small test suite for this case</s>

== High Priority Non-Blockers ==

[http://www.nsnam.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=ns-3&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&deadlinefrom=&deadlineto=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&priority=P2&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0= High priority non blockers]

=== P2 Bugs with patches ===

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=772 Bug 772] - AODV is unable to correctly buffer packets waiting for route reply</s>
* <s>Assigned to: Pavel Boyko</s>
* <s>Patch available, needs review</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=810 Bug 810] - In TCP, Socket::GetSockName() does not return the local socket address</s>
* <s>Assigned to: Josh Pelkey</s>
* <s>Patch available, looks ready to go</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=341 Bug 341] - Get unexpected dropped packets when using SetSendCallback with heavy traffic
* Assigned to: Craig Dowell
* Patch available, but old and possibly untested (from 2008!)
* submitter isn't using ns-3 anymore
* Mathieu has suggested (back in 2008) that this could be tricky
* Craig thinks this is invalid

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=794 Bug 794] - Ipv4Mask constructor for "/yy"-notation is wrong</s>
* <s>Assigned to: Craig Dowell</s>
* <s>+1 from Tom and Craig, looks ready to go</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=231 Bug 231] - SocketAddressTag needs to be removed from a packet before forwarding the packet to the user
* Assigned to: Faker Moatamri
* Possibly trivial now with RemovePacketTag API

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=778 Bug 778] - OLSR ignores specified outgoing interface in RouteOutput()</s>
* <s>Assigned to: Gustavo J. A. M. Carneiro</s>
* <s>Patch from Tom, Gustavo pretty much +1</s>
* <s>looks ready to go</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=788 Bug 788] - OLSR_NEIGH_HOLD_TIME should be 3 times OLSR_REFRESH_INTERVAL</s>
* <s>Assigned to: Gustavo J. A. M. Carneiro</s>
* <s>looks ready to go</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=747 Bug 747] - Listening TCP socket closes on RST</s>
* <s>Assigned to: Josh Pelkey</s>
* <s>+1 from me, looks ready to go</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=748 Bug 748] - Cloned TCP socket uses wrong source address</s>
* <s>Assigned to: Josh Pelkey</s>
* <s>Patch proposal from Fabian Mauchle</s>
* <s>need to look at this</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=555 Bug 555] - DCF immediate access bug
* Assigned to: Mathieu Lacage
* patch needs review

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=602 Bug 602] - WifiRemoteStation lacks information about the access class of outgoing packets</s>
* <s>Assigned to: Mathieu Lacage</s>
* <s>patch needs review</s>
* <s>possibly fixed in changeset 0f012e7d9128</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=521 Bug 521] - Ipv4 global routing inefficient
* Assigned to: Tom Henderson
* I think this one was re-opened, and not sure if the patch is still valid
* I know that Tom has mentioned he is working on this one

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=385 Bug 385] - Add a generic "sequence number" class
* Assigned to: Mathieu Lacage
* patch exists, but there is still some issues about implementation
* tracing is important for this one

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=184 Bug 184] - GtkConfigStore do not support ConfigureDefault</s>
* <s>Assigned to: Faker Moatamri</s>
* <s>another oldie</s>
* <s>Mathieu says, "This bug is now really about making GtkConfigStore do what ConfigStore already does and provide a GUI for the 'default' + 'global' values."</s>
* <s>Faker just updated the patch (Feb. 16, 2010), needs review</s>

=== P2 Bugs without patches ===

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=818 Bug 818] - TCP Socket implementation does not set ACK flag on retransmits
* Assigned to: Josh Pelkey
* Possible fix mentioned, but it causes crash in tcp test suite

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=822 Bug 822] - Default attributes in abstract base classes not working
* Assigned to: Mathieu Lacage
* Has test case to show bug
* Possibly two bugs

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=812 Bug 812] - Assert when getting socket in RecvReply for AODV</s>
* <s>Assigned to: Pavel Boyko</s>
* <s>changed to P2 crit, as this is blocking some people's research</s>
* <s>has example showing assert</s>

<s>[http://www.nsnam.org/bugzilla/show_bug.cgi?id=796 Bug 796] - TCP bug in ns-3-dev branch : Crash detected during retesting of Chord on ns-3-dev branch</s>
* <s>Assigned to: Craig Dowell</s>
* <s>logs attached to this one</s>
* <s>worked in ns-3.6 but not ns-3.7</s>
* <s>possibly bug 806 fix fixed this</s>

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=409 Bug 409] - Routing messages can exceed MTU, and fragmentation not supported
* Assigned to: Mathieu Lacage
* Quick fix available
* IP fragmentation support for UDP is needed

[http://www.nsnam.org/bugzilla/show_bug.cgi?id=631 Bug 631] - RealtimeSimulatorImpl not compatible with python bindings
* Assigned to: Mathieu Lacage
* lots of discussion here, no consensus it seems

HOWTO use VirtualBox to run simulations on Windows machines

2009-11-08T10:30:48Z

Hippo:

{{TOC}}

ns-3 is primarily a Linux platform, and advanced ns-3 features will use Linux specific functions to accomplish their goals. Since Windows is such a widely used platform, ns-3 does provide a supported solution for running in that environment using a Linux-emulation environment called [http://cygwin.com Cygwin]. However, Cygwin is not a perfect emulation of any Linux. This means there will be features available on Linux systems that are simply not usable on Windows systems.

Fortunately, a technology called virtualization exists to allow one to share computer hardware between operating systems and allow you use Linux systems essentially as if they were running natively on your hardware. This happens as your Windows is running, so it appears as if Windows and Linux are sharing your hardware.

There are several virtualization schemes currently available. Two of the most popular are VMware (see [[HOWTO use VMware to set up virtual networks (Windows)]]) and VirtualBox. We will cover VirtualBox in this HOWTO. The following image is a screenshot of Fedora 11 running as a virtual machine on a Windows XP (classic) desktop. You can probably make out that the terminal session on Fedora 11 has just completed running the ns-3 test suite (test.py).

[[Image:Screenshot_fc11.png]]

There is extensive documentation available online for VirtualBox. Look [http://www.virtualbox.org/ here] for a starting point. Note that by downloading the VirtualBox code you are implicitly agreeing to [http://www.virtualbox.org/wiki/VirtualBox_PUEL this license].

== HOWTO use VirtualBox to run simulations on Windows machines ==

1. The first thing you must do is get the VirtualBox binaries.
a. Go to [http://www.virtualbox.org/wiki/Downloads the VirtualBox downloads page]
b. Download and run the VirtualBox binary for Windows Hosts by clicking on
the x86/amd64 link. You will get the usual '''File Download - Security'''
'''Warning''' dialog. Just click '''Run''' to download and run the about
70 megabyte file.
c. After the file downloads, you will get the usual Windows '''Internet'''
'''Explorer - Security Warning''' dialog. Just select '''Run'''.

2. Step through the '''Sun VirtualBox Setup Wizard'''.
a. Press the '''Next >''' button.
b. Accept the terms of the license agrreement (if you desire) by clicking
the corresponding radio button.
c. Press the '''Next >''' button.
d. Review the features that will be installed if you desire. I just accept
them as-is.
e. Press the '''Next >''' button.
f. Decide if you want a desktop and quick lanch icon. If you expect to
use ns-3 a lot it is probably worthwhile, but completely up to your
preference.
g. Press the '''Next >''' button.

3. Perform the actual installation. Warning: This step will temporarily
disconnect you from the Internet.
a. Press the '''Install''' button to start the installation process.
b. You will see a number of dialog boxes (six) complaining that VirtualBox
has not passed '''Windows Logo Testing'''. Press '''Continue Anyway'''.
c. When you see the '''Sun VirtualBox installation is complete''' message
leave the '''Start Sun VirtualBox after installation''' radio button
selected.
d. Press the '''Finish''' button.

4. Register with Sun Online. VirtualBox will ask you to register with Sun
Online. If you already have a Sun Online account, enter it or just fill
out the account creation part of the page and press '''Register'''. If the
registration process complains about a bad IP address, just create a new
account.

----
Sidebar: In this HOWTO, we explain how to download a CD image from the web and use it to install a guest operating system in VirtualBox. There is an alternative, which is to start with a pre-configured OS "Virtual Applicance." These are VMware things, but VirtualBox can read them. You can browse through hundreds of applicances [http://www.vmware.com/appliances/directory/cat/508 here].
----

5. Download a Linux CD image.
a. Decide which version of Linux you are going to use. If you have no
strong preference, I would use the same version that ns-3 does most
of its testing on. Look [http://www.nsnam.org/wiki/index.php/Main_Page here] for the ns-3 wiki. Follow the
[http://ns-regression.ee.washington.edu:8010/waterfall Buildbot Waterfall Display] link, and notice the list of platforms.
At the time of this writing, most of them are fc10. This translates
to Fedora Core 10. You can infer that ns-3 testing is mostly performed
on Fedora systems, so Fedora it is; and Fedora 11 is the latest release
as of this writing.
b. Go to [http://fedoraproject.org/ The Fedora Project] and then to [http://fedoraproject.org/en/get-fedora Get Fedora] and download a
CD image. You will get the usual '''File Download - Do you want to open'''
'''or save this file?''' dialog. Just click '''Save''' and tell the system
where to put the almost 700 megabyte file.

6. Create a new virtual machine.
a. Go to the Sun VirtualBox window you started in step 3.
b. Press the "New" button. This will start a '''New Virtual Machine Wizard'''.
c. Press '''Next >''' in the wizard.
d. Give your new virtual machine a name, say "ns-3-fedora-11".
e. In the '''OS Type''' box, select '''Linux''' as the Operating System and
'''Fedora''' as the Version.
f. Press '''Next >''' in the wizard.
g. Keeping in mind how much physical memory you have in your host machine,
give the new virtual machine some memory. This won't be available for
your host machine. I choose 512 MB on my 2 GB Windows machine.
h. Press '''Next >''' in the wizard.
i. Keeping in mind how much hard disk space you have in your host machine
give the new virtual machine some memory. You will need disk for the
base OS, the toolchain and at least one ns-3 distribution, which will
require about 1.2 gig at the time of this writing.
j. Press '''Next >''' in the '''New Virtual Machine Wizard''' to start the
'''Create New Virtual Disk Wizard'''.
k. Press '''Next >''' in the '''Create New Virtual Disk Wizard'''.
l. Leave the '''Dynamically expanding storage''' radio button selected and
press '''Next >''' in the '''Create New Virtual Disk Wizard'''.
m. Select a maximum size for the disk (I use 10 GB) and press '''Next >'''
in the '''Create New Virtual Disk Wizard'''.
o. Press '''Finish''' in the '''Create New Virtual Disk Wizard''' to create
your disk.
p. This takes you back to the '''New Virtual Machine Wizard''' which will
be giving you a summary of the new virtual machine parameters. Press
'''Finish''' in the '''Create New Virtual Disk Wizard''' to create
your new virtual machine.

7. "Insert" your boot CD. In the Sun VirtualBox window, you should now see a
virtual machine named "ns-3-fedora-11" in the powered off state on the left
side. On the right side, you should see the "Details" tab selected, with the
details for "ns-3-fedora-11" displayed.
a. Click on the CD/DVD-ROM item.
b. Select the '''Mount CD/DVD Drive''' check box.
c. Select the '''ISO Image File''' radio button.
d. Browse for the ISO Image File.
e. Select the "Add" Icon and browse to the ISO image file for Fedora 11
you saved in step 5.
f. Press '''Select''' and then '''OK'''.

8. Power up the virtual machine and install Fedora 11.
a. Select the "Start" icon in the Sun VirtualBox window. It is shaped like
a green arrow.
b. Read the information dialog about how to get in and out of the virtual
machine window and press '''OK'''.
c. Read the information dialog about color mode and press '''OK'''.
d. Click into the new virtual machine window, select '''Capture''' and
watch Fedora 11 start to install (this will take a while).
e. When the login box appears, press "Log In" and then double click the
'''Install to Hard Disk''' icon.
f. Press '''Next''' to begin the Fedora 11 installation process and copy the
image to the virtual machine hard drive. This is going to take some
considerable time since you are installing a whole operating system.
We won't cover how to proceed here in detail since this is not a Fedora
11 installation guide. Google is your friend if you have problems.
g. Eventually you'll see "Congratulations, your Fedora installation is
complete". Press '''Close'''.
h. Shut down the Fedora system.

9. "Remove" your boot CD. In the Sun VirtualBox window, you should now see a
virtual machine named "ns-3-fedora-11" in the powered off state on the left
side. On the right side, you should see the "Details" tab selected, with the
details for "ns-3-fedora-11" displayed.
a. Click on the CD/DVD-ROM item.
b. Deselect the '''Mount CD/DVD Drive''' check box.
c. Press '''OK'''.

10. Bring up your shiny new Fedora 11 system.
a. Select the "Start" icon in the Sun VirtualBox window. It is shaped like
a green arrow.
b. You'll have to do a few more setup steps (create a user) in the Fedora
'''Setup Agent'''. This will reboot one more time and then you can log
in with your new user name.

11. Install the GNU toolchain and some useful tools. If you have added yourself as a sudoer, you can run the following commands (or others according to your taste) using sudo, otherwise log on as root. A more complete list is available [http://www.nsnam.org/wiki/index.php/Installation#Prerequisites here].
a. yum install libxml2 libxml2-devel
b. yum install gcc gcc-c++ make automake autoconf binutils
c. yum install openssh-server openssh-clients openssl
d. yum install python python-devel mercurial bzr
e. yum install scons flex bison
f. yum install tcpdump valgrind gdb emacs

12. Get and Test ns-3-dev
a. Make sure you have exited from su root, if you did that in step 11.
b. cd ~
c. mkdir repos
d. cd repos
e. hg clone http://code.nsnam.org/ns-3-allinone
f. cd ns-3-allinone
g. ./download.py
h. ./build.py
i. cd ns-3-dev
j. ./test.py
k. ./waf --regression

As an old math professor once said, "I feel joy"!

If you are really going to use a virtual machine as a primary development platform, you will probably be annoyed by the limitation of the device driver to 800x600 resolution. You can fix this by installing the so-called VirtualBox Guest Additions. This will aso get rid of the annoying "mouse capture" and "mouse release" business. If you install the Guest Additions, you can resize your virtual desktop to any size you want and mouse in and out of it just as if you were in a Windows window. Recommended. The screen shot at the top of the page was taken of a my home system which has these additions enabled. See the VirtualBox documentation for instructions.

----
[[User:Craigdo|Craigdo]] 22:21, 7 November 2009 (UTC)

HOWTO use VirtualBox to run simulations on Windows machines

2009-11-08T09:20:49Z

Hippo: markup and typos fixes

{{TOC}}

ns-3 is primarily a Linux platform, and advanced ns-3 features will use Linux specific functions to accomplish their goals. Since Windows is such a widely used platform, ns-3 does provide a supported solution for running in that environment using a Linux-emulation environment called [http://cygwin.com Cygwin]. However, Cygwin is not a perfect emulation of any Linux. This means there will be features available on Linux systems that are simply not usable on Windows systems.

Fortunately, a technology called virtualization exists to allow one to share computer hardware between operating systems and allow you use Linux systems essentially as if they were running natively on your hardware. This happens as your Windows is running, so it appears as if Windows and Linux are sharing your hardware.

There are several virtualization schemes currently available. Two of the most popular are VMware (see [[HOWTO use VMware to set up virtual networks (Windows)]]) and VirtualBox. We will cover VirtualBox in this HOWTO. The following image is a screenshot of Fedora 11 running as a virtual machine on a Windows XP (classic) desktop. You can probably make out that the terminal session on Fedora 11 has just completed running the ns-3 test suite (test.py).

[[Image:Screenshot_fc11.png]]

There is extensive documentation available online for VirtualBox. Look [http://www.virtualbox.org/ here] for a starting point. Note that by downloading the VirtualBox code you are implicitly agreeing to [http://www.virtualbox.org/wiki/VirtualBox_PUEL this license].

== HOWTO use VirtualBox to run simulations on Windows machines ==

1. The first thing you must do is get the VirtualBox binaries.
a. Go to [http://www.virtualbox.org/wiki/Downloads the VirtualBox downloads page]
b. Download and run the VirtualBox binary for Windows Hosts by clicking on
the x86/amd64 link. You will get the usual '''File Download - Security'''
'''Warning''' dialog. Just click '''Run''' to download and run the about
70 megabyte file.
c. After the file downloads, you will get the usual Windows '''Internet'''
'''Explorer - Security Warning''' dialog. Just select '''Run'''.

2. Step through the '''Sun VirtualBox Setup Wizard'''.
a. Press the '''Next >''' button.
b. Accept the terms of the license agrreement (if you desire) by clicking
the corresponding radio button.
c. Press the '''Next >''' button.
d. Review the features that will be installed if you desire. I just accept
them as-is.
e. Press the '''Next >''' button.
f. Decide if you want a desktop and quick lanch icon. If you expect to
use ns-3 a lot it is probably worthwhile, but completely up to your
preference
g. Press the '''Next >''' button.

3. Perform the actual installation. Warning: This step will temporarily
disconnect you from the Internet.
a. Press the '''Install''' button to start the installation process.
b. You will see a number of dialog boxes (six) complaining that VirtualBox
has not passed '''Windows Logo Testing'''. Press '''Continue Anyway'''.
c. When you see the '''Sun VirtualBox installation is complete''' message
leave the '''Start Sun VirtualBox after installation''' radio button
selected.
d. Press the '''Finish''' button.

4. Register with Sun Online. VirtualBox will ask you to register with Sun
Online. If you already have a Sun Online account, enter it or just fill
out the account creation part of the page and press '''Register'''. If the
registration process complains about a bad IP address, just create a new
account.

----
Sidebar: In this HOWTO, we explain how to download a CD image from the web and use it to install a guest operating system in VirtualBox. There is an alternative, which is to start with a pre-configured OS "Virtual Applicance." These are VMware things, but VirtualBox can read them. You can browse through hundreds of applicances [http://www.vmware.com/appliances/directory/cat/508 here].
----

5. Download a Linux CD image.
a. Decide which version of Linux you are going to use. If you have no
strong preference, I would use the same version that ns-3 does most
of its testing on. Look [http://www.nsnam.org/wiki/index.php/Main_Page here] for the ns-3 wiki. Follow the
[http://ns-regression.ee.washington.edu:8010/waterfall Buildbot Waterfall Display] link, and notice the list of platforms.
At the time of this writing, most of them are fc10. This translates
to Fedora Core 10. You can infer that ns-3 testing is mostly performed
on Fedora systsms, so Fedora it is; and Fedora 11 is the latest release
as of this writing.
b. Go to [http://fedoraproject.org/ The Fedora Project] and then to [http://fedoraproject.org/en/get-fedora Get Fedora] and download a
CD image. You will get the usual '''File Download - Do you want to open'''
'''or save this file?''' dialog. Just click '''Save''' and tell the system
where to put the almost 700 megabyte file.

6. Create a new virtual machine
a. Go to the Sun VirtualBox window you started in step 3.
b. Press the "New" button. This will start a '''New Virtual Machine Wizard'''.
c. Press '''Next >''' in the wizard.
d. Give your new virtual machine a name, say "ns-3-fedora-11".
e. In the '''OS Type''' box, select '''Linux''' as the Operating System and
'''Fedora''' as the Version.
f. Press '''Next >''' in the wizard.
g. Keeping in mind how much physical memory you have in your host machine,
give the new virtual machine some memory. This won't be available for
your host machine. I choose 512 MB on my 2 GB Windows machine.
h. Press '''Next >''' in the wizard.
i. Keeping in mind how much hard disk space you have in your host machine
give the new virtual machine some memory. You will need disk for the
base OS, the toolchain and at least one ns-3 distribution, which will
require about 1.2 gig at the time of this writing.
j. Press '''Next >''' in the '''New Virtual Machine Wizard''' to start the
'''Create New Virtual Disk Wizard'''.
k. Press '''Next >''' in the '''Create New Virtual Disk Wizard'''.
l. Leave the '''Dynamically expanding storage''' radio button selected and
press '''Next >''' in the '''Create New Virtual Disk Wizard'''.
m. Select a maximum size for the disk (I use 10 GB) and press '''Next >'''
in the '''Create New Virtual Disk Wizard'''.
o. Press '''Finish''' in the '''Create New Virtual Disk Wizard''' to create
your disk.
p. This takes you back to the '''New Virtual Machine Wizard''' which will
be giving you a summary of the new virtual machine parameters. Press
'''Finish''' in the '''Create New Virtual Disk Wizard''' to create
your new virtual machine.

7. "Insert" your boot CD. In the Sun VirtualBox window, you should now see a
virtual machine named "ns-3-fedora-11" in the powered off state on the left
side. On the right side, you should see the "Details" tab selected, with the
details for "ns-3-fedora-11" displayed.
a. Click on the CD/DVD-ROM item.
b. Select the '''Mount CD/DVD Drive''' check box.
c. Select the '''ISO Image File''' radio button.
d. Browse for the ISO Image File.
e. Select the "Add" Icon and browse to the ISO image file for Fedora 11
you saved in step 5.
f. Press '''Select''' and then '''OK'''.

8. Power up the virtual machine and install Fedora 11.
a. Select the "Start" icon in the Sun VirtualBox window. It is shaped like
a green arrow.
b. Read the information dialog about how to get in and out of the virtual
machine window and press '''OK'''.
c. Read the information dialog about color mode and press '''OK'''.
d. Click into the new virtual machine window, select '''Capture''' and
watch Fedora 11 start to install (this will take a while).
e. When the login box appears, press "Log In" and then double click the
'''Install to Hard Disk icon'''.
f. Press '''Next''' to begin the Fedora 11 installation process and copy the
image to the virtual machine hard drive. This is going to take some
considerable time since you are installing a whole operating system.
We won't cover how to proceed here in detail since this is not a Fedora
11 installation guide. Google is your friend if you have problems.
g. Eventually you'll see "Congratulations, your Fedora installation is
complete. Press '''Close'''.
h. Shut down the Fedora system.

9. "Remove" your boot CD. In the Sun VirtualBox window, you should now see a
virtual machine named "ns-3-fedora-11" in the powered off state on the left
side. On the right side, you should see the "Details" tab selected, with the
details for "ns-3-fedora-11" displayed.
a. Click on the CD/DVD-ROM item.
b. Deselect the '''Mount CD/DVD Drive''' check box.
c. Press '''OK'''.

10. Bring up your shiny new Fedora 11 system.
a. Select the "Start" icon in the Sun VirtualBox window. It is shaped like
a green arrow.
b. You'll have to do a few more setup steps (create a user) in the Fedora
'''Setup Agent'''. This will reboot one more time and then you can log
in with your new user name.

11. Install the GNU toolchain and some useful tools. If you have added yourself as a sudoer, you can run the following commands (or others according to your taste) using sudo, otherwise log on as root. A more complete list is available [http://www.nsnam.org/wiki/index.php/Installation#Prerequisites here].
a. yum install libxml2 libxml2-devel
b. yum install gcc gcc-c++ make automake autoconf binutils
c. yum install openssh-server openssh-clients openssl
d. yum install python python-devel mercurial bzr
e. yum install scons flex bison
f. yum install tcpdump valgrind gdb emacs

12. Get and Test ns-3-dev
a. Make sure you have exited from su root, if you did that in step 11.
b. cd ~
c. mkdir repos
d. cd repos
e. hg clone http://code.nsnam.org/ns-3-allinone
f. cd ns-3-allinone
g. ./download.py
h. ./build.py
i. cd ns-3-dev
j. ./test.py
k. ./waf --regression

As an old math professor once said, "I feel joy"!

If you are really going to use a virtual machine as a primary development platform, you will probably be annoyed by the limitation of the device driver to 800x600 resolution. You can fix this by installing the so-called VirtualBox Guest Additions. This will aso get rid of the annoying "mouse capture" and "mouse release" business. If you install the Guest Additions, you can resize your virtual desktop to any size you want and mouse in and out of it just as if you were in a Windows window. Recommended. The screen shot at the top of the page was taken of a my home system which has these additions enabled. See the VirtualBox documentation for instructions.

----
[[User:Craigdo|Craigdo]] 22:21, 7 November 2009 (UTC)