User FAQ

From Nsnam
Revision as of 18:25, 8 September 2008 by Mathieu.lacage (Talk | contribs)

Jump to: navigation, search

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

The Network Simulator ns-3: Frequently Asked Questions (FAQ)

This wiki page is devoted to questions for users of the simulator. There is a similar Developer_FAQ page for ns-3 software developers and maintainers.

What is the difference between ns-2 and ns-3?

ns-2 is a popular discrete-event network simulator developed under several previous research grants and activities. It remains in active use and will continue to be maintained.

ns-3 is a new software development effort focused on improving upon the core architecture, software integration, models, and educational components of ns-2. The project commenced in July 2006 and the first release was made on June 30, 2008.

Will ns-2 scripts run on ns-3?

No. ns-2 uses OTcl as its scripting environment. ns-3 uses C++ programs or python scripts to define simulations.

I found a bug in ns-3. How do I report it?

Please consult this page. Also, please consider fixing the bug, not just reporting it :)


merging a separate repository with a main repository

Q. I want to incorporate some code from a mercurial branch (repository) that is off the main repository.

A. (from Mathieu Lacage)

You can create a local clone of the repository and pull into it from the main repository: you can push these yourself by creating a local clone of that repo and then pushing it back to the main repo. It will keep the original history; e.g.:

hg clone
cd ns-3-ptr
# merge from main ns-3 repository into this other repository
hg pull
hg merge

Pushing this new merged repository into another repository will then keep the original change history:

# push back-- must have privileges to push to the repository
hg push ssh://

working with subsets of repositories

Q. Is there a way with mercurial to pull/merge/push subsets of the repositories? For instance, suppose I wanted only to grab the samples directory from a repo and merge that alone.

A. (from Mathieu Lacage) You cannot cherry-pick individual changesets other than by exporting them to patches first. The reason is that each Changeset contains a single hash which is, among others, based on the hash of the 'parent' changeset hash. So, if you 'reparent' a changeset, you change its hash id because the id of the parent changes. If the hash id of a changeset changes, it is a different changeset so, mercurial cannot really manage these individual changesets. There is, however, the transplant extension that lets you do just that.

So, the idea is that merging happens from one repo to another, and cannot be done on a sub-dir basis. The other alternatives are:

1) the latest mercurial has support for in-repo branches: you can maintain multiple branches within a single repository but each branch represents a branch for the whole repository.

2) the latest mercurial contains the forest extension which is a way to make mercurial manage a 'forest' of repos: each repo is independent but they also behave as a single big repo through the forest extension.

WAF (build process)

See also the WAF developers FAQ

How to build NS-3

First choose the debug level that you want. To select the debug level, you have to configure NS-3 first with the command:
./waf configure -d debuglevel

Where debuglevel is one of:

  • debug (the default): builds NS-3 with the most suited options for debugging. This includes disabling of all optimization, since it confuses the debugger and makes debugging very difficult. It also activates NS-3 internal assertions to catch all programming errors, as well as enabling support for debugging messages (NS_DEBUG and NS_DEBUG_UNCONDITIONAL). This mode should be used initially for development, until you are happy that the code runs correctly and does not contain any serious programming mistake.
  • optimized: this compiles NS-3 with optimization, but disabled assertions and debugging messages. Use this when the program is correct and you just want to extrat results.

It is also possible to customize the C compilation flags through the CXXFLAGS environment variable. Example:

CXXFLAGS='-O3' ./waf configure -d optimized

See here for a list of additional environment variables that can be used to control waf configure. After configuration, NS-3 can be built with the command:

./waf build

[ The waf command build can be omitted, since it is the default command. ]

WARNING: even though the -d option is accepted outside "waf configure", it is completely ignored unless applied together with the configure command.

Note:: If you have a multicore machine, you can accelerate the building and linking process by using the -j option. For instance, for a machine with four cores:

./waf -j4

How to run NS-3 programs

First, the builtin NS-3 unit tests can be executed with the command:

./waf check

To run the remaining programs, there are three different ways to do it.

  1. The hard way: because NS-3 is built as a set of shared library (dll) files, it requires you to manually configure LD_LIBRARY_PATH, PATH, or DYLD_LIBRARY_PATH, depending on your platform, to make them point to each ns-3 module directory. Only then can you run the programs that were built as build/<debuglevel>/path/to/program.
  2. Easy way #2: run ./waf --shell. You will then have a new nested shell from which programs can be run, e.g. gdb ./build/debug/examples/simple-p2p.
  3. Easy way #1: ./waf --run programname, or ./waf --run "programname args". To find out available program names, run ./waf --run non-existent-program-name.

How to run NS-3 programs under another tool

For running ns-3 programs with gdb or valgrind, try the following:

  • Use the "command-template" argument; e.g.
    • waf --run csma-cd-one-subnet --command-template="gdb %s"
    • waf --run csma-cd-one-subnet --command-template="valgrind %s"
  • To run the unit tests (waf check) under gdb:
    • ./waf --command-template="gdb %s" --run run-tests

How to configure cygwin

cygwin works reasonably-well by default: just make sure you grab the cygwin installer from cygwin includes support for mercurial, gcc, and, python so, nothing else should be needed.

How to configure mingw

mingw requires much more work than cygwin to setup. You need to grab:

If you don't want to use msvc to build ns-3, you need to tell ./waf to use your mingw g++ compiler instead: <code>./waf --check-cxx-compiler=g++ will do this

Python bindings

Questions about how to use Python with ns-3? See ns-3 python wiki page