3.2 Building ns-3

3.2.1 Building with build.py

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-allinone-3.6 under your ~/tarballs directory. Take a deep breath and 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:

  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
  'build' finished successfully (2m30.586s)

Once the project has built you can say goodbye to your old friends, the ns-3-allinone scripts. You got what you needed from them and will now interact directly with Waf and we do it in the ns-3-dev directory, not in the ns-3-allinone directory. Go ahead and change into the ns-3-dev directory (or the directory for the appropriate release you downloaded.

  cd ns-3-dev

3.2.2 Building with Waf

We use Waf to configure and build the ns-3 project. It’s not strictly required at this point, but it will be valuable to take a slight detour and look at how to make changes to the configuration of the project. Probably the most useful configuration change you can make will be to build the optimized version of the code. By default you have configured your project to build the debug version. Let’s tell the project to do make an optimized build. To explain to Waf that it should do optimized builds you will need to execute the following command,

  ./waf -d optimized configure

This runs Waf out of the local directory (which is provided as a convenience for you). As the build system checks for various dependencies you should see output that looks similar to the following,

  Checking for program g++                 : ok /usr/bin/g++
  Checking for program cpp                 : ok /usr/bin/cpp
  Checking for program ar                  : ok /usr/bin/ar
  Checking for program ranlib              : ok /usr/bin/ranlib
  Checking for g++                         : ok
  Checking for program pkg-config          : ok /usr/bin/pkg-config
  Checking for regression reference traces  : ok ../ns-3-dev-ref-traces (guessed)
  Checking for -Wno-error=deprecated-declarations support : yes
  Checking for -Wl,--soname=foo support                   : yes
  Checking for header stdlib.h                            : ok
  Checking for header signal.h                            : ok
  Checking for header pthread.h                           : ok
  Checking for high precision time implementation         : 128-bit integer
  Checking for header stdint.h                            : ok
  Checking for header inttypes.h                          : ok
  Checking for header sys/inttypes.h                      : not found
  Checking for library rt                                 : ok
  Checking for header netpacket/packet.h                  : ok
  Checking for pkg-config flags for GSL                   : ok
  Checking for header linux/if_tun.h                      : ok
  Checking for pkg-config flags for GTK_CONFIG_STORE      : ok
  Checking for pkg-config flags for LIBXML2               : ok
  Checking for library sqlite3                            : ok
  Checking for NSC location                               : ok ../nsc (guessed)
  Checking for library dl                                 : ok
  Checking for NSC supported architecture x86_64          : ok
  Checking for program python                             : ok /usr/bin/python
  Checking for Python version >= 2.3                      : ok 2.5.2
  Checking for library python2.5                          : ok
  Checking for program python2.5-config                   : ok /usr/bin/python2.5-config
  Checking for header Python.h                            : ok
  Checking for -fvisibility=hidden support                : yes
  Checking for pybindgen location                         : ok ../pybindgen (guessed)
  Checking for Python module pybindgen                    : ok
  Checking for pybindgen version                          : ok 0.10.0.640
  Checking for Python module pygccxml                     : ok
  Checking for pygccxml version                           : ok 0.9.5
  Checking for program gccxml                             : ok /usr/local/bin/gccxml
  Checking for gccxml version                             : ok 0.9.0
  Checking for program sudo                               : ok /usr/bin/sudo
  Checking for program hg                                 : ok /usr/bin/hg
  Checking for program valgrind                           : ok /usr/bin/valgrind
  ---- Summary of optional NS-3 features:
  Threading Primitives          : enabled
  Real Time Simulator           : enabled
  Emulated Net Device           : enabled
  GNU Scientific Library (GSL)  : enabled
  Tap Bridge                    : enabled
  GtkConfigStore                : enabled
  XmlIo                         : enabled
  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)
  Build examples and samples    : enabled
  Static build                  : not enabled (option --enable-static not selected)
  'configure' finished successfully (2.870s)

Note the last part of the above output. Some ns-3 options are not enabled by default or require support from the underlying system to work properly. For instance, to enable XmlTo, the library libxml-2.0 must be found on the system. If this library were not found, the corresponding ns-3 feature would not be enabled and a message would be displayed. Note further that there is a feature to use the program sudo to set the suid bit of certain programs. This is not enabled by default and so this feature is reported as “not enabled.”

Now go ahead and switch back to the debug build.

  ./waf -d debug configure

The build system is now configured and you can build the debug versions of the ns-3 programs by simply typing,

  ./waf

Some waf commands are meaningful during the build phase and some commands are valid in the configuration phase. For example, if you wanted to use the emulation features of ns-3 you might want to enable setting the suid bit using sudo as described above. This turns out to be a configuration-time command, and so you could reconfigure using the following command

  ./waf -d debug --enable-sudo configure

If you do this, waf will have run sudo to change the socket creator programs of the emulation code to run as root. There are many other configure- and build-time options available in waf. To explore these options, type:

  ./waf --help

We’ll use some of the testing-related commands in the next section.

Okay, sorry, I made you build the ns-3 part of the system twice, but now you know how to change the configuration and build optimized code.

This document was generated on August 20, 2010 using texi2html 1.82.