Difference between revisions of "Installation"

From Nsnam
Jump to: navigation, search
Line 136: Line 136:
 
  sudo apt-get install python-pygraphviz python-kiwi python-pygoocanvas
 
  sudo apt-get install python-pygraphviz python-kiwi python-pygoocanvas
  
−
== Configuration ==
+
== Installation ==
  
−
The Waf build system is used to build ns-3.  Waf is a Python-based
+
The ns-3 code is available in Mercurial repositories on the server
−
build system (http://www.freehackers.org/~tnagy/waf.html).
+
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).
  
−
=== Installing Waf ===
+
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.
  
−
The top-level ns-3 directory should contain a current waf script.
+
=== 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 ss-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 @command{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.4.tar.bz2
 +
  tar xjf ns-3.4.tar.bz2
 +
 
 +
If you change into the directory ns-allinone-3.4 you should see a
 +
number of files:
 +
 
 +
  build.py*    ns-3.4-RC2/            nsc-0.5.0/            util.py
 +
  constants.py  ns-3.4-RC2-ref-traces/  pybindgen-0.10.0.630/
 +
 
 +
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 ===
 
=== Configuration with Waf ===
  
−
To build ns-3 with waf type the commands from the top-level directory:
+
To see valid configure options, type ./waf --help.  The most important option
−
# ./waf configure [options]
+
is -d <debug level>.  Valid debug levels (which are listed in waf --help) are:  
−
# ./waf
+
"debug" or "optimized". It is also possible to change the flags used for
 +
compilation with (e.g.):
 +
 
 +
  CXXFLAGS="-O3" ./waf configure
  
−
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
 
or, alternately, the gcc compiler
 +
 
   CXX=g++-3.4 ./waf configure
 
   CXX=g++-3.4 ./waf configure
  
Line 162: Line 300:
 
the option must be supplied during the configure stage rather than
 
the option must be supplied during the configure stage rather than
 
the build stage (i.e., "./waf -d optimized" will not work; instead, do
 
the build stage (i.e., "./waf -d optimized" will not work; instead, do
 +
 
   ./waf -d optimized configure; ./waf  
 
   ./waf -d optimized configure; ./waf  
  
Line 167: Line 306:
  
 
To start over a configuration from scratch, type:
 
To start over a configuration from scratch, type:
 +
 
   ./waf distclean
 
   ./waf distclean
  
 
For instance, to forcibly disable python bindings, you can provide the following option:
 
For instance, to forcibly disable python bindings, you can provide the following option:
 +
 
     --disable-python      Don't build Python bindings.
 
     --disable-python      Don't build Python bindings.
  
 
To see all options:
 
To see all options:
 +
 
   ./waf --help
 
   ./waf --help
−
 
−
== 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 ==
 
== Validating ==
  
−
ns-3 has unit tests:
+
ns-3 has unit tests that can be run to verify the installation:
 +
 
 
   ./waf check
 
   ./waf check
 +
 
which should produce output like:
 
which should produce output like:
 
<pre>
 
<pre>
Line 199: Line 337:
 
</pre>
 
</pre>
  
−
and also regression tests that compare the packet trace output against known good traces (similar to ns-2's validation suite):
+
To run the regression tests mentioned above:
 +
 
 
   ./waf --regression
 
   ./waf --regression
  
Line 211: Line 350:
  
 
----
 
----
−
[[User:Craigdo|Craigdo]] 17:40, 31 March 2009 (UTC)
+
[[User:Craigdo|Craigdo]] 18:14, 31 March 2009 (UTC)

Revision as of 18:14, 31 March 2009

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/g++-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
  3. Mac OS X, x86/ppc, gcc-4.x
  4. Cygwin (a Linux-like environment for Windows)

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. 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
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               : enabled
Python API Scanning Support   : enabled
Use sudo to set suid bit      : not enabled (option --enable-sudo not selected)

The distinction between "not enabled" and "disabled" is that the latter is used when the user explicitly disables a feature (such as "--disable-python") while the former is when the platform is missing some requirement for the option.

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

Option status
Option Linux gcc-4.x Linux gcc-3.4 OS X Cygwin
Optimized build note1 X 2
Python bindings X 3
Threading X
Real-time simulator X
Emulated Net Device X X
Tap Bridge X X
Network simulation cradle note4 X X

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

Notes:

  1. Generally supported, but gcc-4.3.2 (ubuntu intrepid) is blocked by http://www.nsnam.org/bugzilla/show_bug.cgi?id=337
  2. only supported for gcc-3.4.6
  3. Cygwin limitation explained here
  4. 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). Also note that installation should be similar for Red Hat/Fedora based systems, with "yum" replacing "apt-get".

  • 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
  • The ns-3 manual and tutorial are written in Texinfo (doc/tutorial or doc/manual):
 sudo apt-get install texinfo dia texlive-extra-utils 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
  • Support for Gustavo's ns-3-pyviz visualizer
sudo apt-get install python-pygraphviz python-kiwi python-pygoocanvas

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 ss-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 @command{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.4.tar.bz2
 tar xjf ns-3.4.tar.bz2

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

 build.py*     ns-3.4-RC2/             nsc-0.5.0/             util.py
 constants.py  ns-3.4-RC2-ref-traces/  pybindgen-0.10.0.630/

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.

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.

To see all options: 

 ./waf --help

Validating

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

 ./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
...

To run the regression tests mentioned above: 

 ./waf --regression

Using Python

See this page.

Troubleshooting

See this page.

Craigdo 18:14, 31 March 2009 (UTC)

Retrieved from "https://www.nsnam.org/mediawiki/index.php?title=Installation&oldid=2516"