User FAQ

Main Page - Roadmap - Summer Projects - Project Ideas - Developer FAQ - Tools - Related Projects

HOWTOs - Installation - Troubleshooting - User FAQ - 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 there have not yet been any releases (pre-alpha stage).

If you are looking for a simulator to currently use for research, please use ns-2.

Will ns-2 scripts run on ns-3?

No. ns-2 uses OTcl as its scripting environment. ns-3 will use 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 :)

Mercurial

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 http://code.nsnam.org/mathieu/ns-3-ptr
cd ns-3-ptr
# merge from main ns-3 repository into this other repository
hg pull http://code.nsnam.org/ns-3
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://code@code.nsnam.org/repos/ns-3

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 (new 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.

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"

Scons (old build process)

Library not loaded error

Question: On Apple osX, I built ns-3 successfully, but when I try to run a sample program I get something like:

> ./sample-packet
dyld: Library not loaded: build-dir/dbg-shared/lib/libcommon.dylib
  Referenced from: /tmp/ns-3/build-dir/dbg-shared/bin/./sample-packet
  Reason: image not found
Trace/BPT trap

Answer: This is because the library path variable of your environment does not include the location where the ns-3 modules (libraries) are located.

In OS X, you need to set the DYLD_LIBRARY_PATH variable to include the library directory. These need to include the lib/ directory where these ns-3 libraries are built. On Linux and Solaris systems, you should never warnings of this kind. If you do, please, report a bug.

In this example, setting DYLD_LIBRARY_PATH=/tmp/ns-3/build-dir/dbg-shared/lib/ will work.

How do I do the equivalent of a "make clean"?

scons -c