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-3-allinone-3.4 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:

  Build finished successfully (00:02:37)
  Leaving directory `./ns-3-dev'

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 and 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 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 header linux/if_tun.h                      : ok
Checking for pkg-config flags for GTK_CONFIG_STORE      : ok
Package libxml-2.0 was not found in the pkg-config search path.
Perhaps you should add the directory containing `libxml-2.0.pc'
to the PKG_CONFIG_PATH environment variable
No package 'libxml-2.0' found
Checking for pkg-config flags for LIBXML2               : not found
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
Package goocanvas was not found in the pkg-config search path.
Perhaps you should add the directory containing `goocanvas.pc'
to the PKG_CONFIG_PATH environment variable
No package 'goocanvas' found
Checking for pkg-config flags for MOBILITY_VISUALIZER   : not found
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.630
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
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)
Configuration finished successfully (00:00:02); project is now ready to build.

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. in the example above, this library was not found and the corresponding feature was not enabled. There is a feature to use sudo to set the suid bit of certain programs. This was not enabled by default.

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. This is a configuration command, and so you could have run the following command

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

If you had done this, waf would have run sudo to change the socket creator programs 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 April, 2 2009 using texi2html 1.78.