Getting Started with ns-3

This short guide is aimed at people new to ns-3, to understand what ns-3 does and how to use it.

ns-3 is a discrete-event network simulator written in C++ and with an optional Python scripting API. If you are new to discrete-event network simulation, you may want to first review this Wikipedia page.

Getting ns-3

There are several ways to get the ns-3 source code:

  • Download the most recent stable release (currently ns-3.9);
  • Download a repository using mercurial and compile it from source. This is recommended if you want to look at current code or you want to examine an alternate or experimental code branch. If you have Mercurial already installed, you can simply try "hg clone http://code.nsnam.org/ns-3-dev"
  • Browse the source code repositories at http://code.nsnam.org

Supported operating systems

Much of the ns-3 development is performed on GNU/Linux. The ns-3 project supports the following operating systems:

  • 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)
  • Cygwin gcc 3.4.4 (debug only), gcc 4.3.2 (debug and optimized)
ns-3 consists of a core system with multiple options; some options are not supported on all systems, or must be configured into the system. For a complete guide to installing and building ns-3, consult this wiki page.

Compiling ns-3 from source

Building the ns-3 core has only a few dependencies: a modern Python installation (python 2.4 or greater) and the GNU C compiler package. ns-3 is written in C++ and is known to compile on gcc 4.x. Here are some quick instructions for those who want to build it right away. First, download ns-3.9 using the link above. Then open a console to the directory where you saved the file and do the following: 

  bunzip2 ns-allinone-3.9.tar.bz2
  tar xvf ns-allinone-3.9.tar
  cd ns-allinone-3.9
  ./build.py
For a complete guide to installing and building ns-3, consult this wiki page.

The Waf build system is used to build ns-3. Waf is a Python-based build system. Further instructions are in the doc/build.txt file in the distribution.

These links are likely to be of some additional help getting started:

Validating an ns-3 compilation

You can run ns-3 unit tests by changing into the ns-3.9 directory and typing "./test.py" after the build step from above finishes. It should produce output such as: 

PASS: TestSuite histogram
PASS: TestSuite sample
PASS: TestSuite devices-mesh-flame
...
PASS: Example wireless/wifi-wired-bridging
PASS: Example wireless/wifi-simple-adhoc-grid
PASS: Example wireless/wifi-ap --verbose=0
93 of 93 tests passed (93 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors)

You can also run ns-3 regression tests of the examples and compare the output with known good traces. Try typing "./waf --regression".

The ns-commits mailing list posts nightly build results from the ns-3-dev repository.

Running ns-3

See this wiki page

Troubleshooting

Please consult this wiki page.


Generated on 02/Sep/2010 at 13:00:02. Thanks to the XORP (http://www.xorp.org) project for this stylesheet.