Installation

From Nsnam
Revision as of 06:03, 10 September 2008 by Tomh (Talk | contribs) (start of detailed installation guide)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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

This is a detailed installation guide for ns-3. Basic installation instructions can be found at the Getting Started page or in the 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 or greater, and python 2.4 or greater.

ns-3 is also supported on the following primary platforms:

  1. Linux x86/x86-64 gcc-4.x
  2. Linux x86/x86-64 gcc-3.4 (note 1)
  3. Mac OS X, x86/ppc, gcc-4.x
  4. Cygwin (a Linux-like environment for Windows) (note 2)

note 1: optimized build not supported in gcc-3.4 versions except for gcc-3.4.6

note 2: Python bindings not supported for Cygwin in ns-3.2

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. ns-3 may also run on currently unsupported platforms. Additional maintainers are invited to make more platforms 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 the waf script:

---- Summary of optional NS-3 features:
Threading Primitives          : enabled
Real Time Simulator           : enabled
GtkConfigStore                : not enabled (library 'gtk+-2.0 >= 2.12' not found)
SQlite stats data output      : enabled
Network Simulation Cradle     : not enabled (--enable-nsc configure option not given)
Python Bindings               : not enabled (Python development headers not found.)

The table below is meant to help sort out the different features and on which platforms they are supported.

Option status
Option Linux gcc-4.x Linux gcc-3.4 OS X Cygwin
Optimized build X 1
Python bindings X 2
Threading X
Real-time simulator X
Network simulation cradle  ?  ?

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

Notes:

  1. only supported for gcc-3.4.6
  2. Cygwin limitation explained here

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.

  • Fetching ns-3-dev (or other development repositories) via Mercurial
 sudo apt-get install mercurial
  • A GTK-based configuration system
 sudo apt-get install libgtk2.0-0 libgtk2.0-dev
  • Debugging:
 sudo apt-get install valgrind
  • Doxygen and related inline documentation:
 sudo apt-get install doxygen graphviz imagemagick
 sudo apt-get install texlive texlive-pdf texlive-latex-extra
  • The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):
 sudo apt-get install texinfo dia tgif
  • To install gcc-3.4 for some Network Simulation Cradle (nsc) stacks:
 sudo apt-get install g++-3.4 gcc-3.4
  • To fetch python bindings (ns-3 development branch)
sudo apt-get install bzr
  • To read pcap packet traces
sudo apt-get install tcpdump
  • Database support for statistics framework
sudo apt-get install sqlite sqlite3

Configuration

The Waf build system is used to build ns-3. Waf is a Python-based build system (http://www.freehackers.org/~tnagy/waf.html).

Installing Waf

The top-level ns-3 directory should contain a current waf script.

Configuration with Waf

To build ns-3 with waf type the commands from the top-level directory:

  1. ./waf configure [options]
  2. ./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.

To start over a configuration from scratch, type:

 ./waf distclean

For instance, to forcibly disable python bindings, you can provide the following option:

   --disable-python      Don't build Python bindings.

Build

Type "./waf" after configuration has succeeded. If you are on a multicore machine, you can exploit the cores by using the "-j" argument, as in this example for a quad-core machine:

 ./waf -j4

Validating

ns-3 has unit tests:

 ./waf check

which should produce output like:

Compilation finished successfully 
PASS GlobalRouteManagerImpl
PASS EventGarbageCollector
PASS Olsr
PASS OlsrRoutingTable
PASS OlsrHeader
PASS UdpSocket
PASS Tags
PASS Packet
...

and also regression tests:

 ./waf --regression

Using Python

See this page.

Troubleshooting

See this page.